如何更高效的完成 API 联调

在日常开发工作中，离不开各种联调工作，包括 Web 前后端联调、后端服务之间的联调。API 是应用程序之间沟通的桥梁，联调则是 API 提供者和 API 使用者一起完成这座桥梁安装和调试的过程。联调工作不是一个人能独立搞定的，需要和其他开发人员、其他团队，甚至其他公司一起来合作完成。

正因为 API 联调是需要彼此合作的才能完成的工作，往往会花费大量的时间。使用方经常会抱怨服务提供方 API 不够合理，bug 较多，不够稳定；服务提供方又会觉得是使用方的姿势不对所导致。因此联调过程往往会反反复复，耗费大量的沟通成本。

如何提高 API 联调效率，让调用双方都能更加顺畅的完成联调呢？下面分别从 API 提供者和 API 使用者两方面来说一下我的几点经验。

对于 API 提供者

联调不顺畅、效率低，绝大部分情况都是因为 API 的质量不高导致的反复修改。下面我逐一列出 API 设计者需要注意的几个地方，并给出相应的解决方案。

1. 设计合理的 API，并形成文档
2. 重视对错误的处理
3. 对 API 充分的自测
4. 提供 API 调用示例

设计合理的 API，并形成文档

API 文档不仅仅是给使用者看的，对于 API 提供者来说也非常重要，相当于是你要实现服务的总目录。因此，我建议在明确业务需求后，具体的开发之前，就要从 API 文档入手开始设计 API。在 API 文档中一般要明确：

• 需要实现哪些 API，各自有什么功能
• 每个 API 的请求参数有哪些
• 每个 API 在正常情况下的响应格式
• 每个 API 在出错时的响应格式，会出现哪些异常

至于如何生成文档，可以通过编辑 wiki 的方式，比如使用 confluence，我个人则更倾向于通过工具来生成文档，工具的好处是定义文档更方便快捷，并且对测试更友好。

比如，如果是基于 Restful 的 API，推荐使用 swagger 来生成文档，swagger 生成的文档可以直接通过网页来完成 API 的测试，还可以方便的生成不同语言的 code。如果后台基于 gRPC 服务，则可以直接用 protobuf 定义作为文档，使用者可以方便的理解，也可以方便的生成客户端代码。如果采用 dubbo 服务，则直接写 java 接口，通过 javadoc 生成文档即可。

重视对错误的处理

错误分为两类：一类是可预期的错误，对这类错误需要分门别类，给出各自的错误码，方便使用者来做处理。另一类是未预料到的错误，一般会通过某个地方集中捕捉（比如 Filter, Interceptor, Middleware 等，不同语言和框架叫法不同，但原理一致)，对这类错误可以设置一个特殊的错误码，并给出具体的错误信息。

针对第二类（未预料到的）错误，提供的错误信息越具体越有利于后续的问题查找。有一个情况例外，就是如果接口可以在外网直接访问到，则不要提供具体的出错信息。针对这种情况可以在接口中加一个 debug 字段，只有在测试环境中才显示。比如：

// 测试环境包含 debug 信息
{
    "success": false,
    "debug": "xxxxx"
}

// 生成环境无 debug 信息
{
    "success": false,
}

无论针对以上哪种错误，都需要 记录错误日志，以备后续的错误定位和分析。

推荐在 API 调用链路中加入 traceId，同一个请求经过的所有链路中都记录 traceId，这对于后续的问题定位帮助很大，debug 信息里可以加入 tranceId，这样服务使用者可以很方便的将出错的 traceId 告诉服务提供者。

充分的自测

在给到下游使用者之前，API 开发者必须做充分的自测，测试范围需要覆盖文档中列出的全部 API。如果只做了部分 API 逻辑的修复和更新，则需要测试相关的 API。

对于 Restful API，可以采用：

• 直接使用 curl 来测试
• 使用 Postman
• 通过 .http 的文件，在 IntelliJ IDEA 和 VS Code(需要安装 REST Client 插件) 中都可以方便的执行示例

对于 RPC 调用，一般需要通过编写客户端代码来完成 API 的自测。

提供 API 调用示例

需要给出详细的调用示例，而不仅是笼统的给出哪些参数。比如针对 Restful API，需要指定 Http method，是 get 还是 post, put, …；必要的 Header 信息，比如 Context-Type 是 application/x-www-form-urlencoded 还是 application/json, 这些微小的细节有时候会在联调中造成较大困扰，拉长整体联调的时间。

API 调用示例，可以采用下面几种方式：

• 直接导出 Postman 里的调用示例
• 提供 curl 调用示例
• 提供 .http 文件示例
• 客户端调用代码示例

对于 API 使用者

API 使用者在联调过程中，直接看 API 文档和调用示例即可，这比反复的和 API 提供者沟通要节省时间。

在调试中遇到错误，可以对比示例中的调用方法和你的调用方法有哪些异同。如果在示例调用中换成你的参数后，响应是正常的，则说明是使用者这边的问题。通过比较示例请求和你的请求之间的细节差异，就能比较容易的找到问题所在了。

如果按照示例调用的方式仍出现错误，将完整的请求和响应信息给到 API 提供者，方便他们重现错误。有了完整的调用信息，API 提供者也可以比较方便的根据相关的 debug 信息，或者 traceId 信息查询相关的日志来快速定位问题。

结束

以上是关于提高 API 联调效率的几条小建议。相信只要做到以上几点，就可以大幅度提高 API 质量和联调效率，小伙伴之间的合作也会更加和谐愉快。