基于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的能力

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

从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风格校验和兼容性校验等能力。

如何理解风格校验?

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

如何理解兼容性校验?

不管你是采用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

Apache ServiceComb社区现诚邀开发者参加2020年华为开发者大会（HDC）！

时间

2020年2月11日-12日

地点

深圳市福田区会展中心

活动详情

为答谢大家长期对社区的支持与贡献，我们准备了一些华为开发者大会参会门票。此次Apache ServiceComb社区设有3场主题演讲、2个codelabs、黑客松活动。

Apache ServiceComb黑客松的题目是利用ServiceComb框架开发微服务化的AI Web相册。

第1，2名参赛获奖团队可获得价值3999元的Altas 200 DK开发者套件，参与就有香蕉派开发板和T恤奖品。

报名黑客松大赛 & 获取HDC门票

长按识别二维码，添加”ServiceComb小助手“

快来报名参赛 or 领取免费门票吧！

备注：本次参赛队伍名额有限，请大家火速报名。免费门票数量有限，先到先得，赠完为止。本活动有效期截止至2020年2月10日，赠送活动最终解释权归ServiceComb社区。

如您对开源开发、微服务感兴趣

欢迎微信扫码添加

ServiceComb小助手

咱们一起做点有意思的事情~

长按二维码加入我们

在看一点，BUG退散