Apache ServiceComb Toolkit 是基于契约的微服务开发工具套件
遗留应用提取契约文件
在基于SpringMVC/POJO/JAX-RS模型开发的应用中,一键提取符合OpenAPI规范的服务契约文件。
契约文件生成微服务工程
输入符合OpenAPI规范的服务契约,一键生成以ServiceComb/SpringCloud/Swagger为底座,以及以SpringMVC/POJO/JAX-RS或SpringBoot为开发模型的微服务项目。
契约与代码一致性校验
校验应用的实际实现(如数据和服务API)是否与样本服务契约描述一致。
契约的风格校验和兼容性校验
风格校验检查契约是否符合[OAS 3.0.2规范][openapi-3.0.2]以及自定义的规则; 兼容性校验检查新旧两个版本的OAS的兼容性
契约/代码生成文档
输入符合OpenAPI规范的服务契约,一键生成html格式的文档。
Todo List
支持gradle plugin, eclipse plugin, intellij plugin。
支持word、pdf等流行格式文档。
支持契约增量生成代码。
工具能力服务化。
Server端自动/半自动测试
Interface匹配性校验
支持生成包含连接Mysql/Redis等常见DB的代码片段的微服务脚手架
集成多厂商应用的企业
问题:厂商数据、服务标准不一致,开发语言、习惯、框架不一致,集成商难集成,企业难管控。
措施:通过统一定义的接口描述标准(服务契约),使用工具套件一键生成基于指定微服务框架的微服务工程,并且通过服务契约校验手段协同维护整体系统的一致性。以此协调多个开发团队,降低沟通成本且避免后期的混乱。
遗留系统微服务化快速改造
问题:用户需要额外学习和理解微服务及相关框架后,再设计微服务工程,学习成本高。
措施:使用工具套件分析遗留应用提取服务契约,再一键生成基于指定微服务框架的微服务工程后,即可聚焦业务开发,减少用户对微服务框架的学习成本。
构建环境要求:
# 从github获取toolkit最新源码 $ git clone https://github.com/apache/servicecomb-toolkit.git $ cd toolkit # 构建打包 $ mvn clean install
在maven项目的pom文件中配置
<plugin> <groupId>org.apache.servicecomb.toolkit</groupId> <artifactId>toolkit-maven-plugin</artifactId> <version>0.3.0-SNAPSHOT</version> <configuration> <!-- 输入源。设置为 code,表示解析当前代码;设置为 contract,表示解析指定目录的契约文件。不设置则默认为 code --> <sourceType>code</sourceType> <!-- 生成契约文件的类型,不设置则默认为 yaml --> <contractFileType>yaml</contractFileType> <!-- 生成文档的类型,不设置则默认为 html --> <documentType>html</documentType> <!-- 生成契约文件、文档的根目录,不设置则默认为运行命令所在目录下的 target 目录,生成的微服务工程在 project 目录,契约文件在 contract 目录,文档在 document 目录 --> <outputDirectory>./target</outputDirectory> <!-- 被解析的契约文件路径,在 sourceType 设置为 contract 时有效,且必须设置 --> <contractLocation>./contract</contractLocation> <!-- 被校验的契约文件目录,在 sourceType 设置为 contract 时有效,且必须设置 --> <sourceContractPath>./target/contract</sourceContractPath> <!-- 样本契约文件目录,必须设置 --> <destinationContractPath>./contract</destinationContractPath> <!-- 生成的微服务代码工程配置 --> <service> <!-- 微服务的类型,可生成 provider/consumer/all,默认值为 all --> <serviceType>all</serviceType> <!-- 微服务的 groupid,用户可选,默认值为 domain.orgnization.project --> <groupId>domain.orgnization.project</groupId> <!-- 微服务的 artifactId,用户可选,默认值为 sample --> <artifactId>sample</artifactId> <!-- 微服务的 artifactVersion,用户可选,默认值为 0.1.0-SNAPSHOT --> <artifactVersion>0.1.0-SNAPSHOT</artifactVersion> <!-- 微服务的 packageName,用户可选,默认值为 domain.orgnization.project.sample --> <packageName>domain.orgnization.project.sample</packageName> <!-- 微服务框架,用户可选。设置为 ServiceComb,生成ServiceComb风格的微服务项目;设置为 SpringCloud,生成SpringCloud风格的微服务项目。默认值为 ServiceComb --> <microServiceFramework>ServiceComb</microServiceFramework> <!-- 服务提供者的服务id。仅包含服务消费者的场景(serviceType=consumer)必须设置该值 --> <providerServiceId>servicecomb-provider</providerServiceId> <!-- 服务id,默认值为artifactId的值 --> <serviceId>servicecomb-consumer</serviceId> </service> <!-- 指定额外的属性值,这些属性值可以被mustach模板引用。仅为生成代码时使用,即goal为generate --> <additionalProperties> <prop1>value</prop1> <prop2>value</prop2> ... <propN>value</propN> </additionalProperties> </configuration> </plugin>
# 生成契约,文档和微服务工程 mvn toolkit:generate # 校验代码和契约一致性 mvn toolkit:verify
配置项(不显式设置 <configuration>
则使用默认配置) 例:
<plugin> <groupId>org.apache.servicecomb.toolkit</groupId> <artifactId>toolkit-maven-plugin</artifactId> <version>0.3.0-SNAPSHOT</version> <configuration> <!-- 输入源。设置为 code,表示解析当前代码;设置为 contract,表示解析指定目录的契约文件。不设置则默认为 code --> <sourceType>code</sourceType> <!-- 生成契约文件、文档的根目录,不设置则默认为运行命令所在目录下的 target 目录,生成的微服务工程在 project 目录,契约文件在 contract 目录,文档在 document 目录 --> <outputDirectory>./target</outputDirectory> <!-- 生成的微服务代码工程配置 --> <service> <!-- 微服务的类型,可生成 provider/consumer/all,默认值为 all --> <serviceType>all</serviceType> </service> </configuration> </plugin>
运行命令
mvn toolkit:generate
代码生成契约现已支持以下注解(类级别)编写的restful接口
RestController, RestSchema, RpcSchema, RequestMapping
代码生成契约时,restful接口方法修饰符必须指定为public
配置项(不显式设置 <configuration>
则使用默认配置) 例:
<plugin> <groupId>org.apache.servicecomb.toolkit</groupId> <artifactId>toolkit-maven-plugin</artifactId> <version>0.3.0-SNAPSHOT</version> <configuration> <!-- 输入源。设置为 code,表示解析当前代码;设置为 contract,表示解析指定目录的契约文件。不设置则默认为 code --> <sourceType>contract</sourceType> <!-- 被解析的契约文件路径,在 sourceType 设置为 contract 时有效,且必须设置 --> <contractLocation>./contract</contractLocation> <!-- 生成契约文件、文档的根目录,不设置则默认为运行命令所在目录下的 target 目录,生成的微服务工程在 project 目录,契约文件在 contract 目录,文档在 document 目录 --> <outputDirectory>./target</outputDirectory> <!-- 生成的微服务代码工程配置 --> <service> <!-- 微服务的类型,可生成 provider/consumer/all,默认值为 all --> <serviceType>provider</serviceType> </service> </configuration> </plugin>
运行命令
mvn toolkit:generate
配置项 例:
<plugin> <groupId>org.apache.servicecomb.toolkit</groupId> <artifactId>toolkit-maven-plugin</artifactId> <version>0.3.0-SNAPSHOT</version> <configuration> <!-- 输入源。设置为 code,表示解析当前代码;设置为 contract,表示解析指定目录的契约文件。不设置则默认为 code --> <sourceType>code</sourceType> <!-- 样本契约文件目录,必须设置 --> <destinationContractPath>./contract</destinationContractPath> </configuration> </plugin>
运行命令
mvn toolkit:verify
如果你使用的是正式发布版本(>=0.2.0),可以在解压二进制包后直接使用里面的脚本文件
如果你是通过源码构建,可以将cli/scripts/cli.*
与cli/target/bin/toolkit-cli-{version}.jar
放置在同一目录,然后根据不同环境选择不同脚本
以下所有示例均通过Linux环境的cli.sh进行介绍
$ ./cli.sh help
$ ./cli.sh codegenerate -m ServiceComb -i swagger.yaml -o ./project -p SpringMVC
codegenerate 命令选项说明:
$ ./cli.sh docgenerate -i swagger.yaml -o ./document
docgenerate 命令选项说明:
$ ./cli.sh checkstyle -r style-check-rules.yaml -f oas.yaml or $ ./cli.sh cs -r style-check-rules.yaml -f oas.yaml
checkstyle Command argument
$ ./cli.sh checkcompatibility left-oas.yaml right-oas.yaml 或者 $ ./cli.sh cc left-oas.yaml right-oas.yaml
checkcompatibility Command argument
可以在这里找到使用插件的一些示例
See Pull Request Guide for details.