对于最新的稳定版本，请使用 Spring Cloud Config 4.3.0！spring-doc.cadn.net.cn

Spring Cloud Config 客户端

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

Spring Boot 配置数据导入

Spring Boot 2.4 引入了一种通过spring.config.import财产。这现在是绑定到 Config Server 的默认方式。spring-doc.cadn.net.cn

要选择性地连接到配置服务器，请在 application.properties 中设置以下内容：spring-doc.cadn.net.cn

应用程序属性
spring.config.import=optional:configserver:

这将连接到默认位置“http://localhost:8888”的配置服务器。删除optional:前缀将导致 Config Client 在无法连接到 Config Server 时失败。要更改配置服务器的位置，请将spring.cloud.config.uri或将 url 添加到spring.config.import语句，例如，spring.config.import=optional:configserver:http://myhost:8888.import 属性中的位置优先于 uri 属性。spring-doc.cadn.net.cn

Spring Boot Config Data 在两步过程中解析配置。首先，它使用default轮廓。这允许 Spring Boot 收集可能激活任何其他配置文件的所有配置。 收集所有激活的配置文件后，它将加载活动配置文件的任何其他配置。 因此，您可能会看到向 Spring Cloud Config Server 发出多个请求以获取配置。这 是正常的，并且是 Spring Boot 在使用spring.config.import.在以前的 Spring Cloud Config 版本中只有一个请求，但这意味着您无法激活配置文件 来自配置服务器的配置。附加请求仅包含default配置文件现在使 这是可能的。spring-doc.cadn.net.cn

一个bootstrap文件（属性或 yaml）对于通过导入的 Spring Boot Config Data 方法不需要spring.config.import.

配置第一个引导程序

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

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

发现优先查找

除非您使用 config first bootstrap，否则您需要有一个spring.config.import属性，并在配置属性中使用optional:前缀。 例如spring.config.import=optional:configserver:.

如果您使用DiscoveryClient实现，例如 Spring Cloud Netflix 和 Eureka Service Discovery 或 Spring Cloud Consul，您可以让 Config Server 向 Discovery Service 注册。spring-doc.cadn.net.cn

如果您更喜欢使用DiscoveryClient要找到配置服务器，您可以通过将spring.cloud.config.discovery.enabled=true（默认值为false). 例如，使用 Spring Cloud Netflix，您需要定义 Eureka 服务器地址（例如，在eureka.client.serviceUrl.defaultZone). 使用此选项的价格是在启动时进行额外的网络往返，以查找服务注册。 好处是，只要发现服务是固定点，配置服务器就可以更改其坐标。 默认服务 ID 为configserver，但您可以通过在客户端上设置spring.cloud.config.discovery.serviceId（在服务器上，以服务的常用方式，例如通过将spring.application.name).spring-doc.cadn.net.cn

发现客户端实现都支持某种元数据映射（例如，我们有eureka.instance.metadataMap尤里卡）。 可能需要在其服务注册元数据中配置服务器的一些附加属性，以便客户端可以正确连接。 如果配置服务器使用 HTTP Basic 进行保护，则可以将凭据配置为user和password. 此外，如果配置服务器具有上下文路径，您可以将configPath. 例如，以下 YAML 文件适用于作为 Eureka 客户端的 Config Server：spring-doc.cadn.net.cn

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

使用 Eureka 和 WebClient 的首次发现引导

如果您使用 EurekaDiscoveryClient来自 Spring Cloud Netflix 并且也想使用WebClient而不是Jersey或RestTemplate, 您需要包括WebClient在你的类路径上以及eureka.client.webclient.enabled=true.spring-doc.cadn.net.cn

配置客户端快速故障

在某些情况下，如果服务无法连接到配置服务器，则可能需要启动服务失败。 如果这是所需的行为，请设置引导配置属性spring.cloud.config.fail-fast=true使客户端因异常而停止。spring-doc.cadn.net.cn

要使用spring.config.import，只需省略optional:前缀。

配置客户端重试

如果您预计应用程序启动时配置服务器可能偶尔不可用，则可以让它在失败后继续尝试。 首先，您需要设置spring.cloud.config.fail-fast=true. 然后你需要添加spring-retry和spring-boot-starter-aop到你的类路径。 默认行为是重试六次，初始回退间隔为 1000 毫秒，后续回退的指数乘数为 1.1。 您可以通过设置spring.cloud.config.retry.*配置属性。 使用随机指数退避策略集spring.cloud.config.retry.useRandomPolicy自true.spring-doc.cadn.net.cn

什么时候spring.cloud.config.retry.useRandomPolicy是true这max-attempts,initial-interval,max-interval和multiplier属性将 即使使用随机指数退避策略，仍然有效。有关如何使用它们的详细信息，请参阅ExponentialRandomBackOffPolicy和ExponentialBackOffPolicy在春季重试中。
要完全控制重试行为并使用旧版引导程序，请添加@Bean类型RetryOperationsInterceptorID 为configServerRetryInterceptor. Spring Retry 有一个RetryInterceptorBuilder这支持创建一个。

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

重试适用于 Spring Bootspring.config.import语句和 normal 属性有效。但是，如果 import 语句位于配置文件中，例如application-prod.properties，则需要以不同的方式配置重试。配置需要作为 url 参数放置在 import 语句上。spring-doc.cadn.net.cn

应用程序生产属性
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=true（注意上面缺少的前缀）和所有可用的spring.cloud.config.retry.*配置属性。spring-doc.cadn.net.cn

查找远程配置资源

配置服务提供来自/{application}/{profile}/{label}，其中客户端应用中的默认绑定如下所示：spring-doc.cadn.net.cn

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

您可以通过设置spring.cloud.config.*（其中 是*name,profile或label). 这label对于回滚到以前版本的配置很有用。 使用默认的 Config Server 实现，它可以是 git 标签、分支名称或提交 ID。 标签也可以作为逗号分隔的列表提供。 在处理功能分支时，此行为非常有用。 例如，您可能希望将配置标签与分支对齐，但将其设为可选（在这种情况下，请使用spring.cloud.config.label=myfeature,develop).spring-doc.cadn.net.cn

请求多个标签

在 Spring Cloud Config 4.2.0 之前，如果您将spring.cloud.config.label到逗号分隔的标签列表，Config Client 将 通过向 Config Server 发出请求来尝试每个标签，直到找到有效的标签。这意味着如果找到第一个标签，则不会尝试后续标签。spring-doc.cadn.net.cn

从 Spring Cloud Config 4.2.0 开始，如果您将spring.cloud.config.label到以逗号分隔的标签列表 AND setspring.cloud.config.send-all-labelsConfig Client 将向 Config Server 发出一个带有逗号分隔标签列表的请求 如果配置服务器使用的是 4.2.0 或更高版本，它将返回一个响应，其中包含所有标签的属性源。spring-doc.cadn.net.cn

设置spring.cloud-config.send-all-labels自true设置spring.cloud.config.label到逗号分隔的标签列表， 使用 4.2.0 之前的 Config Server 版本将导致意外行为，因为 Config Server 将尝试查找标签 与逗号分隔的列表值匹配，并且不会尝试拆分标签。

通过在单个请求中发送所有标签，您可以减少向 Config Server 发出的请求数量。spring-doc.cadn.net.cn

spring.cloud.config.send-all-labels设置为false默认情况下，旧行为仍然是默认行为，并且它也保持 与旧版本的 Config Server 兼容。spring-doc.cadn.net.cn

为配置服务器指定多个 URL

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

下面列出的 URLspring.cloud.config.uri按列出的顺序进行尝试。默认情况下，配置客户端将尝试从每个 URL 获取属性，直到尝试成功以确保高可用性。spring-doc.cadn.net.cn

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

可以在单个spring.config.import键而不是spring.cloud.config.uri.位置将按照定义的顺序进行处理，以后导入优先。但是，如果spring.cloud.config.fail-fast是true，如果第一次配置服务器调用因任何原因不成功，则配置客户端将失败。如果fail-fast是false，它将尝试所有 URL，直到一次调用成功，无论失败的原因如何。（这spring.cloud.config.multiple-uri-strategy在spring.config.import.)spring-doc.cadn.net.cn

如果您在 Config Server 上使用 HTTP 基本安全性，则目前只有在spring.cloud.config.uri财产。如果您使用任何其他类型的安全机制，则（当前）无法支持每个配置服务器的身份验证和授权。spring-doc.cadn.net.cn

配置超时

如果要配置超时阈值：spring-doc.cadn.net.cn

配置字符集

如果要配置特定的字符集，资源应该由服务器传递，则需要通过字符集应用它。spring-doc.cadn.net.cn

spring:
  cloud:
    config:
      charset: UTF-8

charset 配置属性定义为java.nio.charset.Charsetspring-doc.cadn.net.cn

安全

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

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

以下示例显示了传递相同信息的另一种方法：spring-doc.cadn.net.cn

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

这spring.cloud.config.password和spring.cloud.config.username值将覆盖 URI 中提供的任何内容。spring-doc.cadn.net.cn

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

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

如果配置服务器需要客户端 TLS 证书，您可以通过属性配置客户端 TLS 证书和信任存储，如以下示例所示：spring-doc.cadn.net.cn

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>

这spring.cloud.config.tls.enabled需要为 true 才能启用配置客户端 TLS。什么时候spring.cloud.config.tls.trust-store省略，则使用 JVM 默认信任存储。的默认值spring.cloud.config.tls.key-store-type和spring.cloud.config.tls.trust-store-type是 PKCS12。如果省略密码属性，则假定为空密码。spring-doc.cadn.net.cn

如果您使用其他形式的安全性，则可能需要提供一个RestTemplate到ConfigServicePropertySourceLocator（例如，通过在引导上下文中抓取它并注入它）。spring-doc.cadn.net.cn

健康指标

Config Client 提供了一个 Spring Boot Health Indicator，该指示器尝试从 Config Server 加载配置。 可以通过设置management.health.config.enabled=false. 出于性能原因，响应也会被缓存。 默认缓存生存时间为 5 分钟。 要更改该值，请将health.config.time-to-live属性（以毫秒为单位）。spring-doc.cadn.net.cn

提供自定义 RestTemplate

在某些情况下，您可能需要自定义从客户端向配置服务器发出的请求。 通常，这样做涉及将特殊Authorization标头来验证对服务器的请求。spring-doc.cadn.net.cn

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

要提供自定义RestTemplate使用配置数据时：spring-doc.cadn.net.cn

  1. 创建一个实现BootstrapRegistryInitializerspring-doc.cadn.net.cn

    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;
		});
	}

}

  2. 在resources/META-INF，创建一个名为spring.factories并指定自定义配置，如以下示例所示：spring-doc.cadn.net.cn

    spring.工厂
    org.springframework.boot.BootstrapRegistryInitializer=com.my.config.client.CustomBootstrapRegistryInitializer

使用 Bootstrap 提供自定义 RestTemplate

要提供自定义RestTemplate使用 Bootstrap 时：spring-doc.cadn.net.cn

  1. 创建一个新的配置 Bean，实现为PropertySourceLocator，如以下示例所示：spring-doc.cadn.net.cn

    CustomConfigServiceBootstrapConfiguration.java
    @Configuration
public class CustomConfigServiceBootstrapConfiguration {
    @Bean
    public ConfigServicePropertySourceLocator configServicePropertySourceLocator() {
        ConfigClientProperties clientProperties = configClientProperties();
       ConfigServicePropertySourceLocator configServicePropertySourceLocator =  new ConfigServicePropertySourceLocator(clientProperties);
        configServicePropertySourceLocator.setRestTemplate(customRestTemplate(clientProperties));
        return configServicePropertySourceLocator;
    }
}
    对于添加的简化方法Authorizationheaders，则spring.cloud.config.headers.*属性可以代替。

  2. 在resources/META-INF，创建一个名为spring.factories并指定自定义配置，如以下示例所示：spring-doc.cadn.net.cn

    spring.工厂
    org.springframework.cloud.bootstrap.BootstrapConfiguration = com.my.config.client.CustomConfigServiceBootstrapConfiguration

库

将 Vault 用作配置服务器的后端时，客户端需要为服务器提供Tokens以从 Vault 检索值。 可以通过将spring.cloud.config.token在bootstrap.yml，如以下示例所示：spring-doc.cadn.net.cn

spring:
  cloud:
    config:
      token: YourVaultToken

Vault 中的嵌套密钥

Vault 支持将键嵌套在存储在 Vault 中的值中，如以下示例所示：spring-doc.cadn.net.cn

echo -n '{"appA": {"secret": "appAsecret"}, "bar": "baz"}' | vault write secret/myapp -spring-doc.cadn.net.cn

此命令将 JSON 对象写入 Vault。 要在 Spring 中访问这些值，您可以使用传统的点（.） 注释，如以下示例所示spring-doc.cadn.net.cn

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

前面的代码将设置namevariable 设置为appAsecret.spring-doc.cadn.net.cn

AOT 和原生映像支持

因为4.0.0，Spring Cloud Config Client 支持 Spring AOT 转换和 GraalVM 原生镜像。spring-doc.cadn.net.cn

AOT 和本机映像支持不适用于配置首次引导（使用spring.config.use-legacy-processing=true).
本机映像不支持刷新范围。如果您要将配置客户端应用程序作为本机映像运行，请确保将spring.cloud.refresh.enabled属性设置为false.
在构建包含 Spring Cloud Config 客户端的项目时，您必须确保它连接到的配置数据源（例如 Spring Cloud Config Server、Consul、Zookeeper、Vault 等）可用。例如，如果您从 Spring Cloud Config Server 检索配置数据，请确保其实例在 Config Client 设置中指示的端口上运行且可用。这是必要的，因为应用程序上下文在构建时正在优化，并且需要解析目标环境。
由于在AOT和本机模式下，正在处理配置并在构建时优化上下文，因此任何会影响bean创建的属性（例如在引导上下文中使用的属性）都应在构建时和运行时设置为相同的值，以避免意外行为。
由于 Config Client 在从本机映像启动时连接到正在运行的数据源（例如 Config Server），因此快速启动时间将因进行此网络通信所需的时间而减慢。

附录

可观测性元数据

可观测性 - 指标

您可以在下面找到此项目声明的所有指标的列表。spring-doc.cadn.net.cn

环境存储库

围绕 EnvironmentRepository 创建的观察。spring-doc.cadn.net.cn

指标名称 spring.cloud.config.environment.find（由约定类定义org.springframework.cloud.config.server.environment.ObservationEnvironmentRepositoryObservationConvention).类型 timer.spring-doc.cadn.net.cn

指标名称 spring.cloud.config.environment.find.active（由约定类定义org.springframework.cloud.config.server.environment.ObservationEnvironmentRepositoryObservationConvention).类型 long task timer.spring-doc.cadn.net.cn

启动观察后添加的 KeyValues 可能在 *.active 指标中缺失。
千分尺内部使用nanoseconds用于基站。但是，每个后端都确定了实际的基数单元。（即普罗米修斯使用秒）

封闭类的完全限定名称org.springframework.cloud.config.server.environment.DocumentedConfigObservation.spring-doc.cadn.net.cn

所有标签必须以spring.cloud.config.environment前缀！
表 1.低基数键

名称spring-doc.cadn.net.cn

描述spring-doc.cadn.net.cn

spring.cloud.config.environment.application （必填）spring-doc.cadn.net.cn

正在查询的属性的应用程序名称。spring-doc.cadn.net.cn

spring.cloud.config.environment.class （必填）spring-doc.cadn.net.cn

EnvironmentRepository 的实现。spring-doc.cadn.net.cn

spring.cloud.config.environment.label （必填）spring-doc.cadn.net.cn

正在查询的属性的标签。spring-doc.cadn.net.cn

spring.cloud.config.environment.profile （必填）spring-doc.cadn.net.cn

正在查询的属性的应用程序名称。spring-doc.cadn.net.cn

可观测性 - 跨度

您可以在下面找到此项目声明的所有跨度的列表。spring-doc.cadn.net.cn

环境存储库跨度

围绕 EnvironmentRepository 创建的观察。spring-doc.cadn.net.cn

跨度名称 spring.cloud.config.environment.find（由约定类定义org.springframework.cloud.config.server.environment.ObservationEnvironmentRepositoryObservationConvention).spring-doc.cadn.net.cn

封闭类的完全限定名称org.springframework.cloud.config.server.environment.DocumentedConfigObservation.spring-doc.cadn.net.cn

所有标签必须以spring.cloud.config.environment前缀！
表 2.标记键

名称spring-doc.cadn.net.cn

描述spring-doc.cadn.net.cn

spring.cloud.config.environment.application （必填）spring-doc.cadn.net.cn

正在查询的属性的应用程序名称。spring-doc.cadn.net.cn

spring.cloud.config.environment.class （必填）spring-doc.cadn.net.cn

EnvironmentRepository 的实现。spring-doc.cadn.net.cn

spring.cloud.config.environment.label （必填）spring-doc.cadn.net.cn

正在查询的属性的标签。spring-doc.cadn.net.cn

spring.cloud.config.environment.profile （必填）spring-doc.cadn.net.cn

正在查询的属性的应用程序名称。spring-doc.cadn.net.cn