Externalized Configuration

默认情况下，当指定的配置数据位置不存在时，Spring Boot 将抛出一个 ConfigDataLocationNotFoundException，并且你的应用程序将不会启动。

如果你想指定一个位置，但你不介意它是否一直存在，则可以使用 optional: 前缀。你可以在 spring.config.location 和 spring.config.additional-location 属性以及 spring.config.import 声明中使用此前缀。

例如，即使不存在 myconfig.properties 文件，spring.config.import 值为 optional:file:./myconfig.properties 也可以允许你的应用程序启动。

如果你想要忽略所有 ConfigDataLocationNotFoundExceptions 并始终继续启动你的应用程序，你可以使用 spring.config.on-not-found 属性。使用 SpringApplication.setDefaultProperties(…​) 或通过系统/环境变量将值设置为 ignore。

如果配置文件位置包含最后一个路径段的 * 字符，它会被视为通配符位置。通配符会在加载配置时展开，以便也检查立即子目录。当存在多种配置属性源时，诸如 Kubernetes 之类的环境中会特别有用通配符位置。

例如，如果你有一些 Redis 配置和一些 MySQL 配置，你可能想要将这两部分配置分开，同时要求两者都存在于 application.properties 文件中。这可能会导致两个单独的 application.properties 文件挂载在不同的位置，例如 /config/redis/application.properties 和 /config/mysql/application.properties。在这种情况下，拥有 config/*/ 的通配符位置将导致处理这两个文件。

默认情况下，Spring Boot 在默认搜索位置中包括 config/*/。这意味着将搜索 jar 外部 /config 目录的所有子目录。

你可以自己使用 spring.config.location 和 spring.config.additional-location 属性使用通配符位置。

除了 application 属性文件之外，Spring Boot 还会尝试使用命名约定 application-{profile} 加载特定于概要的文件。例如，如果你的应用程序激活了名为 prod 的概要并使用了 YAML 文件，那么 application.yaml 和 application-prod.yaml 都将被考虑。

特定于概要的属性从与标准 application.properties 相同的位置加载，其中特定于概要的文件始终覆盖非特定于概要的文件。如果指定了多个概要，则应用“最近者优先”策略。例如，如果通过 configprop:spring.profiles.active[] 属性指定了概要 prod,live，则 application-prod.properties 中的值可以被 application-live.properties 中的值覆盖。

如果未设置任何活动概要，Environment 有一组默认概要（默认情况下为 [default]）。换言之，如果没有明确激活任何概要，则会考虑 application-default 中的属性。

应用程序属性可以使用 spring.config.import 属性从其他位置导入更多配置数据。导入在被发现时处理，并被视为立即在声明导入的位置下方插入的附加文档。

例如，你可能在 classpath application.properties 文件中拥有以下内容：

这将触发从当前目录中导入一个 dev.properties 文件（如果存在此文件）。导入的 dev.properties 的值将优先于触发导入的文件。在上面的示例中，dev.properties 可以将 spring.application.name 重新定义为一个不同的值。

无论声明次数如何，导入只导入一次。导入在一个文档内部的 properties/yaml 文件中的定义顺序无关紧要。例如，下面的两个示例生成相同的结果：

在上面的两个示例中，my.properties 文件中的值将优先于触发其导入的文件。

多个位置可以指定在一个 spring.config.import 键下。位置将按照它们定义的顺序处理，其中后面的导入优先。

一些云平台无法为已装载的文件添加文件扩展名。要导入这些没有扩展名的文件，你需要向 Spring Boot 提供一个提示，以便它知道如何加载它们。你可以通过在方括号中放置扩展名提示来执行此操作。

例如，假设你有希望导入为 yaml 的 s0 文件。你可以使用以下命令从 s1 导入它：

在云平台（例如 Kubernetes）上运行应用程序时，你通常需要读取平台提供的配置值。为此目的使用环境变量很常见，但这可能存在缺陷，尤其是在该值应保密时。

作为环境变量的替代方案，许多云平台现在允许你将配置映射到已装载的数据卷。例如，Kubernetes 可以卷装载 s4 和 s5。

可以使用两种常见的卷装载模式：

对于第一个案例，您可以直接使用 `spring.config.import`导入 YAML 或 Properties 文件，如 above中所述。对于第二个案例，您需要使用 `configtree:`前缀，以便 Spring Boot 知道它需要公开所有文件作为属性。

例如，让我们想象一下 Kubernetes 挂载了以下卷：

`username`文件的内容将是 config 值，而 `password`的内容将是机密。

要导入这些属性，您可以将以下内容添加到您的 `application.properties`或 `application.yaml`文件中：

然后，您可以通过 `Environment`以通常的方式访问或注入 `myapp.username`和 `myapp.password`属性。

如果您有多个 config 树要从同一个父文件夹导入，可以使用通配符快捷方式。任何以 `/*/`结尾的 `configtree:`位置都将导入所有直接子级作为 config 树。与非通配符导入一样，每个 config 树下的文件夹和文件名称构成了属性名称。

例如，给定以下卷：

您可以使用 `configtree:/etc/config/*/`作为导入位置：

这将添加 db.username、db.password、`mq.username`和 `mq.password`属性。

Configuration 树也可以用于 Docker 机密。当 Docker 群集服务被授予访问机密的权限时，机密会被装载到容器中。例如，如果在位置 `/run/secrets/`上装载了一个名为 `db.password`的机密，则可以使用以下内容使 `db.password`可用于 Spring 环境：

application.properties`和 `application.yaml`中的值在使用时将通过现有的 `Environment`进行过滤，因此您可以返回到先前定义的值（例如，来自系统属性或环境变量）。标准 `${name}`属性占位符语法可以在值中的任何位置使用。属性占位符还可以使用 `:`指定默认值，以将默认值与属性名称分开，例如 `${name:default}。

以下示例显示了带或不带默认值使用占位符的情况：

假设 username`属性尚未在其他地方设置，则 `app.description`将具有值 `MyApp is a Spring Boot application written by Unknown。

Spring Boot 允许将一个物理文件拆分为多个独立添加的逻辑文档。按从上到下的顺序处理文档。后面的文档可以覆盖早期文档中定义的属性。

对于 application.yaml 文件，使用标准 YAML 多文档语法。三个连续连字符表示一个文档的结尾和下一个文档的开头。

例如，以下文件有两个逻辑文档：

对于 application.properties 文件，使用特殊的 #--- 或 !--- 注释来标记文档拆分：

有时仅在满足特定条件时激活给定的属性集是很有用的。例如，可以具备仅在特定配置文件处于活动状态时才相关的属性。

可以使用 spring.config.activate.* 根据条件激活属性文档。

以下激活属性可用：

例如，以下指定第二个文档仅在 Kubernetes 上运行时处于活动状态，并且仅当 “prod” 或 “staging” 配置文件处于活动状态时：

YAML 文档需要从其分层格式转换为可以用 Spring Environment 使用的平面结构。例如，考虑以下 YAML 文档：

为了从 Environment 访问这些属性，它们会被展平如下：

同样，YAML 列表也需要展平。它们表示为带有 [index] 解引用器的属性键。例如，考虑以下 YAML：

前面对例将被转换为以下属性：

Spring Framework 提供了两个方便的类，可以用来加载 YAML 文档。YamlPropertiesFactoryBean 将 YAML 作为 Properties 加载，而 YamlMapFactoryBean 将 YAML 作为 Map 加载。

如果您想将 YAML 作为 Spring PropertySource 加载，您也可以使用 YamlPropertySourceLoader 类。

可以绑定一个声明标准 JavaBean 属性的 Bean，如下例所示：

前述 POJO 定义了以下属性：

前一节中的示例可以用不可变的方式改写，如下例所示：

在此设置中，存在一个单参数化构造函数暗示应使用构造函数绑定。这意味着绑定器将找到具有您希望绑定的参数的构造函数。如果您的类具有多个构造函数，则 @ConstructorBinding 注解可用于指定应针对构造函数绑定使用哪个构造函数。要选择不为具有单个参数化构造函数的类进行构造函数绑定，必须使用 @Autowired 注解构造函数。构造函数绑定可用于记录。除非记录有多个构造函数，否则无需使用 @ConstructorBinding。

构造函数绑定类的嵌套成员（如上述示例中的 Security）也将通过其构造函数进行绑定。

可以使用 @DefaultValue 在构造函数参数和记录组件上指定默认值。转换服务将应用于强制转换批注的 String 值为缺少属性的目标类型。

参考前一个示例，如果没有任何属性绑定到 Security，则 MyProperties 实例将包含 security 的 null 值。为了使其包含一个非空 Security 实例，即使没有任何属性绑定到它（当使用 Kotlin 时，这要求 Security 的 username 和 password 参数被声明为可为空的，因为它们没有默认值），请使用 @DefaultValue 空注解：

Spring Boot 提供基础设施，用于绑定“@1”类型并将其注册为 bean。您可以逐个类启用配置属性，或启用与组件扫描工作方式类似的配置属性扫描。

有时，使用“@2”进行注释的类可能不适合扫描，例如，如果您正在开发自己的自动配置，或您希望有条件地启用它们。在这些情况下，请使用“@3”注释指定要使用该类型的列表。这可以在任何“@4”类上完成，如下例所示：

要使用配置属性扫描，请向您的应用程序添加“@5”注释。通常，它被添加到使用“@6”进行注释的主应用程序类，但它可以被添加到任何“@7”类。默认情况下，将从声明注释的类的包中进行扫描。如果您希望定义要扫描的特定包，可以按照如下示例进行操作：

我们建议“@26”只处理环境，尤其是，不从上下文中注入其他 bean。对于特殊情况，可以使用 setter 注入或该框架提供的任何“@27”接口（例如，如果您需要访问“@29”，则可以使用“@28”）。如果您仍然希望使用构造函数注入其他 bean，则配置属性 bean 必须使用“@30”进行注释，并使用基于 JavaBean 的属性绑定。

这种配置方式特别适合于“@31”外部 YAML 配置，如下例所示：

要使用“@32”bean，您可以像注入其他任何 bean 一样注入它们，如下例所示：

除了使用“@35”对类进行注释外，您还可以在公有的“@36”方法上使用它。当您希望将属性绑定到不受您控制的第三方组件时，这样做特别有用。

要从“@37”属性配置 bean，请将其“@38”添加到其 bean 注册，如下例所示：

任何使用“@39”前缀定义的 JavaBean 属性都以类似于前面“@41”示例的方式映射到该“@40”bean。

Spring Boot 使用一些宽松的规则将“@42”属性绑定到“@43”bean，因此“@44”属性名称和 bean 属性名称之间不必完全匹配。这方面有用的常见示例包括以破折号分隔的环境属性（例如，“@45”绑定到“@46”）和首字母大写的环境属性（例如，“@47”绑定到“@48”）。

例如，考虑以下“@49”类：

使用前面代码，可以使用以下所有属性名称：

当列表在多个地方配置时，覆盖通过替换整个列表起作用。

例如，假设一个 s12 对象具有 s13 和 s14 属性，它们在默认为 s15 的情况下更新。以下示例从 s17 揭示了 s16 对象的列表：

考虑以下配置：

如果 dev 配置文件未激活，则 MyProperties.list 包含一个 MyPojo 条目，如前所定义。但是，如果 dev 配置文件已启用，则 list still 仅包含一个条目（名称为 my another name，描述为 null）。此配置 does not 会将第二个 MyPojo 实例添加到列表，但不会合并项目。

当在多个配置文件中指定 List 时，会使用优先级最高的那个（并且仅使用该那个）。考虑以下示例：

在上述示例中，如果 dev 配置文件处于活动状态，则 MyProperties.list 包含 one MyPojo 条目（名称为 my another name，描述为 null）。对于 YAML，可以用逗号分隔的列表和 YAML 列表来完全覆盖列表的内容。

对于 Map 属性，您可以与从多个来源获取的属性值绑定。但是，对于多个来源中的同一属性，将使用优先级最高的那个。以下示例从 MyProperties 公开 Map<String, MyPojo>：

考虑以下配置：

如果 dev 配置文件未激活，则 MyProperties.map 包含一个键为 key1 的条目（名称为 my name 1，描述为 my description 1）。但是，如果 dev 配置文件已启用，则 map 包含两个键为 key1（名称为 dev name 1，描述为 my description 1）和 key2 (名称为 dev name 2，描述为 dev description 2）的条目。

Spring Boot 尝试在绑定到 @ConfigurationProperties Bean 时强制将外部应用程序属性转换为正确的类型。如果您需要自定义类型转换，可以提供一个 ConversionService Bean（Bean 名称 conversionService）或自定义属性编辑器（通过 CustomEditorConfigurer Bean）或自定义 Converters（带标注为 @ConfigurationPropertiesBinding 的 Bean 定义）。

Spring Boot 会尝试验证 @ConfigurationProperties 类，只要它们使用 Spring 的 @Validated 注解进行注释。您可以在配置类上直接使用 JSR-303 jakarta.validation 约束注解。为此，请确保您的类路径中存在兼容的 JSR-303 实现，然后将约束注解添加到字段中，如下例所示：

为了确保即使未找到属性也始终触发嵌套属性的验证，关联的字段必须使用 @Valid`进行注释。以下示例基于前面的 `MyProperties 示例：

您还可以通过创建名为 configurationPropertiesValidator 的 Bean 定义来添加自定义 Spring Validator。应该将 @Bean 方法声明为 static。配置属性验证器在应用程序生命周期的早期创建，并将 @Bean 方法声明为静态允许在无需实例化 @Configuration 类的情况下创建 Bean。这样做避免了可能由早期实例化引起的任何问题。

@Value 注解是一个核心容器特性，它不提供与类型安全配置属性相同的功能。下表总结了 @ConfigurationProperties 和 @Value 支持的功能：

如果您为自己的组件定义了一组配置键，我们建议您将它们分组到使用 @ConfigurationProperties 进行注释的 POJO 中。这样做将为您提供结构化的类型安全对象，您可以将其注入到您自己的 Bean 中。

application property files 中的 SpEL 表达式在解析这些文件并填充环境时不会被处理。但是，可以在 @Value 中编写 SpEL 表达式。如果来自应用程序属性文件的属性值是 SpEL 表达式，则在通过 @Value 使用它时对其进行评估。