DDD落地之API文档化

1.

2. 个人介绍 • 李征 , 去哪儿网技术总监/业务研发技术委员会委员 • 去哪儿网机票C端前台服务负责人 • 持续专注于基于 API 治理的领域能力标准化、领域服务治理、多租户理念的业务模型落地等工作。 • 致力于通过领域化、模型化、可感知来解决业务复杂问题。期望以 DDD 领域驱动降低系统复杂度，提升团队效能。 • 近期在BFF（服务于前端的后端）的实践思路中进行了大量思考，希望推动业务服务接入简单化。

3. DDD落地之API文档化让领域服务治理走向有迹可循主讲人：李征 /去哪儿网 Qunar Engineering Director

4. CONTENTS 目录 DDD启示录为什么需要API 用DDD来设计API API标准化在Qunar的落地

5. DDD启示录

6. DDD-启示录

7. DDD – 启示录

8. DDD – 启示录

9. 领域模型边界表达与可延续性

10. 软件开发~破窗效应 l脏代码 l测试 l没有测试 l混乱的测试代码 l难以测试 l混乱的源代码管理 l无序的部署方式

11. 亚马逊：“超级API”公司 Ø 从今天起，所有的团队都要以服务接口的方式，提供数据和各种功能 Ø 团队之间必须通过接口来通信。 Ø 不允许任何其他形式的互操作 p 不允许直接链接 p 不允许直接读其他团队的数据 p 不允许共享内存 p 不允许任何形式的后门 p 唯一许可的通信方式，就是通过网络调用服务 Ø 具体的实现技术不做规定 Ø 所有的服务接口，必须从一开始就以可以公开作为设计导向。 API标准化的要求 Ø 不遵守上面规定，就开除没有例外

12. API标准化的作用尤其重要的是，要明确一个团队只在单一的限界上下文中工作，别给其他团队机会去修改你的源代码，从而引发意外，你的团队控制着源代码和数据库并定义了官方API，必须通过这些API 才可以调用限界上下文，这是使用DDD所能带来的好处之一” -<领域驱动设计精粹>

13. API是什么服务能力的具体体现领域间交互的契约领域内分层定义的描述领域模型的具象化表现

14. 软件分析和设计经历了三个阶段的演进 • 单体架构第一阶段 • 面向过程，数据驱动 • 集中式架构第二阶段 • 面向对象，分层设计 2.5阶段 • SOA与远程调用 • 通过传统SOA或远程调用，实现初级的业务隔离，充分发挥康威定律。（大多在这个阶段） • 分布式架构第三阶段 • 采用领域驱动设计的方法，使用微服务架构模式

15. 领域模型边界表达与可延续性

16. 用DDD来设计API

17. 思潮：API-first 从前将来

18. 用DDD设计API – 领域接口化设计经典案例对于银行行行的 API 来说，账户就是一一个领域对象（DDD 里里里的实体）。这次我们不不再使用用 CRUD 来为账户建模，而而是为账户定义一一组业务操作。以下是一一系列列写入入操作： •开户（Open）——新开一一个账户。 •销户（Close）——注销一一个已有的账户。 •取出（Debit）——从账户里里里扣掉一一些钱。在定义好业务操作之后，就可以将它们与 REST API 映射起来： •存入入（Credit）——往账户里里里存入入一一些钱。 •POST /account ——新开一一个账户。 •PUT /account/close ——注销一一个已有的账户。 •PUT /account/debit ——从账户里里里扣掉一一些钱。 •PUT /account/credit ——往账户里里里存入入一一些钱。 •GET /account/——通过账户 ID 加载相应的账户信息。 •GET /account/transactions ——列列出账户的交易易历史。 •GET /accounts/query/customerId/——列列出指定客户的所有账户。

19. API在Qunar的落地 QDoc

20. 落地 – 目标所有的服务接口，必须从一开始就以可以公开作为设计导向，没有例外项目开发流程织入文档版本化文档代码一致性

21. 效果

22. 文档化 – 路线图感知到自然流程融入工具审视规范定义

23. 规范定义 – 标准之争一般的接口定义规范 JavaDoc • 适用于Java • 一种文档过注视方案 Wiki/Word OAS （OpenAPI- Specification） • 大多数在用 • 合同、协议使用 • 标准的 • 语言无关的 • RESTful API 接口规范

24. 工具审视 Swagger eolinker Postman YAPI 其他 • • • • • • 业界公认可集成度高商业应用有一定知名度开发常用工具 Workbanch方向发展 • • • • • Qunar开源项目 Apifox smart-doc showdoc Orion-API-Manager

25. Qunar工具选择 - QDoc OAS（OpenApi-Specification） Qdoc – 自研研发流程织入从感知到自然代码自动化（Doc2Code)

26. 流程融入 – 代码即文档

27. 流程融入 – 发布流程集成

28. 流程融入 – PMO(JIRA)集成

29. 代码自动化 – Doc2Code 效率风格治理监控/ 降级

30. 落地规范易用治理成熟度

31. API – 成熟度推进API产业化确立API的核心地位埃森哲API 成熟度模型将API视为业务策略有选择的开发并确立API的商业化战略无计划的开发

32. API – 成熟度级别7：API 作为业务 API架构的七级成熟度模型级别6：开放式 API 级别5：基于微服务架构的私有API 级别4：面向服务的体系结构级别3：基于组件的体系结构级别2：非结构化集成级别1：隔离的应用程序

33. 终话

34. 贝索斯：API宣言 Ø 从今天起，所有的团队都要以服务接口的方式，提供数据和各种功能 Ø 团队之间必须通过接口来通信。 Ø 不允许任何其他形式的互操作 p 不允许直接链接 p 不允许直接读其他团队的数据 p 不允许共享内存 p 不允许任何形式的后门 p 唯一许可的通信方式，就是通过网络调用服务 Ø 具体的实现技术不做规定 Ø 所有的服务接口，必须从一开始就以可以公开作为设计导向。没有例外 Ø 不遵守上面规定，就开除

35.