对内 DDD 对外 API 之—对外 API 的设计理念_对内接口和对外接口-优快云博客

2017年2月加入去哪儿网。目前专注于领域服务治理、基于API治理的领域能力标准化。致力于通过领域化、模型化、可感知来解决业务复杂度。期望用DDD驱动，降低系统复杂度，提升团队效能。

前言

对内 DDD，对外 API 是去哪儿网机票目的地事业群业务研发团队2020年 Q3 重点推出的业务重塑架构设计理念。在2020年 Q3，去哪儿网在过往的基础上，在 API 标准化这个领域做出了一些进步，这篇文章主要就是把这方面的经验和大家分享一下。

什么是对内 DDD，对外 API 呢，这个是我们业务研发领域内使用 DDD 作为领域设计、微服务设计的理念的实践原则，领域间使用 API 进行交互的一种通俗易懂的说法。

1 去哪儿网 API 发展的历史简述

去哪儿网在 API 领域其实有不少成熟的工具，常用主要包括 wiki、YAPI 和 swagger。

wiki 是去哪儿网最为传统的 API 承载工具，公司较早出现的公共平台，如支付中心，所提供的标准 API 就全部是通过 wiki 的方式呈现出来的。wiki 的优点是自由度相对较高，不受到各种规范的约束，修改也比较随意，可以非常个性化的去满足某些接口阅读者的诉求，天然的安全性较好，非公司内员工没有权限进行访问。缺点就要更多一些，例如因为没有一定的接口规范进行约束，接口的定义方式五花八门，有各种非常个性化的约定方式，相同的约定方式，呈现方式也不一样，有的倾向于给出嵌套式的呈现，有的则倾向于给出模块化的呈现，接口定义与接口之间的同步全部依赖规范和工程师的自觉，极易出现 wiki 与代码不匹配的情况。

正因为如此，我们可以说从提供 API 的角度看，wiki 可以提供可读性较好的 API 但是 wiki 不能提供可信、可靠的 API。

在去哪儿网起到支撑作用的第二个解决方案是 YAPI，YAPI 兴起的背景是从2016年开始的前后端分离架构。前后端分离使得前端工程变得更加独立。YAPI 也在2018年成为了去哪儿网的开源项目。YAPI 作为前端同学开发的接口平台直到现在仍然是去哪儿网 API 解决方案中的基石之一。YAPI 的作用用一句话来表述就是“共同维护一份接口定义，并连接前后端”。

YAPI 与 wiki 的区别可以用下图来表示：

从上图可以看出，YAPI 通过支持打桩测试这个抓手，通过运行 API 接口，测试能否得到预期中的结果来倒逼文档与接口定义一致。这个实现方式十分的巧妙，但是也十分依赖测试环境的完善以及对 API 测试的硬性要求，如果这两者得不到保障，那么这么巧妙的一个模式最终造成的结果仍然是接口与接口文档的分类和不同步。与用 wiki 差别不大，只是 YAPI 拥有着更加符合 RestFul API 规范的接口管理平台，这点与 wiki 相比对 API 的定义是一种约束。

为了防止接口定义与接口不同步（文档与代码不同步），后端同学引入了用于与代码使用 annotation 方式绑定在一起的 swagger，并且在 swagger 的基础之上做了一些基于 maven 的扩展，使得通过 swagger 编写的规范能够通过 maven 命令和发布等工程状态变化将接口的变化更新到 YAPI 平台，解决接口文档与接口实现不匹配的问题。

swagger -> YAPI 取得了一定的效果，但是因为使用 swagger 来编写 API 文档的工程比较少，并且少有人知道有 swagger -> YAPI 这个工具，使得 swagger -> YAPI 这种方式并没有在公司内部推广开来使用。