阅读 1502

为了偷懒,我们做了Yapi生成Typescript接口请求工具

在使用swagger时:

我:“接口文档啥时候能给到?我页面写好了,就差接口对接,明天都明天提测了~~”

后端:“我们用的swagger,需要我先把接口写完才能给你”

我:“😭”

使用yapi之后:

后端:“我接口写完了,啥时候来联调?”

我:“我已经对接完丢test了,你上test环境看看就行🐶”

​ 最近为了走协议先行的开发模式,加快开发效率。后端的API文档从swagger迁移到yapi,所以抛弃了之前一直使用的Pont。因为懒得每次都手写接口请求方法和接口的声明文件🐶,实现了从Yapi中生成Typescript的全局包工具。同时提供了vscode插件版本。

整体思路

​ 要实现接口自动生成,首先我们需要确定一个最小的生成细粒度,例如是支持当个接口的生成?还是当个分类的生成?这里我按照分组项目模块 对Yapi进行了3层的划分,然后确定最小细粒度到模块那个层面。因为我们在项目开发时,一般一个迭代会有多个接口,所以如果细粒度到接口层面其实非必要而且操作也会更加繁琐。

想要实现的功能

  1. 根据权限拉取Yapi接口列表

  2. 自动生成声明文件

  3. 声明可以方便的在项目中使用

  4. 自动生成接口请求文件

  5. 方便的使用mock

  6. 方便的进行接口diff对比

主要流程

process

鉴权

​ 拉取Yapi接口时,我们需要通过Token或者账号密码来进行鉴权,这里我选择的是账号密码。为什么使用账号密码登录,为什么不用token?在Yapi中有提供Token的机制,让我们可以方便的拉取到某个API项目中的所有接口。但是这里有个局限,我们一个工程中可能需要用到多个API项目,而且基于权限考虑可能不会把Token给到所有人。所以这里我采用了账号密码登录,这样可以实现一套账号密码运用于不同的项目,同时也能够适配Yapi中的权限管理。

多API服务支持

​ 在现在微服务盛行的环境下,一个前端项目同时调用多个Api域名是很常见的事情了。所以在配置时通过projectMapping这个字段来根据不同的项目Id来区分不同的请求方法,示范的配置如下,具体可以查看底部的详细配置

projectMapping: {
    ProjectId: {
      // 请求方法名
      exportName: 'Api',
      // 返回报文泛式
      wrapper: '{ code: string, message: string, data: T }',
    },
 }
复制代码

Mock

​ 因为Yapi中已经集成了Mock,所以在这里我们需要充分的利用起来🐶当需求开发时,只需要将请求的URL改写到对应Mock地址就行了

image-20210707180839373

​ 在生成的接口请求方法中,最后一位参数为isMock。当后端接口没出时,直接传入true既可开启mock

image-20210707181531923

Diff

​ 这个功能其实是从Pont来的灵感。当接口变更时,如果后端没有通知到位的话,其实我们并不知道接口变更了。那么就会有存在请求时入参出参错误的问题。所以在实现工具时,在生成代码的时候记录了下每个接口的最后修改时间,通过最后更新时间判断接口是否变更。可以方便的定位到有接口变更的模块,快速生成

image-20210707182242065

使用说明

Y2T提供了2种使用形式:

  1. 全局包:使用npm install -g y2t全局安装即可

  2. vscode插件:在插件市场搜索y2t,安装即可

    这里更推荐使用vscode插件,因为可以跟着插件版本号升级自动升级,而不需要每次更新后重新安装全局包

全局包使用方式

使用说明

// 生成默认配置
$ y2t -i
// 根据项目修改配置后
$ y2t -g
复制代码

完整功能列表

$ y2t --help
Options:
  -v, --version   获取当前版本
  -i, --init      初始化配置文件
  -g, --generate  生成接口文档
  -r, --remove    移除缓存
  -d, --diff      当前项目Diff
复制代码
  • -v, --version:获取包的版本号
  • -i, --init:初始化配置文件,会放在项目当前执行目录下的ygt.config.js
  • -g, --generate:根据配置生成接口文件,当没有配置时会初始化默认配置
  • -r, --remove:根据移除本地缓存,主要用于当本地文件变更时,diff失败时重置
  • -d, --diff:根据本地缓存进行接口对比,获取更新的模块

vscode插件使用方式

功能入口

插件安装完成后,会在 Vs Code 底部工具栏新增WorkY2TY2T-DIFF按钮

Snipaste_2021-08-04_16-07-56

工作区划分 Work

考虑到各人开发习惯不同,当使用多工作区开发时可以通过Work选择你需要生成的工作区

生成配置文件

首次打开工具栏中的Y2T按钮会提示没有配置文件,可以选择默认生成,会在项目中生成ygt.config.js文件

接口生成 Y2T

配置好ygt.config.js后,再次点击Y2T按钮。顶部会出现弹窗以此选择需要生成的分组项目模块既可。

image-20210804160939489

接口对比 Y2T-DIFF

生成 api 完毕后y2t会在vscode中基于workspace储存缓存, 点击Y2T-DIFF按钮,弹出检测API是否更新清除API工作区缓存

``检测API是否更新`:可以进行检测 api 接口是否有更新, 如果有的话会进行询问,按照个人需求选择更新与否

清除API工作区缓存:则可以进行清除缓存,主要用于本地缓存紊乱时的状态恢复

image-20210804161024614

详细配置

示范配置:

module.exports = {
  // 账号
  account: 'xxxxx@xxx.cn',
  // 密码
  password: 'xxxxx',
  // Yapi网址链接
  originUrl: 'https://yapi.xxx.cn/',
  // 请求声明模块
  fetchModule: 'import { AxiosPromise as RequestPromise , AxiosRequestConfig as RequestConfig } from "axios";',
  // 输出目录
  outDir: './src/apis',
  // 项目跟请求方法映射
  projectMapping: {
    537: {
      exportName: 'crmApi',
      // 返回报文泛式
      wrapper: '{ code: string, message: string, data: T }',
    },
  },
  // 请求体实例文件路径
  requestFilePath: 'src/utils/http',
  // 忽略ts校验
  tsIgnore: true,
  // 忽略eslint
  esLintIgnore: true
};
复制代码

配置具体说明

  • account:账号,这里不使用yapi的token主要有两个原因:
    1. 为了能够根据账号进行yapi的权限区分
    2. token只能获取到项目级别,无法进行分组级别的筛选
  • password:密码
  • originUrl:Yapi 网址地址
  • outDir:输出目录,相对于当前工作区的根目录
  • fetchModule:请求方法声明模块,这里主要是防止对axios进行了二次封装的场景下可以正确定义
  • projectMapping:项目映射。在微服务盛行的现在一个工程中可能会有多个 api 地址,所以这里按照项目id进行了请求方法映射。
    • projectId:项目 ID,例如url:xxx.xxx.com/project/216…
    • exportName:请求方法名称,为了兼容不同的请求库,所以生成的代码中不会直接生成 ajax 请求方法,需要外部传入,这里的exportName一般就是你配置好了的axios实例
    • wrapper:默认的返回体,如果接口有默认的返回包体时,可以通过wrapper定义 response,其中T代表返回的具体 data
  • requestFilePath:请求方法的文件路径,也就是封装axios请求方法的文件路径,这里最好使用@别名或者src等相对路径
  • tsIgnore:是否开启tslint忽略
  • esLintIgnore:是否开启esLintIgnore忽略

项目地址

最后附上项目地址:github.com/SewerKing/y…

文章分类
前端
文章标签