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

前后端分离带来的变化

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

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

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

除了一份接口文档，前后端分离后：

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

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

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

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

Rap 可以按照团队、仓库、模块来管理细碎的接口，新建一个接口可以很轻松：表格编辑、JSON 导入，甚至是 Java 集成 Swagger 全自动导入，把写文档从一道简答题变成了填空选择题，一般经历过这一点点劳动之后，后面得到的就都是便利了：Mock：Rap 会根据接口结构和 MockJS 的规则提供一个 Mock 接口，前端只要像请求线上真实接口一样请求到 Rap 就可以独立启动开发，Mock 数据可以根据规则灵活变化

接口请求：录入的接口可以直接导出到 Postman，轻松完成接口测试

离线文档：很多项目需要同时交付离线的接口文档，Rap 支持导出 docx 的文档，避免后序繁杂的工作

生成请求函数和 TypeScript 定义

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

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

先在 Rap (http://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 (https://github.com/thx/rapper) 的出现使这套体系完整贯穿了后端代码 -> 接口测试 ->接口文档 -> Mock -> 前端代码与类型的全开发流程，写得更少，做得更多了。

总结

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

资料

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

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

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

Rap 钉钉服务群， Rap 的开发者都在这里：11789704

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