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.2.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> </configuration> </plugin>
# 生成契约,文档和微服务工程 mvn toolkit:generate # 校验代码和契约一致性 mvn toolkit:verify
配置项(不显式设置 <configuration>
则使用默认配置) 例:
<plugin> <groupId>org.apache.servicecomb.toolkit</groupId> <artifactId>toolkit-maven-plugin</artifactId> <version>0.2.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.2.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.2.0-SNAPSHOT</version> <configuration> <!-- 输入源。设置为 code,表示解析当前代码;设置为 contract,表示解析指定目录的契约文件。不设置则默认为 code --> <sourceType>code</sourceType> <!-- 样本契约文件目录,必须设置 --> <destinationContractPath>./contract</destinationContractPath> </configuration> </plugin>
运行命令
mvn toolkit:verify
可执行jar包位于toolkit/cli/target/bin目录下
$ java -jar toolkit-cli-{version}.jar help
$ java -jar toolkit-cli-{version}.jar codegenerate -m ServiceComb -i swagger.yaml -o ./project -p SpringMVC
codegenerate 命令选项说明:
$ java -jar toolkit-cli-{version}.jar docgenerate -i swagger.yaml -o ./document
docgenerate 命令选项说明:
$ java -jar toolkit-cli-{version}.jar checkstyle -r style-check-rules.yaml -f oas.yaml or $ java -jar toolkit-cli-{version}.jar cs -r style-check-rules.yaml -f oas.yaml
checkstyle Command argument
$ java -jar toolkit-cli-{version}.jar checkcompatibility left-oas.yaml right-oas.yaml 或者 $ java -jar toolkit-cli-{version}.jar cc left-oas.yaml right-oas.yaml
checkcompatibility Command argument
可以在这里找到使用插件的一些示例
See Pull Request Guide for details.