Spring Cloud 配置客户端 (Spring Cloud Config Client) | Spring Cloud Config4.1.2中文文档|Spring官方文档|SpringBoot 教程|Spring中文网

Spring Boot 应用程序可以立即利用 Spring Config Server（或应用程序开发人员提供的其他外部属性源）。它还选取了一些与更改事件相关的其他有用功能。Environment

Spring Boot 配置数据导入

Spring Boot 2.4 引入了一种通过属性导入配置数据的新方法。现在，这是绑定到 Config Server 的默认方式。spring.config.import

若要选择性地连接到配置服务器，请在 application.properties 中设置以下内容：

application.properties

spring.config.import=optional:configserver:

这将连接到默认位置“http://localhost:8888”的 Config Server。如果 Config Client 无法连接到 Config Server，则删除前缀将导致 Config Client 失败。要更改 Config Server 的位置，请设置 url 或将 url 添加到语句中，例如。import 属性中的位置优先于 uri 属性。optional:spring.cloud.config.urispring.config.importspring.config.import=optional:configserver:http://myhost:8888

Spring Boot Config Data 通过两步过程解析配置。首先，它使用配置文件加载所有配置。这允许Spring Boot收集所有可能激活任何其他配置文件的配置。收集所有激活的配置文件后，它将加载活动配置文件的任何其他配置。因此，您可能会看到向Spring Cloud Config Server发出多个请求以获取配置。这是正常的，是 Spring Boot 在使用时加载配置方式的副作用。在上一页 Spring Cloud Config 的版本只有一个请求，但这意味着您无法激活配置文件来自配置服务器的配置。现在，仅使用“默认”配置文件的附加请求会使这是可能的。defaultspring.config.import

通过导入的 Spring Boot Config Data 方法不需要文件（properties 或 yaml）。bootstrapspring.config.import

配置第一个引导程序

若要使用旧版引导程序方式连接到 Config Server，必须通过属性或启动器启用引导程序。该物业是 .它必须设置为系统属性或环境变量。启用引导程序后，类路径上具有Spring Cloud Config Client的任何应用程序都将连接到Config Server，如下所示：当配置客户端启动时，它会绑定到 Config Server（通过 bootstrap 配置属性）并使用远程属性源初始化 Spring。spring-cloud-starter-bootstrapspring.cloud.bootstrap.enabled=truespring.cloud.config.uriEnvironment

此行为的最终结果是，所有想要使用 Config Server 的客户端应用程序都需要一个（或环境变量）并设置了服务器地址（默认为“http://localhost:8888”）。bootstrap.ymlspring.cloud.config.uri

发现优先查找

除非您使用 config first 引导程序，否则您需要在配置属性中具有带有前缀的属性。例如。spring.config.importoptional:spring.config.import=optional:configserver:

如果使用实现（如 Spring Cloud Netflix 和 Eureka Service Discovery 或 Spring Cloud Consul），则可以让 Config Server 注册到 Discovery Service。DiscoveryClient

如果您更喜欢使用来查找 Config Server，则可以通过设置（默认为）来实现。例如，使用 Spring Cloud Netflix，您需要定义 Eureka 服务器地址（例如，在中）。使用此选项的代价是在启动时进行额外的网络往返，以查找服务注册。这样做的好处是，只要发现服务是一个固定点，Config Server 就可以更改其坐标。默认服务 ID 是，但您可以在客户端上通过设置（在服务器上，以服务的常用方式（例如通过设置）来更改该 ID 。DiscoveryClientspring.cloud.config.discovery.enabled=truefalseeureka.client.serviceUrl.defaultZoneconfigserverspring.cloud.config.discovery.serviceIdspring.application.name

发现客户端实现都支持某种元数据映射（例如，我们为 Eureka 提供了）。可能需要在其服务注册元数据中配置 Config Server 的某些附加属性，以便客户端可以正确连接。如果 Config Server 使用 HTTP Basic 进行保护，则可以将凭据配置为和。此外，如果 Config Server 具有上下文路径，则可以设置 . 例如，以下 YAML 文件用于作为 Eureka 客户端的 Config Server：eureka.instance.metadataMapuserpasswordconfigPath

eureka:
  instance:
    ...
    metadataMap:
      user: osufhalskjrtl
      password: lviuhlszvaorhvlo5847
      configPath: /config

使用 Eureka 和 WebClient 的 Discovery First Bootstrap

如果您使用 Spring Cloud Netflix 中的 Eureka，并且还想使用代替 Jersey 或，您需要在类路径中包含并设置 .DiscoveryClientWebClientRestTemplateWebClienteureka.client.webclient.enabled=true

除非您使用 config first 引导程序，否则您需要在配置属性中具有带有前缀的属性。例如。spring.config.importoptional:spring.config.import=optional:configserver:

配置客户端快速失败

在某些情况下，如果服务无法连接到 Config Server，您可能希望服务启动失败。如果这是所需的行为，请设置引导程序配置属性，使客户端停止并出现异常。spring.cloud.config.fail-fast=true

要使用获得类似的功能，只需省略前缀即可。spring.config.importoptional:

配置客户端重试

如果您预计在应用程序启动时配置服务器可能偶尔不可用，则可以使其在失败后继续尝试。首先，您需要设置 . 然后，您需要将和添加到您的类路径中。默认行为是重试六次，初始退避间隔为 1000 毫秒，后续退避的指数乘数为 1.1。您可以通过设置配置属性来配置这些属性（和其他属性）。使用设置为的随机指数回退策略。spring.cloud.config.fail-fast=truespring-retryspring-boot-starter-aopspring.cloud.config.retry.*spring.cloud.config.retry.useRandomPolicytrue

何时是、、和属性即使使用随机指数回退策略，仍然有效。有关如何使用它们的详细信息，请参见和 Spring Retry。spring.cloud.config.retry.useRandomPolicytruemax-attemptsinitial-intervalmax-intervalmultiplierExponentialRandomBackOffPolicyExponentialBackOffPolicy

若要完全控制重试行为并使用旧引导程序，请添加 ID 为的 of 类型。 Spring Retry 有一个支持创建一个。@BeanRetryOperationsInterceptorconfigServerRetryInterceptorRetryInterceptorBuilder

使用 spring.config.import 配置客户端重试

重试适用于 Spring Boot 语句，普通属性有效。但是，如果 import 语句位于配置文件中，例如，则需要采用其他方法来配置重试。需要将配置作为 url 参数放在 import 语句上。spring.config.importapplication-prod.properties

application-prod.properties

spring.config.import=configserver:http://configserver.example.com?fail-fast=true&max-attempts=10&max-interval=1500&multiplier=1.2&initial-interval=1100"

这将设置（注意上面缺少的前缀）和所有可用的配置属性。spring.cloud.config.fail-fast=truespring.cloud.config.retry.*

查找远程配置资源

Config Service 提供来自的属性源，其中客户端应用中的默认绑定如下所示：/{application}/{profile}/{label}

“应用程序” =${spring.application.name}
“profile” =（实际上${spring.profiles.active}Environment.getActiveProfiles())
“label” = “主”

设置属性时，请勿在应用名称前加上保留字，以防止在解决正确的属性源时出现问题。${spring.application.name}application-

您可以通过设置（where is ， or ）来覆盖所有这些。这对于回滚到以前版本的配置很有用。对于默认的 Config Server 实现，它可以是 git 标签、分支名称或提交 ID。标签也可以以逗号分隔的列表形式提供。在这种情况下，将逐个尝试列表中的项目，直到一个成功。此行为在处理功能分支时非常有用。例如，您可能希望将配置标签与分支对齐，但将其设置为可选（在这种情况下，请使用）。spring.cloud.config.**nameprofilelabellabelspring.cloud.config.label=myfeature,develop

设置属性时，请勿在应用名称前加上保留字，以防止在解决正确的属性源时出现问题。${spring.application.name}application-

为配置服务器指定多个 URL

为了确保高可用性，当您部署了多个 Config Server 实例，并且预计一个或多个实例不时不可用或无法接受请求（例如，如果 Git 服务器关闭），您可以指定多个 URL（作为属性下的逗号分隔列表）或让所有实例在 Service Registry（如 Eureka）中注册（如果使用 Discovery-First Bootstrap 模式）。spring.cloud.config.uri

下面列出的 URL 将按列出的顺序进行尝试。默认情况下，Config Client 将尝试从每个 URL 获取属性，直到尝试成功以确保高可用性。spring.cloud.config.uri

但是，如果要仅在 Config Server 未运行（即应用程序退出时）或发生连接超时时确保高可用性，请设置为。（的默认值为 .）例如，如果 Config Server 返回 500（内部服务器错误）响应，或者 Config Client 从 Config Server 收到 401（由于凭据错误或其他原因），则 Config Client 不会尝试从其他 URL 获取属性。400 错误（可能 404 除外）表示用户问题，而不是可用性问题。请注意，如果 Config Server 设置为使用 Git 服务器，并且对 Git 服务器的调用失败，则可能会发生 404 错误。spring.cloud.config.multiple-uri-strategyconnection-timeout-onlyspring.cloud.config.multiple-uri-strategyalways

可以在单个键下指定多个位置，而不是。位置将按照定义的顺序进行处理，以后的导入优先。但是，如果是，如果第一次 Config Server 调用因任何原因不成功，则 Config Client 将失败。如果是，它将尝试所有 URL，直到一个调用成功，而不管失败的原因是什么。（在下指定 URL 时，不适用。spring.config.importspring.cloud.config.urispring.cloud.config.fail-fasttruefail-fastfalsespring.cloud.config.multiple-uri-strategyspring.config.import

如果在 Config Server 上使用 HTTP 基本安全性，则当前仅当将凭据嵌入到属性下指定的每个 URL 中时，才能支持每个 Config Server 身份验证凭据。如果使用任何其他类型的安全机制，则（当前）无法支持每配置服务器身份验证和授权。spring.cloud.config.uri

配置超时

如果要配置超时阈值：

可以使用属性来配置读取超时。spring.cloud.config.request-read-timeout
可以使用属性配置连接超时。spring.cloud.config.request-connect-timeout

安全

如果在服务器上使用 HTTP 基本安全性，则客户端需要知道密码（如果不是默认密码，则需要知道用户名）。您可以通过配置服务器 URI 或单独的用户名和密码属性指定用户名和密码，如以下示例所示：

spring:
  cloud:
    config:
     uri: https://user:[email protected]

以下示例显示了传递相同信息的另一种方法：

spring:
  cloud:
    config:
     uri: https://myconfig.mycompany.com
     username: user
     password: secret

和值将覆盖 URI 中提供的任何内容。spring.cloud.config.passwordspring.cloud.config.username

如果在 Cloud Foundry 上部署应用，则提供密码的最佳方式是通过服务凭据（例如在 URI 中，因为它不需要位于配置文件中）。以下示例适用于本地，适用于 Cloud Foundry 上名为：configserver

spring:
  cloud:
    config:
     uri: ${vcap.services.configserver.credentials.uri:http://user:password@localhost:8888}

如果配置服务器需要客户端 TLS 证书，则可以通过属性配置客户端 TLS 证书和信任库，如以下示例所示：

spring:
  cloud:
    config:
      uri: https://myconfig.myconfig.com
      tls:
        enabled: true
        key-store: <path-of-key-store>
        key-store-type: PKCS12
        key-store-password: <key-store-password>
        key-password: <key-password>
        trust-store: <path-of-trust-store>
        trust-store-type: PKCS12
        trust-store-password: <trust-store-password>

需要为 true 才能启用配置客户端 TLS。省略时，将使用 JVM 缺省信任库。和的默认值为 PKCS12。如果省略密码属性，则假定为空密码。spring.cloud.config.tls.enabledspring.cloud.config.tls.trust-storespring.cloud.config.tls.key-store-typespring.cloud.config.tls.trust-store-type

如果使用其他形式的安全性，则可能需要向 RestTemplate 提供（例如，通过在引导程序上下文中获取它并注入它）。ConfigServicePropertySourceLocator

健康指示器

Config Client 提供 Spring Boot 运行状况指示器，用于尝试从 Config Server 加载配置。可以通过设置来禁用运行状况指示器。出于性能原因，还会缓存响应。默认缓存生存时间为 5 分钟。若要更改该值，请设置属性（以毫秒为单位）。health.config.enabled=falsehealth.config.time-to-live

提供自定义 RestTemplate

在某些情况下，您可能需要自定义从客户端向配置服务器发出的请求。通常，这样做涉及传递特殊标头以对服务器的请求进行身份验证。Authorization

使用配置数据提供自定义 RestTemplate

要在使用配置数据时提供自定义，请执行以下操作：RestTemplate

创建一个实现BootstrapRegistryInitializer

CustomBootstrapRegistryInitializer.java

public class CustomBootstrapRegistryInitializer implements BootstrapRegistryInitializer {

	@Override
	public void initialize(BootstrapRegistry registry) {
		registry.register(RestTemplate.class, context -> {
			RestTemplate restTemplate = new RestTemplate();
			// Customize RestTemplate here
			return restTemplate;
		});
	}

}

在中，创建一个名为并指定自定义配置的文件，如以下示例所示：resources/META-INFspring.factories
spring.factories
```
org.springframework.boot.BootstrapRegistryInitializer=com.my.config.client.CustomBootstrapRegistryInitializer
```

使用 Bootstrap 提供自定义 RestTemplate

要在使用 Bootstrap 时提供自定义，请执行以下操作：RestTemplate

使用的实现创建新的配置 Bean，如以下示例所示：PropertySourceLocator

CustomConfigServiceBootstrapConfiguration.java

@Configuration
public class CustomConfigServiceBootstrapConfiguration {
    @Bean
    public ConfigServicePropertySourceLocator configServicePropertySourceLocator() {
        ConfigClientProperties clientProperties = configClientProperties();
       ConfigServicePropertySourceLocator configServicePropertySourceLocator =  new ConfigServicePropertySourceLocator(clientProperties);
        configServicePropertySourceLocator.setRestTemplate(customRestTemplate(clientProperties));
        return configServicePropertySourceLocator;
    }
}

对于添加标头的简化方法，可以改用该属性。Authorizationspring.cloud.config.headers.*

在中，创建一个名为并指定自定义配置的文件，如以下示例所示：resources/META-INFspring.factories
spring.factories
```
org.springframework.cloud.bootstrap.BootstrapConfiguration = com.my.config.client.CustomConfigServiceBootstrapConfiguration
```

库

使用 Vault 作为配置服务器的后端时，客户端需要为服务器提供令牌，以便从 Vault 检索值。可以通过在中设置来提供此令牌，如以下示例所示：spring.cloud.config.tokenbootstrap.yml

spring:
  cloud:
    config:
      token: YourVaultToken

对于添加标头的简化方法，可以改用该属性。Authorizationspring.cloud.config.headers.*

Vault 中的嵌套密钥

保险柜支持将密钥嵌套在存储在保险柜中的值中，如以下示例所示：

echo -n '{"appA": {"secret": "appAsecret"}, "bar": "baz"}' | vault write secret/myapp -

此命令将 JSON 对象写入 Vault。要在 Spring 中访问这些值，您将使用传统的 dot（）注解，如以下示例所示.

@Value("${appA.secret}")
String name = "World";

前面的代码会将变量的值设置为。nameappAsecret

AOT 和原生映像支持

从那时起，Spring Cloud Config Client 支持 Spring AOT 转换和 GraalVM 原生镜像。4.0.0

AOT 和本机映像支持不适用于配置优先引导程序（使用）。spring.config.use-legacy-processing=true

本机映像不支持刷新范围。如果要将配置客户端应用程序作为本机映像运行，请确保将 property 设置为。spring.cloud.refresh.enabledfalse

在构建包含 Spring Cloud Config Client 的项目时，必须确保它连接到的配置数据源（例如 Spring Cloud Config Server、Consul、Zookeeper、Vault 等）可用。例如，如果从 Spring Cloud Config Server 检索配置数据，请确保其实例在 Config Client 设置中指示的端口上运行且可用。这是必要的，因为在构建时正在优化应用程序上下文，并且需要解析目标环境。

由于在 AOT 和本机模式下，正在处理配置并在构建时优化上下文，因此任何会影响 Bean 创建的属性（例如在引导上下文中使用的属性）都应在构建时和运行时设置为相同的值，以避免意外行为。

由于 Config Client 在从本机映像启动时连接到正在运行的数据源（例如 Config Server），因此快速启动时间将因发生此网络通信所需的时间而减慢。

AOT 和本机映像支持不适用于配置优先引导程序（使用）。spring.config.use-legacy-processing=true

本机映像不支持刷新范围。如果要将配置客户端应用程序作为本机映像运行，请确保将 property 设置为。spring.cloud.refresh.enabledfalse

由于 Config Client 在从本机映像启动时连接到正在运行的数据源（例如 Config Server），因此快速启动时间将因发生此网络通信所需的时间而减慢。

附录

可观测性元数据

可观测性 - 指标

您可以在下面找到此项目声明的所有指标的列表。

环境存储库

围绕 EnvironmentRepository 创建的观察结果。

指标名称（由约定类定义）。键入。spring.cloud.config.environment.findorg.springframework.cloud.config.server.environment.ObservationEnvironmentRepositoryObservationConventiontimer

指标名称（由约定类定义）。键入。spring.cloud.config.environment.find.activeorg.springframework.cloud.config.server.environment.ObservationEnvironmentRepositoryObservationConventionlong task timer

*.active 指标中可能缺少在启动观察任务后添加的 KeyValues。

千分尺内部用于基本单元。但是，每个后端都决定了实际的基本单位。（即 Prometheus 使用秒）nanoseconds

封闭类 .org.springframework.cloud.config.server.environment.DocumentedConfigObservation

所有标签都必须以前缀为前缀！spring.cloud.config.environment

表 1.低基数键
名字	描述
`spring.cloud.config.environment.application` （必填）	要查询其属性的应用程序名称。
`spring.cloud.config.environment.class` （必填）	EnvironmentRepository 的实现。
`spring.cloud.config.environment.label` （必填）	要查询其属性的标签。
`spring.cloud.config.environment.profile` （必填）	要查询其属性的应用程序名称。

可观测性 - 跨度

您可以在下面找到此项目声明的所有跨度的列表。

环境存储库跨度

围绕 EnvironmentRepository 创建的观察结果。

Span 名称（由约定类定义）。spring.cloud.config.environment.findorg.springframework.cloud.config.server.environment.ObservationEnvironmentRepositoryObservationConvention

封闭类 .org.springframework.cloud.config.server.environment.DocumentedConfigObservation

所有标签都必须以前缀为前缀！spring.cloud.config.environment

表 2.标签键
名字	描述
`spring.cloud.config.environment.application` （必填）	要查询其属性的应用程序名称。
`spring.cloud.config.environment.class` （必填）	EnvironmentRepository 的实现。
`spring.cloud.config.environment.label` （必填）	要查询其属性的标签。
`spring.cloud.config.environment.profile` （必填）	要查询其属性的应用程序名称。

*.active 指标中可能缺少在启动观察任务后添加的 KeyValues。

千分尺内部用于基本单元。但是，每个后端都决定了实际的基本单位。（即 Prometheus 使用秒）nanoseconds

所有标签都必须以前缀为前缀！spring.cloud.config.environment

表 1.低基数键
名字	描述
`spring.cloud.config.environment.application` （必填）	要查询其属性的应用程序名称。
`spring.cloud.config.environment.class` （必填）	EnvironmentRepository 的实现。
`spring.cloud.config.environment.label` （必填）	要查询其属性的标签。
`spring.cloud.config.environment.profile` （必填）	要查询其属性的应用程序名称。

所有标签都必须以前缀为前缀！spring.cloud.config.environment

表 2.标签键
名字	描述
`spring.cloud.config.environment.application` （必填）	要查询其属性的应用程序名称。
`spring.cloud.config.environment.class` （必填）	EnvironmentRepository 的实现。
`spring.cloud.config.environment.label` （必填）	要查询其属性的标签。
`spring.cloud.config.environment.profile` （必填）	要查询其属性的应用程序名称。