文档中心

微服务平台CSP开发指南

最近更新时间：

1 微服务平台开发指南

1.1 前提

需要将依赖的工具类库导入您开发环境的 Maven 私服中。工具类库和导入过程请参见 SDK 导入 Maven 仓库。

1.2 使用Spring Cloud开发应用

1.2.1 服务注册与发现

微服务平台 CSP 支持服务发现同时也提供实时健康检查，以防止将请求发往不健康的主机或服务实例。借助 CSP，您可以更容易的实现微服务治理。

1.2.1.1 前提条件

在开始开发前，请确保您已经完成以下工作。 

下载“Maven”并设置环境变量。 

配置 JDK 环境。 

Spring Boot 版本在 2.2.X.RELEASE 及 2.3.X.RELEASE 版本，Spring Cloud

2.2.2RELEASE 以上版本。 

Spring Boot 版本在 2.4 以上需要额外适配。

1.2.1.2 创建服务提供者

(1) 在本地创建服务提供者应用工程，添加依赖，开启服务注册与发现功能，并将注册中心指定为 CSP 平台。

(2) 创建命名为 csp-service-provider 的 Maven 工程。

(3) 在 pom.xml 文件中添加依赖。

< dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

<version>2.2.10.RELEASE</version>

</dependency>

<groupId>com.cecloud.csp</groupId>

<artifactId>spring-cloud-starter-cecloud-csp-discovery</artifactId>

<version>1.0.3.RELEASE</version>

</dependency>

(4) 在 src\main\java 下创建 Package com.csp.test。

(5) 创建启动类。

package com.csp.test;

Import org.springframework.boot.SpringApplication;

Import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication

@EnableDiscoveryClient

public class Application {

public static void main(String[] args) {

SpringApplication.run(Application.class, args);

}

(6) 在 Package com.csp.test.controller 中创建 TestController。

(7) 在 TestController 中，指定 URL mapping 为/echo/{string}，指定 HTTP 方法为 GET 返回字符串{string}。

package com.csp.test.controller;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RestController;

@RestController

public class TestController {

@RequestMapping(value = "/echo/{string}", method = RequestMethod.GET)

public String echo(@PathVariable String string) {

return string;

}

(8) 在 src\main\resources 路径下创建文件 bootstrap.yml，在 bootstrap.yml 中添加如下配置。

spring:

application:

name:demo-provide

server:

port:8080

spring.application.name: test-provide 服务名

server.port: 8080 服务端口

(9) 运行在 CSP 平台上的应用，可以直接在微服务治理 > 服务页面进行管理。

示例代码如下： csp-demo-provi der.zip （附件 1）

WX20230409-203303@2x.png

1.2.1.3 服务的消费者

(1) 在本地创建服务消费者应用工程，添加依赖，开启服务注册与发现功能，并将注册中心指定为 CSP 平台。

(2) 创建命名为 csp-service-consumer 的 Maven 工程。

(3) 在 pom.xml 文件中添加依赖。

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

<version>2.2.10.RELEASE</version>

</dependency>

<groupId>com.cecloud.csp</groupId>

<artifactId>spring-cloud-starter-cecloud-csp-discovery</artifactId>

<version>1.0.3.RELEASE</version>

</dependency>

(4) 在 src\main\java 下创建 Package com.csp.test。

(5) 创建启动类。

package com.csp.test;

import org.springframework.boot.SpringApplication;

import org.springframework.boot.autoconfigure.SpringBootApplication;

import org.springframework.cloud.client.discovery.EnableDiscoveryClient;

import org.springframework.cloud.openfeign.EnableFeignClients;

@SpringBootApplication

@EnableDiscoveryClient

@EnableFeignClients

public class ConsumerApplication {

public static void main(String[] args) {

SpringApplication.run(ConsumerApplication.class,args);

}

(6) 在 Package com.csp.test.controller 中创建 TestController。

@RestController

public class TestController {

@Autowired

private ProviderFeign providerFeign ;

@RequestMapping(value = "/echo-feign/{str}", method = RequestMethod.GET)

public String feign(@PathVariable String str) {

return "ProviderFeign return: " + providerFeign.echo(str);

}

(7) 需要使用 Feign 调用远程服务，参考如下 demo：

@EnableFeignClients

Feign client 代码

package com.csp.test.feign;

import org.springframework.cloud.openfeign.FeignClient;

import org.springframework.web.bind.annotation.PathVariable;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RequestMethod;

@FeignClient(name = "demo-provide")

public interface ProviderFeign {

@RequestMapping(value = "/echo/{str}", method = RequestMethod.GET)

String echo(@PathVariable("str") String str);

}

 Feign 客户端提供重试机制，默认只重试 GET 请求并且重试一次（参考配置如下）可自行在代码 yml 中自行设置自定义参数。更多可参考 Feign 官方文档。

### 请求处理的超时时间

ribbon:

# 等待请求响应的超时时间. 单位：ms

ReadTimeout: 5000

# 连接超时时间. 单位：ms

ConnectTimeout: 1000

# 是否对所有请求进行失败重试, 设置为 false, 让 feign 只针对 Get 请求进行重试.

OkToRetryOnAllOperations: false

# 同一台实例最大重试次数,不包括首次调用默认 0

MaxAutoRetries: 0

# 重试负载均衡其他的实例最大重试次数,不包括首次调用默认 1

MaxAutoRetriesNextServer: 2

 CSP 提供的 YAML 下线功能，Spring SDK 中有 spring-boot-actuator 依赖所以用户可以直接使用相关功能具体配置可参考如下并添加到代码 yml 中。

management:

endpoint:

shutdown:

enabled: true

endpoints:

web:

exposure:

include: "*"

(8) 在 src\main\resources 路径下创建文件 bootstrap.yml，在 bootstrap.yml 中添加如下配置。

spring:

application:

name:demo-consumer

server:

port:8081

1.2.1.4 打包及部署应用

(1) 添加 Maven 打包工具，配置如下：

<build>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-maven-plugin</artifactId>

<mainClass>com.csp.test.Application</mainClass>

</configuration>

<goals>

<goal>repackage</goal>

</goals>

</execution>

</executions>

</plugin>

</plugins>

</build>

(2) 将打包好的 Jar 程序包上传到 CSP 控制台，进行部署操作，无需关注额外配置。示例代码：csp-demo-consumer.zip（附件 2）

1.2.2 服务治理

1.2.2.1 前提条件

 开通 CSP 平台服务。

 请确保您的机器上已经安装了 Java 和 Maven。

1.2.2.2 创建 Demo 应用

(1) 登录 CSP 平台。

(2) 在左侧导航栏，选择“应用管理”，在“命名空间列表”页面创建命名空间 test_ns。

(3) 在“应用组”页面选中创建的命名空间 test_ns，创建应用组 test_group。

(4) 在应用页面选择创建的命名空间 test_ns，应用组 test_group，单击右上角“创建”，创建provider-8889，demo 示例如下：

csp-service-provider.zip（附件 3）

a. 在 SpringBoot 应用的 pom.xml 文件中引入如下依赖。

<groupId>com.cecloud.csp</groupId>

<artifactId>spring-cloud-starter-cecloud-csp-discovery</artifactId>

<version>-1.0.3.RELEASE</version>

</dependency>

<groupId>com.cecloud.csp</groupId>

<artifactId>spring-cloud-starter-cecloud-csp-config</artifactId>

<version>1.0.3.RELEASE</version>

</dependency>

<groupId>com.cecloud.csp</groupId>

<artifactId>spring-cloud-starter-cecloud-csp-gov</artifactId>

<version>1.0.2.RELEASE</version>

</dependency>

b. 打包并上传 SpringBoot 应用 Jar 包。

(5) 单击“创建”，就可以在应用页面对应的命名空间和应用组看到创建的应用 provider-8889。

(6) 单击“启动”后可以在“微服务治理 > 服务”页面根据命名空间 test_ns 看到应用对应的服务 service-provider。

1.2.2.3 创建流控规则

场景简介

本示例中，通过不断访问 service-provider 服务/test 接口，可以在“微服务治理 > 服务”页面，单击 service-provider 服务的“接口详情”看到/test 接口调用频繁，需对 service-provider 服务的/test 接口设置 QPS 为 2 的流控规则。

操作步骤

(1) 在“微服务治理 > 服务”页面，根据命名空间 test_ns 找到服务 service-provider。

(2) 单击服务 service-provider 后面的“接口详情”。

(3) 在该服务的“接口详情”页，单击“/test”，然后单击右上角的齿轮。

(4) 在新建流控规则对话框中，设置单机 QPS 阈值为 2，其他选项保持默认。

(5) 单击“新建”。

1.2.2.4 结果验证

在服务的接口详情页面，查看/test 接口的 QPS 数据。可以看到该资源的通过 QPS 指标降到 2。

1.2.3 配置管理

1.2.3.1 场景简介

CSP 提供了配置中心，使用 CSP 作为配置中心开发的应用无需修改任何代码，需要在应用管理里面新建命名空间和应用组。

部署到 CSP 后，即可使用 CSP 提供的配置中心。本文介绍如何开发对 Spring Cloud 微服务示例应用（包含一个 config-demo 服务）。

1.2.3.2 创建服务并且使用配置

(1) 在本地创建应用工程，添加依赖，开启服务配置功能。

(2) 创建命名为 csp-config 的 Maven 工程。

(3) 在 pom.xml 文件中添加依赖。

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

<version>2.2.10.RELEASE</version>

</dependency>

<groupId>com.cecloud.csp</groupId>

<artifactId>spring-cloud-starter-cecloud-csp-config</artifactId>

<version>1.0.3.RELEASE</version>

</dependency>

(4) 在 src\main\java 下创建 Package com.csp.test。

(5) 创建启动类。

package com.csp.test;

import org.springframework.boot.SpringApplication;

import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication

public class ConfigApplication {

public static void main(String[] args) {

SpringApplication.run(ConfigApplication.class);

}

(6) 在 Package com.csp.test.controller 中创建 TestController。

package com.csp.test.controller;

import com.csp.test.config.User;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.beans.factory.annotation.Value;

import org.springframework.cloud.context.config.annotation.RefreshScope;

import org.springframework.web.bind.annotation.GetMapping;

import org.springframework.web.bind.annotation.RestController;

@RestController

@RefreshScope

public class TestConfigController {

@Value("${config.maxNum}")

int maxNum;

@Value("${mysql.pwd}")

int pwd;

@Autowired

private User user;

@GetMapping("/test")

public String config(){

return String.valueOf(maxNum) +" "+ user.toString() +" "+ pwd;

}

package com.csp.test.config;

import org.springframework.boot.context.properties.ConfigurationProperties;

import org.springframework.cloud.context.config.annotation.RefreshScope;

import org.springframework.stereotype.Component;

@Component

@RefreshScope

@ConfigurationProperties(prefix ="config.user")

public class User {

private String name;

private String age;

public void setName(String name) {

this.name = name;

}

public void setAge(String age) {

this.age = age;

}

@Override

public String toString() {

return "User{" +

"name='" + name + '\'' +

", age='" + age + '\'' +

'}';

}

@RefreshScope 定时刷新

两种获取配置的模式：

 @Value("${config.maxNum}") 适用于获取单个配置。

 @ConfigurationProperties(prefix = "config.user") 适用于多个配置获取，注意需要添加对应值的 set 方法或者使用注解代替例如 lombok 的@Setter。

配置如下：

config:

user:

name:zhangsan

age:19

maxNum:100

(7) 在 src\main\resources 路径下创建文件 application.yml（或者 bootstarp.properties），在其中添加如下配置。

spring:

application:

name:demo

server:

port:8084

(8) 在 CSP 平台创建服务配置。可以到配置列表或者应用栏修改。

1.2.3.3 共享配置

场景简介

本部分介绍额外增加共享配置的具体配置步骤。

注意：

新增配置一定需要按照如下格式 xxxx.yaml 文件名.文件类型，例子 mysql.yaml 文件类型

（yaml/json/properties）。

例子 DataID:mysql.yaml Group:share 对应下面在工程配置文件里面新增如下配置。

创建共享配置的时候请查看应用配置属于什么类型务必保持一致。

操作步骤

(1) 在 CSP 新增配置。需要注意三个值的选择：命名空间、DataId、Group。

mysql.yaml(或者 mysql.yml)配置为：

mysql:

pwd:123456

(2) 新增配置的时候需要和应用所处的命名空间为同一个。

spring:

application:

cloud:

cecloud:

csp:

config:

file-extension: yaml

shared-configs[0]:

data-id: mysql.yaml

group: share

refresh:true

shared-configs[1]:

data-id: redis.yaml

group: share

refresh:true

server:

port:8084

(3) 配置样例工程代码。

demo-config.zip（附件 4）

(4) 配置所需要的 jar 包（请配置 Maven 仓库获取对应的 jar）。

1.2.4 低版本兼容

1.2.4 低版本兼容

限制与指导

 适用于 Spring Boot 2.1.x 版本。

 仅支持原生 SDK 功能，对应 spring-cloud-alibaba 2.1.1.RELEASE 版本。

操作步骤

将 1.2.1 及 1.2.2 步骤中的 pom.xml 文件中依赖做如下替换。

<groupId>com.cecloud.csp</groupId>

<artifactId>spring-cloud-starter-cecloud-csp-discovery</artifactId>

<version>2.1.1.RELEASE</version>

</dependency>

<groupId>com.cecloud.csp</groupId>

<artifactId>spring-cloud-starter-cecloud-csp-config</artifactId>

<version>2.1.1.RELEASE</version>

</dependency>

1.3 使用Dubbo开发应用

1.3.1 前提条件

 开通 CSP 平台服务。

 请确保您的机器上已经安装了 Java 和 Maven。

 建议使用 Dubbo 版本为 2.7.x 及以上版本。

1.3.2 示例工程

1.3.2.1 创建服务提供者

dubbo-consumer.zip（附件 5）

(1) 创建一个 Maven 工程，命名为 provider，在 pom.xml 文件中引入如下依赖：

<groupId>org.apache.dubbo</groupId>

<artifactId>dubbo-spring-boot-starter</artifactId

</dependency>

<groupId>com.cecloud.csp</groupId>

<artifactId>dubbo-registry-recos</artifactId>

<version>1.0.1.RELEASE</version>

</dependency>

<groupId>com.cecloud.csp</groupId>

<artifactId>spring-cloud-starter-cecloud-csp-config</artifactId>

<version>1.0.1.RELEASE</version>

</dependency>

<groupId>com.cecloud.csp</groupId>

<artifactId>spring-cloud-starter-cecloud-csp-gov</artifactId>，

<version>1.0.1.RELEASE</version>

<artifactId>csp-gov-dubbo-adapter</artifactId>

<groupId>com.cecloud.csp</groupId>

</exclusion>

</exclusions>

</dependency>

(2) 在 src\main\java 目录下创建 Package com.csp.cecloud.csp.provider。

(3) 创建启动类。

Package com.cecloud.csp.provider;

import org.springframework.boot.SpringApplication;

import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication

public class DubboProvider {

public static void main(String[] args) {

SpringApplication.run(DubboProvider.class, args);

}

(4) 创建接口 EchoService 作为 provider 提供给 consumer 的服务。

package com.cecloud.csp.provider;

public interface EchoService {

String echo(String name);

}

(5) 创建接口 EchoService 的实现类 EchoServiceImpl。

package com.cecloud.csp.provider;

import org.apache.dubbo.config.annotation.DubboService;

@DubboService(version = "1.0.0", group = "DUBBO")

public class EchoServiceImpl implements EchoService {

@Override

public String echo(String name) {

return "hello " + name;

}

(6) 在 src\main\resources 路径下创建文件 application.yml，在 application.yml 中添加如下配置。

server:

port:8089 #服务对外暴露端口

dubbo:

scan:

base-packages:com.cecloud.csp.provider #dubbo 扫描路径

application:

name:dubbo-spring-boot-provider #服务名称

1.3.2.2 创建服务消费者

dubbo-consumer.zip（附件 6）

(1) 与创建 provider 相同，创建一个 Maven 工程，命名为 consumer，在 pom.xml 文件中引入如下依赖：

<groupId>org.apache.dubbo</groupId>

<artifactId>dubbo-spring-boot-starter</artifactId>

</dependency>

<groupId>com.cecloud.csp</groupId>

<artifactId>dubbo-registry-recos</artifactId>

<version>1.0.1.RELEASE</version>

</dependency>

<groupId>com.cecloud.csp</groupId>

<artifactId>spring-cloud-starter-cecloud-csp-config</artifactId>

<version>1.0.1.RELEASE</version>

</dependency>

<groupId>com.cecloud.csp</groupId>

<artifactId>spring-cloud-starter-cecloud-csp-gov</artifactId>

<version>1.0.1.RELEASE</version>

<artifactId>csp-gov-dubbo-adapter</artifactId>

<groupId>com.cecloud.csp</groupId>

</exclusion>

</exclusions>

</dependency>

(2) 在 src\main\java 目录下创建 Package com.csp.cecloud.csp.provider 和com.csp.cecloud.csp.consumer。

(3) 创建启动类。

package com.cecloud.csp.consumer;

import org.springframework.boot.SpringApplication;

import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication

public class ConsumerApplication {

public static void main(String[] args) {

SpringApplication.run(ConsumerApplication.class, args);

}

(4) 在 com.csp.cecloud.csp.provider 创建与 provider 中相同的接口 EchoService。

package com.cecloud.csp.provider;

public interface EchoService {

String echo(String name);

}

(5) 在 Package com.csp.cecloud.csp.consumer.controller 中创建 TestController。

TestController 中，指定 URL mapping 为/echo

package com.cecloud.csp.consumer.controller;

import com.csp.cecloud.csp.provider.EchoService;

import org.apache.dubbo.config.annotation.DubboReference;

import org.springframework.web.bind.annotation.GetMapping;

import org.springframework.web.bind.annotation.RestController;

@RestController

public class TestController {

@DubboReference(check = false, version = "1.0.0", group = "DUBBO")

private EchoService echoService;

@GetMapping("/echo")

public String echo() {

return echoService.echo("dubbo");

}

(6) 在 src\main\resources 路径下创建文件 bootstrap.yml，在 bootstrap.yml 中添加如下配置。

server:

port: 8088

dubbo:

scan:

base-packages: com.cecloud.csp.provider

application:

1.3.2.3 部署应用

(1) 在 CSP 控制台“应用管理 > 应用”页，单击“创建”，打包并上传 Dubbo 应用 jar 包，包括 provider 与 consumer。

(2) 在“应用管理 > 应用”页面，找到上一步创建的应用，单击应用，再进入版本管理界面，单击“新建版本”，选择以时间作为版本号，上传 jar 包。

(3) 在“应用管理 > 应用”页面，单击“部署”，选择上一步按时间生成的版本号，provider 输入应用端口 8089，consumer 输入应用端口号 8088，单击“提交”。

(4) 单击“启动”后可以在“微服务治理 > 服务”页面查看应用对应的服务。

1.3.2.4 tomcat 版本支持

 tomcat10 war 包改造。

CSP 当前支持 tomcat8/9/10，应用从 tomcat9 及以下升级到 tomcat10 需要进行改造，未经改造直接部署 tomcat10，只能看到 tomcat 的启动日志，看不到业务注册日志。由于 JavaEE 改为 Jakarta EE，javax 的包全都换成 jakarta。tomcat9 以及之前的版本需要使用工具来转换一下。工具链接是：https://tomcat.apache.org/download-migration.cgi。经过转换的 war 包运行是可以看到注册过程的。

 tomcat10 监控支持问题。

当前的监控 Agent 版本为 8.8.0，支持 tomcat7/8/9 版本，tomcat10 对 HTTP 服务暂不支持，因此，tomcat10 的 war 包部署进来，会看不到 rest 接口相关数据（包括链路追踪和应用监控数据）、JVM 数据可以正常监控。

1.4 如何将应用迁移到CSP

1.4.1 注册中心迁移

场景简介

CSP 平台提供了商用化的注册中心，部署到 CSP 后，即可使用 CSP 提供的共享注册中心。

已经接入 Consul 服务注册与发现的应用，只需要修改 pom.xml 依赖，就可以将服务接入 CSP 服务注册发现中心。

操作步骤

(1) 接入 SpringCloud 框架体系，然后额外添加 pom.xml。

<groupId>com.cecloud.csp</groupId>

<artifactId>spring-cloud-starter-cecloud-csp-discovery</artifactId>

<version>1.0.3.RELEASE</version>

</dependency>

(2) 接入 Dubbo 框架体系，额外添加 pom.xml。

<groupId>com.cecloud.csp</groupId>

<artifactId>dubbo-registry-recos</artifactId>

<version>1.0.1.RELEASE</version>

</dependency>

(3) 替换完成后即迁移成功。

1.4.2 配置中心迁移

场景简介

CSP 平台支持配置的编辑、存储、分发、变更管理、历史版本管理，实时更新，客户端 SDK 会在本地生成配置的快照。当客户端无法连接到 CSP 平台时，可以使用配置快照显示系统的整体容灾能力。

操作步骤

(1) 接入 SpringCloud/Dubbod 框架体系，然后额外添加 pom.xml。

<groupId>com.cecloud.csp</groupId>

<artifactId>spring-cloud-starter-cecloud-csp-config</artifactId>

<version>1.0.3.RELEASE</version>

</dependency>

(2) @RefreshScope 定时刷新。

两种获取配置的模式：

 @Value("${config.maxNum}") 适用于获取单个配置。

 @ConfigurationProperties(prefix = "config.user")适用于多个配置获取，注意需要添加对应值的 set 方法或者使用注解代替例如 lombok 的@Setter。

1.5 如何进行本地化调试

CSP 支持使用 Nacos 工具进行本地化开发，请下载 Nacos 并在您本地环境运行，即可进行代码的运行及联调测试，测试完成后可直接在微服务平台进行部署运行。

spring:

application:

cloud:

cecloud:

csp:

discovery:

server-addr: 127.0.0.1 #nacos 提供的注册中心地址

group: test #nacos 组

namespace: edb0a562-ded4-4231-xxxxxxx-xxxx-xxx #nacos 命名空间

config:

server-addr: 127.0.0.1 #nacos 提供的注册中心地址

group: test #组

namespace: edb0a562-ded4-4231-xxxxxxx-xxxx-xxx #命名空间

prefix: springcloud-jar-provider-config

file-extension: yaml

shared-configs[0]:

data-id: mysql.yaml

group: share

refresh: true

server:

port: 8089

意见反馈

文档内容是否对您有帮助？

如您有其他疑问，您也可以通过在线客服来与我们联系探讨在线客服