转载

基于API的一键式微服务开发工具原理（文末赠票福利~）

没关注？伸出手指点这里---

Apache ServiceComb Toolkit的诞生

对于用户而言，将原有系统升级到微服务架构时，需要额外学习和理解微服务及相关框架后，再去设计微服务工程，学习成本较高。每次切换框架都会有新的编程模型，如 SpringMVC、JaxRs 等。 API 定义没有统一规范，定义混乱，不同框架对于 API 的默认行为不一致，如 SpringMVC 框架的 RestController 注解默认返回 JSON 格式数据，而其它框架则不一定。

围绕着以上问题，第一版 Apache ServiceComb Toolkit 诞生了。它选择了基于 OpenAPI 规范去解决以上问题。 OpenAPI 规范是一个社区驱动的关于 API 定义的开放规范。对于 OpenAPI 规范，来自 Swagger OpenAPI 小组的 Keshav Vasudevan 在他的博文“ The Benefits of OpenAPI-Driven API Development ” （ https://swagger.io/blog/api-strategy/benefits-of-openapi-api-development/）中做了详细阐述。

OpenAPI 规范相对于 REST ，就像 WSDL 相对于 SOAP 。它为设计人员、开发人员、测试人员和 DevOps 提供了一个通用框架来构建和维护 API 。可以将规范视为一组用于构建和实现 REST API 的规则。 OAS 具有语言无关性，并且是人类和机器可读的，允许人类和计算机在无需访问源代码、附加文档或检查网络流量的情况下发现和理解服务的功能。

通过以上描述我们不难发现，基于 OpenAPI 驱动的开发能做到语言无关， API 定义统一，而且也易于围绕其做各种工具化的事情。

Apache ServiceComb Toolkit的能力

基于API的一键式微服务开发工具原理（文末赠票福利~）

Apache ServiceComb Toolkit 是一个基于 OpenAPI 规范的工具套件，提供了代码生成契约、契约生成代码、契约生成文档、合规性校验、兼容性校验等等能力，帮助用户一键式快速构建基于流行微服务框架和流行编程模型的微服务工程，降低微服务入门成本，使用户聚焦业务开发，提升遗留系统重构、开发效率。下图为项目的整体设计，分为三层，对用户提供的统一交互层，有命令行工具， maven 插件等。交互层直接依赖于接口层。而接口层提供了扩展点，方便有定制需求的用户实现个性化的功能。而其中最底部的微服务 SDK 模板仅仅是实现层中会使用到，并不属于独立的一层

基于API的一键式微服务开发工具原理（文末赠票福利~）

从OpenAPI v3一键式生成微服务工程

传统新建一个微服务，我们需要自己寻找微服务框架，选择版本，而版本之间的对应关系复杂，配置繁多。所以我们简化了新建一个微服务项目的步骤。现在只需要提供一份 OpenAPI 契约文件，就能以命令的形式生成新的微服务项目。其中的原理很简单， OpenAPI 规范本身对 API 的描述非常详尽，而我们通过解析其 API 定义，再结合 mustache 模板技术，便能动态的生成微服务工程。

从OpenAPI v3一键式生成文档

OpenAPI 规范是人类可读的，但对使用 API 的人员依旧不够友好。而一份可视化文档可以帮助人们更好的理解 API 的定义和使用 API 。典型的有 Swagger UI ， Asciidoc 等。 Apache ServiceComb Toolkit 提供了将 OpenAPI 文件转换为文档的能力，帮助用户快速理解和使用 API。

从代码生成OpenAPI v3

为了从代码生成 OpenAPI V3 ，我们需要找到代码中的接口定义。在现阶段， Apache ServiceComb Toolkit 目前支持对 Java 代码的解析。 Java 中有许多的框架和规范可以用来开发 Restful API 接口，如 Spring MVC 框架， Jax-Rs 规范， ServiceComb 框架等等。它们都具有一定共同的特点，就是可以通过有限的注解（ Annotation ）标识 Restful API 接口。 Apache ServiceComb Toolkit 通过识别这些注解进而识别 Restful API 接口，分析其中的元数据，最后汇聚出一个完整的 OpenAPI 对象。

规范化OpenAPI Spec文档

toolkit 在 0.2.0 版本时接受了新开普软件研究院捐赠的 OAS Validator 工具。该工具提供 OpenAPI V3 风格校验和兼容性校验等能力。

基于API的一键式微服务开发工具原理（文末赠票福利~）

如何理解风格校验 ?

在一个微服务架构的系统中，提供RESTful API的组件可能会有很多个，并且由不同开发人员/团队开发，那么在使用这些接口的时候有一个很自然的需求就是希望这些接口（或接口文档）的风格是一致的。OAS Validator的风格校验做的就是这部分工作。

基于API的一键式微服务开发工具原理（文末赠票福利~）

如何理解兼容性校验 ?

不管你是采用Code First还是Contract First，Contract的变动不可避免，那么如何保证变化后的Contract能够对下游应用向下兼容就成了不可回避的问题。这个问题的具体描述就是根据V1.0 Contract开发的下游应用是否依然能够与根据V1.1 Contract实现的接口正确交互。

OAS Validator 支持命令行调用的方式，而且支持自定义校验风格，用户可以通过指定规则文件灵活定制不同的风格。

更多命令行的使用介绍请参考 https://github.com/apache/servicecomb-toolkit#333-service-contract-style-checking

有关于更多校验的细节，请参考 使用 OAS Validator 帮助你规范 OpenAPI Spec 文档 ( http://servicecomb.apache.org/cn/docs/use-oas-validator-help-standardize-oas-spec/ )

同时支持Swagger 2.0 & OpenAPI v3

在 Apache ServiceComb Toolkit 0.2.0 版本的开发中，我们在各个模块中不同程度的增加了对 OpenAPI v3 的支持。如 contractgen 模块支持生成 v3 契约， codegen 模块支持解析 v3 契约， oas-validator 支持对 v3 的合规性校验和兼容性校验等。

为什么要迁移到 OpenAPI v3 ？因为 v3 相比于 v2 ，结构更加简洁，紧凑，组件重用性更好。具体的对比可以参考文章 A Guide to What ’ s New in OpenAPI 3.0（ https://swagger.io/blog/news/whats-new-in-openapi-3-0/ ）

Apache ServiceComb Toolkit 可以基于 OpenAPI 生成微服务项目，规范化代码目录，简化开发者的开发步骤，帮助开发者提高效率。 Apache ServiceComb Toolkit 目前正在发展中，欢迎各位参与进来，一起定义它的未来。

Apache ServiceComb Toolkit ： https://github.com/apache/servicecomb-toolkit

基于API的一键式微服务开发工具原理（文末赠票福利~）