使用auto-service，拒绝any

本文首发于：https://github.com/bigo-frontend/blog/ 欢迎关注、转载。

使用auto-service，拒绝any

背景

bigo brpc服务管理平台，是笔者首个基于react纯ts开发的项目。初期的时候，由于迭代较快，项目中有很多any类型的数据，主要是api request以及response data。any太多，一方面不规范，另一方面绕过校验，ts的优势也就不复存在了。

基于上述问题，解决方案如下：

使用auto-service，结合开源mock平台yapi，自动生成model。

auto-service简介

auto-service，可以根据 Swagger 或者 YApi 格式的接口文档（JSON）自动生成 TypeScript 格式的API调用代码以及接口request/response的类型定义。auto-service 依赖基于开源项目 Swagger Codegen 定制开发的 Java 生成工具，请确保已经安装 Java。

本文介绍的使用方式是结合yapi使用。

auto-service使用

安装

npm i -D auto-service

配置文件

新建配置文件json2service.json，token在yapi项目下的设置选项卡下获取

{
    "url": "yapi.json",
    "remoteUrl": "https://yapi.domain.com/api/open/plugin/export-full?type=json&pid=4232&status=all&token=xxxx",
    "type": "yapi"
}

新增生成命令

在package.json新增命令 :

"auto2ts": "autos -c json2service.json --clear"

-c filename 表示使用配置文件；
–clear 表示生成新产物之前清空旧产物；
–models 表示仅生产interface。

具体其他配置可以看文档介绍。

运行

npm run auto2ts

效果

样例API：

生成结果：

api请求参数的models，在api文件夹下，api返回数据的model，在model文件夹中。

// 请求参数model
// DefaultApi.ts

import ajax, { AjaxPromise, ExtraFetchParams } from "@ajax";
import * as models from "../model/models";

/**
 * @description apiV1AppSvrGet参数
 * @property `appName` 应用名
 * @property `[svrName]` 服务名
 */
export interface ParamsapiV1AppSvrGet {
  // queryParams
  /**
   * 应用名
   */
  appName: string;
  /**
   * 服务名
   */
  svrName?: string;
}

export class DefaultApi {
  /**
   * 
   * @summary 获取应用所有服务
   * @param params ParamsapiV1AppSvrGet
   * @returns models.ApiV1AppSvr
   */
  public apiV1AppSvrGet = (
    params: ParamsapiV1AppSvrGet,
    opt?: ExtraFetchParams
  ): AjaxPromise<models.ApiV1AppSvr> => {
   // fetch
  };
}

export default new DefaultApi();

// 返回数据model
//ApiV1AppSvr.ts
/**
 * @property `[status]` 1表示正常，非1请求错误
 * @property `[data]`
 */
export interface ApiV1AppSvr {
  /**
   * 1表示正常，非1请求错误
   */
  status?: number;
  data?: Array<models.ApiV1AppSvrData>;
}

//ApiV1AppSvrData.ts
/**
 * @property `appName` 应用名
 * @property `svrName` 服务名
 * @property `createTime` 创建时间
 * @property `creator` 创建人
 */
export interface ApiV1AppSvrData {
  /**
   * 应用名
   */
  appName: string;
  /**
   * 服务名
   */
  svrName: string;
  /**
   * 创建时间
   */
  createTime: string;
  /**
   * 创建人
   */
  creator: string;
}

auto-service的工作流程

yapi数据转化流程如下：

1. 根据yapi地址，下载yapi json；
2. 将yapi json 转化为swagger格式，启动express服务，将数据流暂存；
3. 下载swagger json数据流，与本地缓存数据进行diff对比，新起express服务供用户操作合并；
4. 用户操作结束之后，更新本地缓存数据；
5. 经过一系列校验，包括tags校验、风险校验后，写入临时文件；
6. 使用java命令，将临时文件中的swagger data，转化成typescript api以及models。

问题

忽略生成产物

因为我不直接使用产物，而是从中截取需要的部分，所以要忽略git追踪，具体修改.gitignore文件：新增/src/services。

程序启动运行报错

因为自身项目中的请求用了一些中间件，用于统一拦截请求与回复，所以auto-services生成的api，并不能直接拿来使用。生成的产物可能会导致项目运行报错，一方面可能是缺少依赖包，另一方面可能是json格式错误，或者eslint报错，因此需要在运行的时候绕过这个生成的文件夹。具体修改tsconfig.json，新增：

"exclude": [
    "src/services"
]

以上，如有错误，欢迎指正。

引用

github

doc

欢迎大家留言讨论，祝工作顺利、生活愉快！

我是bigo前端，下期见。