bigo-frontend / blog

👨🏻‍💻👩🏻‍💻 bigo前端技术博客
https://juejin.cn/user/4450420286057022/posts
MIT License
129 stars 9 forks source link

【bigo】使用auto-service,拒绝any #47

Open Husbin opened 3 years ago

Husbin commented 3 years ago

背景

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

基于上述问题,解决方案如下:

使用auto-service,结合公司内部使用的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:

image-20210529182332880

生成结果:

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

image-20210529182631176

// 请求参数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的工作流程

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

程序启动运行报错

image-20210529180733246

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

"exclude": [
    "src/services"
]

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

引用

github

doc