ServiceComb课题实验手册(一)

本实验手册参考了 ServiceComb 的官方文档，并对案例进行了改造、扩展，以有利于学员按照步骤完成实验并理解ServiceComb的相关概念和原理。

要完成本实验，学员需要在电脑中安装、配置如下软件:

环境准备

JDK 8 - Java 8 以上的版本都可以，但需要安装 JDK，而不是 JRE
Git - 最新版本即可
Maven - 安装 3.x 版本
IntelliJ IDEA Community Edition - 选择最新的社区版（免费版即可）
Docker - 建议安装比较新的版本，比如 19.0 以上

安装ServiceComb库

建立 Projects 目录，然后进入该目录，执行

1	git clone https://github.com/apache/servicecomb-java-chassis.git

执行完后，ServiceComb 的源代码已经克隆到 Projects 目录的 servicecomb-java-chassis 中，

然后进入该目录，执行

1	mvn clean install -DskipTests

在构建过程中，总共需要下载约 188M 大小的第三方库，然后 maven 会将 ServiceComb 项目编译、打包并部署到本地 maven 的仓库中，该仓库一般位于用户目录中的 .m2 目录。

构建完成后，可以看到类似如下的信息:

[INFO] Reactor Summary for ServiceComb Java Chassis 1.3.0-SNAPSHOT:
[INFO] 
[INFO] ServiceComb Java Chassis ........................... SUCCESS [09:07 min]
[INFO] Java Chassis::Dependencies ......................... SUCCESS [  0.024 s]
[INFO] Java Chassis::Dependencies::Default ................ SUCCESS [  0.037 s]
[INFO] Java Chassis::Dependencies::Spring4 ................ SUCCESS [  0.025 s]
[INFO] Java Chassis::Dependencies::Spring5 ................ SUCCESS [  0.020 s]
[INFO] Java Chassis::Dependencies::Springboot1 ............ SUCCESS [  0.019 s]
[INFO] Java Chassis::Dependencies::Springboot2 ............ SUCCESS [  0.019 s]
[INFO] Java Chassis::Parent::Default ...................... SUCCESS [  0.018 s]
[INFO] Java Chassis::Parent::Spring4 ...................... SUCCESS [  0.018 s]
[INFO] Java Chassis::Parent::Spring5 ...................... SUCCESS [  0.017 s]
[INFO] Java Chassis::Parent::Springboot1 .................. SUCCESS [  0.017 s]
[INFO] Java Chassis::Parent::Springboot2 .................. SUCCESS [  0.017 s]
[INFO] Java Chassis::Parents .............................. SUCCESS [  0.016 s]
[INFO] Java Chassis::Foundations .......................... SUCCESS [  0.015 s]
[INFO] Java Chassis::Foundations::Test Scaffolding ........ SUCCESS [05:12 min]
[INFO] Java Chassis::Foundations::Common .................. SUCCESS [01:46 min]
[INFO] Java Chassis::Common ............................... SUCCESS [  0.019 s]
[INFO] Java Chassis::Common::Javassist .................... SUCCESS [  0.446 s]
[INFO] Java Chassis::Foundations::Config .................. SUCCESS [ 16.072 s]
[INFO] Java Chassis::Foundations::SSL ..................... SUCCESS [01:09 min]
[INFO] Java Chassis::Foundations::Vertx ................... SUCCESS [  2.495 s]
[INFO] Java Chassis::Deployment ........................... SUCCESS [  0.263 s]
[INFO] Java Chassis::Service Registry ..................... SUCCESS [  1.993 s]
[INFO] Java Chassis::Swagger .............................. SUCCESS [  0.014 s]
[INFO] Java Chassis::Swagger::Generator ................... SUCCESS [  0.022 s]
[INFO] Java Chassis::Swagger::Generator::Core ............. SUCCESS [ 22.755 s]
[INFO] Java Chassis::Swagger::Generator::Jaxrs ............ SUCCESS [  0.360 s]
[INFO] Java Chassis::Swagger::Invocation .................. SUCCESS [  0.019 s]
[INFO] Java Chassis::Swagger::Invocation::Core ............ SUCCESS [ 18.300 s]
[INFO] Java Chassis::Core ................................. SUCCESS [  6.575 s]
[INFO] Java Chassis::Foundations::Protobuf ................ SUCCESS [04:25 min]
[INFO] Java Chassis::Swagger::Generator::Spring MVC ....... SUCCESS [ 17.957 s]
[INFO] Java Chassis::Common::Protobuf ..................... SUCCESS [  0.684 s]
[INFO] Java Chassis::Common::Rest ......................... SUCCESS [  1.675 s]
[INFO] Java Chassis::Foundations::Metrics ................. SUCCESS [  0.352 s]
[INFO] Java Chassis::Handlers ............................. SUCCESS [  0.013 s]
[INFO] Java Chassis::Handlers::Tracing Zipkin ............. SUCCESS [ 15.052 s]
[INFO] Java Chassis::Handlers::Bizkeeper .................. SUCCESS [ 24.727 s]
[INFO] Java Chassis::Handlers::Flow Control QPS ........... SUCCESS [  0.463 s]
[INFO] Java Chassis::Handlers::Loadbalance ................ SUCCESS [ 10.783 s]
[INFO] Java Chassis::Handlers::Fault Injection ............ SUCCESS [  0.295 s]
[INFO] Java Chassis::Handlers::PublicKey Auth ............. SUCCESS [  0.573 s]
[INFO] Java Chassis::Providers ............................ SUCCESS [  0.010 s]
[INFO] Java Chassis::Providers::Rest Common ............... SUCCESS [  0.274 s]
[INFO] Java Chassis::Swagger::Invocation::JAXRS ........... SUCCESS [  0.239 s]
[INFO] Java Chassis::Providers::JAXRS ..................... SUCCESS [  0.096 s]
[INFO] Java Chassis::Providers::POJO ...................... SUCCESS [  0.326 s]
[INFO] Java Chassis::Swagger::Invocation::Spring MVC ...... SUCCESS [  0.345 s]
[INFO] Java Chassis::Providers::Spring MVC ................ SUCCESS [  0.571 s]
[INFO] Java Chassis::Transports ........................... SUCCESS [  0.011 s]
[INFO] Java Chassis::Transports::common ................... SUCCESS [  0.160 s]
[INFO] Java Chassis::Transports::Hightway ................. SUCCESS [  0.453 s]
[INFO] Java Chassis::Transports::Rest ..................... SUCCESS [  0.012 s]
[INFO] Java Chassis::Transports::Rest::Client ............. SUCCESS [  0.465 s]
[INFO] Java Chassis::Transports::Rest::Vertx .............. SUCCESS [  0.686 s]
[INFO] Java Chassis::Transports::Rest::Servlet ............ SUCCESS [  0.355 s]
[INFO] Java Chassis::Swagger::Invocation::Validator ....... SUCCESS [ 22.564 s]
[INFO] Java Chassis::Tracing .............................. SUCCESS [  0.019 s]
[INFO] Java Chassis::Tracing::Common ...................... SUCCESS [ 25.407 s]
[INFO] Java Chassis::Tracing::Zipkin ...................... SUCCESS [ 30.681 s]
[INFO] Java Chassis::Edge ................................. SUCCESS [  0.024 s]
[INFO] Java Chassis::Edge::Core ........................... SUCCESS [  0.372 s]
[INFO] Java Chassis::Metrics .............................. SUCCESS [  0.015 s]
[INFO] Java Chassis::Metrics::Core ........................ SUCCESS [  0.754 s]
[INFO] Java Chassis::Metrics::Integration ................. SUCCESS [  0.012 s]
[INFO] Java Chassis::Metrics::Integration::Prometheus ..... SUCCESS [  4.803 s]
[INFO] Java Chassis::Dynamic Config ....................... SUCCESS [  0.018 s]
[INFO] Java Chassis::Dynamic Config::Apollo ............... SUCCESS [  0.287 s]
[INFO] Java Chassis::Foundations::Config CC ............... SUCCESS [  0.905 s]
[INFO] Java Chassis::Archetypes ........................... SUCCESS [  0.044 s]
[INFO] Java Chassis::Archetypes::JAXRS .................... SUCCESS [01:39 min]
[INFO] Java Chassis::Archetypes::POJO ..................... SUCCESS [  0.051 s]
[INFO] Java Chassis::Archetypes::Spring MVC ............... SUCCESS [  0.043 s]
[INFO] Java Chassis::Archetypes::Spring Boot Starter ...... SUCCESS [  0.041 s]
[INFO] Java Chassis::Archetypes::Spring Boot2 Starter ..... SUCCESS [  0.048 s]
[INFO] Java Chassis::Foundations::Spring Boot Common ...... SUCCESS [  0.164 s]
[INFO] Java Chassis::Spring Boot Starter::Parent .......... SUCCESS [  0.013 s]
[INFO] Java Chassis::Spring Boot Starter::Configuration ... SUCCESS [  0.079 s]
[INFO] Java Chassis::Spring Boot Starter::ServiceComb ..... SUCCESS [  1.746 s]
[INFO] Java Chassis::Spring Boot Starter::Provider ........ SUCCESS [  0.138 s]
[INFO] Java Chassis::Spring Boot Starter::Transport ....... SUCCESS [  0.288 s]
[INFO] Java Chassis::Spring Boot Starter::Discovery ....... SUCCESS [01:20 min]
[INFO] Java Chassis::Spring Boot Starter::Registry ........ SUCCESS [  0.312 s]
[INFO] Java Chassis::Spring Boot Starter::Spring Cloud Zuul SUCCESS [ 48.775 s]
[INFO] Java Chassis::Spring Boot Starter::Spring Cloud Zuul Zipkin SUCCESS [  2.698 s]
[INFO] Java Chassis::Spring Boot2 Starter::Parent ......... SUCCESS [  0.014 s]
[INFO] Java Chassis::Spring Boot2 Starter::Starter ........ SUCCESS [02:37 min]
[INFO] Java Chassis::Spring Boot2 Starter::Servlet ........ SUCCESS [01:31 min]
[INFO] Java Chassis::Spring Boot2 Starter::Standalone ..... SUCCESS [  0.210 s]
[INFO] Java Chassis::Spring Boot2 Starter::Discovery ...... SUCCESS [02:25 min]
[INFO] Java Chassis::Spring Boot2 Starter::Gateway ........ SUCCESS [ 23.755 s]
[INFO] Java Chassis::Spring Boot .......................... SUCCESS [  0.014 s]
[INFO] Java Chassis::Inspector ............................ SUCCESS [01:09 min]
[INFO] Java Chassis::Solutions ............................ SUCCESS [  0.008 s]
[INFO] Java Chassis::Solutions::BASIC ..................... SUCCESS [  0.105 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  40:40 min
[INFO] Finished at: 2019-10-24T16:49:01+08:00
[INFO] ------------------------------------------------------------------------

建立服务项目

准备项目

在 IDEA 中新建一个 maven 类型的项目，将 GroupI 名为为: org.apache.servicecomb.samples, artifactId 指定为：bmi-calculator。项目建立后，打开项目中的 pom.xml 文件，将其修改为以下内容:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.apache.servicecomb.samples</groupId>
    <artifactId>bmi-calculator</artifactId>
    <version>1.3.0-SNAPSHOT</version>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
        <java-chassis.version>${project.version}</java-chassis.version>
        <spring-boot-1.version>1.5.14.RELEASE</spring-boot-1.version>
    </properties>

    <repositories>
        <repository>
          <id>central</id>
          <url>http://central</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
          </snapshots>
        </repository>
    </repositories>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.apache.servicecomb</groupId>
                <artifactId>java-chassis-dependencies</artifactId>
                <version>${java-chassis.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot-1.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>org.hibernate.validator</groupId>
            <artifactId>hibernate-validator</artifactId>
        </dependency>
        <dependency>
            <groupId>javax.validation</groupId>
            <artifactId>validation-api</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>

        <dependency>
            <groupId>org.apache.servicecomb</groupId>
            <artifactId>spring-boot-starter-provider</artifactId>
        </dependency>

        <dependency>
            <groupId>org.apache.servicecomb</groupId>
            <artifactId>handler-flowcontrol-qps</artifactId>
        </dependency>
        <dependency>
            <groupId>org.apache.servicecomb</groupId>
            <artifactId>handler-bizkeeper</artifactId>
        </dependency>
        <dependency>
            <groupId>org.apache.servicecomb</groupId>
            <artifactId>handler-tracing-zipkin</artifactId>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.6.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>2.2.0.RELEASE</version>
                <configuration>
                    <fork>true</fork>
                    <mainClass>org.apache.servicecomb.samples.bmi.CalculatorApplication</mainClass>
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>repackage</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.apache.rat</groupId>
                <artifactId>apache-rat-plugin</artifactId>
                <version>0.13</version>
                <configuration>
                    <excludes>
                        <exclude>.travis.yml</exclude>
                        <exclude>**/*.md</exclude>
                        <exclude>**/target/*</exclude>
                        <!-- Skip the ssl configuration files -->
                        <exculde>**/resources/ssl/**</exculde>
                        <!-- Skip the protobuf files -->
                        <exclude>**/*.proto</exclude>
                        <!-- Skip the idl files -->
                        <exclude>**/*.idl</exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

保存以后， IDEA 会自动下载需要的第三方库。

构建 Calculator 服务

在源码中新建一个名为: org.apache.servicecomb.samples.bmi.service 的 package, 然后在里面新建一个名为: CalculatorService 的接口。该接口负责计算体质指数的行为。定义如下:

public interface CalculatorService {

    double calculate(double height, double weight);
}

在源码中新建一个名为: org.apache.servicecomb.samples.bmi.service.impl 的 package, 然后在里面新建一个名为：CalculatorServiceImpl 的类，该类是 CalculatorService 的实现类，负责实现具体的记录逻辑，对应的代码如下:

@Service
public class CalculatorServiceImpl implements CalculatorService {

    /**
     * {@inheritDoc}
     */
    @Override
    public double calculate(double height, double weight) {
        if (height <= 0 || weight <= 0) {
            throw new IllegalArgumentException("Arguments must be above 0");
        }
        double heightInMeter = height / 100;
        double bmi = weight / (heightInMeter * heightInMeter);
        return roundToOnePrecision(bmi);
    }

    private double roundToOnePrecision(double value) {
        return BigDecimal.valueOf(value).setScale(1, RoundingMode.HALF_UP).doubleValue();
    }
}

注意: 我们使用了 Spring 中的 @Service 对该类进行了注解，定义其为一个Spring中的服务组件

构建 Instance 服务

在 org.apache.servicecomb.samples.bmi.service 中再定义一个接口: InstanceInfoService, 代码如下:

public interface InstanceInfoService {

    String getInstanceId();
}

同样，在 org.apache.servicecomb.samples.bmi.service.impl 中新建 InstanceInfoService 接口的实现, 代码如下:

@Service
public class InstanceInfoServiceImpl implements InstanceInfoService {

    /**
     * {@inheritDoc}
     */
    @Override
    public String getInstanceId() {

        MicroserviceInstance instance = RegistryUtils.getMicroserviceInstance();
        if (instance == null) {
            throw new IllegalStateException(
                    "unable to find any service instances, maybe there is problem registering in service center?");
        }
        return instance.getInstanceId();
    }
}

该类的实现是从注册中心去找当前节点在注册中心中的唯一标识。

创建服务端点

服务端点用于生成服务契约，使得服务间能无缝进行通信

首先定义一个数据类，表示需要返回给服务调用者的数据结构。新建一个名为: org.apache.servicecomb.samples.bmi.vo 的 package。然后在其中定义一个名为: BMIViewObject 的类, 代码如下：

public class BMIViewObject {

    private double result;

    private String instanceId;

    private String callTime;

    public BMIViewObject(double result, String instanceId, Date now) {
        this.result = result;
        this.instanceId = instanceId;
        this.callTime = new SimpleDateFormat("HH:mm:ss").format(now);
    }

    public double getResult() {
        return result;
    }

    public void setResult(double result) {
        this.result = result;
    }

    public String getInstanceId() {
        return instanceId;
    }

    public void setInstanceId(String instanceId) {
        this.instanceId = instanceId;
    }

    public String getCallTime() {
        return callTime;
    }

    public void setCallTime(String callTime) {
        this.callTime = callTime;
    }
}

定义端点接口，新建一个名为: org.apache.servicecomb.samples.bmi.endpoint 的 package。然后在 package 中定义一个名为: CalculatorEndpoint 的接口。代码如下:

public interface CalculatorEndpoint {

    BMIViewObject calculate(double height, double weight);
}

定义端点实现类，新建一个名为: org.apache.servicecomb.samples.bmi.endpoint.impl 的 package。它实现了 CalculatorEndpoint 接口。代码如下:

@RestSchema(schemaId = "calculatorRestEndpoint")
@RequestMapping(path = "/")
public class CalculatorRestEndpoint implements CalculatorEndpoint {

    private final CalculatorService calculatorService;

    private final InstanceInfoService instanceInfoService;

    @Autowired
    public CalculatorRestEndpoint(CalculatorService calculatorService, InstanceInfoService instanceInfoService) {
        this.calculatorService = calculatorService;
        this.instanceInfoService = instanceInfoService;
    }

    @GetMapping(path = "/bmi")
    @Override
    public BMIViewObject calculate(double height, double weight) {

        String instanceId = instanceInfoService.getInstanceId();
        double bmiResult = calculatorService.calculate(height, weight);
        return new BMIViewObject(bmiResult, instanceId, new Date());
    }
}

其中，用 @RestSchema 和 @RequestMapping 注解了类，用 @GetMapping 修饰了方法 calculate。有 Spring Boot 基础的学员可以看出，通过这个类的定义方式和 Spring Boot 中用 @RestController 注解的类很相似。

构建启动类

在通常的SpringBoot应用中，需要定义一个启动类来执行服务程序的启动。代码如下：

@SpringBootApplication
@EnableServiceComb
public class CalculatorApplication {

    public static void main(String[] args) {
        SpringApplication.run(CalculatorApplication.class, args);
    }
}

定义服务配置文件

在项目的 src/main/resources 目录下新增一个名为： microservice.yaml 的文件。该文件是 ServiceComb 默认的微服务配置文件。文件内容如下:

APPLICATION_ID: bmi
service_description:
  # name of the declaring microservice
  name: calculator
  version: 0.0.1
servicecomb:
  service:
    registry:
      address: http://127.0.0.1:30100
  rest:
    address: 0.0.0.0:7777
  handler:
    chain:
      Provider:
        default: bizkeeper-provider

可以看到，文件指明了几个运行时的关键信息:

应用唯一标识(APPLICATION_ID)： bmi
服务的名称(name): calculator
注册服务器的地址: 本机的30100端口，接下来我们会通过 Docker 来运行该服务。
服务自身的监听地址和端口: 本机的 7777 端口

运行服务

启动注册中心

执行以下命令，拉取注册中心的镜像

1	docker pull servicecomb/service-center

拉起完成后，可以通过 docker images 命令查看本地镜像进行确认

1	docker images

系统显示

1 2	REPOSITORY TAG IMAGE ID CREATED SIZE servicecomb/service-center latest e02a181056c2 5 months ago 49.8MB

执行以下命令启动注册中心:

1	docker run --name service-center -d -p 30100:30100 servicecomb/service-center

启动完成后，可以用 docker ps 命令查看启动结果:

1 2	CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 1917ed3b4820 servicecomb/service-center "/opt/service-center…" 7 seconds ago Up 5 seconds 0.0.0.0:30100->30100/tcp service-center

运行 Calculator 服务

在 IDEA 中运行刚才建的 bmi-calculator 项目。可以看到在 Run TAB 中的输出如下:

2019-10-24 19:02:50.296  INFO 8493 --- [           main] org.apache.servicecomb.core.SCBEngine    : Status already changed to up.
2019-10-24 19:02:50.297  INFO 8493 --- [           main] org.apache.servicecomb.core.SCBEngine    : Service information is shown below:
service center: [http://127.0.0.1:30100]
config center: not exist
AppID: bmi
ServiceName: calculator
Version: 0.0.1
Environment: production
ServiceID: 08088b0d11f4dc26858875798d5467de098dea4f
InstanceID; d1ac38d2f64d11e9b64a0242ac110002

2019-10-24 19:02:50.297  INFO 8493 --- [           main] o.a.s.samples.bmi.CalculatorApplication  : Started CalculatorApplication in 8.797 seconds (JVM running for 9.936)
2019-10-24 19:02:50.421  INFO 8493 --- [worker-thread-3] o.a.s.s.c.h.ServiceRegistryClientImpl    : watching microservice 08088b0d11f4dc26858875798d5467de098dea4f successfully, the chosen service center address is 127.0.0.1:30100
2019-10-24 19:03:20.278  INFO 8493 --- [pty queue][31]]] o.a.s.s.task.ServiceCenterTaskMonitor    : sc task interval changed from -1 to 30

可以看到项目已经成功运行并注册到注册中心了。

验证服务

打开浏览器，比如 Chrome, 在地址栏输入以下地址

1	http://localhost:7777/bmi?height=120&weight=50

如果一切正常，可以看到浏览器中显示服务返回的结果

1	{"result":34.7,"instanceId":"d1ac38d2f64d11e9b64a0242ac110002","callTime":"19:17:40"}

下一步

在下一篇文章中，将介绍如何为 calculator 服务搭建配套的其它服务能力。