Skip to content

Spring Cloud Tencent Discovery 使用文档

Haotian Zhang edited this page Sep 8, 2024 · 41 revisions

目录

模块简介

服务注册发现模块是 Spring Cloud Tencent 最核心的模块之一,实现了标准的 Spring Cloud Discovery SPI 接口 (PolarisDiscoveryClient.java)。任何一个 Spring Cloud 标准应用都能快速平滑的使用 Spring Cloud Tencent Discovery。

Spring Cloud Tencent Discovery 背后对接的是社区流行的统一服务发现和治理平台 Polaris

快速入门

本章节将介绍如何在 Spring Cloud 项目中使用 Spring Cloud Tencent Discovery 的功能。

完整 Example 代码请参考:quickstart-example

第一步:引入 Polaris 服务端

请参考 安装北极星服务端

第二步:引入服务注册与发现依赖

  1. 参考 Spring Cloud Tencent 版本管理 文档获取最新的版本号,引入 Spring Cloud Tencent Bom

注意: Spring Cloud 、 Spring Boot 、 Spring Framework 之间有严格的版本对应关系,在 Spring Cloud Tencent 版本管理 文档中有详细罗列版本兼容性关系。请您在引入 Spring Cloud Tencent 版本时,根据项目 Spring Boot 和 Spring Framework 的版本,选择合适的 Spring Cloud Tencent 版本。

例如:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tencent.cloud</groupId>
            <artifactId>spring-cloud-tencent-dependencies</artifactId>
            <version>1.8.2-Hoxton.SR9</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
  1. 引入 Spring Cloud Tencent Discovery Starter

方式一: 只引入 spring-cloud-starter-tencent-polaris-discovery

<dependency>
    <groupId>com.tencent.cloud</groupId>
    <artifactId>spring-cloud-starter-tencent-polaris-discovery</artifactId>
</dependency>

方式二:通过 spring-cloud-starter-tencent-all 引入 sct 所有 starters

<dependency>
    <groupId>com.tencent.cloud</groupId>
    <artifactId>spring-cloud-starter-tencent-all</artifactId>
</dependency>

如果使用 Spring Cloud 2021 版本,还需要添加如下依赖:

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

第三步:增加相关配置文件

  1. 在您的 bootstrap.yml 配置文件中加入以下配置内容
spring:
  application:
    name: ${application.name}
  cloud:
    polaris:
      address: grpc://${修改为第一步部署的 Polaris 服务地址}:8091
      namespace: default

第四步:启动应用

应用成功启动后,到 Polaris 控制台查看服务注册信息。如下图所示:

image

到此接入 Spring Cloud Tencent Discovery 即已完成。

第五步:服务调用

在 Spring Cloud 中可通过 RestTemplate 或者 Feign 发起服务调用。无论通过哪种方式,都需要引入 spring-cloud-starter-tencent-polaris-discovery 依赖,才能从北极星获取服务提供者的地址信息。

<dependency>
    <groupId>com.tencent.cloud</groupId>
    <artifactId>spring-cloud-starter-tencent-polaris-discovery</artifactId>
</dependency>

RestTemplate

只需要在实例化 RestTemplate 的地方加上 @LoadBalanced 注解即可。

@Bean
@LoadBalanced
public RestTemplate restTemplate() {
	return new RestTemplate();
}

Feign

通过 Feign 框架调用,无需做任何适配工作,按照标准的 Feign 方式即可。实际代码可参考 polaris-discovery-example

拓展使用

元数据

元数据定义

服务实例通常带有一系列的标签信息,例如实例所属的机房信息、地域信息、环境信息等,这些信息统称为服务实例的元信息。实例注册到注册中心时,会带上自身的元数据信息。当消费方从注册中心获取到实例时,既可以同时获取到每个实例的元信息。

image

元数据来源

来源一:项目里的配置文件

Spring Cloud 项目里的 application.yml 中配置以下内容:

spring:
  cloud:
    tencent:
      metadata:
        content:
          idc: shanghai
          env: dev1

应用在启动注册时,会自动读取配置文件并带上 idc=shanghaienv=dev1 两个元数据信息。

通过配置文件的方式为最直接的方式,但是这种方式有一个最大的弊端,就是设置不同元数据值时需要重新编译打包。本质上的原因就是:大部分的元数据信息属于部署环境的信息或者叫机器的信息,而不是应用静态代码的信息。

来源二:应用启动参数

众所周知,Spring Boot 应用配置文件定义的配置项都可以通过 -D 启动参数覆盖,例如通过以下方式覆盖 env 值为 dev2 :

Java -jar -Dspring.cloud.tencent.metadata.content.env=dev2  demo.jar

通过启动参数的方式,可以在启动时动态修改元数据信息,而不用重新打包,从而解决了方式一的弊端。

但是这种方式也有弊端,就是谁负责修改启动脚本,加上 -D 参数呢?

大部分情况下,Java -jar 启动命令都放在项目里的 start.sh 脚本里,那也就是说,每次需要增加 -D 参数都要修改 start.sh,这本身也会增加维护成本。

来源三:环境变量

环境变量的方式则完全跟运行的应用解耦,是完完全全的机器信息。Spring Cloud Tencent 约定了前缀 SCT_METADATA_CONTENT_ 的环境变量为应用的元数据信息。例如:

SCT_METADATA_CONTENT_IDC=shanghai
SCT_METADATA_CONTENT_ENV=dev1

应用在启动时,则会自动携带 IDC=shanghaiENV=dev 的元数据。

通过环境变量的方式,paas 平台在拉起一台虚拟机或者一个容器 Pod 时,只需要设置相应的环境变量即可。而应用自身无需做任何其它事情。

以上几种方式,可以通过查看启动日志确认是否正确打标:

grep "Loaded static metadata info" xx.log

来源四:自定义实现 SPI

前面三种方式为 SCT(Spring Cloud Tencent 的缩写) 内置的方式,但是并不一定符合每个公司自己的规范或者实现。例如:

  • 把元数据放到机器上的某一个配置文件里,例如 /etc/metadata
  • 启动时,调用 CMDB 的接口获取元信息

所以 SCT 定义了 InstanceMetadataProvider SPI,方便用户自己实现元数据来源。SCT 在注册前,回调 SPI 获取元数据信息,并注册到注册中心。

控制台调整实例的权重、下线实现等操作

如下图所示,可以在控制台上对实例进行一系列管控操作,例如隔离实例,调整实例权重等。

心跳上报

Spring Cloud Tencent 会异步定时 5s 向北极星服务端发送心跳请求,表示当前实例是存活的状态。为了更准确的表达“健康”的语义,用户可以配置 spring.cloud.polaris.discovery.health-check-url 配置项。配置 health-check-url 之后,Spring Cloud Tencent 在向北极星服务端发送心跳之前,先自检一下健康状态,如果健康才会发送心跳请求。

心跳上报时间间隔可通过 spring.cloud.polaris.discovery.heartbeat-interval 参数调整,默认为 5s。

Actuator Endpoint

Spring Cloud Tencent 扩展了 Spring Boot 标准的 Actuator 能力。通过 Actuator 接口,可以实时查询当前运行实例内存里存储的服务实例列表,便于排查问题。详细可以参考: Actuator Endpoint 扩展

服务注册信息个性化(1.12.0+)

从1.12.0版本开始,支持服务注册前,针对 PolarisRegistration 对象进行个性化修改。例如添加元数据、修改注册端口号等。

具体开发方式为,实现 PolarisRegistrationCustomizer 接口。

自定义参数

除了控制台页面可以调整参数以外,Spring Cloud Tencent Discovery 提供了很多自定义参数满足各类场景。以权重随机策略为例,您可以在项目里的 bootstrap.yml 配置文件里配置 spring.cloud.polaris.weight 既可以调整权重值(默认为 100)。

完整的的配置列表如下

配置项Key 默认值 是否必填 初始版本 配置项说明
spring.cloud.polaris.address Polaris 后端地址
spring.cloud.polaris.namespace default 服务所在的命名空间名称
spring.cloud.polaris.service ${spring.application.name} 服务名称
spring.cloud.polaris.local-ip-address 注册的 IP 地址,默认情况下 Spring Boot 会自动获取 IP 地址无需指定 IP 地址,当需要自定义 IP 地址(比如内网 IP 映射等情况)时才需要设置
spring.cloud.polaris.local-port 1.11.0 注册的端口号,默认情况下 Spring Boot 会自动获取 IP 地址无需指定端口号,当需要自定义端口号(比如内网端口映射等情况)时才需要设置
spring.cloud.polaris.discovery.enabled true 是否开启服务发现
spring.cloud.polaris.discovery.register true 是否开启服务注册
spring.cloud.polaris.discovery.health-check-url 健康检查 url,向北极星服务端发送心跳前回调健康检查 url 判断当前服务是否健康,只有健康才会发送心跳
spring.cloud.polaris.discovery.token 鉴权 Token
spring.cloud.polaris.discovery.version null 微服务版本
spring.cloud.polaris.discovery.protocol null 微服务协议类型
spring.cloud.polaris.discovery.weight 100 微服务权重
spring.cloud.polaris.discovery.service-list-refresh-interval 60000 服务列表刷新间隔(毫秒)
spring.cloud.polaris.discovery.heartbeat-interval 5000 1.7.0 心跳间隔(毫秒)
spring.cloud.polaris.logging.path 1.13.0 日志输出绝对路径
Clone this wiki locally