官网地址：

• • Externalized Configuration :: Spring Boot

Spring Boot外部配置加载顺序

• Spring Boot使用一种非常特定的PropertySource顺序设计，以便合理地覆盖值。后面的属性源可以覆盖前面定义的值(后面的优先级高于前面的)。属性源的考虑顺序如下：

• • 默认属性（通过设置SpringApplication.setDefaultProperties指定）。
  • 在你的@Configuration类上的@PropertySource注释。请注意，这些属性源在应用上下文刷新之前不会添加到Environment中。因此，这对于配置某些属性（如logging.和spring.main.）来说为时已晚，因为这些属性在应用上下文刷新之前被读取。
  • 配置数据（例如application.properties文件）。
  • 随机值属性源（RandomValuePropertySource），其属性仅在random.*。
  • 操作系统环境变量。
  • Java系统属性（System.getProperties()）。
  • 来自java:comp/env的JNDI属性。
  • ServletContext init参数。
  • ServletConfig init参数。
  • 来自SPRING_APPLICATION_JSON的属性（内联JSON嵌入在环境变量或系统属性中）。
  • 命令行参数。
  • 测试中的属性属性。在@SpringBootTest和用于测试应用特定切片的测试注释中可用。
  • 测试中的@DynamicPropertySource注释。
  • 测试中的@TestPropertySource注释。
  • 当devtools激活时，在$HOME/.config/spring-boot目录中的Devtools全局设置属性。

• 配置数据文件按照以下顺序考虑(后面的属性源可以覆盖前面定义的值，即后面的优先级高于前面的)：

• • 打包在jar中的应用属性（application.properties及其YAML变体）。
  • 打包在jar中的特定profile的应用属性（application-{profile}.properties及其YAML变体）。
  • 打包在jar外的应用属性（application.properties及其YAML变体）。
  • 打包在jar外的特定profile的应用属性（application-{profile}.properties及其YAML变体）。

• 建议为整个应用坚持使用一种格式。如果在同一位置有.properties和YAML格式的配置文件，.properties优先。如果你使用环境变量而不是系统属性，大多数操作系统不允许使用以句点(.)分隔的键名，但你可以改用下划线（例如，SPRING_CONFIG_NAME代替spring.config.name）。如果你的应用在一个Servlet容器或应用服务器中运行，那么可以使用JNDI属性（在java:comp/env中）或servlet context初始化参数，代替或添加环境变量或系统属性。
• 示例：

• • 以下是一个具体的例子，假设你开发了一个使用name属性的@Component，如下所示：

import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;@Component
public class MyBean {@Value("${name}")private String name;// ...
}

• • 在你的应用Classpath（例如，在你的jar内）中可以有一个application.properties文件，它为name提供了一个合适的默认属性值。当在新环境中运行时，可以提供一个jar外的application.properties文件来覆盖name。对于一次性测试，你可以使用特定的命令行开关启动（例如，java -jar app.jar --name="Spring"）。
  • env和configprops端点在确定为什么某个属性具有特定值时是有用的。你可以使用这两个端点来诊断意外的属性值。有关详细信息，请参阅Production ready features部分。

访问命令行属性

• 默认情况下，SpringApplication会将任何命令行选项参数（即以--开头的参数，如--server.port=9000）转换为一个属性，并将其添加到Spring Environment。前面提到的，命令行属性总是优先于基于文件的属性源。如果你不希望命令行属性被添加到Environment中，则可以使用SpringApplication.setAddCommandLineProperties(false)来禁用它们。

JSON应用程序属性

• 环境变量和系统属性通常有一些限制，意味着某些属性名称不能使用。为了解决这个问题，Spring Boot允许你将一块属性编码成一个JSON结构。当你的应用启动时，任何spring.application.json或SPRING_APPLICATION_JSON属性将被解析并添加到Environment。例如，可以在UN*X shell中作为环境变量提供SPRING_APPLICATION_JSON属性：

$ SPRING_APPLICATION_JSON='{"my":{"name":"test"}}' java -jar myapp.jar

• 在上面的例子中，你最终会得到my.name=test在Spring Environment中。同样的JSON也可以作为系统属性提供：

$ java -Dspring.application.json='{"my":{"name":"test"}}' -jar myapp.jar

• 或者你可以通过命令行参数提供JSON：

$ java -jar myapp.jar --spring.application.json='{"my":{"name":"test"}}'

• 如果你部署到经典的应用服务器，你还可以使用名为java:comp/env/spring.application.json的JNDI变量。虽然JSON中的空值会被添加到结果属性源中，但PropertySourcesPropertyResolver会将空属性视为缺失值。这意味着JSON不能用空值覆盖来自低顺序属性源的属性。

外部应用程序属性

Spring Boot 在应用程序启动时会自动查找并加载以下位置的 application.properties 和 application.yaml 文件：

• 从类路径

• • 类路径根目录
  • 类路径中的 /config 目录

• 从当前目录

• • 当前目录
  • 当前目录中的 config/ 子目录
  • config/ 子目录的直接子目录

列表按照优先级排序（较低位置的值会覆盖较前面的值）。从加载的文件中提取的文档会作为 PropertySources 添加到 Spring Environment 中。

如果您不喜欢 application 作为配置文件名，可以通过指定 spring.config.name 环境属性切换到其他文件名。例如，要查找 myproject.properties 和 myproject.yaml 文件，可以按以下方式运行您的应用程序：

$ java -jar myproject.jar --spring.config.name=myproject

也可以使用 spring.config.location 环境属性引用显式位置。此属性接受一个或多个位置的逗号分隔列表。
下面的示例展示了如何指定两个不同的文件：

$ java -jar myproject.jar --spring.config.location=\optional:classpath:/default.properties,\optional:classpath:/override.properties

如果这些位置是可选的，并且您不介意它们不存在，可以使用可选前缀 optional:。

spring.config.name、spring.config.location 和 spring.config.additional-location 被非常早期地使用，以确定要加载哪些文件。它们必须定义为环境属性（通常是操作系统环境变量、系统属性或命令行参数）。

如果 spring.config.location 包含目录（而不是文件），则它们应以 / 结尾。在运行时，它们会在加载之前附加上从 spring.config.name 生成的名称。spring.config.location 中指定的文件会被直接导入。

目录和文件位置的值也会被扩展以检查特定配置文件的文件。例如，如果您有一个 spring.config.location 为 classpath:myconfig.properties，那么也会找到并加载相应的 classpath:myconfig-.properties 文件。
在大多数情况下，每个 spring.config.location 条目您添加的都将引用单个文件或目录。位置按照定义的顺序处理，后面的可以覆盖前面的值。

如果您有一个复杂的位置设置，并且使用配置文件特定的配置文件，您可能需要提供进一步的提示，以便 Spring Boot 知道它们应如何分组。位置组是被视为同一级别的一组位置。例如，您可能希望先分组所有类路径位置，然后分组所有外部位置。位置组内的项应以 ; 分隔。有关详细信息，请参阅“配置文件特定文件”部分中的示例。

通过使用 spring.config.location 配置的位置将替换默认位置。例如，如果为 spring.config.location 配置了值 optional:classpath:/custom-config/,optional:file:./custom-config/，则考虑的完整位置集为：

optional:classpath:custom-config/
optional:file:./custom-config/

如果您希望添加额外的位置，而不是替换它们，可以使用 spring.config.additional-location。从附加位置加载的属性可以覆盖默认位置中的那些属性。例如，如果为 spring.config.additional-location 配置了值 optional:classpath:/custom-config/,optional:file:./custom-config/，则考虑的完整位置集为：

optional:classpath:/;optional:classpath:/config/
optional:file:./;optional:file:./config/;optional:file:./config/*/
optional:classpath:custom-config/
optional:file:./custom-config/

这种搜索顺序让您可以在一个配置文件中指定默认值，然后在另一个文件中选择性地覆盖这些值。您可以在 default locations 的 application.properties（或使用 spring.config.name 选择的其他基名）中为应用程序提供默认值。然后，这些默认值可以在运行时使用位于自定义位置的不同文件进行覆盖。

可选位置

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

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

例如，spring.config.import 值为 optional:file:./myconfig.properties 允许您的应用程序启动，即使 myconfig.properties 文件丢失。

如果希望忽略所有 ConfigDataLocationNotFoundException 并始终继续启动应用程序，可以使用 spring.config.on-not-found 属性。设置该属性的值为 ignore 可以通过 SpringApplication.setDefaultProperties(...) 或系统/环境变量的方式。

通配符位置

如果配置文件位置包含最后一个路径段的 * 字符，则被视为通配符位置。加载配置时会展开通配符位置，以便立即检查子目录。通配符位置在有多个配置属性源的环境中特别有用，比如 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 属性自己使用通配符位置。
通配符位置必须仅包含一个 * 并且以 */ 结尾以用于搜索目录位置，或以 */ 结尾以用于搜索文件位置。包含通配符的位置基于文件名的绝对路径按字母顺序排序。

通配符位置仅适用于外部目录。您不能在 classpath: 位置中使用通配符。

配置文件特定文件

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

配置文件特定的属性从与标准 application.properties 相同的位置加载，配置文件特定的文件总是覆盖非特定的文件。如果指定了多个配置文件，则采用最后一个赢的策略。例如，如果通过 spring.profiles.active 属性指定了配置文件 prod,live，那么 application-prod.properties 中的值可以被 application-live.properties 中的那些值覆盖。

最后一个赢的策略适用于位置组级别。spring.config.location 为 classpath:/cfg/,classpath:/ext/ 将不会具有与 classpath:/cfg/;classpath:/ext/ 相同的覆盖规则。

例如，继续上述的 prod,live 示例，我们可能有以下文件：

/cfgapplication-live.properties
/extapplication-live.propertiesapplication-prod.properties

当我们有 spring.config.location 为 classpath:/cfg/,classpath:/ext/ 时，我们在所有 /cfg 文件之前处理所有 /ext 文件：

/cfg/application-live.properties
/ext/application-prod.properties
/ext/application-live.properties

当我们有 classpath:/cfg/;classpath:/ext/ 时（使用 ; 分隔符），我们在同一级别处理 /cfg 和 /ext：

/ext/application-prod.properties
/cfg/application-live.properties
/ext/application-live.properties

如果没有激活任何配置文件，Environment 有一组默认配置文件（默认情况下为 [default]）。换句话说，如果没有显式激活任何配置文件，则会考虑 application-default 的属性。

属性文件只会被加载一次。如果您已经直接导入了配置文件特定的属性文件，那么它不会再次被导入。

导入额外数据

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

例如，您可能在类路径 application.properties 文件中有以下内容：

spring:application:name: "myapp"config:import: "optional:file:./dev.properties"

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

一个导入只会被导入一次，不管它声明了多少次。在单个 properties/yaml 文件的单个文档内的导入定义顺序无关紧要。例如，下面的两个示例产生相同的结果：

spring:config:import: "my.properties"
my:property: "value"

my:property: "value"
spring:config:import: "my.properties"

在这两个示例中，my.properties 文件中的配置将优先于原配置文件中的相应配置项。

可以在单个 spring.config.import 键下指定多个位置。位置将按照定义的顺序处理，后续导入优先。
在适当的情况下，也会考虑配置文件特定的变体进行导入。上述示例将导入 my.properties 以及任何 my-.properties 变体。

Spring Boot 包含可插入的 API 允许支持各种不同的位置地址。默认情况下，您可以导入 Java Properties、YAML 和配置树。

第三方 jar 可以提供对其他技术的支持（不要求文件是本地的）。例如，您可以想象配置数据来自外部存储，如 Consul、Apache ZooKeeper 或 Netflix Archaius。

如果您希望支持自己的位置，请参阅 org.springframework.boot.context.config 包中的 ConfigDataLocationResolver 和 ConfigDataLoader 类。

导入无扩展名的文件

某些云平台无法向卷挂载文件添加扩展名。要导入这些无扩展名的文件，您需要给 Spring Boot 一个提示，以便它知道如何加载它们。您可以通过将扩展名提示放在方括号中来实现。

例如，假设您有一个 /etc/config/myconfig 文件，希望将其作为 yaml 导入。您可以通过您的 application.properties 进行导入：

spring:config:import: "file:/etc/config/myconfig[.yaml]"

使用配置树

在云平台（如 Kubernetes）上运行应用程序时，您经常需要读取平台提供的配置值。使用环境变量用于这种用途并不罕见，但这可能有缺点，特别是如果该值应该保密。

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

有两种常见的卷挂载模式：

• 一个文件包含一组完整属性（通常写为 YAML）。
• 多个文件写入到目录树中，文件名成为“键”，内容成为“值”。

对于第一种情况，如上所述，您可以直接使用 spring.config.import 导入 YAML 或 Properties 文件。对于第二种情况，您需要使用 configtree: 前缀，让 Spring Boot 知道需要将所有文件作为属性公开。

例如，让我们假设 Kubernetes 已挂载以下卷：

etc/config/myapp/usernamepassword

username 文件的内容将是一个配置值，password 的内容将是一个秘密。
要导入这些属性，您可以将以下内容添加到 application.properties 或 application.yaml 文件中：

spring:config:import: "optional:configtree:/etc/config/"

然后可以通过环境中的常规方式访问或注入 myapp.username 和 myapp.password 属性。

配置树下的文件和文件夹名称构成属性名。在上述示例中，要以 username 和 password 的名义访问属性，可以将 spring.config.import 设置为 optional:configtree:/etc/config/myapp。

点标记法的文件名也会正确映射。例如，在上述示例中，/etc/config 下的 myapp.username 文件将导致在环境中有一个 myapp.username 属性。

配置树值可以绑定到字符串 String 和字节数组 byte[] 类型，取决于预期的内容。

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

例如，给定以下卷：

etc/config/dbconfig/db/usernamepasswordmqconfig/mq/usernamepassword

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

spring:config:import: "optional:configtree:/etc/config/*/"

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

使用通配符加载的目录按字母顺序排序。如果您需要不同的顺序，则应将每个位置列为单独的导入。

配置树也可用于 Docker 的 secret。当 Docker swarm 服务被授予对一个 secret 的访问权限时，该 secret 会被挂载到容器中。例如，如果名为 db.password 的 secret 挂载在 /run/secrets/ 位置，您可以使用以下内容使 db.password 在 Spring Environment 中可用：

spring:config:import: "optional:configtree:/run/secrets/"

属性占位符

application.properties 和 application.yaml 中的值在使用时通过现有 Environment 进行了过滤，因此您可以引用之前定义的值（例如，来自 System 属性或环境变量）。标准 𝑛𝑎𝑚𝑒属性占位符语法可以在值的任何地方使用。属性占位符也可以使用:分隔属性名和默认值来指定默认值，例如name属性占位符语法可以在值的任何地方使用。属性占位符也可以使用:分隔属性名和默认值来指定默认值，例如{name:default}.

使用默认值和不使用默认值的占位符如下示例所示：

app:name: "MyApp"description: "${app.name} 是由 ${username:Unknown} 编写的 Spring Boot 应用程序"

假设 username 属性未在其他地方设置，app.description 将具有值 MyApp 是由 Unknown 编写的 Spring Boot 应用程序。

您应该始终使用其规范形式（使用小写字母的 kebab-case）引用占位符中的属性名。这样将允许 Spring Boot 使用与松散绑定 @ConfigurationProperties 时相同的逻辑。

例如，𝑑𝑒𝑚𝑜.𝑖𝑡𝑒𝑚−𝑝𝑟𝑖𝑐𝑒将会从𝑎𝑝𝑝𝑙𝑖𝑐𝑎𝑡𝑖𝑜𝑛.𝑝𝑟𝑜𝑝𝑒𝑟𝑡𝑖𝑒𝑠文件中提取𝑑𝑒𝑚𝑜.𝑖𝑡𝑒𝑚−𝑝𝑟𝑖𝑐𝑒和𝑑𝑒𝑚𝑜.𝑖𝑡𝑒𝑚𝑃𝑟𝑖𝑐𝑒形式的配置，还会从系统环境提取𝐷𝐸𝑀𝑂𝐼𝑇𝐸𝑀𝑃𝑅𝐼𝐶𝐸。如果您使用demo.item−price将会从application.properties文件中提取demo.item−price和demo.itemPrice形式的配置，还会从系统环境提取DEMOITEMPRICE。如果您使用{demo.itemPrice}，demo.item-price 和 DEMO_ITEMPRICE 则不会被考虑。

您还可以使用此技术来创建现有 Spring Boot 属性的“短”变体。有关详细信息，请参阅“如何做指南”中的“使用‘短’命令行参数”部分。

处理多文档文件

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

对于 application.yaml 文件，使用标准的 YAML 多文档语法。三个连续的短横线代表一个文档的结束，另一个文档的开始。

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

spring:application:name: "MyApp"
---
spring:application:name: "MyCloudApp"config:activate:on-cloud-platform: "kubernetes"

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

spring.application.name=MyApp
#---
spring.application.name=MyCloudApp
spring.config.activate.on-cloud-platform=kubernetes

属性文件分隔符不能有任何前导空格，必须有正好三个短横线字符。分隔符之前和之后的行不能有相同的注释前缀。

多文档属性文件通常与激活属性结合使用，如 spring.config.activate.on-profile。有关详细信息，请参阅下一部分。

多文档属性文件不能通过 @PropertySource 或 @TestPropertySource 注解加载。

激活属性

有时仅在满足某些条件时激活某些属性集很有用。例如，您可能有仅在特定配置文件激活时才相关的属性。
您可以使用 spring.config.activate.* 有条件地激活一个属性文档。

可用的激活属性如下：

表 1. 激活属性

属性	备注
on-profile	必须匹配的配置文件表达式，以使文档生效。
on-cloud-platform	必须检测到的 CloudPlatform，以使文档生效。

例如，以下内容指定第二个文档仅在 Kubernetes 上运行时激活，并且在“prod”或“staging”配置文件激活时激活：

myprop: "always-set"
---
spring:config:activate:on-cloud-platform: "kubernetes"on-profile: "prod | staging"
myotherprop: "sometimes-set"

加密属性

Spring Boot 不提供对加密属性值的内置支持，但它确实提供了必要的钩子点来修改 Spring Environment 中包含的值。EnvironmentPostProcessor 接口允许您在应用程序启动之前操作 Environment。有关详细信息，请参阅“在启动前自定义 Environment 或 ApplicationContext”。

如果您需要一种安全的方式来存储凭证和密码，可以使用 Spring Cloud Vault 项目，它提供支持在 HashiCorp Vault 中存储外部化配置。

使用 YAML

YAML 是 JSON 的超集，因此是一种方便的格式，可以用于指定层次结构的配置数据。只要类路径中有 SnakeYAML 库，SpringApplication 类就能自动支持 YAML 作为 properties 的替代。

如果您使用 starters，spring-boot-starter 会自动提供 SnakeYAML。

将 YAML 映射到 Properties

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

environments:dev:url: "https://dev.example.com"name: "Developer Setup"prod:url: "https://another.example.com"name: "My Cool App"

为了从 Environment 中访问这些属性，它们会被平铺为如下形式：

environments.dev.url=https://dev.example.com
environments.dev.name=Developer Setup
environments.prod.url=https://another.example.com
environments.prod.name=My Cool App

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

my:servers:- "dev.example.com"- "another.example.com"

上述示例将被转换为以下属性：

my.servers[0]=dev.example.com
my.servers[1]=another.example.com

使用 [index] 符号的属性可以使用 Spring Boot 的 Binder 类绑定到 Java List 或 Set 对象。有关更多详细信息，请参阅下面的“类型安全的配置属性”部分。

YAML 文件不能通过 @PropertySource 或 @TestPropertySource 注解加载。因此，如果需要通过这种方式加载值，您需要使用 properties 文件。

直接加载 YAML

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

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

配置随机值

RandomValuePropertySource 对于注入随机值（例如到 secrets 或测试用例中）非常有用。它可以生成整数、长整数、UUID 或字符串，如下例所示：

my:secret: "${random.value}"number: "${random.int}"bignumber: "${random.long}"uuid: "${random.uuid}"number-less-than-ten: "${random.int(10)}"number-in-range: "${random.int[1024,65536]}"

random.int* 语法是 OPEN value (,max) CLOSE，其中 OPEN 和 CLOSE 是任何字符，value 和 max 是整数。 如果提供 max，则 value 是最小值，max 是最大值（不包含）。

配置系统环境属性

Spring Boot 支持为环境属性设置前缀。这对于由多个具有不同配置要求的 Spring Boot 应用程序共享的系统环境非常有用。系统环境属性的前缀可以直接在 SpringApplication 上设置。

例如，如果将前缀设置为 input，则诸如 remote.timeout 的属性在系统环境中也会解析为 input.remote.timeout。

类型安全的配置属性

使用 @Value("${property}") 注解来注入配置属性有时会比较繁琐，特别是当您要处理多个属性或数据是层次结构时。Spring Boot 提供了处理属性的替代方法，让强类型的 bean 来管理和验证应用程序的配置。

另请参见 @ConfigurationProperties 与 @Value。

JavaBean 属性绑定

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

import java.net.InetAddress;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import org.springframework.boot.context.properties.ConfigurationProperties;@ConfigurationProperties("my.service")
public class MyProperties {private boolean enabled;private InetAddress remoteAddress;private final Security security = new Security();// getters / setters...public boolean isEnabled() {return this.enabled;}public void setEnabled(boolean enabled) {this.enabled = enabled;}public InetAddress getRemoteAddress() {return this.remoteAddress;}public void setRemoteAddress(InetAddress remoteAddress) {this.remoteAddress = remoteAddress;}public Security getSecurity() {return this.security;}public static class Security {private String username;private String password;private List<String> roles = new ArrayList<>(Collections.singleton("USER"));// getters / setters...public String getUsername() {return this.username;}public void setUsername(String username) {this.username = username;}public String getPassword() {return this.password;}public void setPassword(String password) {this.password = password;}public List<String> getRoles() {return this.roles;}public void setRoles(List<String> roles) {this.roles = roles;}}
}

上述 POJO 定义了以下属性：

• my.service.enabled，默认值为 false。
• my.service.remote-address，类型可以从 String 强制转换。
• my.service.security.username 是一个嵌套的 "security" 对象，其名称由属性名称决定。特别是，类型在那里完全没有使用，可能是 SecurityProperties。
• my.service.security.password。
• my.service.security.roles 是一个默认值为 USER 的字符串集合。

映射到 @ConfigurationProperties 类的属性通过属性文件、YAML 文件、环境变量等机制进行配置，这些属性类是公共 API，但类本身的访问器（getter/setter）并不打算直接使用。

这种配置依赖于默认的空构造函数，并且 getter 和 setter 通常是必要的，因为绑定是通过标准的 Java Beans 属性描述符完成的，就像在 Spring MVC 中一样。以下几种情况下可以省略 setter：

• Map，只要初始化了，需要 getter 而不一定需要 setter，因为可以通过绑定器来操作。
• 集合和数组可以通过索引访问（通常用 YAML）或使用逗号分隔的值（properties）。后者情况下，setter 是必须的。我们建议始终为这些类型添加 setter。如果初始化了一个集合，请确保它不是不可变的（如上述示例中）。
• 如果嵌套的 POJO 属性是已初始化的（如上述示例中的 Security 字段），不需要 setter。如果希望绑定器通过默认构造函数创建实例，需要一个 setter。
• 有些人使用 Project Lombok 来自动添加 getter 和 setter。确保 Lombok 不为这些类型生成任何特定的构造函数，因为容器会自动使用它来实例化对象。

最后，只有标准的 Java Bean 属性被考虑，静态属性的绑定不支持。

构造绑定

可以将上一节中的示例重新编写为不可变形式，如下所示：

import java.net.InetAddress;
import java.util.List;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.bind.DefaultValue;@ConfigurationProperties("my.service")
public class MyProperties {// fields...private final boolean enabled;private final InetAddress remoteAddress;private final Security security;public MyProperties(boolean enabled, InetAddress remoteAddress, Security security) {this.enabled = enabled;this.remoteAddress = remoteAddress;this.security = security;}// getters...public boolean isEnabled() {return this.enabled;}public InetAddress getRemoteAddress() {return this.remoteAddress;}public Security getSecurity() {return this.security;}public static class Security {// fields...private final String username;private final String password;private final List<String> roles;public Security(String username, String password, @DefaultValue("USER") List<String> roles) {this.username = username;this.password = password;this.roles = roles;}// getters...public String getUsername() {return this.username;}public String getPassword() {return this.password;}public List<String> getRoles() {return this.roles;}}
}

在此设置中，单个参数化构造函数的存在意味着应使用构造绑定。这意味着绑定器将找到一个具有希望绑定的参数的构造函数。如果类有多个构造函数，可以使用 @ConstructorBinding 注解来指定用于构造绑定的构造函数。要选择退出具有单个参数化构造函数的类的构造绑定，必须使用 @Autowired 或将构造函数设置为 private。构造绑定可以与记录一起使用。除非记录有多个构造函数，否则无需使用 @ConstructorBinding。

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

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

参照上述示例，如果没有属性绑定到 Security，MyProperties 实例将包含一个 null 值的 security。要使其在没有属性绑定时包含一个非 null 的 Security 实例（使用 Kotlin 时，这将需要将 Security 的 username 和 password 参数声明为可空，因为它们没有默认值），使用空的 @DefaultValue 注解：

public MyProperties(boolean enabled, InetAddress remoteAddress, @DefaultValue Security security) {this.enabled = enabled;this.remoteAddress = remoteAddress;this.security = security;
}

要使用构造绑定，必须通过 @EnableConfigurationProperties 或配置属性扫描启用该类。不能使用常规 Spring 机制（例如 @Component bean，通过 @Bean 方法创建的 bean 或通过 @Import 加载的 bean）创建的 bean 使用构造绑定。

要使用构造绑定，必须使用 -parameters 进行编译。如果使用 Spring Boot 的 Gradle 插件，或者使用 Maven 并使用 spring-boot-starter-parent，这将自动发生。

不推荐将 java.util.Optional 与 @ConfigurationProperties 一起使用，因为它主要用于作为返回类型。因此，它不适合配置属性注入。为了与其他类型的属性一致，如果声明了一个 Optional 属性并且没有值，将绑定 null 而不是一个空的 Optional。

启用 @ConfigurationProperties 注解类型

Spring Boot 提供了基础设施来绑定 @ConfigurationProperties 类型并将它们注册为 bean。您可以逐个类地启用配置属性，也可以启用配置属性扫描，类似于组件扫描。

有时，使用 @ConfigurationProperties 注解的类可能不适合扫描，例如，如果您正在开发自己的自动配置，或希望条件性地启用它们。在这些情况下，使用 @EnableConfigurationProperties 注解指定要处理的类型列表。这可以在任何 @Configuration 类上完成，如以下示例所示：

import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(SomeProperties.class)
public class MyConfiguration {
}

import org.springframework.boot.context.properties.ConfigurationProperties;@ConfigurationProperties("some.properties")
public class SomeProperties {
}

要使用配置属性扫描，请将 @ConfigurationPropertiesScan 注解添加到您的应用程序中。通常，它会添加到用 @SpringBootApplication 注解的主应用程序类中，但它可以添加到任何 @Configuration 类中。默认情况下，扫描将从声明该注解的类的包开始进行。如果要定义特定的包进行扫描，可以按照以下示例进行定义：

import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;@SpringBootApplication
@ConfigurationPropertiesScan({ "com.example.app", "com.example.another" })
public class MyApplication {
}

当使用配置属性扫描或通过 @EnableConfigurationProperties 注册 @ConfigurationProperties bean 时，该 bean 有一个常规名称：<prefix>-<fqn>，其中<prefix>是 @ConfigurationProperties 注解中指定的环境键前缀，而<fqn>是该 bean 的完全限定名。如果注解没有提供任何前缀，则仅使用 bean 的完全限定名。

假设在 com.example.app 包中，上述 SomeProperties 示例的 bean 名称为 some.properties-com.example.app.SomeProperties。

我们建议 @ConfigurationProperties 只处理环境，不注入上下文中的其他 bean。在某些极端情况下，可以使用注入器（setter injection）或框架提供的任何 *Aware 接口（例如，如果需要访问 Environment，则使用 EnvironmentAware）。如果您仍希望使用构造函数注入其他 bean，配置属性 bean 必须注解为 @Component 并使用基于 JavaBean 的属性绑定。

使用 @ConfigurationProperties 注解类型

这种配置风格与 SpringApplication 的外部 YAML 配置特别契合，如下例所示：

my:service:remote-address: 192.168.1.1security:username: "admin"roles:- "USER"- "ADMIN"

要使用 @ConfigurationProperties bean，可以像使用其他 bean 一样注入它们，如以下示例所示：

import org.springframework.stereotype.Service;@Service
public class MyService {private final MyProperties properties;public MyService(MyProperties properties) {this.properties = properties;}public void openConnection() {Server server = new Server(this.properties.getRemoteAddress());server.start();// ...}// ...
}

使用 @ConfigurationProperties 还可以生成元数据文件，这些文件可供 IDE 提供自动完成功能以供您自己的键使用。有关详细信息，请参阅附录。

第三方配置

除了使用 @ConfigurationProperties 注解类，还可以将其注解在公共的 @Bean 方法上。当您希望将属性绑定到您无法控制的第三方组件时，这特别有用。

要从环境属性配置 bean，请在其 bean 注册中添加 @ConfigurationProperties，如以下示例所示：

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration(proxyBeanMethods = false)
public class ThirdPartyConfiguration {@Bean@ConfigurationProperties(prefix = "another")public AnotherComponent anotherComponent() {return new AnotherComponent();}
}

任何以 another 为前缀定义的 JavaBean 属性都会映射到 AnotherComponent bean，方式类似于上述 SomeProperties 示例。

宽松绑定

Spring Boot 使用一些宽松规则将 Environment 属性绑定到 @ConfigurationProperties bean，因此在 Environment 属性名称和 bean 属性名称之间不需要完全匹配。常见的例子包括带有连字符分隔的环境属性（例如，context-path 绑定到 contextPath）和大写环境属性（例如 PORT 绑定到 port）。

例如，考虑以下 @ConfigurationProperties 类：

import org.springframework.boot.context.properties.ConfigurationProperties;@ConfigurationProperties(prefix = "my.main-project.person")
public class MyPersonProperties {private String firstName;public String getFirstName() {return this.firstName;}public void setFirstName(String firstName) {this.firstName = firstName;}
}

通过上述代码，可以使用以下属性名称：

属性	备注
my.main-project.person.first-name	Kebab case，建议在 .properties 和 YAML 文件中使用
my.main-project.person.firstName	标准驼峰命名法
my.main-project.person.first_name	下划线表示法，.properties 和 YAML 文件中的替代格式
MY_MAINPROJECT_PERSON_FIRSTNAME	大写格式，建议使用系统环境变量时使用

注解的 prefix 值必须为 kebab case（小写字母并用 - 分隔，例如 my.main-project.person）。

各属性源的宽松绑定规则表：

属性源	简单	列表
Properties 文件	驼峰命名法、kebab case 或下划线表示法	使用 [ ] 的标准列表语法，或逗号分隔的值
YAML 文件	驼峰命名法、kebab case 或下划线表示法	YAML 标准列表语法或逗号分隔的值
环境变量	使用下划线作为分隔符的大写格式（参见从环境变量绑定）	数值被下划线包围（参见从环境变量绑定）
系统属性	驼峰命名法、kebab case 或下划线表示法	使用 [ ] 的标准列表语法，或逗号分隔的值

我们建议在可能的情况下将属性存储在小写 kebab 格式中，例如 my.person.first-name=Rod。

绑定映射(Map)

当我们把配置属性绑定到 Map 类型的属性时，通常希望保留键值的原始形式，特别是当键包含特殊字符时。在常规绑定过程中，任何不在方括号 ([]) 内的非字母数字字符、连字符 (-) 或点 (.) 都会被移除。为了保留这些特殊字符，需要使用方括号来包裹这些键。

例让我们通过一个具体的例子进行解释。

示例配置

假如我们在配置文件中有如下内容：

my:map:"[/key1]": "value1""[/key2]": "value2""/key3": "value3"

在上述示例中，键 /key1 和 /key2 被方括号包裹，而 /key3 没有。

解析如何进行

Spring Boot 在加载这些配置时，会分别处理每个键：

• 对于 [/key1] 和 [/key2]，因为它们被方括号包裹，键会被原样保留。
• 对于 /key3，因为没有方括号包裹，解析时斜杠 (/) 会被移除，所以结果键会是 key3。

最终解析绑定到 Map<String,String> 时，对应的Map内容如下所示：

Map<String, String> map = new HashMap<>();
map.put("/key1", "value1"); // 保留斜杠
map.put("/key2", "value2"); // 保留斜杠
map.put("key3", "value3");  // 斜杠被移除

标量值绑定

对于标量值（简单的 Java 对象类型，例如 String、Integer、Double 等），键名包含点 (.) 时，不需要使用方括号包裹。这些键的点会被保留。

例如，有如下配置：

a.b=c

当绑定到 Map<String, String> 时，结果Map内容如下：

Map<String, String> map = new HashMap<>();
map.put("a.b", "c");

键 a.b 保持原样。

更复杂的类型

但是，当绑定到更复杂的类型时，例如 Map<String, Object>，并且键包含点 (.) 时，需要使用方括号包裹键名，以确保点得以保留并作为键的一部分。

例如，有如下配置：

a.b=c

当绑定到 Map<String, Object> 时，如果不使用方括号，Spring 会认为 a 是包含 b=c 的一个嵌套对象。因此返回的 Map 将如下所示：

Map<String, Object> map = new HashMap<>();
map.put("a", Map.of("b", "c"));

而使用方括号后的配置：

[a.b]=c

绑定效果是：

Map<String, Object> map = new HashMap<>();
map.put("a.b", "c");

在这个例子中，键 a.b 被完整保留，成为单独的一个键值对。

总结一下：

• 非方括号包裹的键名中，任何非字母数字字符、连字符 (-) 或点 (.) 会被移除。
• 为了保留特殊字符（例如 /），需要用方括号包裹键名。
• 对于标量值，点 (.) 保留不变，无需方括号。
• 对于更复杂的类型，如 Map<String, Object>，需要用方括号包裹包含点 (.) 的键名，以确保点被作为键的一部分保留。

从环境变量绑定

大多数操作系统对环境变量名有严格的规定。例如，Linux shell 变量只能包含字母（a 到 z 或 A 到 Z）、数字（0 到 9）或下划线字符（_）。按照惯例，Unix shell 变量名通常是大写的。

Spring Boot 的宽松绑定规则尽可能地与这些命名约束兼容。

要将属性名称从规范形式转换为环境变量名称，可以遵循以下规则：

• 用下划线 (_) 替换点号 (.)。
• 移除任何连字符 (-)。
• 转换为大写。

例如，配置属性 spring.main.log-startup-info 将成为环境变量 SPRING_MAIN_LOGSTARTUPINFO。

绑定到对象列表时也可以使用环境变量。要绑定到 List，元素编号应在变量名中用下划线包围。

例如，配置属性 my.service[0].other 将使用环境变量 MY_SERVICE_0_OTHER。

缓存

宽松绑定使用缓存来提升性能。默认情况下，此缓存仅应用于不可变属性源。要自定义此行为，例如为可变属性源启用缓存，可以使用 ConfigurationPropertyCaching。

合并复杂类型

当列表在多个地方配置时，覆盖操作会替换整个列表。

例如，假设一个 MyPojo 对象，默认情况下 name 和 description 属性都是 null。下面的示例公开了一些来自 MyProperties 的 MyPojo 对象列表：

import java.util.ArrayList;
import java.util.List;
import org.springframework.boot.context.properties.ConfigurationProperties;@ConfigurationProperties("my")
public class MyProperties {private final List<MyPojo> list = new ArrayList<>();public List<MyPojo> getList() {return this.list;}
}

考虑以下配置：

my:list:- name: "my name"description: "my description"
---
spring:config:activate:on-profile: "dev"
my:list:- name: "my another name"

如果 dev 配置文件未激活，MyProperties.list 包含一个 MyPojo 条目，如之前定义的。如果启用了 dev 配置文件，列表仍然只包含一个条目（name 为 my another name，description 为 null）。此配置不会将第二个 MyPojo 实例添加到列表中，也不会合并这些项。

当列表在多个配置文件中指定时，使用优先级最高的那个（仅此一个）。考虑以下示例：

my:list:- name: "my name"description: "my description"- name: "another name"description: "another description"
---
spring:config:activate:on-profile: "dev"
my:list:- name: "my another name"

在上述示例中，如果 dev 配置文件是活动的，MyProperties.list 包含一个 MyPojo 条目（name 为 my another name，description 为 null）。对于 YAML，逗号分隔列表和 YAML 列表都可以用于完全覆盖列表的内容。

对于 Map 属性，可以绑定来自多个源的属性值。但是，对于多个源中的相同属性，使用优先级最高的那个。以下示例从 MyProperties 暴露一个 Map<String, MyPojo>：

import java.util.LinkedHashMap;
import java.util.Map;
import org.springframework.boot.context.properties.ConfigurationProperties;@ConfigurationProperties("my")
public class MyProperties {private final Map<String, MyPojo> map = new LinkedHashMap<>();public Map<String, MyPojo> getMap() {return this.map;}
}

考虑以下配置：

my:map:key1:name: "my name 1"description: "my description 1"
---
spring:config:activate:on-profile: "dev"
my:map:key1:name: "dev name 1"key2:name: "dev name 2"description: "dev description 2"

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

上述合并规则适用于来自所有属性源的属性，而不仅仅是文件。

属性转换

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

由于这个 bean 在应用程序生命周期的早期被请求，确保限制 ConversionService 使用的依赖项。通常，您需要的任何依赖项在创建时可能尚未完全初始化。如果自定义 ConversionService 不需要用于配置键的强制转换，可以将其重命名，仅依赖于带有 @ConfigurationPropertiesBinding 注解的自定义转换器。

转换持续时间

Spring Boot 对表示持续时间有专门的支持。如果您公开一个 java.time.Duration 属性，以下格式在应用程序属性中可用：

• 常规的 long 表示形式（默认使用毫秒为单位，除非指定了 @DurationUnit）
• java.time.Duration 使用的标准 ISO-8601 格式
• 更易读的格式，值和单位耦合（例如 10s 表示 10 秒）

例如：

import java.time.Duration;
import java.time.temporal.ChronoUnit;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.convert.DurationUnit;@ConfigurationProperties("my")
public class MyProperties {@DurationUnit(ChronoUnit.SECONDS)private Duration sessionTimeout = Duration.ofSeconds(30);private Duration readTimeout = Duration.ofMillis(1000);// getters / setters...public Duration getSessionTimeout() {return this.sessionTimeout;}public void setSessionTimeout(Duration sessionTimeout) {this.sessionTimeout = sessionTimeout;}public Duration getReadTimeout() {return this.readTimeout;}public void setReadTimeout(Duration readTimeout) {this.readTimeout = readTimeout;}
}

要指定一个 30 秒的会话超时时间，30、PT30S 和 30s 都是等效的。一个 500ms 的读取超时可以使用以下任何形式：500、PT0.5S 和 500ms。

您还可以使用任何支持的单位。这些单位包括：

• ns 表示纳秒
• us 表示微秒
• ms 表示毫秒
• s 表示秒
• m 表示分钟
• h 表示小时
• d 表示天

默认单位是毫秒，可以如上述示例中使用 @DurationUnit 进行重写。

如果您更喜欢使用构造绑定，可以如下面的示例公开相同的属性：

import java.time.Duration;
import java.time.temporal.ChronoUnit;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.bind.DefaultValue;
import org.springframework.boot.convert.DurationUnit;@ConfigurationProperties("my")
public class MyProperties {// fields...private final Duration sessionTimeout;private final Duration readTimeout;public MyProperties(@DurationUnit(ChronoUnit.SECONDS) @DefaultValue("30s") Duration sessionTimeout,@DefaultValue("1000ms") Duration readTimeout) {this.sessionTimeout = sessionTimeout;this.readTimeout = readTimeout;}// getters...public Duration getSessionTimeout() {return this.sessionTimeout;}public Duration getReadTimeout() {return this.readTimeout;}
}

如果您正在升级一个 Long 属性，如果不是毫秒，请确保定义单位（使用 @DurationUnit）。这样可以提供透明的升级路径，同时支持更丰富的格式。

转换周期

除了持续时间，Spring Boot 还可以处理 java.time.Period 类型。以下格式可以在应用程序属性中使用：

• 常规的 int 表示形式（默认使用天为单位，除非指定了 @PeriodUnit）
• java.time.Period 使用的标准 ISO-8601 格式
• 更简单的格式，值和单位成对耦合（例如 1y3d 表示 1 年和 3 天）

简单格式支持以下单位：

• y 表示年
• m 表示月
• w 表示周
• d 表示天

java.time.Period 类型实际上从未存储过周数，它是“7 天”的快捷方式。

转换数据大小

Spring Framework 有一个 DataSize 值类型，用于表示以字节为单位的大小。如果您公开一个 DataSize 属性，以下格式在应用程序属性中可用：

• 常规的 long 表示形式（默认使用字节为单位，除非指定了 @DataSizeUnit）
• 更易读的格式，值和单位耦合（例如 10MB 表示 10 兆字节）

示例：

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.convert.DataSizeUnit;
import org.springframework.util.unit.DataSize;
import org.springframework.util.unit.DataUnit;@ConfigurationProperties("my")
public class MyProperties {@DataSizeUnit(DataUnit.MEGABYTES)private DataSize bufferSize = DataSize.ofMegabytes(2);private DataSize sizeThreshold = DataSize.ofBytes(512);// getters/setters...public DataSize getBufferSize() {return this.bufferSize;}public void setBufferSize(DataSize bufferSize) {this.bufferSize = bufferSize;}public DataSize getSizeThreshold() {return this.sizeThreshold;}public void setSizeThreshold(DataSize sizeThreshold) {this.sizeThreshold = sizeThreshold;}
}

要指定 10 兆字节的缓冲区大小，10 和 10MB 是等效的。一个 256 字节的大小阈值可以表示为 256 或 256B。

您还可以使用任何支持的单位。包括：

• B 表示字节
• KB 表示千字节
• MB 表示兆字节
• GB 表示千兆字节
• TB 表示太字节

默认单位是字节，可以如上述示例中使用 @DataSizeUnit 进行重写。

如果您更喜欢使用构造绑定，可以如下面的示例公开相同的属性：

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.bind.DefaultValue;
import org.springframework.boot.convert.DataSizeUnit;
import org.springframework.util.unit.DataSize;
import org.springframework.util.unit.DataUnit;@ConfigurationProperties("my")
public class MyProperties {// fields...private final DataSize bufferSize;private final DataSize sizeThreshold;public MyProperties(@DataSizeUnit(DataUnit.MEGABYTES) @DefaultValue("2MB") DataSize bufferSize,@DefaultValue("512B") DataSize sizeThreshold) {this.bufferSize = bufferSize;this.sizeThreshold = sizeThreshold;}// getters...public DataSize getBufferSize() {return this.bufferSize;}public DataSize getSizeThreshold() {return this.sizeThreshold;}
}

如果您正在升级一个 Long 属性，如果不是以字节为单位，请确保定义单位（使用 @DataSizeUnit）。这样可以提供透明的升级路径，同时支持更丰富的格式。

@ConfigurationProperties 验证

@ConfigurationProperties 注解用于将外部配置文件中的属性绑定到一个类上，以便在 Spring Boot 应用程序中使用。当在 @ConfigurationProperties 类上使用了 Spring 的 @Validated 注解时，Spring Boot 将尝试验证这些属性。下面详细解释如何使用和验证这些配置属性。

基本用法

假设有一个配置类 MyProperties，用于绑定以 my.service 开头的配置属性：

import java.net.InetAddress;
import jakarta.validation.constraints.NotNull;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;@ConfigurationProperties("my.service")
@Validated
public class MyProperties {@NotNullprivate InetAddress remoteAddress;// getters/setters...public InetAddress getRemoteAddress() {return this.remoteAddress;}public void setRemoteAddress(InetAddress remoteAddress) {this.remoteAddress = remoteAddress;}
}

在这个例子中，remoteAddress 属性使用了 @NotNull 注解，表示它不能为空。当 Spring Boot 加载这个配置类时，如果 remoteAddress 为空，将会抛出验证异常。

嵌套属性的验证

如果配置类中包含嵌套的属性，需要确保嵌套的类也被验证。例如，扩展上面的例子，加入一个 Security 类来处理安全相关的配置：

import java.net.InetAddress;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotEmpty;
import jakarta.validation.constraints.NotNull;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;@ConfigurationProperties("my.service")
@Validated
public class MyProperties {@NotNullprivate InetAddress remoteAddress;@Validprivate final Security security = new Security();// getters/setters...public InetAddress getRemoteAddress() {return this.remoteAddress;}public void setRemoteAddress(InetAddress remoteAddress) {this.remoteAddress = remoteAddress;}public Security getSecurity() {return this.security;}public static class Security {@NotEmptyprivate String username;// getters/setters...public String getUsername() {return this.username;}public void setUsername(String username) {this.username = username;}}
}

在这个例子中，Security 类的 username 属性使用了 @NotEmpty 注解，确保用户名不为空。通过在 MyProperties 类中使用 @Valid 注解，确保 security 属性中的嵌套属性也会被验证。

自定义验证器

如果需要自定义验证逻辑，可以通过创建一个名为 configurationPropertiesValidator 的 Bean 来实现。这个 Bean 方法应该声明为静态方法，以便在 Spring Boot 启动时进行早期创建，避免因实例化顺序问题而引起的验证失败。以下是一个示例：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.validation.beanvalidation.LocalValidatorFactoryBean;@Configuration
public class MyValidationConfig {@Beanpublic static LocalValidatorFactoryBean configurationPropertiesValidator() {return new LocalValidatorFactoryBean();}
}

这里的 configurationPropertiesValidator 方法返回了一个 LocalValidatorFactoryBean，它是 Spring 提供的用于 JSR-303 验证的工厂类。

查看配置属性信息

Spring Boot 的 actuator 模块提供了一个端点 /actuator/configprops，用于公开所有 @ConfigurationProperties Bean 的详细信息。有关详细信息，请参阅Endpoints :: Spring Boot。

@ConfigurationProperties 与 @Value

对比表格

特性	@ConfigurationProperties	@Value
定义	用于将配置属性绑定到结构化对象	用于将单个配置属性注入到字段或方法参数
使用位置	类级别、@Bean 方法、@Component 类	字段、方法或构造函数参数级别
宽松绑定	完全支持。可以自动将不同命名风格（如camelCase、kebab-case、snake_case）的属性映射到Java字段	有限支持。使用kebab-case时可以匹配camelCase和UPPER_CASE
元数据支持	支持。可以生成配置元数据，用于IDE自动完成和文档生成	不支持
SpEL表达式支持	不支持	支持。可以在@Value注解中使用SpEL表达式
类型转换	自动进行复杂的类型转换，包括Duration、DataSize等	基本的类型转换，复杂类型需要自定义转换器
嵌套属性	支持。可以轻松映射复杂的嵌套结构	有限支持。需要使用点号表示法，如"parent.child.property"
数组和集合绑定	完全支持。可以轻松绑定到List、Set、Map等	有限支持。可以绑定到数组，但复杂集合需要额外配置
验证	支持。可以与@Validated注解结合使用，应用JSR-303验证	不直接支持。需要额外的验证逻辑
默认值	通过字段初始化、@DefaultValue注解或在@ConfigurationProperties中指定	在@Value注解中直接指定，如@Value("${property:default}")
前缀支持	支持。可以使用@ConfigurationProperties(prefix="myapp")指定前缀	不直接支持。每次都需要完整的属性名
批量属性注入	支持。可以一次性注入多个相关属性	不支持。每个属性需要单独的@Value注解
重载属性	支持。可以在不同配置文件中覆盖属性，遵循Spring Boot的属性优先级	支持。同样遵循Spring Boot的属性优先级
环境变量支持	自动支持。可以从环境变量中读取值，支持规范化命名	支持。可以使用${ENV_VAR}语法直接引用环境变量
配置文件位置	通常在application.properties或application.yml中集中定义，但也支持自定义配置文件	可以从任何Spring环境中可用的属性源读取
重构友好性	高。由于是类型安全的，IDE可以更好地支持重构	低。基于字符串，重构时可能会遗漏
测试友好性	高。可以轻松创建测试配置类或使用@TestPropertySource	中等。可以使用@TestPropertySource，但每个属性可能需要单独设置
性能	较好。属性会被一次性绑定到对象，缓存结果	相对较差。每次访问都可能需要解析，但Spring有一定的缓存机制
IDE支持	优秀。提供自动完成、类型检查等	有限。主要是字符串基础的支持
适用场景	大型配置集合，模块化配置，类型安全至关重要的场景	简单配置，单个值注入，需要SpEL表达式支持的场景
可维护性	高。集中管理相关配置，结构清晰	中等。分散的属性可能导致难以维护
文档生成	支持。可以生成配置属性文档，特别是结合@ConfigurationProperties使用	不直接支持。需要手动文档
条件装配	支持与@ConditionalOnProperty等注解结合使用	可以与@ConditionalOnExpression结合使用
动态更新	不直接支持。通常需要应用重启	可以通过@RefreshScope支持动态更新
国际化支持	可以与Spring的国际化机制结合使用	直接支持，可以使用#{...}语法引用消息源

特性：定义和使用

@ConfigurationProperties:

• 类级别注解，用于将配置属性绑定到结构化对象。
• 示例：

@Configuration
@ConfigurationProperties(prefix = "mail")
public class MailProperties {private String host;private int port;// getters and setters
}

@Value:

• 字段、方法或构造函数参数级别的注解，用于注入单个属性。
• 示例：

@Component
public class MailService {@Value("${mail.host}")private String host;@Value("${mail.port}")private int port;
}

特性：宽松绑定

@ConfigurationProperties:

完全支持。可以自动将不同命名风格的属性映射到Java字段。

示例：

配置文件：

mail:smtp-host: smtp.example.comsmtp-port: 25

Java类：

@ConfigurationProperties(prefix = "mail")
public class MailProperties {private String smtpHost; // 自动映射smtp-hostprivate int smtpPort; // 自动映射smtp-port
}

@Value:

有限支持。主要支持kebab-case到camelCase的转换。

示例：

配置文件：

mail:smtp-host: smtp.example.comsmtp-port: 25

Java类：

@Component
public class MailService {@Value("${mail.smtp-host}")private String smtpHost;@Value("${mail.smtp-port}")private int smtpPort;
}

特性：元数据支持

@ConfigurationProperties:

支持。可以生成配置元数据，用于IDE自动完成和文档生成。

示例：

@ConfigurationProperties(prefix = "acme")
public class AcmeProperties {/*** 服务器IP地址*/private String remoteAddress;// IDE可以显示此注释作为提示
}

@Value:

不支持。无法为IDE提供自动完成或属性说明。

示例：

@Component
public class AcmeService {@Value("${acme.remote-address}")private String remoteAddress;// IDE无法提供关于此属性的额外信息
}

特性：SpEL表达式支持

@ConfigurationProperties:

• 不支持SpEL表达式。
• 示例：不适用

@Value:

• 支持SpEL表达式。
• 示例：

@Component
public class SpelExample {@Value("#{systemProperties['user.region']}")private String region;@Value("#{T(java.lang.Math).random() * 100.0}")private double randomNumber;
}

特性：类型转换

@ConfigurationProperties:

自动进行复杂的类型转换。

示例：

配置文件：

app:timeout: 5scolors: red,green,blue

Java类：

@ConfigurationProperties(prefix = "app")
public class AppProperties {private Duration timeout; // 自动转换为Durationprivate List<String> colors; // 自动转换为List<String>
}

@Value:

基本的类型转换，复杂类型需要自定义转换器。

示例：

@Component
public class AppConfig {@Value("${app.timeout}")private String timeout; // 仍然是String，需手动转换@Value("${app.colors}")private String[] colors; // 可以自动转换为数组
}

嵌套属性：

@ConfigurationProperties：

@Component
@ConfigurationProperties(prefix = "app")
public class AppConfig {private MailConfig mail;public MailConfig getMail() {return mail;}public void setMail(MailConfig mail) {this.mail = mail;}public static class MailConfig {private String host;private int port;// getters and setters}
}

配置文件（application.properties）：

app.mail.host=smtp.example.com
app.mail.port=25

@Value：

@Component
public class MailService {@Value("${app.mail.host}")private String mailHost;@Value("${app.mail.port}")private int mailPort;// getters and setters
}

数组和集合绑定：

@ConfigurationProperties：

@Component
@ConfigurationProperties(prefix = "app")
public class AppConfig {private List<String> servers;// getters and setters
}

配置文件（application.properties）：

app.servers[0]=server1
app.servers[1]=server2

@Value：

java
复制代码
@Component
public class ServerConfig {@Value("${app.servers}")private String[] servers;// getters and setters
}

验证：

@ConfigurationProperties：

@Component
@ConfigurationProperties(prefix = "app")
@Validated
public class AppConfig {@NotBlankprivate String name;// getters and setters
}

@Value：需要手动验证，例如使用JSR-303的注解或自定义逻辑来验证属性。

默认值：

@ConfigurationProperties：

@Component
@ConfigurationProperties(prefix = "app")
public class AppConfig {@DefaultValue("defaultName")private String name;// getters and setters
}

@Value：

@Component
public class MessageService {@Value("${app.message:defaultMessage}")private String defaultMessage;// getters and setters
}

批量属性注入：

@ConfigurationProperties：

@Component
@ConfigurationProperties(prefix = "app")
public class AppConfig {private Map<String, String> properties;// getters and setters
}

配置文件（application.properties）：

app.properties.key1=value1
app.properties.key2=value2

@Value：每个属性需要单独的注解来注入。

环境变量支持：

@ConfigurationProperties：

@Component
@ConfigurationProperties(prefix = "app")
public class AppConfig {private String envVar;public String getEnvVar() {return envVar;}public void setEnvVar(String envVar) {this.envVar = envVar;}
}

环境变量设置：

arduino
复制代码
export APP_ENV_VAR=myenvvalue

@Value：

@Component
public class EnvironmentService {@Value("${APP_ENV_VAR}")private String envVar;// getters and setters
}

前缀支持、重载属性、配置文件位置

@ConfigurationProperties：

@ConfigurationProperties(prefix = "app")
@Component
public class AppConfig {private String name;private String environment;private String version;// getters and setters
}

配置文件（application.properties）：

app.name=MyApp
app.environment=dev

配置文件（application-prod.properties）：

app.environment=prod
app.version=1.0.0

@Value：

@Component
public class MessageService {@Value("${app.name}")private String appName;@Value("${app.environment}")private String environment;@Value("${app.version:1.0.0}")private String version;// getters and setters
}

重构友好性

@ConfigurationProperties： 由于是类型安全的，重构时可以直接在Java类中重命名字段，IDE可以帮助检测和更新所有相关使用该属性的地方，如：

@ConfigurationProperties(prefix = "app")
@Component
public class AppConfig {private String applicationName;// getters and setters
}

@Value： 在使用字符串的情况下，重构时需要手动查找和更新所有使用该属性的地方，容易遗漏：

@Component
public class MessageService {@Value("${app.name}")private String applicationName;// getters and setters
}

测试友好性

@ConfigurationProperties： 使用@TestPropertySource注解可以轻松模拟配置属性，使得单元测试编写更加方便：

java
复制代码
@RunWith(SpringRunner.class)
@SpringBootTest
@TestPropertySource(locations = "classpath:test.properties")
public class AppConfigTests {@Autowiredprivate AppConfig appConfig;// test cases
}

@Value： 每个属性通常需要单独的模拟，测试配置相对繁琐：

@RunWith(SpringRunner.class)
@SpringBootTest
public class MessageServiceTests {@Value("${app.name}")private String appName;// test cases
}

性能

@ConfigurationProperties： 属性一次性绑定到对象，性能较好：

@ConfigurationProperties(prefix = "app")
@Component
public class AppConfig {private String name;// getters and setters
}

@Value： 每次访问时需要解析字符串，性能相对较差：

@Component
public class MessageService {@Value("${app.name}")private String appName;// getters and setters
}

IDE支持

@ConfigurationProperties： 提供良好的IDE支持，包括自动完成和类型检查：

@ConfigurationProperties(prefix = "app")
@Component
public class AppConfig {private String name;// getters and setters
}

@Value： 基于字符串的支持，IDE功能受限：

@Component
public class MessageService {@Value("${app.name}")private String appName;// getters and setters
}

适用场景

@ConfigurationProperties： 适用于大型配置集合、模块化配置和类型安全要求较高的场景：

@ConfigurationProperties(prefix = "app")
@Component
public class AppConfig {private String name;// getters and setters
}

@Value： 适用于简单的配置注入、单个值的读取和需要SpEL表达式支持的简单场景：

@Component
public class MessageService {@Value("${app.name}")private String appName;// getters and setters
}

可维护性

@ConfigurationProperties： 高，能够集中管理相关配置，结构清晰：

@ConfigurationProperties(prefix = "app")
@Component
public class AppConfig {private String name;// getters and setters
}

@Value： 中等，分散的属性可能导致配置不易维护：

@Component
public class MessageService {@Value("${app.name}")private String appName;// getters and setters
}

文档生成

@ConfigurationProperties： 支持生成配置属性的文档，有助于团队成员理解和使用配置：

@ConfigurationProperties(prefix = "app")
@Component
public class AppConfig {private String name;// getters and setters
}

@Value： 不直接支持文档生成，需要额外的文档工作来说明每个属性的用途和配置。

注意

本文大多翻译自原文，进行了适当补充与扩展。