对内 DDD 对外 API 之—对外 API 的设计理念，为什么spring能最好地改变Java

本文链接：https://blog.csdn.net/m0_59117112/article/details/136923381

规范术语后，我们开始制定与术语相对应的注解和注释，一期我们先规范了对应的注解：

领域（@QDomainDoc）

应用（@QAppcodeDoc）服务（@QServiceDoc）接口（@QInterfaceDoc）这里面存在参数注解和返回值是否可以删除参数（@QParamDocs）

参数（@QParamDoc） Model参数（@QParamModel） Model属性的注解（@QParamModelProperty）类型（@QTypeDoc）等同于 @RequestParam。目前未实现，后续支持返回值状态码的描述（@QResponses) 返回值状态码的描述（@QResponse) 返回值数据描述说明返回值数据（@QResponseDocs) 返回值数据（@QResponseDoc) 异常（@QExceptionDoc）扩展（@QExtensionDoc）

相应的每一个注解我们也都会给出对应 annotation 参数使用说明：

服务（@QServiceDoc）描述 service 的用途：

对内 DDD 对外 API 之—对外 API 的设计理念

大家可以看到，QDoc 给出的规范术语和 annotation 充分考虑到了去哪儿同学通常使用的工程上下文语境，例如 Domain、AppCode，都是去哪儿网工程语境中的常用词汇，一看到这些词就能想到是做什么用的，这些贴近工程师常用词汇的术语使得工程师对于 QDoc 规范的理解很顺畅，不需要看大段的说明就可以理解个大概，学习成本低，上手使用很快。这点是去哪儿网制定的规范与 swagger2.0，swagger3.0，smart-doc 等第三方 API 工具的很主要的区别，也是我们在支持 OpenAPI3.0 规范的前提下，采用自定义 API 术语的一个很重要的原因。

当完成了基于 annotation 的 API 规范化组件定义后，下一步就是对应工具、插件的开发以及工具的接入工作。

4.2 组件易接入

=========

QDoc 为了方便业务线工程师的接入，最大限度的不让业务线开发工程师再接入 QDoc 的过程中有额外的开发量，采用了 jar 包加 maven 插件的方式，接入步骤十分简单：

服务接入步骤

接入 qdoc 服务需要在 pom 中引入对应的 maven 插件，来完成 qdoc 的发布；
如需采用 Annotation 方式撰写 API 文档，则，需要 qdoc-annotation 包以便完成编写；
具体依赖引入：（Maven Plugin)

com.qunar.fd

qdoc-maven-plugin

${qdoc.maven.version}

QDoc Annotation

com.qunar.fd

qdoc-annotation

${qdoc.annotation.version}

provided

复制代码

4.3 语法易使用

=========

QDoc 的语法分为两部分：一部分是 git 工程侧语法，一部分是代码 API 侧语法，两部分共同构成了去哪儿网标准化的 API。

Git 工程侧语法如下，QDomainDoc 和 QAppcodeDoc 都采用这种方式进行应用。

对内 DDD 对外 API 之—对外 API 的设计理念

除 QDomainDoc 和 QAppcodeDoc 外的其他注解与 API 代码结合但非入侵式应用：

@QInterfaceDoc(

type = “dubbo”,

define = “给用户发送短信验证码,dubbo接口”,

desc = “校验手机号是否为用户所有,给用户发送短信验证码”,

scene = “给用户发送短信验证码”,

notice = “内网使用”,

since = “发送短信验证码,产品需求引入”,

authors = “fanrong.zhao”,

url = “dubbo_send”

)

@QParamDocs({

@QParamDoc(name = “paramV1”, value = “第一个参数”, paramType = “form”, dataType = “String”, notice = “必须是string类型的”, paramExample = “username”),

@QParamDoc(name = “paramV2”, value = “第二个参数”, required = false, paramType = “form”, dataType = “Boolean”, notice = “必须是boolean类型的”, paramExample = “true”)

})

@QResponses({

@QResponse(code = -1, message = “系统异常”),

@QResponse(code = 200, message = “成功”)

})

@QResponseDocs({

@QResponseDoc(bindValueName = “data”, description = “第一个参数”, bindValueType = “object”, propertys = {

@QProperty(type = “String”, name = “name”, desc = “描述1”),

@QProperty(type = “int”, name = “age”, desc = “描述2”),

@QProperty(type = “com.qunar.fd.qdoc.qdocexample.vo.ExampleResultVO”,name = “food”,desc = “描述3”)

}),

})

public ApiResponseV2 example0(@RequestParam String paramV1,@RequestParam boolean paramV2) {

return null;

}

复制代码

通过目前已经在使用的去哪儿网工程师同学们反馈，一个中等复杂度的 API，通过注解方式书写 API 只需要5分钟的时间。

4.4 执行易管理

=========

去哪儿网 QDoc 工具在 API 同步方面主要支持两种方式，maven 命令同步与发布系统同步。maven 命令同步一方面可以满足 Design2doc 的诉求，另一方面也更为灵活，也继承了去哪儿网在 swagger-YAPI 方面的积累，通过发布系统同步是本次 QDoc 的主要工作。这方面的工作解决了接口与 Master 版本不同步的所有问题，包括接口创建、更新、回滚等。

我们可以看到：

服务开通步骤

发布系统开通展示在去哪儿网应用树中，对应 appcode 下有服务列表，服务列表中【QDoc】，点击开通，即可完成应用树的集成开通。
CM 发布集成在去哪儿网发布系统中，对应 appcode 下通过服务集市进行开通。

开通后，Portal 发布线上后，会自动触发文档的更新操作，这时，就可以在应用树中看到我们的文档了。

对内 DDD 对外 API 之—对外 API 的设计理念

通过简单的3步，我们就完成了 QDoc 与发布系统的集成。

4.5 平台易应用

=========

前面的工作完成得再好，如果没有交互良好的展示平台进行支撑，那么对于使用者来说也是十分痛苦的，应用费力度高的系统也是很难进行普及的。我们最终的选择是，YAPI 嵌入到 App 管理平台，与 Appcode 管理相绑定，给与团队管理者一站式的管理体验。

YAPI 可以参考开源版本

hellosean1025.github.io/yapi/

但是，只有 appcode 维度的 API 管理只能方便工程师团队进行 API 的一站式管理，不能对 DDD 业务重塑中十分重要的 Domain 维度的 API 管理产生正向的帮助。目前我们正在对 Domain 维度的 API 管理平台做着不断的优化：

对内 DDD 对外 API 之—对外 API 的设计理念

当然，我们建立了 Domain 维度的 API 管理体系后，顺带可以做的就是通过去哪儿网成熟的网关体系来外放我们的 API：

对内 DDD 对外 API 之—对外 API 的设计理念

介绍到这里，去哪儿网通过 QDoc 工具，从代码中的 API 注解到开放平台的领域 API 的全流程就介绍完毕了。

那么在项目中我们遇到了哪些难点呢？

5 API 标准化的实施难点

==============

1、开发资源从哪里来

这个项目是去哪儿网机票目的地事业群业务研发 TC 发起的项目，没有直接的团队进行资源支持，所需要的资源跨 CM、YAPI 平台、工具开发、业务试点项目接入开发几大块，几乎涉及到了公司所有团队的工程师，项目采用了公司内开源项目管理的方式，成立项目组，单独立项，跨团队联合各个团队的资源完成项目，项目的完成对于项目管理人员也是不小的挑战。

2、Design First or Code First

作为项目的初始阶段，同时支持 Design First 和 Code First 两种方式是不可能的，我们通过调研发现，Design First 更加适合非 Domain 维度接口的制定，例如一个前后端联调接口，这类支撑类接口不具有通用性，会随着页面的变化而重新进行开发，通常不复用。Code First 更适合帮助 Domain 维度的长期维护支持的接口保持高质量。而我们这次做 API 标准化工作的初衷就是要帮助 DDD 业务重塑做好 Domain 维度接口的规范化维护工作。所以我们选择首先支持 Code First 的接口提供方式。

3、Annotation or Comments

在我们做 QDoc之前，在公司内有一定使用度的 API 标准化工具包括 swagger2.0,swagger3.0,smart-doc ，在这点上我们通过调研发现，使用注解方式的 swagger 相关工具的工程师要明显多于使用 smart-doc 类注释方式的工程师，尽管 annotation 的方式存在 API 代码上方 annotation 堆积过多，会产生代码不美观的问题，但是既然使用 annotation 注解方式的用户明显更多，我们决定 QDoc 优先支持注解方式。这并不代表之后 QDoc 不会支持注释方式。

4、支持完整的 OpenAPI3.0规范 or 支持 OpenAPI3.0规范的子集

这个问题来自于我们已经有了2018年开源的已经相当成熟的 YAPI 平台，那么我们是否满足 YAPI 的接口要求就已足够？是否不必完全满足 OpenAPI3.0规范的要求，我们的回答是否定的。平台是在不断发展的，YAPI 也会有老去的一天，当 YAPI 老去的时候我们也会在支持 OpenAPI3.0规范的其他平台中作出选择，目前看 knife4j 就是一个在我们视线之内的 API 平台。

6 项目的成果

=======

DDD 与 API 最终会师。核心域、支撑域、通用域 API 均已接入。