从 Java 到 TS,阿里妈妈的接口管理一把梭

从 Java 到 TS,阿里妈妈的接口管理一把梭

这两天看到知乎上的:后端开发完接口才给出接口文档,合理吗?引起了不少的讨论,说起来这是前后端分离普及之后带来的一个新问题,阿里妈妈前端团队比较早在业务中全面使用单页应用,对接口管理有过一些探索和积累,最后搞出了一套贯穿【后端代码 -> 接口测试 ->接口文档 -> Mock -> 前端代码与类型】全开发流程的接口解决方案,在集团(6000+阿里开发者)和社区(1w+ stars)都有广泛的使用,这里再和大家分享一下~

前后端分离带来的变化

前后端分离其实意味着:项目的分离、开发周期的分离和开发人员的分离。

我们接到一个需求,开始项目排期,前端和后端分属两个人开发,产品经理打死也不会同意前端刷着知乎等到后端开发完接口、产出文档之后再介入开发,一定是双方并行开发最后再联调的。

在两不相见的之前,提前产出的一份接口约定可以说是必需的,不然很容易就促成联调驱动开发,项目进度一拖再拖的惨案。

除了一份接口文档,前后端分离后:

对于前端,我们需要一份准确的 Mock 数据,能够让项目摆脱后端独立运行;

对于后端,我们写起接口文档有点麻烦,最好能简化,需要能自行发起 API 请求测试接口可用性;

一次录入,多次使用,接口管理就是一把梭

我们用一个接口管理工具 Rap (rap2.taobao.org/) 来把这些需求一把梭解决,它大概长成下面这个样子:


Rap 可以按照团队、仓库、模块来管理细碎的接口,新建一个接口可以很轻松:表格编辑、JSON 导入,甚至是 Java 集成 Swagger 全自动导入,把写文档从一道简答题变成了填空选择题,一般经历过这一点点劳动之后,后面得到的就都是便利了:

  • Mock:Rap 会根据接口结构和 MockJS 的规则提供一个 Mock 接口,前端只要像请求线上真实接口一样请求到 Rap 就可以独立启动开发,Mock 数据可以根据规则灵活变化
  • 接口请求:录入的接口可以直接导出到 Postman,轻松完成接口测试
  • 离线文档:很多项目需要同时交付离线的接口文档,Rap 支持导出 docx 的文档,避免后序繁杂的工作
  • 更多功能可以去 rap2.taobao.org/ 体验一下

生成请求函数和 TypeScript 定义

在 TypeScript 兴起后,前端拥抱类型化已经是大势所趋,但是定义类型可是真的累到不行。

如果你使用 Rap 管理你的接口,配合 Rap 官方的一款工具 Rapper,就能帮你把接口的请求函数和类型信息自动生成,随时同步变更。

先在 Rap (rap2.taobao.org/) 建立一个仓库,在仓库里点击「生成 TS 代码」,按照步骤就可以把 Rapper 安装到项目中了

用了这货,连自己封装请求函数的步骤都省去了,直接传参调用就能拿到返回的 Promise,而且是富类型定义的,再也不怕地址写错、参数传错、返回值拿错,靠着 vscode 强大的类型提示一路点下去就行,每个字段的注释都显示得明明白白:

而且请求和返回类型可以直接复用于其他代码:

如果你用 React 和 Redux,Rapper 还有进阶的模式帮你生成接口相关套路明显的 action、reducer 代码,不用自己去处理 Redux 异步问题,帮你在全局缓存接口数据,还提供了时髦的 Hooks 取数。

import { useResponse } from 'model/rapper'  
const [responseData, { id, isPending, errorMessage }] = useResponse['GET/adgroup/price/update$']()

Rapper (github.com/thx/rapper) 的出现使这套体系完整贯穿了后端代码 -> 接口测试 ->接口文档 -> Mock -> 前端代码与类型的全开发流程,写得更少,做得更多了。

总结

回到最开始有关于编写接口文档的争论,实际上我们这些手段降低录入的工作量,并把接口数据尽可能地结构化管理,一份数据充分流转满足多方需求,当这个数据能服务于前端、后端乃至测试同学时,每个人都有足够的动力维护这份【文档】的准确,扯皮也就不存在了。

资料

对 Rap 感兴趣的朋友向下看 ️:

Rap 官方部署版本(托管了 10w+ 仓库):rap2.taobao.org/

Rap 同时也提供 Docker 私有部署,请移步仓库(欢迎留下star):github.com/thx/rap2-del

Rapper 仓库:github.com/thx/rapper

Rapper 文档:yuque.com/rap/rapper/re

Rap 钉钉服务群, Rap 的开发者都在这里:11789704

mux.alimama.com/ 可以了解到 MUX 的更多产品和用户体验相关的研究报告

编辑于 2020-04-03 21:35