对内 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 这种方式并没有在公司内部推广开来使用。

2 去哪儿网推进 API 标准化建设的原因

2020年因为疫情的原因，去哪儿网开始了轰轰烈烈的“练内功”行动，这其中就包括核心业务领域的业务 DDD 重塑、硬件成本节约、API 内部实现重构等。

做这几件事情的时候我们面临了一些困难：

1、DDD 重构需要与领域外通过接口进行调用，那么一个领域与外部领域之间提供多少接口比较合适呢？10个？30个？50个？如果提供的 API 过多，是否意味着 API 不够标准，质量不够高呢？

2、硬件成本中包括实体机&虚拟机节点成本和离线日志、实时日志成本，那么实体机虚拟机节点多少是比较合适的？系统的离线日志、实时日志产出多少又是合适的？这部分很依赖系统 API 的数量以及 API 访问量的提供。

3、API 内部功能重构后，哪些下游访问了这个 API？在使用诸如 QueryDiff 等工具对接口本身进行回归之后，出于保险起见需要对哪些下游系统进行回归测试呢？这方面就很依赖于 API 的上下游关系的治理，而想实现基于治理结果的自动化测试则依赖 API 的标准化。

通过上面几个例子我们看到，API 重新成为重要的技术改进点是整体上对内 DDD，对外 API 系统架构理念的需要，是硬件成本管理的需要，是平台化服务重构的需要。

3 API 标准化的理论基础

API 标准化的理论基础来自于 Jeff Bezos 2002年提出的系统间接口化理念，后续这个理念被逐步充实成为了一种