现在 OpenAPI 已经成为完成系统之间集成的重要桥梁，OpenAPI 的可用性以及用户在使用时的体验就变得愈来愈重要，阿里云前架构师曾说过："阿里云的本质是一家卖 API 的公司。API 有没有作好，是关乎生死的大事"。可是从平常来自用户的反馈中咱们总结了如下比较通用的几点 OpenAPI 体验问题：git
- 云产品 OpenAPI 没有提供 SDK 或者 SDK 语言不全；
- 部分云产品的 SDK 使用风格差别过大，致使使用成本增长；
- API 文档缺失或者不够清晰，不具有指导意义；
- 没有场景化 Code Sample 或提供 CodeSample 没法运行。
多语言 SDK 生成
提及生成多语言 SDK，你们第一时间想起的必定是当前业界内生成多语言 SDK 的通用方案——Swagger，开发者经过 Swagger 定义的 OpenAPI 标准并配合模板的方式来生成多语言 SDK。不过问题并无所以而获得完美的解决。首先模版的生成方式相对生硬，虽然实现起来容易，但维护起来却不那么灵活；其次，大量 OpenAPI 并非 RESTful 风格的，这就致使不少产品现存的 OpenAPI 在文档、SDK 等场景下，没法使用上 Swagger 这样强大的生态工具链。既然没法沿用 Swagger 规范元数据的方法来解决这个问题，咱们就须要对咱们的工做从新进行抽象。在笔者看来，之因此没有一套元数据能够适用于全部的网关主要仍是由于每一个网关所对应的后端状况不一样，就像机器语言或者汇编语言会由于架构的不一样而有所不一样，可是其本质仍是描述如何经过操做寄存器、内存里的数据来完成一个程序，高级语言就是经过 AST 兼容了各平台的这些不一样最后解决了这些问题。而对于 OpenAPI 来讲也是一样的道理，因此咱们经过从新定义一门 DSL 语言 Darabonba 来描述各类各样的 OpenAPI。github
经过 Darabonba 对 OpenAPI 进行描述，其本质就是统一了元数据，只是这个元数据并非 JSON 或者 Yaml 这样的方式来描述的，而是经过 DSL 代码来描述。Darabonba 的编译器则会将 Darabonba 的 DSL 代码转化为 AST，经过 OpenAPI 描述转化而来的 AST 不只包含了 OpenAPI 的信息，并且还包含整个 OpenAPI 的流程性描述，因此咱们只须要经过 AST 开发对应的各语言SDK就能够生成多语言的 SDK了。Darabonba 具体的设计思路和理念可参考文章：Darabonba：支持任意 OpenAPI 网关的多语言 SDK 方案，这里就再也不赘述。后端
模块化设计
在经过元数据向生成 SDK 的过程当中，仅仅经过对 OpenAPI 的数据模型和请求/响应描述是不够的，还须要各类参数处理，签名生成，文件上传，流操做等各类复杂的方法，以往经过模板生成 SDK 的时会选择维护一个各语言的核心模块来封装这些方法，可是随着支持的 OpenAPI 愈来愈多核心库中的方法也是愈来愈多，就会产生如下的问题：api
- 客户使用或者开发者接入核心库的 SDK 开发者来讲成本会愈来愈大；
- 核心库的维护人员的维护成本也会愈来愈高，随着方法愈来愈多也须要不断的对核心库进行重构，遇到不兼容性改动的可能性也会愈来愈高；
- 全部方法杂糅在一个核心库中，在修改时容易牵一发动全身，须要大量的测试用例保障。
在经过 Darabonba 生成的 SDK 时也会遇到一样的问题，Darabonba 做为一门 DSL 语言主要能力在于描述 OpenAPI ，为了保障生成的 SDK 具有完整的功能一样须要不少实现不少核心方法，而在总结以往维护核心库的中遇到的问题之后，咱们选择了如今在高级语言中很是常见的模块化开发理念，并提供了相应的命令行工具 Darabonba CLI 和 Darabonba 模块仓库。架构
接口模块
Darabonba 其核心能力是描述 OpenAPI，缺乏复杂逻辑实现的能力，为了弥补这个能力 Darabonba 设计了接口模块的概念。与 Java 中的 interface 接口类型定义相似，Darabonba 的接口模块便是只在 Darabonba 编写的DSL 代码中只定义方法体的集合而并不实现其具体逻辑，真正的逻辑则是由各语言分别实现。例如 Darabonba 中经常使用的 Console 模块：并发
咱们只须要在模块中申明模块包含 log 方法并描述它的出参入参便可，而各语言则经过自身语言的特性来实现该方法便可，其具体实现可参考 Console 模块源码。在编写好生成接口模块之后能够经过 Darabonba 提供的 Darabonba CLI 执行 dara publish 将模块发布到 Darabonba 模块仓库，就能够在 Darabonba 代码中使用了。下面就是咱们经过引入 Console 模块来打印字符串的一段代码：模块化
经过接口模块的设计理念将以往核心库中的方法根据功能拆分红一个个包含了特定功能的基础模块，不只使得生成的 SDK 更好用逻辑更清晰，同时也作到了足够的抽象避免不少在生成 SDK 过程当中重复造轮子的工做。目前 Darabonba 官方提供了包含了经常使用方法的 Util 模块、文件上传所使用的 FileForm 以及 XML 模块等，同时开发者也能够编写与本身业务逻辑相关的接口模块并发布到 Darabonba 模块仓库。工具
OpenAPI 模块
在 Darabonba 的模块化设计中不止有接口模块，事实上每个 Darabonba 的项目都是一个模块，因此基于一组 OpenAPI 描述编写的 Darabonba 代码就是一个 OpenAPI 模块。开发者在完成了 OpenAPI 描述的 Darabonba 代码编写之后，一样能够经过 Darabonba CLI 将描述 OpenAPI 的 Darabonba 模块发布到模块仓库中，这样使用 SDK 的用户就能够经过模块的详情页面查看 SDK 中包含的方法及各语言 SDK 的安装说明等信息了。测试
基于一组 OpenAPI 发布的 Darabonba 模块不只能够帮助用户更好的了解这组 OpenAPI，更能够在这个基础上实现 OpenAPI 接口的 Code Sample 编写，进而实现多语言的 Code Sample 统一辈子成。阿里云
Code Sample 自动生成
能够说对于简单的 API 调用普通的 API 文档就足够了，可是随着如今 OpenAPI 在系统与系统集成之间使用的愈来愈普遍，其复杂度也随之提升，以往单纯使用 API 文档的方式已经不足以让客户顺利的使用 OpenAPI 了。从阿里云目前的工单状况来看，SDK 相关的客户咨询至少有一半是由于没有 Code Sample 形成的，其中更是有1/4的客户是直接要求为 SDK 提供 Code Sample。
这种状况下，可以提供给用户可运行、可调试的 Code Sample 示例就成了文档中必不可少的一部分，可是如何可以编写全语言的 Code Sample 而且保障其可运行，倒是一个极大的问题。若是经过人力来维护，很容易就出现语言不全，或是编写的代码没有维护的问题，阿里云中遇到最多的问题就是 OpenAPI 在迭代，而 Code Sample 却忘记迭代了形成了提供出去的 Code Sample 没法使用从而被用户诟病。
经过引用模块仓库中 Darabonba 模块编写的 CodeSample 则能够避免这样的问题，首先多语言的自动生成，节约了大量的维护成本，并且风格统一利于用户理解；同时 Darabonba 编译时采用类型的强校验，一旦 OpenAPI 的参数或者返回结果出现了不兼容的更新，CodeSample 则会生成失败从而通知到开发者更新相关示例来解决这个问题。下面是阿里云语音服务 SDK 相关的 CodeSample 示例，你们也能够点击示例连接尝试生成：
Test Cases 自动生成
在 OpenAPI 公布上线之后，如何可以保障 OpenAPI 持续可用就是一个很是重要的问题，若是没有一个保障机制，极可能会出现 OpenAPI 出了问题就没法及时发现，客户的投诉也就随之而来。并且 OpenAPI 和 SDK 也会遇到更新升级等状况，如何能保障这些更新升级不会给正在使用 OpenAPI 的客户形成问题也是 OpenAPI 提供方遇到的一个很是大的挑战。为了解决这些挑战， 就须要 OpenAPI 提供方编写 Test Cases 做为平常的持续集成来检验 OpenAPI 的可用性，可是目前多语言的 SDK 的 Test Cases 大多存在如下的问题：
- 须要大量的人力去维护 Test Cases ，并且没法保障全部语言的 SDK 都拥有 Test Cases；
- OpenAPI 的 Test Cases 少且更新频率低，形成了对 OpenAPI 的覆盖面低而没法起到有效的保障做用；
- 各语言 SDK 的由各语言的开发同窗分别维护，因此用例不一样步致使不一样语言之间的测试结果有所差别。
而Darabonba 的多语言生成能力则能够解决以上全部问题，只须要引用 SDK 在模块仓库中对应的 Darabonba 模块与 Darabonba 官方提供的断言模块 Assert 模块编写对应的 Darabonba Test Cases 便可为各语言 SDK 生成其对应的 Test Cases。经过 Darabonba 自动化生成 Test Cases 不只能够解决人力不足 Test Cases 很难覆盖各语言 SDK 的状况，并且生成的各语言 Test Cases 标准一致，也能够解决各语言 Test Cases用例不一样步形成的测试差别问题。下面是一段经过 Darabonba 编写的测试用例：
Darabonba 的主要能力是支持到不一样风格的 OpenAPI，同时支持多语言的 SDK、Code Sample 目标生成。最终的目的仍然是打通从 OpenAPI 定义到文档、到 SDK、CLI 等 OpenAPI 使用场景下的一致性。提供给用户更统1、专业、一致的使用体验。同时也大幅下降 OpenAPI 提供者用来支持用户的成本，经过自动化的方式，节省精力的同时，还可减小人为参与时致使的错误。
参与贡献
Darabonba 的目标是让用户获得极致的 OpenAPI 体验，因此咱们也须要更多的人参与到咱们的开源项目来，你们能够按之前的方式参与 Darabonba 的贡献：
- 参与其余语言生成器的生成，目前 Darabonba 只支持了比较经常使用的六门语言，还须要更多生成器的支持。
- 编写更多底层工具模块，使 Darabonba 可以生成更便捷的 SDK。
- 参与 Darabonba 编译器及 CLI 工具的建设中来。
- 编写更多 OpenAPI 元数据转换到 Darabonba 的工具。
相关阅读