此版本仍在开发中，尚未被视为稳定版本。最新的稳定版本请使用 Spring Cloud Config 4.2.0！spring-doc.cadn.net.cn

Spring Cloud Config 客户端

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

Spring Boot Config 数据导入

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

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

application.properties
spring.config.import=optional:configserver:

这将连接到默认位置 “http://localhost:8888” 的 Config Server。删除optional:前缀将导致 Config Client 无法连接到 Config Server。要更改 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 中，只发出了一个请求，但这意味着您无法激活配置文件 来自来自 Config Server 的配置。仅包含defaultprofile 现在使 这是可能的。spring-doc.cadn.net.cn

一个bootstrap文件（properties 或 yaml）不需要 Spring Boot Config Data 方法的导入方式spring.config.import.

Config First 引导

要使用传统的引导方式连接到 Config Server，必须通过属性或spring-cloud-starter-bootstrap起动机。该属性为spring.cloud.bootstrap.enabled=true.它必须设置为 System Property 或 environment variable。 启用 bootstrap 后，在 Classpath 上具有 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

Discovery 首次查找

除非您使用 config first 引导，否则您需要有一个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要找到 Config Server，您可以通过设置spring.cloud.config.discovery.enabled=true（默认值为false). 例如，对于 Spring Cloud Netflix，您需要定义 Eureka 服务器地址（例如，在eureka.client.serviceUrl.defaultZone). 使用此选项的价格是启动时的额外网络往返，以查找服务注册。 好处是，只要 Discovery Service 是一个固定点，Config Server 就可以更改其坐标。 默认服务 ID 为configserver，但您可以通过在客户端上设置spring.cloud.config.discovery.serviceId（在服务器上，以服务的通常方式，例如通过设置spring.application.name).spring-doc.cadn.net.cn

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

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

使用 Eureka 和 WebClient 的 Discovery First Bootstrap

如果您使用 EurekaDiscoveryClient从 Spring Cloud Netflix 中，也想使用WebClient而不是 Jersey 或RestTemplate, 您需要包括WebClient在你的 Classpath 上以及 seteureka.client.webclient.enabled=true.spring-doc.cadn.net.cn

Config 客户端快速失败

在某些情况下，如果服务无法连接到 Config Server，您可能希望服务启动失败。 如果这是所需的行为，请设置 bootstrap 配置属性spring.cloud.config.fail-fast=true使客户端停止并显示 Exception。spring-doc.cadn.net.cn

要获得类似的功能，请使用spring.config.import，只需省略optional:前缀。

Config 客户端重试

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

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

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

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

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

查找远程配置资源

Config Service 提供来自以下来源的属性源/{application}/{profile}/{label}，其中客户端应用程序中的默认绑定如下所示：spring-doc.cadn.net.cn

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

您可以通过设置spring.cloud.config.*（其中 is*name,profile或label). 这label对于回滚到以前版本的 Configuration 非常有用。 使用默认的 Config Server 实现，它可以是 git 标签、分支名称或提交 ID。 Label 也可以作为逗号分隔的列表提供。 在功能分支上工作时，此行为可能很有用。 例如，您可能希望将 config 标签与分支对齐，但将其设置为可选（在这种情况下，使用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 发出单个请求 如果 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

为 Config Server 指定多个 URL

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

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

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

可以在单个spring.config.importkey 而不是spring.cloud.config.uri.位置将按照定义的顺序进行处理，以后的导入优先。但是，如果spring.cloud.config.fail-fast是true，如果第一次 Config Server 调用因任何原因失败，则 Config Client 将失败。如果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财产。如果您使用任何其他类型的安全机制，则（当前）无法支持每个 Config Server 的身份验证和授权。spring-doc.cadn.net.cn

配置超时

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

配置 Charset

如果要配置特定的 charset，资源应该由服务器交付，你需要通过 charset 来应用它。spring-doc.cadn.net.cn

spring:
  cloud:
    config:
      charset: UTF-8

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

安全

如果您在服务器上使用 HTTP Basic 安全性，则 Client 端需要知道密码（如果不是默认密码，则需要知道用户名）。 您可以通过配置服务器 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 中，因为它不需要位于配置文件中）。 以下示例在本地工作，并适用于名为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 才能启用 config 客户端 TLS。什么时候spring.cloud.config.tls.trust-store，则使用 JVM 默认信任库。的默认值spring.cloud.config.tls.key-store-type和spring.cloud.config.tls.trust-store-type是 PKCS12。如果省略 password 属性，则假定 password 为空。spring-doc.cadn.net.cn

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

运行状况指示器

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

提供自定义 RestTemplate

在某些情况下，您可能需要自定义从 Client 端向 config server 发出的请求。 通常，这样做涉及传递特殊的Authorization标头对向服务器发出的请求进行身份验证。spring-doc.cadn.net.cn

使用 Config 数据提供自定义 RestTemplate

提供自定义RestTemplate使用 Config Data 时：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.factories
    org.springframework.boot.BootstrapRegistryInitializer=com.my.config.client.CustomBootstrapRegistryInitializer

使用 Bootstrap 提供自定义 RestTemplate

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

  1. 使用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.factories
    org.springframework.cloud.bootstrap.BootstrapConfiguration = com.my.config.client.CustomConfigServiceBootstrapConfiguration

库

当使用 Vault 作为配置服务器的后端时，客户端需要为服务器提供一个令牌以从 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";

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

AOT 和本机映像支持

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

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

附录

可观测性元数据

可观测性 - 指标

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

环境存储库

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

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

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

*.active 指标中可能缺少在开始观察后添加的 KeyValue。
千分尺内部使用nanoseconds对于 baseUnit。但是，每个后端都决定了实际的 baseunit。（即 Prometheus 使用秒）

封闭类的完全限定名称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

可观测性 - Span

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

环境存储库跨度

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

Span 名称 spring.cloud.config.environment.find（由 convention 类定义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