Spring 类型安全的配置属性
使用 @Value("${property}") 注解来注入配置属性有时会很麻烦，特别是当你要处理多个属性或你的数据是分层的。 Spring Boot提供了一种处理属性的替代方法，让强类型的Bean管理和验证你的应用程序的配置。
另请参见@Value 和类型安全配置属性之间的区别。
一、 JavaBean 属性绑定
如下面的例子所示，可以绑定一个声明了标准JavaBean属性的bean。
Java
Kotlin
@ConfigurationProperties("my.service")
public class MyProperties {
private boolean enabled;
private InetAddress remoteAddress;
private final Security security = new Security();
// getters / setters...
public static class Security {
private String username;
private String password;
private List roles = new ArrayList<>(Collections.singleton("USER"));
// getters / setters...
}
}
前面的POJO定义了以下属性。
- my.service.enabled，默认值为`false`。
- my.service.remote-address，其类型可由`String`强制提供。
- my.service.security.username，有一个嵌套的 security 对象，其名称由该属性的名称决定。 特别是，那里完全没有使用类型，可以是 SecurityProperties。
- my.service.security.password.
- my.service.security.role，有一个 String 的集合，默认为 USER。
| 映射到Spring Boot中可用的 @ConfigurationProperties 类的属性，通过properties文件、YAML文件、环境变量和其他机制进行配置，这些属性是公共API，但类本身的 getters/setters 并不意味着可以直接使用（一句话，Spring也是通过getter/setter这些public方法进行设置值的，你别用）。 |
| 这样的设计依赖于一个默认的无参构造函数，getter和setter通常是必须的，因为绑定是通过标准的Java Beans property descriptor（Java内省）实现的，就像在Spring MVC中一样。 在以下情况下，可以省略setter。
有些人使用Project Lombok来自动添加getter和setter。 请确保Lombok不会为这样的类型生成任何特定的构造函数，因为它被容器自动用来实例化对象。 最后，只考虑标准的Java Bean属性，不支持对静态属性的绑定。 |
二、 构造函数绑定
上一节的例子可以用不可变的方式重写，如下例所示。
Java
@ConfigurationProperties("my.service")
public class MyProperties {
// fields...
public MyProperties(boolean enabled, InetAddress remoteAddress, Security security) {
this.enabled = enabled;
this.remoteAddress = remoteAddress;
this.security = security;
}
// getters...
public static class Security {
// fields...
public Security(String username, String password, @DefaultValue("USER") List roles) {
this.username = username;
this.password = password;
this.roles = roles;
}
// getters...
}
}
在这种设置中，唯一的“带参数构造函数”的存在意味着应该使用该构造函数进行绑定。 这意味着绑定器会找到一个带有你希望绑定的参数的构造函数。 如果你的类有多个构造函数，可以使用 @ConstructorBinding 注解来指定使用哪个构造函数进行构造函数绑定。 如果要为一个只有一个“带参数构造函数”的类选择不绑定构造函数，该构造函数必须用 @Autowired 来注解。 构造函数绑定可以与 Record 一起使用。 除非你的记录有多个构造函数，否则没有必要使用 @ConstructorBinding。
构造函数绑定类的嵌套成员（如上面例子中的 Security）也将通过其构造函数被绑定。
默认值可以在构造函数参数和Record组件上使用 @DefaultValue 来指定。 转换服务将被应用于将注解的 String 值强制转换为缺失属性的目标类型。
参考前面的例子，如果没有属性绑定到 Security ， MyProperties 实例将包含一个 security 类型的 null 值。 为了使它包含一个非 null 的 Security 实例，即使没有属性与之绑定（当使用Kotlin时，这将要求 Security 的 username 和 password 参数被声明为 nullable，因为它们没有默认值），使用一个空的 @DefaultValue 注解。
Java
Kotlin
public MyProperties(boolean enabled, InetAddress remoteAddress, @DefaultValue Security security) {
this.enabled = enabled;
this.remoteAddress = remoteAddress;
this.security = security;
}
| 要使用构造函数绑定，该类必须使用 @EnableConfigurationProperties 或配置属性扫描来启用。 你不能对通过常规Spring机制创建的Bean使用构造函数绑定（例如 @Component Bean，通过使用 @Bean 方法创建的Bean或通过使用 @Import 加载的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 类上，如下面的例子所示。
Java
@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(SomeProperties.class)
public class MyConfiguration {
}
Java
@ConfigurationProperties("some.properties")
public class SomeProperties {
}
要使用配置属性扫描，请向你的application添加 @ConfigurationPropertiesScan 注解。 通常，它被添加到用 @SpringBootApplication 注解的main类中，但它也可以被添加到任何 @Configuration 类上。 默认情况下，扫描会从注解所在的包开始，你如果想自定义扫描其他包，可以参考如下。
Java
@SpringBootApplication
@ConfigurationPropertiesScan({ "com.example.app", "com.example.another" })
public class MyApplication {
}
| 当 @ConfigurationProperties Bean使用配置属性扫描或通过 @EnableConfigurationProperties 注册时，该Bean有一个常规名称： 假设它在 com.example.app 包中，上面的 SomeProperties 例子的 bean 名称是 some.properties-com.example.app.SomeProperties。 |
我们建议 @ConfigurationProperties 只处理 environment，特别是不从上下文注入其他Bean。 对于边角案例（特殊情况），可以使用 setter 注入或框架提供的任何 *Aware 接口（如 EnvironmentAware ，如果你需要访问 Environment）。 如果你仍然想使用构造器注入其他Bean，配置属性Bean必须用 @Component 来注解，并使用基于JavaBean的属性绑定。
四、 使用 @ConfigurationProperties 类
这种配置方式与 SpringApplication 外部YAML配置配合得特别好，如以下例子所示。
my:
service:
remote-address: 192.168.1.1
security:
username: "admin"
roles:
- "USER"
- "ADMIN"要使用 @ConfigurationProperties Bean，你可以用与其他Bean相同的方式注入它们，如下例所示。
Java
@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 方法上使用它。 当你想把属性绑定到你控制之外的第三方组件时，这样做特别有用。
要从 Environment 属性中配置一个Bean，请在其Bean注册中添加 @ConfigurationProperties ，如下例所示。
Java
@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 类。
Java
@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;
}
}
对以上的代码来说，以下的属性名称都可以使用。
| Table 3. relaxed binding |
|
| Property |
Note |
| my.main-project.person.first-name |
Kebab 风格（短横线隔开），建议在 .properties 和 YAML 文件中使用。 |
| my.main-project.person.firstName |
标准的驼峰语法。 |
| my.main-project.person.first_name |
下划线，这是一种用于 .properties 和 YAML 文件的替代格式。 |
| MY_MAINPROJECT_PERSON_FIRSTNAME |
大写格式，在使用系统环境变量时建议使用大写格式。 |
| 注解的 prefix 值 必须 是kebab风格（小写并以 - 分隔，如 my.main-project.person ）。 |
| Table 4. 每种属性源的宽松绑定规则 |
||
| 属性源 |
简单的 |
列表 |
| Properties 文件 |
驼峰, kebab , 下划线 |
使用 [ ] 或逗号分隔值的标准列表语法 |
| YAML 文件 |
驼峰, kebab , 下划线 |
标准YAML列表语法或逗号分隔的值 |
| 环境变量 |
大写，下划线为分隔符(见 从环境变量绑定). |
Numeric values surrounded by underscores (see 从环境变量绑定) |
| 系统属性（System properties） |
驼峰, kebab , 下划线 |
使用 [ ] 或逗号分隔值的标准列表语法 |
我们建议，在可能的情况下，属性应以小写的kebab格式存储，例如 my.person.first-name=Rod 。
绑定Map
当绑定到 Map 属性时，你可能需要使用一个特殊的括号符号，以便保留原始的 key 值。 如果key没有被 [ ] 包裹，任何非字母数字、- 或 . 的字符将被删除。
例如，考虑将以下属性绑定到一个 Map
Properties
Yaml
my.map.[/key1]=value1
my.map.[/key2]=value2
my.map./key3=value3| 对于YAML文件，括号需要用引号包裹，以使key被正确解析。 |
上面的属性将绑定到一个 Map ，/key1，/key2 和 key3 作为map的key。 斜线已经从 key3 中删除，因为它没有被方括号包裹。
当绑定到标量值时，带有 . 的键不需要用 [] 包裹。 标量值包括枚举和所有 java.lang 包中的类型，除了 Object 。 将 a.b=c 绑定到 Map
从环境变量绑定
例如，Linux shell变量只能包含字母（a 到 z 或 A 到 Z ）、数字（ 0 到 9 ）或下划线字符（ _ ）。 按照惯例，Unix shell变量的名称也将采用大写字母。
Spring Boot宽松的绑定规则被设计为尽可能地与这些命名限制兼容。
要将规范形式的属性名称转换为环境变量名称，你可以遵循这些规则。
- 用下划线（_）替换点（.）。
- 删除任何破折号（-）。
- 转换为大写字母。
例如，配置属性 spring.main.log-startup-info 将是一个名为 SPRING_MAIN_LOGSTARTUPINFO 的环境变量。
环境变量也可以在绑定到对象列表（List）时使用。 要绑定到一个 List，在变量名称中，元素编号（索引）应该用下划线包裹。
例如，配置属性 my.service[0].other 将使用一个名为 MY_SERVICE_0_OTHER 的环境变量。
七、 合并复杂的类型
当List被配置在多个地方时，覆盖的作用是替换整个list。
例如，假设一个 MyPojo 对象的 name 和 description 属性默认为 null。 下面的例子从 MyProperties 中暴露了一个 MyPojo 对象的列表。
Java
@ConfigurationProperties("my")
public class MyProperties {
private final List list = new ArrayList<>();
public List getList() {
return this.list;
}
}
考虑以下配置。
Properties
Yaml
my.list[0].name=my name
my.list[0].description=my description
#---
spring.config.activate.on-profile=dev
my.list[0].name=my another name
如果 dev 配置文件未被激活，MyProperties.list 包含一个 MyPojo 条目，如之前定义的那样。 然而，如果 dev 配置文件被激活，list 仍然只包含一个条目（name 为 my another name，description为 null）。 这种配置不会在列表中添加第二个 MyPojo 实例，也不会合并项目。
当一个 List 在多个配置文件中被指定时，将使用具有最高优先级的那个（并且只有那个）。 考虑下面的例子。
Properties
Yaml
my.list[0].name=my name
my.list[0].description=my description
my.list[1].name=another name
my.list[1].description=another description
#---
spring.config.activate.on-profile=dev
my.list[0].name=my another name
在前面的例子中，如果 dev 配置文件是激活的，MyProperties.list 包含 一个 MyPojo 条目（name 是 my another name，description是 null）。 对于YAML，逗号分隔的列表和YAML列表都可以用来完全覆盖列表的内容。
对于 Map 属性，你可以用从多个来源获取的属性值进行绑定。 然而，对于多个来源中的同一属性，使用具有最高优先级的那个。 下面的例子从 MyProperties 暴露了一个 Map
Java
Kotlin
@ConfigurationProperties("my")
public class MyProperties {
private final Map map = new LinkedHashMap<>();
public Map getMap() {
return this.map;
}
}
考虑以下配置。
Properties
Yaml
my.map.key1.name=my name 1
my.map.key1.description=my description 1
#---
spring.config.activate.on-profile=dev
my.map.key1.name=dev name 1
my.map.key2.name=dev name 2
my.map.key2.description=dev description 2
如果 dev 配置文件没有激活，MyProperties.map 包含一个key为 key1 的条目（name为 my name 1 ，description为 my description 1 ）。 然而，如果 dev 配置文件被激活，map 包含两个条目，key为 key1 （name为 dev name 1，description为 my description 1 ）和 key2（name为 dev name 2，description为 dev description 2）。
前面的合并规则适用于所有属性源的属性，而不仅仅是文件。
八、属性（Properties）转换
当Spring Boot与 @ConfigurationProperties Bean绑定时，它试图将外部application properties强制改为正确的类型。 如果你需要自定义类型转换，你可以提供一个 ConversionService bean（Bean的名称为 conversionService ）或自定义属性编辑器（通过 CustomEditorConfigurer bean）或自定义 Converters Bean（使用 @ConfigurationPropertiesBinding 注解）。
| 由于这个Bean是在应用程序生命周期的早期被请求的，请确保限制你的 ConversionService 所使用的依赖关系。 通常情况下，你所需要的任何依赖关系在创建时可能没有完全初始化。 如果你的自定义 ConversionService 不需要配置keys coercion，你可能想重命名它，并且只依赖用 @ConfigurationPropertiesBinding 限定的自定义转换器。 |
转换为 Duration
Spring Boot对表达持续时间有专门的支持。 如果你公开了一个 java.time.Duration 属性，application properties中的以下格式就可用。
- 普通的 long （使用毫秒作为默认单位，除非指定了 @DurationUnit ）。
- 标准的ISO-8601格式 由 java.time.Duration 使用。
- 一个更易读的格式，其中值和单位是耦合的（10s 表示10秒）。
请考虑以下例子。
Java
@ConfigurationProperties("my")
public class MyProperties {
@DurationUnit(ChronoUnit.SECONDS)
private Duration sessionTimeout = Duration.ofSeconds(30);
private Duration readTimeout = Duration.ofMillis(1000);
// getters / setters...
}
要指定一个30秒的会话超时， 30 、 PT30S 和 30s 都是等价的。 读取超时为500ms，可以用以下任何一种形式指定。 500, PT0.5S 和 500ms.
你也可以使用如下支持的时间单位。
- ns 纳秒
- us 微秒
- ms 毫秒
- s 秒
- m 分
- h 小时
- d 天
默认单位是毫秒，可以使用 @DurationUnit 来重写，如上面的例子所示。
如果你喜欢使用构造函数绑定，同样的属性可以被暴露出来，如下面的例子所示。
Java
@ConfigurationProperties("my")
public class MyProperties {
// fields...
public MyProperties(@DurationUnit(ChronoUnit.SECONDS) @DefaultValue("30s") Duration sessionTimeout,
@DefaultValue("1000ms") Duration readTimeout) {
this.sessionTimeout = sessionTimeout;
this.readTimeout = readTimeout;
}
// getters...
}
如果你要升级一个 Long 的属性，如果它不是毫秒，请确保定义单位（使用 @DurationUnit ）。 这样做提供了一个透明的升级路径，同时支持更丰富的格式
转换为期间（Period）
除了duration，Spring Boot还可以使用 java.time.Period 类型。 以下格式可以在application properties中使用。
- 一个常规的 int 表示法（使用天作为默认单位，除非指定了 @PeriodUnit ）。
- 标准的ISO-8601格式 由 java.time.Period 使用。
- 一个更简单的格式，其中值和单位对是耦合的（ 1y3d 表示1年3天）。
支持下列简单的单位格式。
- y 年
- m 月
- w 周
- d 日
java.time.Period 类型实际上从未存储过周数，它是一个快捷方式，意味着 “7天”。
转换为数据大小（Data Sizes）
Spring Framework有一个 DataSize 值类型，以字节为单位表达大小。 如果你公开了一个 DataSize 属性，application properties中的以下格式就可用。
- 一个常规的 long 表示（使用字节作为默认单位，除非指定了 @DataSizeUnit）。
- 一个更易读的格式，其中值和单位是耦合的（10MB 意味着10兆字节）。
考虑以下例子。
Java
Kotlin
@ConfigurationProperties("my")
public class MyProperties {
@DataSizeUnit(DataUnit.MEGABYTES)
private DataSize bufferSize = DataSize.ofMegabytes(2);
private DataSize sizeThreshold = DataSize.ofBytes(512);
// getters/setters...
}
要指定一个10兆字节（Mb）的缓冲区大小， 10 和 10MB 是等价的。 256字节的大小阈值可以指定为 256 或 256B。
你也可以使用如下这些支持的单位。
- B 字节
- KB KB
- MB MB
- GB GB
- TB TB
默认单位是字节，可以使用 @DataSizeUnit 来重写，如上面的例子所示。
如果你喜欢使用构造函数绑定，同样的属性可以被暴露出来，如下面的例子所示。
Java
@ConfigurationProperties("my")
public class MyProperties {
// fields...
public MyProperties(@DataSizeUnit(DataUnit.MEGABYTES) @DefaultValue("2MB") DataSize bufferSize,
@DefaultValue("512B") DataSize sizeThreshold) {
this.bufferSize = bufferSize;
this.sizeThreshold = sizeThreshold;
}
// getters...
}
如果你正在升级一个 Long 属性，确保定义单位（使用 @DataSizeUnit），如果它不是字节。 这样做提供了一个透明的升级路径，同时支持更丰富的格式。
九、@ConfigurationProperties 校验
只要使用Spring的 @Validated 注解，Spring Boot就会尝试验证 @ConfigurationProperties 类。 你可以直接在你的配置类上使用JSR-303的 jakarta.validation 约束注解。 要做到这一点，请确保你的classpath上有一个兼容的JSR-303实现，然后将约束注解添加到你的字段中，如下面的例子所示。
Java
@ConfigurationProperties("my.service")
@Validated
public class MyProperties {
@NotNull
private InetAddress remoteAddress;
// getters/setters...
}
你也可以通过在 configuration properties 的 @Bean 方法上注解 @Validated 来触发验证。
为了确保总是为嵌套的属性触发验证，即使没有找到属性，相关的字段必须用 @Valid 来注释。 下面的例子建立在前面的 MyProperties 的基础上。
Java
@ConfigurationProperties("my.service")
@Validated
public class MyProperties {
@NotNull
private InetAddress remoteAddress;
@Valid
private final Security security = new Security();
// getters/setters...
public static class Security {
@NotEmpty
private String username;
// getters/setters...
}
}
你也可以通过创建一个名为 configurationPropertiesValidator 的bean定义来添加一个自定义的Spring Validator。 @Bean 方法应该被声明为 static。 配置属性验证器是在应用程序生命周期的早期创建的，将 @Bean 方法声明为静态，可以让Bean的创建不需要实例化 @Configuration 类。 这样做可以避免过早实例化可能引起的任何问题。
spring-boot-actuator 模块包括一个暴露所有 @ConfigurationProperties Bean 的端点。 你可以通过浏览器访问 /actuator/configprops 或使用相应的JMX端点。 详情见"生产就绪"部分。
十、@ConfigurationProperties vs. @Value
@Value 注解是一个核心的容器功能，它不提供与类型安全的配置属性相同的功能。 下表总结了 @ConfigurationProperties 和 @Value 所支持的功能。
| 功能 |
@ConfigurationProperties |
@Value |
| 宽松绑定 |
Yes |
有限制 (见 下文注释) |
| 支持 Meta-data |
Yes |
No |
| SpEL 表达式 |
No |
Yes |
如果你确实想使用 @Value，我们建议你使用属性名称的规范形式（仅使用小写字母的kebab-case）来引用属性名称。 这将允许Spring Boot使用与 宽松绑定 @ConfigurationProperties 时相同的逻辑。
例如，@Value("${demo.item-price}") 将从 application.properties 文件中获取 demo.item-price 和 demo.itemPrice 形式，以及从系统环境中获取 DEMO_ITEMPRICE。 如果你用 @Value("${demo.itemPrice}") 代替，demo.item-price 和 DEMO_ITEMPRICE 将不会被考虑。
如果你为你自己的组件定义了一组配置键，我们建议你将它们分组在一个用 @ConfigurationProperties 注解的POJO中。 这样做将为你提供结构化的、类型安全的对象，你可以将其注入到你自己的bean中。
来自应用application property 文件的 SpEL 表达式在解析这些文件和填充environment时不会被处理。 然而，可以在 @Value 中写一个 SpEL 表达式。 如果来自应用程序属性文件的属性值是一个 SpEL 表达式，它将在被 @Value 消费时被解析。