Spring Boot 中的 @ConfigurationProperties 注解

2023-12-25

1、简介

Spring Boot 有许多有用的功能，包括外部化配置和轻松访问 Properties 文件中定义的属性。上一篇文章介绍了实现这一点的各种方法。

本文将带你了解 Spring Boot 中的 @ConfigurationProperties 注解。

2、项目设置

按照惯例，在 pom.xml 中将 spring-boot-starter-parent 添加为 <parent>：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.0.0</version>
    <relativePath/>
</parent>

为了验证文件中定义的属性，还需要一个 JSR-380 实现，hibernate-validator 就是其中之一，它由 spring-boot-starter-validation 依赖提供。

把它也添加到 pom.xml 中：

<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

更多详细信息可参阅 Hibernate Validator 入门。

3、示例属性

官方文档建议将配置属性隔离到单独的 POJO 中。

如下：

@Configuration
@ConfigurationProperties(prefix = "mail")
public class ConfigProperties {
    
    private String hostName;
    private int port;
    private String from;

    //Get、Set 方法
}

通过 @Configuration 注解，Spring 会在 Application Context 中创建一个 Spring Bean。

@ConfigurationProperties 最适合具有相同前缀的分层属性，这里添加了一个名为 mail 的前缀。

Spring 框架使用标准的 Java Bean Setter，因此必须为每个属性声明 Setter 方法。

注：如果不在 POJO 中使用 @Configuration，则需要在 Spring Application main 类中添加 @EnableConfigurationProperties(ConfigProperties.class) 以将属性绑定到 POJO 中：

@SpringBootApplication
@EnableConfigurationProperties(ConfigProperties.class)
public class EnableConfigurationDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(EnableConfigurationDemoApplication.class, args);
    }
}

如上！Spring 会自动绑定属性文件中定义的、前缀为 mail 且名称与 ConfigProperties 类中某个字段相同的任何属性。

Spring 对绑定属性使用了一些宽松的规则。因此，以下各种变体都可以绑定到属性 hostName：

mail.hostName
mail.hostname
mail.host_name
mail.host-name
mail.HOST_NAME

可以使用下面的 properties 文件来设置所有字段：

# 示例 properties
mail.hostname=host@mail.com
mail.port=9000
mail.from=mailer@mail.com

3.1、Spring Boot 2.2

从 Spring Boot 2.2 开始，Spring 通过 classpath 扫描查找并注册 @ConfigurationProperties 类。对 @ConfigurationProperties 的扫描需要通过添加 @ConfigurationPropertiesScan 注解来明确选择。因此，不必用 @Component（以及 @Configuration 等其他元注解）注解此类类，甚至也不必使用 @EnableConfigurationProperties：

@ConfigurationProperties(prefix = "mail") 
@ConfigurationPropertiesScan 
public class ConfigProperties { 

    private String hostName; 
    private int port; 
    private String from; 

    // 标准的 Get、Set 
}

@SpringBootApplication 启用的 classpath Scanner 找到了 ConfigProperties 类，尽管我们没有用 @Component 对该类进行注解。

此外，还可以使用 @ConfigurationPropertiesScan 注解来扫描自定义位置的配置属性类：

@SpringBootApplication
@ConfigurationPropertiesScan("com.baeldung.configurationproperties")
public class EnableConfigurationDemoApplication { 

    public static void main(String[] args) {   
        SpringApplication.run(EnableConfigurationDemoApplication.class, args); 
    } 
}

如上，Spring 将只在 com.baeldung.properties 包中查找配置属性类。

4、嵌套属性

可以在 List、Map 和 Class 中嵌套属性。

创建一个新的 Credentials 类，用于一些嵌套属性：

public class Credentials {
    private String authMethod;
    private String username;
    private String password;

    //Get、Set 方法
}

还需要更新 ConfigProperties 类，以便使用 List、Map 和 Credentials 类：

public class ConfigProperties {

    private String hostname;
    private int port;
    private String from;
    private List<String> defaultRecipients;
    private Map<String, String> additionalHeaders;
    private Credentials credentials;
 
    // Get、Set 省略
}

下面的属性文件将设置所有字段：

#Simple properties
mail.hostname=mailer@mail.com
mail.port=9000
mail.from=mailer@mail.com

#List properties
mail.defaultRecipients[0]=admin@mail.com
mail.defaultRecipients[1]=owner@mail.com

#Map Properties
mail.additionalHeaders.redelivery=true
mail.additionalHeaders.secure=true

#对象 properties
mail.credentials.username=john
mail.credentials.password=password
mail.credentials.authMethod=SHA1

5、在 @Bean 方法上使用 @ConfigurationProperties

还可以在 @Bean 标注的方法上使用 @ConfigurationProperties 注解。

当要将属性绑定到无法控制的第三方组件时，这种方法可能特别有用。

创建一个简单的 Item 类，在下一个示例中使用：

public class Item {
    private String name;
    private int size;

    // Get、Set 方法省略
}

现在来看看如何在 @Bean 方法中使用 @ConfigurationProperties 将外部化属性绑定到 Item 实例：

@Configuration
public class ConfigProperties {

    @Bean
    @ConfigurationProperties(prefix = "item")
    public Item item() {
        return new Item();
    }
}

如上，任何 item 前缀的属性都将映射到 Spring Context 管理的 Item 实例。

6、属性校验

@ConfigurationProperties 使用 JSR-380 格式对属性进行验证。

例如，把 hostName 属性成为强制性属性：

@NotBlank
private String hostName;

接下来，把 authMethod 属性的长度设为 1 到 4 个字符：

@Length(max = 4, min = 1)
private String authMethod;

然后，port 属性是 1025 到 65536：

@Min(1025)
@Max(65536)
private int port;

最后，from 属性必须与电子邮件地址格式相匹配：

@Pattern(regexp = "^[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,6}$")
private String from;

这可以帮助减少代码中大量的 if - else 判断条件，使代码看起来更简洁明了。

如果其中任何一项验证失败，应用将无法启动，并抛出 IllegalStateException 异常。

Hibernate Validation 框架使用标准的 Java Bean Getter 和 Setter，因此必须为每个属性声明 Getter 和 Setter 方法。

7、属性类型转换

@ConfigurationProperties 支持多种类型的转换，可将属性绑定到相应的 Bean。

7.1、Duration

先来看看如何将属性转换为 Duration 对象。

这里有两个 Duration 类型的字段：

@ConfigurationProperties(prefix = "conversion")
public class PropertyConversion {

    private Duration timeInDefaultUnit;
    private Duration timeInNano;
    ...
}

配置属性如下：

conversion.timeInDefaultUnit=10
conversion.timeInNano=9ns

如上，字段 timeInDefaultUnit 的值为 10 毫秒，而 timeInNano 的值为 9 纳秒。

支持的单位有 ns、us、ms、s、m、h 和 d，分别表示纳秒、微秒、毫秒、秒、分、小时和天。

默认单位是毫秒，这意味着如果不在数值旁边指定单位，Spring 就会将数值转换为毫秒。

还可以使用 @DurationUnit 来覆盖默认单位：

@DurationUnit(ChronoUnit.DAYS)
private Duration timeInDays;

对应的属性如下：

conversion.timeInDays=2

7.2、DataSize

同样，Spring Boot @ConfigurationProperties 也支持 DataSize 类型转换。

添加三个 DataSize 类型的字段：

private DataSize sizeInDefaultUnit;

private DataSize sizeInGB;

@DataSizeUnit(DataUnit.TERABYTES)
private DataSize sizeInTB;

相应的属性如下：

conversion.sizeInDefaultUnit=300
conversion.sizeInGB=2GB
conversion.sizeInTB=4

如上，sizeInDefaultUnit 的值是 300 字节，因为默认单位是字节。

支持的单位有 B、KB、MB、GB 和 TB。还可以使用 @DataSizeUnit 覆盖默认单位。

7.3、自定义 Converter

还可以添加自己的自定义 Converter，以支持将属性转换为特定的类类型。

添加一个简单的 Employee 类：

public class Employee {
    private String name;
    private double salary;
}

然后，创建一个自定义 Converter 来转换该属性：

conversion.employee=john,2000

把它转换为 Employee 类型：

private Employee employee;

需要实现 Converter 接口，然后使用 @ConfigurationPropertiesBinding 注解注册自定义 Converter：

@Component
@ConfigurationPropertiesBinding
public class EmployeeConverter implements Converter<String, Employee> {

    @Override
    public Employee convert(String from) {
        String[] data = from.split(",");
        return new Employee(data[0], Double.parseDouble(data[1]));
    }
}

8、不可变的 @ConfigurationProperties 绑定

从 Spring Boot 2.2 开始，可以使用 @ConstructorBinding 注解来绑定配置属性，而不是老式的 Setter 注入。

这基本上意味着 @ConfigurationProperties 注解的类现在可以是不可变的了。

在 Spring Boot 3 中，如果只有一个带参构造函数，那么构造函数绑定就是隐式的，不需要使用注解。但如果有多个构造函数，必须注解首选的那个：

@ConfigurationProperties(prefix = "mail.credentials")
public class ImmutableCredentials {

    private final String authMethod;
    private final String username;
    private final String password;

    @ConstructorBinding
    public ImmutableCredentials(String authMethod, String username, String password) {
        this.authMethod = authMethod;
        this.username = username;
        this.password = password;
    }

    public ImmutableCredentials(String username, String password) {
        this.username = username;
        this.password = password;
        this.authMethod = "Default";
    }
    public String getAuthMethod() {
        return authMethod;
    }

    public String getUsername() {
        return username;
    }

    public String getPassword() {
        return password;
    }
}

如上，在使用 @ConstructorBinding 时，需要为构造函数提供想要绑定的所有参数。

注意，ImmutableCredentials 的所有字段都是 final 字段。此外，ImmutableCredentials 没有 Setter 方法。

此外，需要强调的是，要使用构造函数绑定，需要通过 @EnableConfigurationProperties 或 @ConfigurationPropertiesScan 明确启用配置类。

9、Java 16 Record

Java 16 引入了 Record 类型（JEP 395）。Record 类是不可变数据的透明载体。这使它们成为配置持有者和 DTO 的理想选择。事实上，可以在 Spring Boot 中将 Java Record 定义为配置属性。例如，前面的示例可以重写为：

@ConstructorBinding
@ConfigurationProperties(prefix = "mail.credentials")
public record ImmutableCredentials(String authMethod, String username, String password) {
}

显然，它比那些模板式的 Getter 和 Setter 更简洁。

此外，从 Spring Boot 2.6 开始，对于单构造函数 Record，可以不用 @ConstructorBinding 注解。但是，如果 Record 有多个构造函数，则仍应使用 @ConstructorBinding 来标识用于属性绑定的构造函数。

10、总结

本文介绍了如何在 Spring Boot 中使用 @ConfigurationProperties 来绑定配置属性，以及如何进行属性验证和属性转换。

Ref：https://www.baeldung.com/configuration-properties-in-spring-boot