tencent cloud

注册配置治理

文档注册配置治理Polaris（北极星）Java 应用开发Spring Cloud 应用开发配置管理

配置管理

PDF
聚焦模式
字号
最后更新时间： 2026-05-08 14:26:44

操作场景

本文介绍在本地开发 Java 应用，通过 Spring Cloud Tencent 的方式接入北极星网格，使用配置管理功能。

前提条件

在开始开发前，请确保您已经下载安装了 Java 和 Maven。

操作步骤

步骤1：引入配置管理依赖

1.1 引入 spring cloud tencent 依赖

修改应用根目录下的 pom.xml，添加dependencyManagement：
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tencent.cloud</groupId>
            <artifactId>spring-cloud-tencent-dependencies</artifactId>
            <version>${version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
注意：
请根据项目 Spring Boot 和 Spring Framework 的版本，选择合适的 Spring Cloud Tencent 版本。

1.2 引入 spring cloud tencent starter

方式一：通过spring-cloud-starter-tencent-all引入 sct 所有 starters。
<dependency>
    <groupId>com.tencent.cloud</groupId>
    <artifactId>spring-cloud-starter-tencent-all</artifactId>
</dependency>
方式二：只引入spring-cloud-starter-tencent-polaris-config。
<dependency>
    <groupId>com.tencent.cloud</groupId>
    <artifactId>spring-cloud-starter-tencent-polaris-config</artifactId>
</dependency>

步骤2：增加配置文件

2.1 配置 Polaris（北极星） 配置中心地址

1. 在项目的 main/resources 目录下创建 application.yml 文件。
2. 在 application.yml 文件中配置应用名、Polaris（北极星）服务端地址等信息。
如果北极星配置中心和注册中心是同一套北极星集群，则只需配置spring.cloud.polaris.address即可。
如果部署了两套北极星集群，分别用于注册中心和配置中心，则需配置spring.cloud.polaris.address用于指定注册中心集群的地址，配置spring.cloud.polaris.config.address用于指定配置中心的地址。如下所示
3. spring.config.import=optional:Polaris需要填写。
spring:
  application:
    name: ${application.name}
  config:
    import: optional:polaris
  cloud:
    polaris:
      address: grpc://${修改为 Polaris 服务地址}:8091 # 必填
      namespace: default # 全局 namespace 参数
      config:
        address: grpc://${独立的配置中心}:8093 # 选填，只有在配置中心和注册中心是两个不同的地址时才需要配置
        auto-refresh: true # 选填，当配置发布后，动态刷新 Spring 上下文，默认值为 true

2.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 的规范，能够满足绝大部分应用场景了。只有当您需要注入额外自定义的配置文件时，才需要在yml里配置 spring.cloud.polaris.config.groups，如下所示：
spring:
  cloud:
    polaris:
      config:
        groups:
          - name: ${spring.application.name} # 选填，注入自定义配置的配置分组
            files: [ "config/application.properties", "config/bootstrap.yml" ] # 注入自定义配置文件列表，当 key 冲突时，排在前面的配置文件优先级高于后面

步骤3：在代码中使用配置

用户可通过两种方式更新代码中的配置信息：使用配置类@ConfigurationProperties和@Value注解。
@Value 比较适用于配置比较少的场景
@ConfigurationProperties 则更适用于有较多配置的情况
1. 通过 @Value注入
@Value("${timeout:1000}")
private int timeout;
2. 通过 @ConfigurationProperties注入
@Component
@ConfigurationProperties(prefix = "teacher")
public class Person {

	private String name;

	private int age;

	String getName() {
		return name;
	}

	void setName(String name) {
		this.name = name;
	}

	int getAge() {
		return age;
	}

	void setAge(int age) {
		this.age = age;
	}

	@Override
	public String toString() {
		return "User{" + "name='" + name + '\\'' + ", age=" + age + '}';
	}

}.

步骤4：在北极星控制台添加配置文件

1. 创建命名空间，参见服务治理指南中命名空间管理相关文档内容。
命名空间为北极星里核心的概念，通过命名空间逻辑隔离资源，例如通常用于标识不同的环境、不同的集群。
注意：
这里的命名空间需要和应用配置中的命名空间保持一致。
2. 创建配置文件分组，参见服务治理指南中配置分组相关文档内容。
北极星的配置文件分组概念为一组配置文件的集合，推荐把应用名作为一个分组名，例如在我们的示例中，新建一个polaris-config-example的分组。 把polaris-config-example应用的配置文件都放在polaris-config-example分组下，这样便于配置管理。
3. 创建并发布配置文件，参见服务治理指南中配置文件相关文档内容。
北极星配置中心的控制台，配置文件名可以通过“/”来按树状目录结构展示，树状结构可以清晰的管理配置文件。例如一个应用下分不同的模块，每个模块都有独立的一组配置文件，则可以创建module1/file1.properties,module1/file2.yaml,module2/file3.yaml。
注意：
配置文件名强烈建议带文件后缀，例如 .properties .yaml .yml .json 等。因为客户端会通过文件名后缀来解析文件内容，如果客户端发现不认识的后缀名则默认当做 .properties 文件处理。

步骤5：启动应用

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

步骤6：动态刷新配置

6.1 刷新 @Value 属性

应用启动时扫描所有的 Bean，构建 @Value属性对应的 Bean 的映射关系。当属性配置更新时，找到所有的待更新的 Bean 并利用 Java 的反射机制更新属性。

6.2 刷新 @ConfigurationProperties 配置类

相比于 @RefreshScope 重建所有的 Bean，优化之后的刷新机制只需要重建更新的配置对应的 @ConfigurationProperties Bean，影响面更小。实现原理请看PolarisRefreshAffectedContextRefresher和AffectedConfigurationPropertiesRebinder。
如果您想使用传统的@RefreshScope方式刷新配置，可以配置spring.cloud.polaris.config.refresh-type=refresh_context。

6.3 关闭动态刷新能力

在bootstrap.yml里配置spring.cloud.polaris.config.auto-refresh=false。
上一篇: 注册发现下一篇: 服务限流

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈