# soapi-cli > 接口平台前端开发使用的 sdk 开发工具 Latest version **2.4.0-beta.1** (published 2025-05-26) · MIT license · 0 weekly downloads ## Install ```sh npm install soapi-cli pnpm add soapi-cli yarn add soapi-cli bun add soapi-cli ``` Provides the command `soapi-cli`. ## Health **Score 30/100 (F)** — status: maintenance-mode. Positive: esm support; no vulnerabilities. Warnings: low downloads; no types. Negative: stale; low maintenance score. ## Facts | | | |---|---| | Version | 2.4.0-beta.1 | | Published | 2025-05-26 | | First published | 2019-08-26 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | ESM + CommonJS | | Node | >=8.9.4 | | Dependencies | 12 | | Unpacked size | 924.9 KB | | Known vulnerabilities | 0 (+1 in 1 direct dependencies) | | Install scripts | no | | Maintainers | lobos, val.istar.guo, rovast, danielchenn, zbqsfs | ## Links - npm: https://www.npmjs.com/package/soapi-cli - npm.io page: https://npm.io/package/soapi-cli ## Dependencies (12) - [ajv](https://npm.io/package/ajv.md) ^6.10.0 - [lodash](https://npm.io/package/lodash.md) ^4.17.11 - [js-yaml](https://npm.io/package/js-yaml.md) ^3.13.1 - [request](https://npm.io/package/request.md) ^2.88.0 - [fs-extra](https://npm.io/package/fs-extra.md) ^7.0.1 - [mustache](https://npm.io/package/mustache.md) ^3.0.1 - [commander](https://npm.io/package/commander.md) ^2.20.0 - [cosmiconfig](https://npm.io/package/cosmiconfig.md) ^5.2.0 - [cross-fetch](https://npm.io/package/cross-fetch.md) ^3.0.4 - [formdata-node](https://npm.io/package/formdata-node.md) ^4.2.2 - [request-promise](https://npm.io/package/request-promise.md) ^4.2.4 - [@babel/preset-env](https://npm.io/package/@babel/preset-env.md) ^7.20.2 ## Recent versions - 2.4.0-beta.1 (latest) — 2025-05-26 - 2.3.0-beta.1 (beta) — 2024-12-10 - 2.3.0 — 2025-05-12 - 2.3.0-alpha.0 — 2025-05-12 - 2.2.1 — 2025-04-08 - 2.3.0-beta.0 — 2024-12-10 - 2.2.0 — 2024-11-22 - 2.2.0-beta.0 — 2024-10-24 - 2.1.1 — 2024-07-04 - 2.0.15 — 2024-07-04 - 2.1.0 — 2024-06-27 - 2.0.14 — 2024-06-27 - 2.0.13 — 2024-05-14 - 2.0.12 — 2024-01-23 - 2.0.11 — 2024-01-22 - … 151 more at https://npm.io/package/soapi-cli/versions ## README # soapi-cli 接口平台前端开发使用的 sdk 开发工具，用于将接口平台的 schema/route 自动化的生成前端 api 代码。 ## Install ```shell npm install soapi-cli ``` or use yarn ```shell yarn add soapi-cli ``` ## Usage ### Configuration 在项目目录下创建`.sdkrc.yml`或`.sdkrc.json`文件进行 sdk 配置 | field | type | default | description | | :------------- | :--------- | :------ | :------------------------------------------------------------ | | \*platform | `string` | - | 接口平台地址 | | \*output | `string` | - | 输出 sdk 的文件夹路径 | | node | `boolean` | `false` | 是否是 node 版本，node 版本 sdk 需要安装`node-fetch` | | \*applications | `object[]` | - | 需要生成 sdk 的接口平台应用，详细结构请看[下文](#application) | #### application | field | type | default | description | | :------ | :----- | :------ | :--------------- | | \*appId | number | - | 应用 id | | \*token | string | - | 应用的授权 token | #### example YAML 格式配置如下： ```yml platform: 'http://localhost:4003' output: src/apis/ node: true applications: - appId: 0 token: 'yourToken' ``` JSON 格式配置如下： ```json { "platform": "http://localhost:4003", "output": "src/apis/", "node": false, "applications": [ { "appId": 0, "token": "yourToken" } ] } ``` ### CLI | commander | description | | :---------------------- | :------------ | | `npx soapi-cli upgrade` | 生成/升级 sdk | | options | description | example | | :------------- | :--------------------- | :------------------------------ | | `--force` | 强制更新全部 API | `npx soapi-cli upgrade --force` | | `-h --help` | show help | `npx soapi-cli -h` | | `-v --version` | show soapi-cli version | `npx soapi-cli -v` | | `--debug` | 展示 debug 信息 | `npx soapi-cli --debug trace` | ### sdk 的使用方法 ```javascript import getArticle from 'sdk/appName.get.api.article' import app from 'sdk/appName' import { setEnv, checkSchema, catchError, } from '@soapi/middlewares' /** * 全局中间件配置 * 所有api接口调用时都会执行 */ app /** * 配置接口运行环境 * 不同的运行环境会调用不同的url * 各环境url配置请到接口平台，sdk插件中配置 * 如果使用中间件进行设置，则默认优先取SDK_ENV，其次取NODE_ENV * 如果无法取得有效值，默认为`prod`环境。 */ .use(setEnv(process.env.NODE_ENV)) .use(catchError(error => { console.log('what the fuck!') /** * 这里如果不抛出错误 * sdk会认为您已经将错误正确的处理，并将继续执行 * 这将导致sdk的api被调用时候，向外抛出的错误被中间件拦截并处理 * 调用的地方将无法得知错误的发生，并按照正常调用处理 */ throw error })) // use in saga try { /** * 根据文档平台定义和入参对象的key自动设置headers,body,query和params * 入参对象中未匹配到的key将会放入body对象中 */ yield getArticle({ articleId: 1 }) } cache (e) { // handle error } // 指定body,支持链式调用 yield getArticle().send({ articleId: 1 }) // 指定headers,支持链式调用 yield getArticle().set('Content-Type', 'application/json').set({ Token: 'token' }) // 指定query,支持链式调用 yield getArticle().query('pageSize', 10).query({ current: 1 }) // 指定params,支持链式调用 yield getArticle().params('id', 1).params({ pid: 1 }) ``` @soapi/middlewares 提供一些通用的 middleware，详见：。 ### 工作流程 ```flow start=>start: 开始 end=>end: 结束 checkPackage=>condition: 是否安装soapi-cli installPackage=>operation: 安装soapi-cli editConfig=>operation: 编辑配置文件 save=>operation: 保存配置 runCli=>operation: 运行cli checkField=>condition: CLI: 检查配置文件 checkApplicationSDKPlugin=>condition: 检查应用是否安装了sdk插件 alertInstalSDKPlugin=>operation: 警告“应用需要启动sdk服务插件，以配置应用的运行环境信息” downloadSDK=>subroutine: CLI: 下载sdk需要的应用信息(需要授权key和applicationId) 至output目录 importSDK=>operation: import 'output/appName.xxx.xxx' start->checkPackage(yes)->runCli checkPackage(no, bottom)->installPackage->editConfig editConfig->save save->runCli->checkField(no)->editConfig checkField(yes)->checkApplicationSDKPlugin(no)->alertInstalSDKPlugin->end checkApplicationSDKPlugin(yes)->downloadSDK->importSDK->end ``` ## 注意事项 1. **`sdk` 自动生成的代码依赖于`fetch`、`Symbol`，如果运行环境不支持，请添加相应的 polyfill。** 2. **`sdk`生成代码需要依赖 `sdk-service` 插件提供一些额外的配置信息。（如：不同环境的应用 url）请先在接口平台的应用中启动`SDK插件`** --- _Source: https://npm.io/package/soapi-cli · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._