前后端接口同步及类型映射流程解析

在开始介绍整个流程之前，我们先来从头捋一捋

1、面临的问题

常见的接口对接方式

日常开发中前后端同学协作的一个非常典型的场景：接口数据请求的调用、处理

以往都是以手动编写的方式来进行协作，但是这种方式所带来的关联性十分脆弱，服务端的代码或者文档出现变动，前端关联的接口代码就会面临出错、失效的问题。

另外在 TypeScript 火热的现在，为了能充分利用 TS 的类型能力来规范接口的字段类型，通常我们也会根据接口文档来编写接口的类型定义。

毕竟，类型定义完备情况下，配合编辑器的提示，真的是太香了！

那么，代价是什么呢？

实际开发中，每个接口都可能存在大量的字段，这个时候去照着接口文档搬运类型定义，不得不说是非常枯燥无聊的，更别说在搬运的过程中也有出错的可能。

所以问题我们总结为以下两点

• 以文档为媒介同步信息的关联性和约束性十分脆弱
• 枯燥耗时的接口类型补全工作

2、理论可行性的建立

OK，问题明确了，要如何去解决呢？首先我们要确立理论上的可行性。

还是上面提到的场景

后端常见的实现：Java、NodeJs

前端常见的实现： JavaScript

虽然前后端实现的语言可能存在区别，但对于接口的发布与使用来说，其实是一一对应的。

那么既然都是用来描述具体业务的，即使是实现语言不同，通过某种转换方式，将强类型语言后端字段自身的定义，传递到前端配合 TS 使用，完全是可能的。

通过理论上的探索，我们可以得到两个结论：

• 接口的发布与使用一一对应且存在一定的调用范式
• 强类型后端有数据字段类型的完备定义

以及我们的目标：

• 使用自动化任务来完成接口、类型的代码生成，达到前后端接口同步及类型映射的目的。

3、寻找相应的技术帮助实现

理论上的可行性确立了，我们还需要一些技术来帮助我们实现具体的功能：

3.1 OpenApi

首先是 OpenApi

OpenApi 规范定义了一个标准的、语言无关的RESTful API 接口规范

可以看到规范数据里会包含相应的接口信息及对象类型的定义，目的是为了通过一定的规范来覆盖不同语言实现的后端和不同终端的前端。

3.2 Swagger

另一个是 Swagger

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务

使用生态提供的相关工具，可以帮助我们更快达成目标（让后端同学配合）

3.3 mustache

最后是 mustache

使用模板语法 mustache 来帮助我们减轻代码生成的字符拼接工作。

4、工程化流程实践

接下来让我们充分利用上面提到的工具，去实现整个处理流程。

对每个步骤逐一做一下说明

4.1 服务端的变动

服务端以 NestJs 为例

4.2 得到的全量接口信息

OpenApi数据示例

4.3 通过解析工具来整合数据

解析整合数据

4.4 依靠nodejs的文件处理能力和mustache的模板预发，批量生成代码和类型定义

编写 mustache 模板，最终批量生成代码

生成代码示例

当完成接口及类型的代码生成后，就可以很好的利用编辑器和 TS 的能力，帮助我们提升开发效率和开发体验

5、业界的解决方案

上面的流程解析中，大部分可以很好的利用相关的生态工具来实现，只有其中的数据解析整合 + 代码生成的部分需要我们考虑是寻找已有的方案还是根据自己的项目去实现

以下是几种方案：

• swagger-api: Swagger 生态的代码生成工具，不过需要 java 运行环境
• Pont: 阿里的接口 swagger 对接方案，支持 vscode 插件，十分强大
• YAPI: 支持接口管理、MOCK等功能，代码生成需要 java 运行环境

通过整个流程的解析，相信不论是自己实现还是使用工具，都能非常好的帮助我们完成前后端的接口对接工作，效率和体验直线上升！

如果有什么建议或意见，欢迎交流！