阎说 微信扫一扫
关注 阎说

Yanxi.me 热爱互联网和技术,喜欢探索的终身学习者

如何更高效的完成 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 质量和联调效率,小伙伴之间的合作也会更加和谐愉快。