Budibase Public API JavaScript SDK 使用指南从 swagger-codegen 自动生成到浏览器端集成【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibaseBudibase Public API SDKnpm 包名budibase/sdk是 Budibase 官方为公共 REST API 提供的 JavaScript 客户端位于仓库的 packages/sdk 目录。它由 swagger-codegen 基于服务端 OpenAPI 规范自动生成专为浏览器环境设计帮助前端应用快速对接 Budibase 的应用、数据表、行、查询与用户等核心资源。读完本文你将掌握该 SDK 的生成机制、环境约束、配置方法与两种调用风格Promise 与回调并理解其底层 API 客户端的封装原理。一、SDK 概览为 Budibase Public API 而生的浏览器端客户端budibase/sdk是 Budibase Public API 的官方 JS SDK其定位非常明确面向浏览器官方文档明确指出 The generated code will only run in a browser. It is not currently useable in a NodeJS environment即生成的代码只能在浏览器中运行目前不可用于 Node.js 环境由 swagger-codegen 自动生成SDK 由 swagger-codegen 的 v3 版本生成镜像swaggerapi/swagger-codegen-cli-v3:3.0.46并非手写维护因此其 API 形状与后端 OpenAPI 规范严格同步生成过程依赖 Docker由于生成器通过 Docker 运行宿主机无需安装 JavaDocker 是生成 SDK 的唯一前置依赖。在包管理层面package.json 中声明了包名为budibase/sdk采用 ESM 模块格式type: module入口为dist/sdk.mjs许可证为 MPL-2.0。二、SDK 是如何生成的脚本、配置与 Docker 调用链SDK 的生成完全由脚本驱动核心入口是yarn run build:sdk内部先执行generate再执行rollup -c。整个生成链路集中在 packages/sdk/scripts 目录下包含两个关键文件1. 生成脚本 generate-sdk.shgenerate-sdk.sh 完整定义了生成流程可分为四步第一步清理旧产物。脚本开头删除历史遗留的openapi.yaml、generated目录以及上一版生成的../sdk源码目录保证每次生成都是全新产物避免增量污染if [[ -f openapi.yaml ]]; then rm openapi.yaml fi if [[ -d generated ]]; then rm -r generated fi if [[ -d ../sdk ]]; then rm -r ../sdk fi第二步引入 OpenAPI 规范。将服务端公共 API 的规范文件复制到脚本目录mkdir generated cp ../../server/specs/openapi.yaml ./这印证了 SDK 的“事实来源”是 server/specs/openapi.yaml——服务端公共 API 的所有端点、模型、鉴权方式都由这份规范定义SDK 只是它的客户端镜像。第三步通过 Docker 运行 swagger-codegen 生成 JS 客户端docker run --rm \ -v ${PWD}/openapi.yaml:/openapi.yml \ -v ${PWD}/generated:/generated \ -v ${PWD}/config.json:/config.json \ -u $(id -u):$(id -g) \ swaggerapi/swagger-codegen-cli-v3:3.0.46 generate \ -i /openapi.yml \ -l javascript \ -o /generated \ -c /config.json关键参数说明参数/挂载含义-v openapi.yaml:/openapi.yml将 OpenAPI 规范挂载进容器作为输入-v generated:/generated生成产物输出目录-v config.json:/config.json生成器配置文件-u $(id -u):$(id -g)以当前用户 UID/GID 运行避免生成文件归属 root-i /openapi.yml输入规范文件-l javascript生成 JavaScript 语言客户端-o /generated输出目录-c /config.json生成器配置第四步提取产物并清理。把生成器输出中真正的源码目录generated/src移动到包根目录下的sdk子目录即../sdk随后删除临时文件。2. 生成器配置 config.jsonconfig.json 的内容非常精简只有一项{ usePromises: true }usePromises: true决定了生成代码默认提供 Promise 风格的 API这也是 README 示例中可以直接await调用applicationsSearchPost的原因。不过 swagger-codegen 生成的 JS 客户端通常会同时保留回调风格的重载具体见下文示例部分。三、环境要求与使用前置条件在使用budibase/sdk之前需要明确以下约束运行时环境为浏览器SDK 依赖浏览器环境XHR/fetch 能力不能在 Node.js 中直接运行如果你的集成端是 Node.js 后端需要自行基于 Public API 规范 实现客户端Docker 仅在生成期需要只有当你需要重新生成 SDK 时才需要 Docker宿主机无需 Java。作为普通消费者直接通过 npm 安装使用即可需要 API Key 鉴权SDK 使用 API Key 认证ApiKeyAuth你需要先在 Budibase 实例中创建 API Key配置位于 Budibase 的 API Key 管理界面同源或跨域前提host应指向 Budibase 实例的根地址例如https://my.budibase.app若使用自托管实例请替换为你的实际域名或 IP。四、官方示例详解configure 与 ApplicationsApiREADME 给出了一个可直接运行的示例用于按名称搜索应用。首先导入并配置客户端import { configure, ApplicationsApi } from budibase/sdk // Configure the API client configure({ apiKey: my-api-key, host: https://my.budibase.app })这里的configure是生成代码提供的全局配置函数用于设置 API Key 与目标主机ApplicationsApi则是应用资源的 API 类。配置完成后即可调用资源方法。1. Promise 风格调用// Search for an app. // We can use the promisified version... const res await ApplicationsApi.applicationsSearchPost({ name: foo }) console.log(Applications:, res.data)applicationsSearchPost对应 Public API 中搜索应用的 POST 端点请求体传入{ name: foo }即可按名称模糊/精确匹配应用。返回的res.data是搜索结果数据。Promise 风格得益于usePromises: true的生成配置让异步流程可以配合async/await使用。2. 回调风格调用// ...or the callback version ApplicationsApi.applicationsSearchPost({ name: foo }, ((error, data) { if (error) { console.error(Failed to search:, error) } else { console.log(Applications:, data.data) } }))回调风格遵循 Node 风格的(error, data)约定第一个参数是请求体第二个参数是回调函数回调中error非空表示调用失败例如 API Key 无效、网络错误否则data.data即为查询结果。注意两种风格的返回结构略有差异Promise 风格取res.data回调风格取data.data——外层.data是 swagger-codegen 生成的响应包装内层才是业务数据。3. 错误处理要点Promise 风格使用try/catch捕获网络错误、4xx/5xx 响应或鉴权失败回调风格优先判断error参数非空即失败通用排查检查apiKey是否正确、host是否可达、对应资源是否具备访问权限。五、源码视角API 客户端封装与默认行为除了生成代码自带的configure/ApiClient包内还提供了一个手写的封装入口 src/index.js将常用资源聚合成一个类export default class SDK { applications new BudibaseApi.ApplicationsApi() queries new BudibaseApi.QueriesApi() rows new BudibaseApi.RowsApi() tables new BudibaseApi.TablesApi() users new BudibaseApi.UsersApi() constructor({ apiKey, host }) { let ApiClient new BudibaseApi.ApiClient() ApiClient.basePath ${host || }/api/public/v1 ApiClient.authentications[ApiKeyAuth].apiKey apiKey ... } }从这份源码可以提炼出几个关键实现事实五大资源域ApplicationsApi应用、QueriesApi查询、RowsApi数据行、TablesApi数据表、UsersApi用户覆盖 Budibase 公共 API 的核心操作面basePath 约定所有请求都指向${host}/api/public/v1即 Budibase Public API 的版本化前缀。特别地host缺省时退化为空字符串basePath 变成相对路径/api/public/v1——这意味着当 SDK 运行在 Budibase 实例同源页面中时可以省略 host自动请求当前域名下的 API鉴权注入通过ApiClient.authentications[ApiKeyAuth].apiKey apiKey将 API Key 挂载到认证对象上后续每次请求都会携带该凭证通常为请求头形式可选 host 传参构造函数同时接受apiKey与host与生成代码的configure({ apiKey, host })参数结构保持一致。六、构建与分发Rollup 打包为 ESM生成代码是 swagger-codegen 的原始 CommonJS 形态包内通过 rollup.config.js 将其打包为浏览器友好的 ESM 产物export default { input: src/index.js, output: [ { sourcemap: false, format: esm, file: ./dist/sdk.mjs, }, ], plugins: [ commonjs(), nodePolyfills(), resolve({ preferBuiltins: true, browser: true, }), ], }这里有三点值得注意输出格式format: esm、文件dist/sdk.mjs与 package.json 中module: dist/sdk.mjs的入口声明一致Node 内置模块 polyfillnodePolyfills()插件为浏览器环境补齐生成代码可能引用的 Node 内置模块这正是只在浏览器运行这一约束的实现基础浏览器优先解析resolve({ browser: true })让打包器按浏览器场景解析依赖。七、在浏览器项目中集成的完整步骤结合上述机制在实际前端项目中集成该 SDK 的推荐流程如下安装在项目中安装budibase/sdk依赖准备 API Key在 Budibase 实例后台创建 API Key并确认目标实例的访问地址初始化在应用入口处调用configure({ apiKey, host })完成全局配置若你的页面与 Budibase 同源可省略host调用资源 API按需导入ApplicationsApi、RowsApi、TablesApi、QueriesApi、UsersApi等类选择 Promise 或回调风格发起请求处理响应统一从响应包装中取业务数据Promise 取res.data回调取data.data并对鉴权/网络错误做兜底处理。若你需要对 SDK 做二次开发或重新生成可执行yarn run build:sdk依赖 Docker生成产物将自动落入sdk子目录并被 Rollup 打包。八、常见问题与限制小结Node.js 环境报错官方明确生成代码仅支持浏览器。若在 Node.js 中使用需要借助浏览器环境模拟或自行实现客户端这也是文档明确标注的当前限制host 与 basePath所有请求统一走/api/public/v1前缀配置 host 时不要重复拼接该前缀生成一致性SDK 的形状完全由 server/specs/openapi.yaml 决定若 Public API 新增端点需重新运行生成脚本同步客户端代码鉴权失败优先核对 API Key 是否有效、是否已通过configure或 SDK 构造参数正确注入对应源码中的ApiKeyAuth认证对象。Budibase Public API SDK 通过OpenAPI 规范 → swagger-codegen → Rollup 打包的流水线将服务端公共 API 完整映射为浏览器端可直接调用的 JS 客户端配合 Promise/回调双风格与五大资源域封装是前端应用集成 Budibase 数据与应用能力的最短路径。【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Budibase Public API JavaScript SDK 使用指南：从 swagger-codegen 自动生成到浏览器端集成
Budibase Public API JavaScript SDK 使用指南从 swagger-codegen 自动生成到浏览器端集成【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibaseBudibase Public API SDKnpm 包名budibase/sdk是 Budibase 官方为公共 REST API 提供的 JavaScript 客户端位于仓库的 packages/sdk 目录。它由 swagger-codegen 基于服务端 OpenAPI 规范自动生成专为浏览器环境设计帮助前端应用快速对接 Budibase 的应用、数据表、行、查询与用户等核心资源。读完本文你将掌握该 SDK 的生成机制、环境约束、配置方法与两种调用风格Promise 与回调并理解其底层 API 客户端的封装原理。一、SDK 概览为 Budibase Public API 而生的浏览器端客户端budibase/sdk是 Budibase Public API 的官方 JS SDK其定位非常明确面向浏览器官方文档明确指出 The generated code will only run in a browser. It is not currently useable in a NodeJS environment即生成的代码只能在浏览器中运行目前不可用于 Node.js 环境由 swagger-codegen 自动生成SDK 由 swagger-codegen 的 v3 版本生成镜像swaggerapi/swagger-codegen-cli-v3:3.0.46并非手写维护因此其 API 形状与后端 OpenAPI 规范严格同步生成过程依赖 Docker由于生成器通过 Docker 运行宿主机无需安装 JavaDocker 是生成 SDK 的唯一前置依赖。在包管理层面package.json 中声明了包名为budibase/sdk采用 ESM 模块格式type: module入口为dist/sdk.mjs许可证为 MPL-2.0。二、SDK 是如何生成的脚本、配置与 Docker 调用链SDK 的生成完全由脚本驱动核心入口是yarn run build:sdk内部先执行generate再执行rollup -c。整个生成链路集中在 packages/sdk/scripts 目录下包含两个关键文件1. 生成脚本 generate-sdk.shgenerate-sdk.sh 完整定义了生成流程可分为四步第一步清理旧产物。脚本开头删除历史遗留的openapi.yaml、generated目录以及上一版生成的../sdk源码目录保证每次生成都是全新产物避免增量污染if [[ -f openapi.yaml ]]; then rm openapi.yaml fi if [[ -d generated ]]; then rm -r generated fi if [[ -d ../sdk ]]; then rm -r ../sdk fi第二步引入 OpenAPI 规范。将服务端公共 API 的规范文件复制到脚本目录mkdir generated cp ../../server/specs/openapi.yaml ./这印证了 SDK 的“事实来源”是 server/specs/openapi.yaml——服务端公共 API 的所有端点、模型、鉴权方式都由这份规范定义SDK 只是它的客户端镜像。第三步通过 Docker 运行 swagger-codegen 生成 JS 客户端docker run --rm \ -v ${PWD}/openapi.yaml:/openapi.yml \ -v ${PWD}/generated:/generated \ -v ${PWD}/config.json:/config.json \ -u $(id -u):$(id -g) \ swaggerapi/swagger-codegen-cli-v3:3.0.46 generate \ -i /openapi.yml \ -l javascript \ -o /generated \ -c /config.json关键参数说明参数/挂载含义-v openapi.yaml:/openapi.yml将 OpenAPI 规范挂载进容器作为输入-v generated:/generated生成产物输出目录-v config.json:/config.json生成器配置文件-u $(id -u):$(id -g)以当前用户 UID/GID 运行避免生成文件归属 root-i /openapi.yml输入规范文件-l javascript生成 JavaScript 语言客户端-o /generated输出目录-c /config.json生成器配置第四步提取产物并清理。把生成器输出中真正的源码目录generated/src移动到包根目录下的sdk子目录即../sdk随后删除临时文件。2. 生成器配置 config.jsonconfig.json 的内容非常精简只有一项{ usePromises: true }usePromises: true决定了生成代码默认提供 Promise 风格的 API这也是 README 示例中可以直接await调用applicationsSearchPost的原因。不过 swagger-codegen 生成的 JS 客户端通常会同时保留回调风格的重载具体见下文示例部分。三、环境要求与使用前置条件在使用budibase/sdk之前需要明确以下约束运行时环境为浏览器SDK 依赖浏览器环境XHR/fetch 能力不能在 Node.js 中直接运行如果你的集成端是 Node.js 后端需要自行基于 Public API 规范 实现客户端Docker 仅在生成期需要只有当你需要重新生成 SDK 时才需要 Docker宿主机无需 Java。作为普通消费者直接通过 npm 安装使用即可需要 API Key 鉴权SDK 使用 API Key 认证ApiKeyAuth你需要先在 Budibase 实例中创建 API Key配置位于 Budibase 的 API Key 管理界面同源或跨域前提host应指向 Budibase 实例的根地址例如https://my.budibase.app若使用自托管实例请替换为你的实际域名或 IP。四、官方示例详解configure 与 ApplicationsApiREADME 给出了一个可直接运行的示例用于按名称搜索应用。首先导入并配置客户端import { configure, ApplicationsApi } from budibase/sdk // Configure the API client configure({ apiKey: my-api-key, host: https://my.budibase.app })这里的configure是生成代码提供的全局配置函数用于设置 API Key 与目标主机ApplicationsApi则是应用资源的 API 类。配置完成后即可调用资源方法。1. Promise 风格调用// Search for an app. // We can use the promisified version... const res await ApplicationsApi.applicationsSearchPost({ name: foo }) console.log(Applications:, res.data)applicationsSearchPost对应 Public API 中搜索应用的 POST 端点请求体传入{ name: foo }即可按名称模糊/精确匹配应用。返回的res.data是搜索结果数据。Promise 风格得益于usePromises: true的生成配置让异步流程可以配合async/await使用。2. 回调风格调用// ...or the callback version ApplicationsApi.applicationsSearchPost({ name: foo }, ((error, data) { if (error) { console.error(Failed to search:, error) } else { console.log(Applications:, data.data) } }))回调风格遵循 Node 风格的(error, data)约定第一个参数是请求体第二个参数是回调函数回调中error非空表示调用失败例如 API Key 无效、网络错误否则data.data即为查询结果。注意两种风格的返回结构略有差异Promise 风格取res.data回调风格取data.data——外层.data是 swagger-codegen 生成的响应包装内层才是业务数据。3. 错误处理要点Promise 风格使用try/catch捕获网络错误、4xx/5xx 响应或鉴权失败回调风格优先判断error参数非空即失败通用排查检查apiKey是否正确、host是否可达、对应资源是否具备访问权限。五、源码视角API 客户端封装与默认行为除了生成代码自带的configure/ApiClient包内还提供了一个手写的封装入口 src/index.js将常用资源聚合成一个类export default class SDK { applications new BudibaseApi.ApplicationsApi() queries new BudibaseApi.QueriesApi() rows new BudibaseApi.RowsApi() tables new BudibaseApi.TablesApi() users new BudibaseApi.UsersApi() constructor({ apiKey, host }) { let ApiClient new BudibaseApi.ApiClient() ApiClient.basePath ${host || }/api/public/v1 ApiClient.authentications[ApiKeyAuth].apiKey apiKey ... } }从这份源码可以提炼出几个关键实现事实五大资源域ApplicationsApi应用、QueriesApi查询、RowsApi数据行、TablesApi数据表、UsersApi用户覆盖 Budibase 公共 API 的核心操作面basePath 约定所有请求都指向${host}/api/public/v1即 Budibase Public API 的版本化前缀。特别地host缺省时退化为空字符串basePath 变成相对路径/api/public/v1——这意味着当 SDK 运行在 Budibase 实例同源页面中时可以省略 host自动请求当前域名下的 API鉴权注入通过ApiClient.authentications[ApiKeyAuth].apiKey apiKey将 API Key 挂载到认证对象上后续每次请求都会携带该凭证通常为请求头形式可选 host 传参构造函数同时接受apiKey与host与生成代码的configure({ apiKey, host })参数结构保持一致。六、构建与分发Rollup 打包为 ESM生成代码是 swagger-codegen 的原始 CommonJS 形态包内通过 rollup.config.js 将其打包为浏览器友好的 ESM 产物export default { input: src/index.js, output: [ { sourcemap: false, format: esm, file: ./dist/sdk.mjs, }, ], plugins: [ commonjs(), nodePolyfills(), resolve({ preferBuiltins: true, browser: true, }), ], }这里有三点值得注意输出格式format: esm、文件dist/sdk.mjs与 package.json 中module: dist/sdk.mjs的入口声明一致Node 内置模块 polyfillnodePolyfills()插件为浏览器环境补齐生成代码可能引用的 Node 内置模块这正是只在浏览器运行这一约束的实现基础浏览器优先解析resolve({ browser: true })让打包器按浏览器场景解析依赖。七、在浏览器项目中集成的完整步骤结合上述机制在实际前端项目中集成该 SDK 的推荐流程如下安装在项目中安装budibase/sdk依赖准备 API Key在 Budibase 实例后台创建 API Key并确认目标实例的访问地址初始化在应用入口处调用configure({ apiKey, host })完成全局配置若你的页面与 Budibase 同源可省略host调用资源 API按需导入ApplicationsApi、RowsApi、TablesApi、QueriesApi、UsersApi等类选择 Promise 或回调风格发起请求处理响应统一从响应包装中取业务数据Promise 取res.data回调取data.data并对鉴权/网络错误做兜底处理。若你需要对 SDK 做二次开发或重新生成可执行yarn run build:sdk依赖 Docker生成产物将自动落入sdk子目录并被 Rollup 打包。八、常见问题与限制小结Node.js 环境报错官方明确生成代码仅支持浏览器。若在 Node.js 中使用需要借助浏览器环境模拟或自行实现客户端这也是文档明确标注的当前限制host 与 basePath所有请求统一走/api/public/v1前缀配置 host 时不要重复拼接该前缀生成一致性SDK 的形状完全由 server/specs/openapi.yaml 决定若 Public API 新增端点需重新运行生成脚本同步客户端代码鉴权失败优先核对 API Key 是否有效、是否已通过configure或 SDK 构造参数正确注入对应源码中的ApiKeyAuth认证对象。Budibase Public API SDK 通过OpenAPI 规范 → swagger-codegen → Rollup 打包的流水线将服务端公共 API 完整映射为浏览器端可直接调用的 JS 客户端配合 Promise/回调双风格与五大资源域封装是前端应用集成 Budibase 数据与应用能力的最短路径。【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考