配置中心

模块简介

配置中心模块是 Spring Cloud Tencent 最核心的模块之一，实现了 Spring Cloud 的 PropertySourceLocator 和 ConfigDataLoader 接口。在应用启动阶段，Spring Cloud 会调用相关接口从 Polaris 服务端获取配置文件并加载到 Spring 上下文里。通过 Spring Boot 标准的 @Value，@ConfigurationProperties 注解即可获取配置内容。

快速入门

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

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

第一步：引入 Polaris 服务端

请参考安装北极星服务端

第二步：引入动态配置依赖

参考 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>${the.latest.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

引入 Spring Cloud Tencent Config Starter

方式一：只引入 spring-cloud-starter-tencent-polaris-config

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

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

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

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

在您项目的 application.yml 配置文件中加入以下配置内容。

1. 配置 Polaris 配置中心地址

如果您使用的北极星配置中心和注册中心是同一套北极星集群，则只需配置 spring.cloud.polaris.address 即可。

如果您部署了两套北极星集群，分别用于注册中心和配置中心，则 spring.cloud.polaris.address 用于指定注册中心集群的地址，spring.cloud.polaris.config.address 用于指定配置中心的地址。

如下所示：

spring:
  application:
    name: ${application.name}
  cloud:
    polaris:
      address: grpc://${修改为第一步部署的 Polaris 服务地址}:8091 # 必填
      namespace: default # 全局 namespace 参数
      config:
        address: grpc://${独立的配置中心}:8093 # 选填，只有在配置中心和注册中心是两个不同的地址时才需要配置
        auto-refresh: true # 选填，当配置发布后，动态刷新 Spring 上下文，默认值为 true

2. 注入配置文件

我们推荐的最佳实践是在北极星管控端创建一个名为当前应用名（ ${spring.application.name}）的配置分组，Spring Cloud Tencent Config 会自动注入当前应用名分组下的

application-${activeProfile}.properties
application-${activeProfile}.yml
application-${activeProfile}.yaml
application.properties
application.yml
application.yaml
bootstrap-${activeProfile}.properties
bootstrap-${activeProfile}.yml
bootstrap-${activeProfile}.yaml
bootstrap.properties
bootstrap.yml
bootstrap.yaml

优先级从上到下越来越低。与此同时，远端配置优先级大于本地配置优先级。优先级高的配置覆盖优先级低的配置。

自动注入以上配置文件符合 Spring Boot 的规范，能够满足绝大部分应用场景了。

只有当您需要注入额外自定义的配置文件时，才需要在 application.yml 里配置 spring.cloud.polaris.config.groups，如下所示：

spring:
  cloud:
    polaris:
      config:
        groups:
          - name: ${spring.application.name} # 选填，注入自定义配置的配置分组
            files: [ "config/config1.properties", "config/config2.yml" ] # 注入自定义配置文件列表，当 key 冲突时，排在前面的配置文件优先级高于后面

第四步：代码里使用配置

1. 通过 `@Value` 注入

@Value("${timeout:1000}")
private int timeout;

2. 通过 `@ConfigurationProperties` 注入

@Component
@ConfigurationProperties("datasource")
@RefreshScope
public class DataSourceProperties {

	private String jdbcUrl;
	private String username;
	private String password;

	public String getJdbcUrl() {
		return jdbcUrl;
	}

	public void setJdbcUrl(String jdbcUrl) {
		this.jdbcUrl = jdbcUrl;
	}

	public String getUsername() {
		return username;
	}

	public void setUsername(String username) {
		this.username = username;
	}

	public String getPassword() {
		return password;
	}

	public void setPassword(String password) {
		this.password = password;
	}

	@Override
	public String toString() {
		return "jdbcUrl='" + jdbcUrl + '\'' +
				", username='" + username + '\'' +
				", password='" + password + '\'';
	}
}

第五步：在北极星控制台添加配置文件

1. 创建 `Namespace`

Namespace 为北极星里核心的概念，通过 Namespace 逻辑隔离资源，例如通常用于标识不同的环境、不同的集群。

注意这里需要和应用配置中的命名空间保持一致！

2. 创建配置文件分组

北极星的配置文件分组概念为一组配置文件的集合，推荐把应用名作为一个分组名，例如在我们的示例中，新建一个 QuickstartCalleeService 的分组。把 QuickstartCalleeService 应用的配置文件都放在QuickstartCalleeService 分组下，这样便于配置管理。

3. 创建并发布配置文件

北极星配置中心的控制台，配置文件名可以通过 / 来按树状目录结构展示，树状结构可以清晰的管理配置文件。例如一个应用下分不同的模块，每个模块都有独立的一组配置文件，则可以创建 config/callee.properties。

注意：配置文件名强烈建议带文件后缀，例如 .properties、.yaml、.yml等。因为客户端会通过文件名后缀来解析文件内容，如果客户端发现不认识的后缀名则默认当做 .yaml 文件处理。

配置好的实例如下图所示：

第六步：启动应用

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

第七步：实现动态刷新配置能力

开启动态刷新能力

默认开启配置动态刷新能力。代码中按照开源 Spring Cloud 的方式编写动态刷新配置即可。

关闭动态刷新能力

在 application.yml 里配置 spring.cloud.polaris.config.auto-refresh=false

拓展使用

自定义配置监听器

方式一：使用 SCT 的事件回调机制

1.6.0 版本(包含)之后，新增了配置变更回调事件能力。可通过注解@PolarisConfigKVFileChangeListener实现针对指定的配置属性名称或者属性前缀进行监听，配置发生变更时会触发方法回调。

注意：目前只支持 KV 结构的配置文件监听

@Component
public final class PersonConfigChangeListener {

	/**
	 * PolarisConfigKVFileChangeListener Example .
	 * @param event instance of {@link ConfigChangeEvent}
	 */
	@PolarisConfigKVFileChangeListener(interestedKeyPrefixes = "datasource")
	public void onChange(ConfigChangeEvent event) {
		Set<String> changedKeys = event.changedKeys();

		for (String changedKey : changedKeys) {
			System.out.printf("%s = %s \n", changedKey, event.getChange(changedKey));
		}
	}

}

方式二：使用 Spring Boot 的事件机制

1.8.0 版本之后，可通过 Spring Boot 标准事件机制来监听配置的变更，代码如下所示：

@Component
public class PersonConfigChangeSpringListener implements ApplicationListener<ConfigChangeSpringEvent> {

	@Override
	public void onApplicationEvent(ConfigChangeSpringEvent event) {
		for (String key : event.changedKeys()) {
			System.out.println("Change Key = " + key + ", info = " + event.getChange(key));
		}
	}
}

支持 Spring Config Data

SCT 2021 及以上版本支持了标准的 Spring Config Data 方式注入配置文件。同样的 SCT 默认会注入 application.yml、application-${activeProfile}.yml、application.yaml、application-${activeProfile}.yaml、bootstrap.yml、bootstrap-${activeProfile}.yml，除此之外可以通过以下配置注入额外的配置文件。

spring
  config:
    import:
      - optional:polaris
      - optional:polaris:test.yml
      - optional:polaris:configdataexample:test.yml
      - optional:polaris:config/bootstrap.yml

格式说明

optional:${数据来源，固定值 polaris}:${配置分组名：缺省值为当前应用名}:${配置文件名}

Actuator Endpoint

Spring Cloud Tencent 扩展了 Spring Boot 标准的 Actuator 能力，通过 Actuator 接口，可以实时查询当前运行实例内存里配置文件内容，便于排查问题。详细可以参考: Actuator Endpoint 扩展

本地开发模式（1.8.0+版本）

在某些场景下，期望使用本地的配置文件而不是从远端的北极星服务获取配置。例如：

当前开发环境处于一个没有网络的环境，飞机上、游轮上等
避免修改北极星服务端的配置从而影响其它环境的配置

1.8.0 版本之后，动态配置模块将会在本地 ./polaris/backup/config 目录下缓存从北极星服务端获取的所有配置文件。SCT 配置 spring.cloud.polaris.config.data-source=local 参数即可切换到本地模式（从 ./polaris/backup/config 读取配置）。此时如果您需要修改配置，则只需要修改 ./polaris/backup/config 下的配置文件即可。

注意：修改配置文件时需要同时增加版本号，因为需要通过版本号来做乐观锁，只有在版本号增大时，才认为配置文件有修改

另外，您需要自定义本地文件目录可以通过 spring.cloud.polaris.config.local-file-root-path 配置项指定根目录。

单配置项刷新（2.0.0.0+版本）

配置刷新支持细粒度区分，当变更配置 key 列表涉及 @RefreshScope 相关的 key。才通过重新构建整个 Spring Context 的方式重建 Bean，否则只需要反射更新。具体行为如下：

refresh_context 刷新方式(默认)
- 有 RefreshScope 相关的配置 key
  - ConfigurationProperties：反射更新
  - Refresh Scope + @Value：重建对象
  - 纯 @Value：不动态更新
- 无 RefreshScope 相关的配置 key
  - ConfigurationProperties ：反射更新
  - Refresh Scope + @Value：不刷新
  - 纯 @Value：不动态更新
reflect 刷新方式
- 有 RefreshScope 相关的配置 key
  - ConfigurationProperties：反射更新
  - Refresh Scope + @Value：重建对象
  - 纯 @Value：反射更新
- 无 RefreshScope 相关的配置 key
  - ConfigurationProperties：反射更新
  - Refresh Scope + @Value：不刷新
  - 纯 @Value：反射更新

RefreshScope 相关的配置 key 的类型

class 注解定义 bean （@RestController、@Service、 @Configuration 等），@RefreshScope 在 class 上。该类下所有 @Value 注解涉及的配置 key 都是 RefreshScope 相关的配置 key

@Component
@RefreshScope
private static class ValueTest {
	@Value("${timeout:1000}")
	private int timeout;
	// ignore setter getter
}

通过 @Bean 和 @RefreshScope 定义 bean，bean 的类所有 @Value 注解涉及的配置 key 都是 RefreshScope 相关的配置 key

@Configuration
public class TestConfig {
	@Bean
	@RefreshScope
	public TestBean testBean() {
		return new TestBean();
	}
}

class TestBean {
	@Value("${test.bean.name:}")
	private String name;
	// ignore setter getter
}

通过 @Bean 和 @RefreshScope 定义 bean，参数有 @Value 标注。@Value 注解涉及的配置 key 是 RefreshScope 相关的配置 key

@Configuration
public class TestConfig {
	@Bean
	@RefreshScope
	public TestBean testBean(@Value("${test.param.name:}") String name) {
		return new TestBean(name);
	}
}

通过 @Bean 和 @RefreshScope 定义 bean，bean 的类的 setter 方法存在 @Value 注解。 @Value 注解涉及的配置 key 都是 RefreshScope 相关的配置 key

@Configuration
public class TestConfig {
	@Bean
	@RefreshScope
	public TestBean testBean() {
		return new TestBean();
	}
}
class TestBean {
	private int timeout;
	@Value("${test.bean.timeout:0}")
	public void setTimeout(int timeout) {
		this.timeout = timeout;
	}
	// ignore getter
}

通过 @Bean 和 @RefreshScope 定义 bean，参数为 ConfigurationProperties 对象。ConfigurationProperties 对象涉及的配置 key 都是 RefreshScope 相关的配置 key

@Configuration
public class TestConfig {
	@Bean
	@RefreshScope
	public TestBean testBean(TestBeanProperties testBeanProperties) {
		return new TestBean(testBeanProperties.getName());
	}
}
@Component
@ConfigurationProperties("test.properties")
class TestBeanProperties {
	private String name;
	private HashMap<String, String> map;
	private ArrayList<String> list;
	// ignore setter getter
}

通过 @Bean 和 @RefreshScope 定义 bean，使用类里的 ConfigurationProperties 对象。ConfigurationProperties 对象涉及的配置 key 都是 RefreshScope 相关的配置 key

@Configuration
public class TestConfig {
	@Autowired
	private TestBeanProperties testBeanProperties;
	@Bean
	@RefreshScope
	public TestBean testBean() {
		return new TestBean(testBeanProperties.getName());
	}
}

完整的配置参数

配置项Key	起始版本	默认值	是否必填	配置项说明
spring.cloud.polaris.config.enabled		true	否	是否开启配置模块
spring.cloud.polaris.config.address		无	否	北极星服务端地址，可不填。当配置中心和注册中心为不同的地址时候才需要填写
spring.cloud.polaris.config.port		8093	否	北极星配置中心的端口号，默认为 8093
spring.cloud.polaris.config.auto-refresh		true	否	是否动态更新配置
spring.cloud.polaris.config.groups		无	否	从北极星服务端获取自定义的配置文件
spring.cloud.polaris.config.connect-remote-server		true	否	是否连接到远程北极星配置中心服务端，当没有网络环境或者无北极星服务端时可关闭
spring.cloud.polaris.config.refresh-type	1.7.0	REFRESH_CONTEXT	否	动态刷新配置的实现方式。 `refresh_context` 为 Spring Cloud 默认的方式, `reflect` 为 SCT 实现的通过反射的机制实现的，优点是无需重建 Bean
spring.cloud.polaris.config.shutdown-if-connect-to-config-server-failed	1.7.0	true	否	应用启动时检查配置中心的后端连接，如果连接配置中心失败，是否需要终止应用启动（true 为终止启动）
spring.cloud.polaris.config.data-source	1.8.0	polaris	否	动态配置数据源类型，当前支持 polaris 和 local 两种模式，默认为 polaris。 - polaris: 从北极星服务端获取配置文件。 - local: 从本地磁盘读取配置文件
spring.cloud.polaris.config.local-file-root-path	1.8.0	./polaris/backup/config	否	当 `spring.cloud.polaris.config.data-source=local` 时，可设置本地磁盘读取配置文件根目录
spring.cloud.polaris.config.crypto.enabled	1.13.0	true	否	是否开启配置加解密，参考文档
spring.cloud.polaris.config.internal-enabled	2.0.0.0	true	否	是否默认注入`application.yml`、`application-${activeProfile}.yml`、`application.yaml`、`application-${activeProfile}.yaml`、`bootstrap.yml`、`bootstrap-${activeProfile}.yml`

您在使用过程中遇到任何问题，请提 Issue 或者加入我们的开发者群告诉我们，我们会在第一时间反馈
Spring Cloud Tencent 社区期待您的加入，一个 Star、PR 都是对我们最大的支持

项目介绍
使用指南
最佳实践
- 多注册与多发现
开发文档
- 参与共建
学习资料
- B站 Spring Cloud Tencent 微服务系列教程 @北冥
- 腾讯正式开源Spring Cloud Tencent，打造一站式微服务解决方案

配置中心

目录

模块简介

快速入门

第一步：引入 Polaris 服务端

第二步：引入动态配置依赖

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

1. 配置 Polaris 配置中心地址

2. 注入配置文件

第四步：代码里使用配置

1. 通过 @Value 注入

2. 通过 @ConfigurationProperties 注入

第五步：在北极星控制台添加配置文件

1. 创建 Namespace

2. 创建配置文件分组

3. 创建并发布配置文件

第六步：启动应用

第七步：实现动态刷新配置能力

开启动态刷新能力

关闭动态刷新能力

拓展使用

自定义配置监听器

方式一：使用 SCT 的事件回调机制

方式二：使用 Spring Boot 的事件机制

支持 Spring Config Data

Actuator Endpoint

本地开发模式（1.8.0+版本）

单配置项刷新（2.0.0.0+版本）

完整的配置参数

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

1. 通过 `@Value` 注入

2. 通过 `@ConfigurationProperties` 注入

1. 创建 `Namespace`