@soapi/sdk

@soapi/sdk

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

Install

npm install @soapi/sdk

or use yarn

yarn add @soapi/sdk

Usage

Configuration

在项目目录下创建.sdkrc.yml文件进行 sdk 配置

field	type	default	description
*platform	string	-	接口平台地址
*output	string	-	输出 sdk 的文件夹路径
node	boolean	false	是否是 node 版本，node 版本 sdk 需要安装node-fetch
target	es3 or es5 or es6 or esnext or ts	esnext	指定 ECMAScript 目标版本
module	commonjs or es6 or esnext or amd or umd or System	指定生成哪个模块系统代码
*applications	object[]	-	需要生成 sdk 的接口平台应用，详细结构请看下文

application

field	type	default	description
*id	number	-	应用 id
*key	string	-	应用的授权 key

CLI

commander	description
npx sdk init	生成 sdk
npx sdk upgrade	升级 sdk

options	description
--key	应用授权 key（需在接口平台申请）
--platform	接口平台地址
--output	sdk 输出文件存储路径
--module	输出文件格式[es2015, esnext, amd, umd]
--target	输出文件格式[es3, es5, es6, esnext, ts]
-h --help	show help
-v --version	show @soapi/sdk cli version

sdk 的使用方法

import article from 'sdk/www.xxx.com.8080.api.article'
// 如何兼容路径参数
// import comment from 'sdk/www.xxx.com.8080.api.article.:articleId.comment'
import * as api from 'sdk/appName.api'
import articleApi from 'sdk/appName.api.article'
import * as sdk from 'sdk'
import { apply } from '@soapi/sdk'
import {
  envSetter,
  ajvChecker,
  errorCatcher,
  headerSetter,
} from '@soapi/middlewares'


/**
 * 全局中间件配置
 * 所有api接口调用时都会执行
 */
apply(sdk)
  /**
   * 配置接口运行环境
   * 不同的运行环境会调用不同的url
   * 各环境url配置请到接口平台，sdk插件中配置
   */
  .use(envSetter(process.env.NODE_ENV))
  .use(errorCatcher(error => {
    console.log('what the fuck!')

    /**
     * 这里如果不抛出错误
     * sdk会认为您已经将错误正确的处理，并将继续执行
     * 这将导致sdk的api被调用时候，向外抛出的错误被中间件拦截并处理
     * 调用的地方将无法得知错误的发生，并按照正常调用处理
     */
    throw error
  }))

/**
 * 局部中间件
 * 仅当apiName/api域下的api被调用时执行
 */
apply(api)
  .use(headerSetter('lang', 'jp'))

// use in saga
try {
  yield articleApi({ articleId, commentId })
} cache (e) {
  // handle error
}

工作流程

start=>start: 开始
end=>end: 结束
checkPackage=>condition: 是否安装
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

注意事项

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