1、 个人介绍 李征 , 去哪儿网技术总监/业务研发技术委员会委员 去哪儿网机票C端前台服务负责人 持续专注于基于 API 治理的领域能力标准化、领域服 务治理、多租户理念的业务模型落地等工作。 致力于通过领域化、模型化、可感知来解决业务复杂问 题。期望以 DDD 领域驱动降低系统复杂度，提升团队 效能。 近期在BFF（服务于前端的后端）的实践思路中进行了 大量思考，希望推动业务服务接入简单化。 DDD落地之API文档化 让领域服务治理走向有迹可循 主讲人：李征 /去哪儿网 Qunar Engineering Director CONTENTS 目录 DDD启示录 为什么需要API 用DDD来设计
2、API API标准化在Qunar的落地 DDD启示录 DDD-启示录 DDD 启示录 DDD 启示录 领域模型边界表达 与可延续性 软件开发破窗效应 l脏代码 l测试 l没有测试 l混乱的测试代码 l难以测试 l混乱的源代码管理 l无序的部署方式 亚马逊：“超级API”公司 从今天起，所有的团队都要以服务接口的方式，提供数据 和各种功能 团队之间必须通过接口来通信。 不允许任何其他形式的互操作 p 不允许直接链接 p 不允许直接读其他团队的数据 p 不允许共享内存 p 不允许任何形式的后门 p 唯一许可的通信方式，就是通过网络调用服务 具体的实现技术不做规定 所有的服务接口，必须从一开始就以可
3、以公开作为设计导 向。 不遵守上面规定，就开除 没有例外API标准化的 要求 API标准化的作用 尤其重要的是，要明确一个团队只在单一的限界上下文中工 作，别给其他团队机会去修改你的源代码，从而引发意外，你的 团队控制着源代码和数据库并定义了官方API，必须通过这些API 才可以调用限界上下文，这是使用DDD所能带来的好处之一” - API是什么 服务能力的具体体现 领域间交互的契约 领域内分层定义的描述 领域模型的具象化表现 软件分析和设计经历了三个阶段的演进 第一阶段 单体架构 面向过程，数据驱动 第二阶段 集中式架构 面向对象，分层设计 2.5阶段 SOA与远程调用 通过传统SOA或远程
4、调用，实现初级的业务隔离，充分发挥康威定律。（大多在这个阶段） 第三阶段 分布式架构 采用领域驱动设计的方法，使用微服务架构模式 领域模型边界表达与可延续性 用DDD来设计API 思潮：API-first 从前 将来 用DDD设计API 领域接口化设计 经典案例 对于银行的 API 来说，账户就是一个领域对象（DDD 里的实体）。这次我们不再使用 CRUD 来为 账户建模，而是为账户定义一组业务操作。以下是一系列写入操作： 开户（Open）新开一个账户。 销户（Close）注销一个已有的账户。 取出（Debit）从账户里扣掉一些钱。 存入（Credit）往账户里存入一些钱。 在定义好业务操作之
5、后，就可以将它们与 REST API 映射起来： POST /account 新开一个账户。 PUT /account/close 注销一个已有的账户。 PUT /account/debit 从账户里扣掉一些钱。 PUT /account/credit 往账户里存入一些钱。 GET /account/通过账户 ID 加载相应的账户信息。 GET /account/transactions 列出账户的交易历史。 GET /accounts/query/customerId/列出指定客户的所有账户。 API在Qunar的落地 QDoc 落地 目标 所有的服务接口，必须从一开始就以可以公开作为设计导
6、向，没有例外 项目开发流程织入 文档版本化 文档代码一致性 效果 文档化 路线图 规范定义 工具审视 流程融入 感知到自然 规范定义 标准之争 一般的接口定 义规范 JavaDoc 适用于Java 一种文档过注 视方案 Wiki/Word 大多数在用 合同、协议使 用 OAS （OpenAPI- Specification） 标准的 语言无关的 RESTful API 接口 规范 工具审视 业界公认 可集成度高 Swagger 商业应用 有一定知名度 eolinker 开发常用工具 Workbanch方向发展 Postman Qunar开源项目YAPI Apifox smart-doc sho
7、wdoc Orion-API-Manager 其他 Qunar工具选择 - QDoc OAS（OpenApi-Specification） Qdoc 自研 研发流程织入 从感知到自然 代码自动化（Doc2Code) 流程融入 代码即文档 流程融入 发布流程集成 流程融入 PMO(JIRA)集成 代码自动化 Doc2Code 效率 风格 治理 监控/ 降级 落地 规范易用治理成熟度 API 成熟度 推进API产业化 确立API的核心地位 将API视为业务策略 有选择的开发 并确立API的 商业化战略 无计划的 开发 埃森哲API 成熟度模 型 API 成熟度 API架构的七 级 成熟度模型 级别7：API 作为业务 级别6：开放式 API 级别5：基于微服务架 构的私有API 级别4：面向服务的体系结构 级别3：基于组件的体系结构 级别2：非结构化集成 级别1：隔离的应用程序 终话 贝索斯：API宣言 从今天起，所有的团队都要以服务接口的方式， 提供数据和各种功能 团队之间必须通过接口来通信。 不允许任何其他形式的互操作 p 不允许直接链接 p 不允许直接读其他团队的数据 p 不允许共享内存 p 不允许任何形式的后门 p 唯一许可的通信方式，就是通过网络调用 服务 具体的实现技术不做规定 所有的服务接口，必须从一开始就以可以公开 作为设计导向。 不遵守上面规定，就开除 没有例 外
