概要

此文章基于去哪儿网-李征在”API文档化让服务治理走向有迹可循”的演讲后做的个人总结。

一、目录结构

DDD启示录

为什么需要API

用DDD来设计API

API标准化在Qunar的落地

总结

二、演讲逻辑

首先说业务，然后说现阶段模式，接着说出现的问题/痛点与改进方式，达到一种什么效果，再接着说出现的问题/痛点(前面的流程线:循环渐进的说)，最后做总结。

细致入微，把某个点说透，让别人知道架构怎么演进，而不是只是让别人觉得自己公司的架构很牛，而不能实现落地。

API文档痛点

几乎每个版本的变更几乎都需要各方之间的联调，联调的基础就是接口。

接口安全案例:

领域内的接口其实并不希望暴露给领域外，联调的时候把作用域暴露出去了，提前不清楚，联调方说此接口的QPS要到达3000以上，但这个接口承受不了，幸亏落地之前发现了。

接口的开发能力，是否对外可见还是不可见，是接口定义的一个不可或缺的一个点。

实际上，代码只能表现出逻辑本身，但翻代码的人还是程序员本身。

真正让领域模型的能力开发出来，让大家能够知晓，做业务的时候对能力有一定的感知，这个文档是不可少的。

起初，一个项目的文档散落在十几处，比如Wiki、Word、代码里、群里直接扔了JSON的上下文，但这个不超过一周就不知道是啥了

文档化、标准在DDD的过程中是非常重要的一环，对每个人都是一个痛点。

DDD启示录

DDD混淆的概念:能力和功能，真正用DDD设计出来的API是领域模型对外提供的能力，而不是功能。

整合模型和分层架构。

接口都是对外端口的一种表现。

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

API是领域模型边界表达与可延续性表达

被重构的周期越来越短。

以前的系统可能跑七八年，现在的系统可能跑三四年，项目结构可能就不适合了，这也是由于业务的发展变化造成的。

现在的整体的代码复杂度，以及相关的破窗效应会使上升效应特别快。

API标准化

做API的期初受到他的影响。

DDD模型在被优化和提炼的，怎么后面变为可持续性和发展呢？API标准化来做这件事情。

再看DDD思想的时候，界限的描述和API的描述是有明确的方式方法和方向的。

API对外开放的能力而不是功能。

能力是模型自身的体现，而功能可能是描述某一次需求或业务，能力有一定的延续性。

规约:一定的约束性、延续性和不变性的。一定程度中，保持一定的稳定。

领域内的分层定义，也是一种API的体现，比如接口安全，是否暴露给外部。

具象化:文档化。能力抽象化，相应的案例、参数、场景，理解会有一定的门槛，通过能力/API，完全可以反过来理解领域本身是什么。

上图表示，经历了什么，导致软件复杂度的变化。

标准化场景，是将来需要探讨的一个方向。

用API的稳定性和可延续性来表达模型的稳定性和可延续性。

没有不变的模型，一定要有核心稳定的模型。

用DDD设计API

API-first。现有API再有能力。

拿什么来驱动API？考虑的方式。

大部分人采用的API设计方式为restfulAPI。

核心思想:一切皆资源。

在做API标准 的过程中，认为的API一定是能力，而不是资源。

在一切皆资源的方式，在做API标准 的过程中，可能不太推崇。

对外接口都是能力的体现，而不是资源实现。

经典案例

虽然跟restful差不多，但核心是能力作为核心的输出。

动作/动词都是一个能力。

API在Qunar的落地:QDoc

重点是一定要有项目开发流程的织入。

从软件过程中融入进去，变成会自然的事情，就会更加简单。

模型是在变化的，体系变化了一定版本。

文档和代码不一致，那么文档就没啥用。

同一个文档的变化要能体现出来。

规范是不可或缺的。

规范是整体落地十分重要的一方面。

完整主动的规范是一个可描述自身的、完备的规范。总的来说，是很放心的一个事情。

要有工具支撑，否则过程很复杂。

软件开发过程中织入，简化开发过程。

文档给大家带来帮助，而不是给大家带来更多的困扰。

各种协议的公共抽象出来，但是还有一些差异。

业界有一个相对完整的描述，openapi。

Openapi本身是swagger前身的那些东西，正好赶上openapi3.0的发布，对整个评估来看，是整个标准的规范化、最全、可落地的方式。

通过openapi的方式来落地，openapi是这里对文档最终的一个文档描述，接入形式并不一定是openapi本身，也可以用javadoc、其他的方式来做文档的描述，但最终生成的文档一定是符合openapi规范的。

Openapi是最终落地到存储到核心的可描述的文档。那么用什么工具来描述文档，是跟效率挂钩的。

自己做的工具。

跟大量内部流程的对接。选择自研的方案。

如果以后逐渐提炼可拆解，那么也会考虑开源的事情。

真正做到API标准化后，可以发现调用、代码生成变得非常简单。

大家在调接口的时候，大部分在沟通接口怎么来使用，如果有标准文档的话，那么可以变成自动化的方式。

如何保证代码和文档的一致性。

做了一套annotation，标准是一定的，但是需要一定的扩展，有扩展性，得提供一系列工具来描述这些扩展性。原始的OS定义可能留了很多扩展性出来，并没有在内部有定义。这套描述话，只是把这套定义描述下来。这样的话，写代码的时候，文档就保存下来了。

做了几件事，从对象里抽取该有的对象有哪些。

把QDOC工具抽取到OS中去，尽量简化在二次写文档，历史代码怎么接入的问题。

文档应该有发布的过程的，

比如草稿-上线-发布，应该跟代码的发布流程是一个一致的流程。

虽然说文档是不需要测试的，但是在文档的迭代过程中，应该有不同的版本，不同版本之间是由功能上线导致文档的变化，是有一个使用的过程的。

文档变成一个可发布的流程，CICD的发布流程。

工具化的落地，包括很多流程的集成。

在批次发布的过程中，会把当前需求变更的文档都放出来，会把当次变更的、可用的文档是什么展示出来，测试也简单，这些变更的肯定是变动范围，测试就不会再问开发了，接口都变了哪些，回归过程也都知道了。

文档自动化后，可发现衔接对接的过程是非常容易的事情了。

通过什么方式，可以让在调用的过程中不用太去关心底层是怎么做的。

对使用极大的提升。新入职的怎么根据公司的规范来做衔接。

对于API文档来讲，将来也要有一个成熟度模型的。

PMP、CMI。

当软件方法到一个阶段之后，怎么评估它的影响力，是否做到了，是应该有迹可循的，而不是每个人一套标准，而应该是有一个模型来描述它，给大家一定的指引，做一个能力的迭代。

亚马逊等云厂商是一家”API公司”，他们都有一套对外提供API的能力。

实际上对API的治理也应该是这么一个方向。

上述两个模型是否适合当下的模型，还在考虑当中。