Spring Boot配置类的注解-原创手记-慕课网

Spring Boot 中，若某类只用 @ConfigurationProperties 注解，然后该类：

没有在扫描路径下
或没用 @Component 等注解

就会导致无法被扫描为 bean，须在配置类用 @EnableConfigurationProperties 注解去指定这个类，才能使 @ConfigurationProperties 生效，并作为一个 bean 添加进 Spring 容器。

@EnableConfigurationProperties 不能单独使用：

@EnableConfigurationProperties 和 @ConfigurationProperties组合使用
@EnableConfigurationProperties将@ConfigurationProperties所修饰的类添加到IoC容器

1 简介

Spring Boot外部化配置和轻松访问 Properties 文件中定义的属性。上文介绍了实现这一点的各种方法。

本文看Spring Boot 的 @ConfigurationProperties。

2 项目设置

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.3.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;
}

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

@ConfigurationProperties 适合具有相同前缀的分层属性。

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; 
}

@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

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

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

看咋在 @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 来绑定配置属性，以及如何进行属性验证和属性转换。

关注我，紧跟本系列专栏文章，咱们下篇再续！

作者简介：魔都架构师，多家大厂后端一线研发经验，在分布式系统设计、数据平台架构和AI应用开发等领域都有丰富实践经验。

各大技术社区头部专家博主。具有丰富的引领团队经验，深厚业务架构和解决方案的积累。

负责：

中央/分销预订系统性能优化

活动&券等营销中台建设

交易平台及数据中台等架构和开发设计

车联网核心平台-物联网连接平台、大数据平台架构设计及优化

LLM Agent应用开发

区块链应用开发

大数据开发挖掘经验

推荐系统项目

目前主攻市级软件项目设计、构建服务全社会的应用系统。

参考：

编程严选网