npm package: @soapi/sdk
Description: 接口平台前端开发使用的 sdk 开发工具
Latest version: 1.0.27

# @soapi/sdk

<!-- description -->

接口平台前端开发使用的 sdk 开发工具，用于将接口平台的 schema/route 自动化的生成前端 api 代码。

<!-- description -->

## Install

```shell
npm install @soapi/sdk
```

or use yarn

```shell
yarn add @soapi/sdk
```

## Usage

<!-- 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        |
| \*key    | string | -       | 应用的授权 token |

#### example

YAML格式配置如下：

```yml
platform: 'http://localhost:4003'
output: src/apis/
node: true
applications:
  - appId: 0
    key: >-
      Bearer
      eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MCwibmFtZSI6InN5c3RlbSIsInJvbGVJZCI6MiwiaWF0IjoxNTYyODM1OTA4fQ._j_4GmEtjP3jJSdL2a6a2nMpM4AuD97oN5SlEkVzSR0
```

JSON格式配置如下：

```json
{
  "platform": "http://localhost:4003",
  "output": "",
  "node": "false",
  "applications": [
    {
      "appId": 0,
      "key": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MCwibmFtZSI6InN5c3RlbSIsInJvbGVJZCI6MiwiaWF0IjoxNTYyODM1OTA4fQ._j_4GmEtjP3jJSdL2a6a2nMpM4AuD97oN5SlEkVzSR0"
    }
  ]
}
```

### CLI

| commander         | description |
| :---------------- | :---------- |
| `npx sopai upgrade` | 生成/升级 sdk    |

| options        | description                             | example
| :------------- | :-------------------------------------- | :---
| `--force`      | 强制更新全部API                           | `npx soapi upgrade --force`
| `-h --help`    | show help                               | `npx soapi -h`
| `-v --version` | show @soapi/sdk cli version             | `npx soapi -v`

### 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 {
  yield getArticle({ articleId })
} cache (e) {
  // handle error
}
```

### 工作流程

```flow
start=>start: 开始
end=>end: 结束
checkPackage=>condition: 是否安装@soapi/sdk
installPackage=>operation: 安装@soapi/sdk
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
```

<!-- usage -->

<!-- supplement -->

## 注意事项

1. **`sdk` 自动生成的代码依赖于`fetch`、`Symbol`，如果运行环境不支持，请添加相应的 polyfill。**
2. **`sdk`生成代码需要依赖 `sdk-service` 插件提供一些额外的配置信息。（如：不同环境的应用 url）请先在接口平台的应用中启动`SDK插件`**

<!-- supplement -->