新特性解读 | Apache ServiceComb Toolkit 0.1.0发布

ServiceComb Toolkit 0.1.0 新功能介绍

ServiceComb Toolkit 0.1.0 已经发布了， Toolkit 是基于契约的微服务开发工具套件，提供契约、代码、文档相互转换及校验的能力，帮助用户一键式快速构建基于流行微服务框架和流行编程模型的微服务工程，降低微服务入门成本，使用户聚焦业务开发，提升遗留系统重构、开发效率。契约遵循 OpenAPI 2.0 规范，也即是 Swagger2.0 ，用于描述 API 接口的定义。

在这个版本中我们提供了如下特性：

• 遗留应用提取契约文件

  在基于 SpringMVC/POJO/JAX-RS 模型开发的应用中，一键提取符合 OpenAPI 规范的服务契约文件。

• 契约文件生成微服务工程

  输入符合 OpenAPI 规范的服务契约，一键生成以 ServiceComb 为底座，以及以 SpringMVC/POJO/JAX-RS 或 SpringBoot 为开发模型的微服务项目。

• 契约与代码一致性校验

  校验应用的服务 API 是否与样本服务契约描述一致。

• 契约 / 代码生成文档

  输入符合 OpenAPI 规范的服务契约，一键生成 html 格式的文档。

大家可以在此查阅到详细的版本更新日志：

https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12321626&version=12345703

一. 适用场景

集成多厂商应用的企业

问题：厂商数据、服务标准不一致，开发语言、习惯、框架不一致，集成商难集成，企业难管控。

措施：通过统一定义的接口描述标准（服务契约），使用工具套件一键生成基于指定微服务框架的微服务工程，并且通过服务契约校验手段协同维护整体系统的一致性。以此协调多个开发团队，降低沟通成本且避免后期的混乱。

遗留系统微服务化快速改造

问题：用户需要额外学习和理解微服务及相关框架后，再设计微服务工程，学习成本高。

措施：使用工具套件分析遗留应用提取服务契约，再一键生成基于指定微服务框架的微服务工程后，即可聚焦业务开发，减少用户对微服务框架的学习成本。

toolkit 为用户提供了两个工具 ：

• maven 插件 toolkit-maven-plugin ，该插件提供了两个功能。 generate 和 verify 。 generate 可以同时生成契约文件，文档和基于 ServiceComb 的微服务工程， verify 可以校验代码与契约的一致性。

• 命令行工具 toolkit-cli ，可以方便的通过契约生成微服务工程和通过契约生成文档。

下面将详细介绍它们的用法。

二. 使用toolkit-maven-plugin插件

解析代码，生成 ServiceComb 微服务工程、契约和文档

假设已有开发了一定代码量的项目 ， 想转型为基于 ServiceComb 的微服务工程 ， 可以使用 toolkit 辅助开发。

在原项目的 pom.xml 中，配置以下插件：

<plugin>

<groupId>org.apache.servicecomb.toolkit</groupId>

<artifactId>toolkit-maven-plugin</artifactId>

<version>0.1.0</version>

<configuration>

<sourceType>code</sourceType>

<outputDirectory>./target</outputDirectory>

<documentType>html</documentType>

<service>

<serviceType>all</serviceType>

</service>

</configuration>

</plugin>

• sourceType 配置契约的来源， 设置为 code ，表示解析当前代码； 设置为 contract ，表示解析指定目录的契约文件。 不设置则默认为 code， 解析当前代码

• outputDirectory 配置生成契约文件、文档的根目录，不设置则默认为运行命令所在目录下的 target 目录，生成的微服务工程在 project 目录，契约文件在 contract 目录，文档在 document 目录。

• service 配置生成的微服务代码工程的相关信息 ，serviceType 配置微服务的类型，可生成 provider/consumer/all ，默认值为 all

• documentType 配置生成文档的类型，不设置则默认为 html

• contractFileType 生成契约文件的类型，不设置则默认为 yaml

• groupId 配置微服务的 groupid ，用户可选，默认值为 domain.orgnization.project

• artifactId 配置微服务的 artifactId ，用户可选，默认值为 sample

• artifactVersion 配置微服务的 artifactVersion ，用户可选，默认值为 0.1.0-SNAPSHOT

• packageName 配置微服务的 packageName ，用户可选，默认值为 domain.orgnization.project.sample

执行命令

mvn toolkit:generate

执行以上命令后，会在 outputDirectory 指定的目录中同时生成文档和基于 ServiceComb 的微服务工程。生成内容大致如下：

target/

├── contract

│ ├── XxxService

│ │ └── XxxController.yaml

├── document

│ ├── XxxService

│ │ └── XxxController.html

└── project

├── XxxService-consumer

│ ├── pom.xml

│ └── src

├── XxxService-model

│ └── pom.xml

├── XxxService-provider

│ ├── pom.xml

│ └── src

└── pom.xml

解析契约，生成 ServiceComb 微服务工程和文档

假设想基于 ServiceComb 开发新的微服务工程 , 可以使用 toolkit 辅助开发。

在新项目的 pom.xml 中，配置以下插件：

<plugin>

<groupId>org.apache.servicecomb.toolkit</groupId>

<artifactId>toolkit-maven-plugin</artifactId>

<version>0.2.0</version>

<configuration>

<sourceType>contract</sourceType>

<contractLocation>./contract</contractLocation>

<outputDirectory>./target</outputDirectory>

<service>

<serviceType>provider</serviceType>

</service>

</configuration>

</plugin>

• sourceType 配置契约的来源，设置为 code ，表示解析当前代码；设置为 contract ，表示解析指定目录的契约文件。不设置则默认为 code ，解析当前代码

• contractLocation 配置被解析的契约文件的路径，在 sourceType 设置为 contract 时有效，且必须设置

• outputDirectory 配置生成契约文件、文档的根目录，不设置则默认为运行命令所在目录下的 target 目录，生成的微服务工程在 project 目录，契约文件在 contract 目录，文档在 document 目录  

• service 配置生成的微服务代码工程的相关信息  

• serviceType 配置微服务的类型，可生成 provider/consumer/all ，默认值为 all 

• documentType 配置生成文档的类型，不设置则默认为 html 

• groupId 配置微服务的 groupid ，用户可选，默认值为 domain.orgnization.project 

• artifactId 配置微服务的 artifactId ，用户可选，默认值为 sample

• artifactVersion 配置微服务的 artifactVersion ，用户可选，默认值为 0.1.0-SNAPSHOT 

• packageName 配置微服务的 packageName ，用户可选，默认值为 domain.orgnization.project.sample

执行命令：

mvn toolkit:generate

执行以上命令后，会在 outputDirectory 指定的目录中同时生成文档和基于 ServiceComb 的微服务工程。生成内容大致如下：

target/

├── document

│ ├── XxxService

│ │ └── XxxController.html

└── project

├── XxxService-consumer

│ ├── pom.xml

│ └── src

├── XxxService-model

│ └── pom.xml

├── XxxService-provider

│ ├── pom.xml

│ └── src

└── pom.xml

校验代码与契约的一致性

当代码发生变化，有可能出现与先前契约不一致的情况，契约校验相当于一次自检。

在项目的 pom.xml 文件中配置 toolkit-maven-plugin

<plugin>

<groupId>org.apache.servicecomb.toolkit</groupId>

<artifactId>toolkit-maven-plugin</artifactId>

<version>0.1.0-SNAPSHOT</version>

<configuration>

<sourceType>code</sourceType>

<destinationContractPath>./contract</destinationContractPath>

</configuration>

</plugin>

• sourceType 配置契约的来源，设置为 code ，表示解析当前代码；设置为 contract ，表示解析指定目录的契约文件。不设置则默认为 code ，解析当前代码。

• destinationContractPath 配置样本契约文件的目录，必须设置 sourceContractPath 配置被校验的契约文件目录，在 sourceType 设置为 contract 时有效，且必须设置。

执行命令：

mvn toolkit:verify

校验结果将会在控制台中输出

例如下图：

三. 使用toolkit cli工具

除了 maven 插件之后，我们还提供了一个命令行工具，默认发行版不包括 toolkit cli 工具，需要通过 maven 命令编译打包。

$ git clone https://github.com/apache/servicecomb-toolkit.git

$ cd servicecomb-toolkit

$ git checkout 0.1.0 -b 0.1.0

$ mvn clean install -DskipTests=true

# 进入toolkit cli工具默认生成目录

$ cd cli/target/bin

$ java -jar toolkit-cli-0.1.0.jar help

通过契约生成微服务工程

$ java -jar toolkit-cli-{version}.jar  codegenerate -m ServiceComb -i swagger.yaml -o ./project -p SpringMVC

codegenerate 命令选项说明 ：

• -m, --microservice-framework : 指定微服务框架 , 现支持 ServiceComb

  例： -m ServiceComb

• -p, --programming-model : 指定编程模型，可选 JAX-RS ， POJO ， SpringMVC ， SpringBoot

  例： -p SpringMvc

• -i, --input : 指定遵循 OpenAPI 规范的契约文件，支持 yaml 和 json 格式，支持指定本地和网络文件

  例： -i http://petstore.swagger.io/v2/swagger.json

• -o, --output : 生成的项目代码输出路径

  例： -o ./project

• --group-id : 指定生成的项目的 group id

  例： --group-id com.demo

• --artifact-id : 指定生成的项目的 artifact id

  例： --artifact-id springmvc-example

• --artifact-version : 指定生成的项目的 artifact version

  例： --artifact-version 1.0.0

• --api-package : 指定生成项目的 api package

  例： --api-package com.demo.api

• --model-package : 指定生成项目的 model package

  例： --model-package com.demo.model

• -t, --service-type : 指定生成的微服务项目的微服务类型。可选值为 provider,consumer,all

  例： --service-type provider

通过契约生成文档

$ java -jar toolkit-cli-{version}.jar docgenerate -i swagger.yaml -o ./document

docgenerate 命令选项说明 ：

• -i, --input : 指定遵循 OpenAPI 规范的契约文件，支持 yaml 和 json 格式，支持指定本地和网络文件

  例： -i http://petstore.swagger.io/v2/swagger.json

• -o, --output : 文档输出路径

  例： -o ./document

• -f, --format : 指定输出文档风格 , 现支持 swagger-ui 例： -f swagger-ui

未来 toolkit-cli 命令工具将支持更多的配置项和功能特性

四. 小结

在  ServiceComb Toolkit 0.1.0 的 第一版中，支持生成基于 ServiceComb 的微服务工程， 后续我们将支持生成基 于其他微服务框架的微服务工程，例如 Spring Cloud 。

未来，新功能还会不断加入，欢迎大家一起参与讨论和开发。

Github地址： https://github.com/apache/servicecomb-toolkit

欢迎点击“ 阅读原文 ”，关注我们，获取更多关于Apache ServiceComb开源微服务的内容。

送票啦

对新特性的有啥看法和观点呢？

转发本文至朋友圈

并点击文末“写留言”说出你的想法

留言区点赞数排名前三的同学

将获得 ServiceComb meetup 赠票 一张

（该票为   华为全联接大会   9月20日开发者活动日门票，可用于参加峰会、专题演讲、动手实验、展区及开放演讲、开发者活动，还可获得纪念品及华为云大礼包）

赠送活动解释权归 ServiceComb 社区。

往期回顾

【大咖连载】SockShop系统服务划分与设计

新特性解读 | Apache ServiceComb Pack 0.5.0发布

Spring Cloud中Hystrix、Ribbon及Feign的熔断关系是什么?

长按扫码

加小助手进群

用心做开源，不忘初衷