在之前的介绍中，我们详细介绍了Spring Boot的配置文件以及Spring Boot的配置文件加载顺序，那么接下来我们来重点介绍一下Spring Boot中比较常用也是比较好用的注解@ConfigurationProperties，这个注解是Spring Boot中提供的一个强大的自定义配置文件映射Java对象的配置注解。这种方式相比于@Value注解的方式来讲可以映射多层次的配置内容，尤其是在读取一些对象、列表、复杂对象结构的时候，这种方式就非常有效了。下面我们就详细介绍一下如何通过@ConfigurationProperties注解来读取复杂配置文件。

在配置文件中定义复杂配置项

在Spring Boot中支持了 application.properties 和 application.yml 两种格式的配置文件，而这里我们使用 application.yml的方式来进行演示，如下所示。

app:
  name: MyApplication
  version: 1.0.0
  timeout: 5000
  datasource:
    url: jdbc:mysql://localhost:3306/mydb
    username: root
    password: secret
  servers:
    - 192.168.1.10
    - 192.168.1.11
  features:
    enable-logging: true
    enable-cache: false

创建Java映射类

创建好配置项之后，接下来我们就可以根据配置项来设计一个Java的映射配置类，如下所示，并且这个类是由@ConfigurationProperties注解标注，用来表示这个就是一个配置类。

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import java.util.List;
import java.util.Map;

@Component
@ConfigurationProperties(prefix = "app") // 绑定 "app" 前缀的配置
public class AppConfig {
    
    private String name;
    private String version;
    private int timeout;
    
    private DataSourceConfig datasource;
    private List<String> servers;
    private Map<String, Boolean> features;

    // Getters and Setters

    public static class DataSourceConfig {
        private String url;
        private String username;
        private String password;
        
        // Getters and Setters
    }
}

通过@ConfigurationProperties(prefix = "app")注解来指定配置绑定的前缀信息，然后在配置文件加载的时候，就会默认匹配app开头的配置。然后在配置类中分别指定了DataSourceConfig、servers、features则会映射不同的配置项。

启用@ConfigurationProperties扫描

在Spring Boot2.2+版本之后，推荐通过@Configuration 类上添加 @EnableConfigurationProperties，或者使用 @Component 直接扫描的方式来启动@ConfigurationProperties配置的扫描如下所示。

使用 @Component（推荐）

例如在上面的配置中我们可以在AppConfig类上直接通过 @Component来进行注册扫描，这样在配置扫描完成之后，就会直接将配置类注册是一个Bean对象提供给容器中进行使用，就不需要再额外进行其他的Bean容器配置。

@Component
@ConfigurationProperties(prefix = "app")
public class AppConfig { ... }

使用 @EnableConfigurationProperties

当然除了上面的方式之外，我们还可以通过@EnableConfigurationProperties注解进行配置，可以在Spring的主类或者是@Configuration配置类中通过@EnableConfigurationProperties注解来手动进行开启配置。

import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableConfigurationProperties(AppConfig.class) // 手动启用
public class AppConfigLoader { }

在其他 Bean 或 Service 中使用

在Spring Boot中会自动将@ConfigurationProperties 绑定的对象注册到Spring容器，因此可以直接在其他Bean或Service中注入，然后进行使用。

import org.springframework.stereotype.Service;

@Service
public class AppService {

    private final AppConfig appConfig;

    public AppService(AppConfig appConfig) {
        this.appConfig = appConfig;
    }

    public void printConfig() {
        System.out.println("App Name: " + appConfig.getName());
        System.out.println("Version: " + appConfig.getVersion());
        System.out.println("Timeout: " + appConfig.getTimeout());
        System.out.println("Database URL: " + appConfig.getDatasource().getUrl());
        System.out.println("Servers: " + appConfig.getServers());
        System.out.println("Features: " + appConfig.getFeatures());
    }
}

校验配置参数

在Spring Boot中还提供了基于javax.validation的参数校验配置，如下所示。

import javax.validation.constraints.Min;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;
import org.springframework.validation.annotation.Validated;

@Component
@ConfigurationProperties(prefix = "app")
@Validated  // 启用校验
public class AppConfig {

    @NotBlank
    private String name;

    @NotBlank
    private String version;

    @Min(1000)
    private int timeout;

    // Getters and Setters
}

在这个配置中，如果timeout小于1000或name为空，在启动的时候就会提示报错信息。

结合record（Java 14+ 简化写法）

如果使用的是JDK14+的版本，那么就可以通过record 来简化代码配置，如下所示。

@ConfigurationProperties(prefix = "app")
public record AppConfig(
    String name,
    String version,
    int timeout,
    DataSourceConfig datasource,
    List<String> servers,
    Map<String, Boolean> features
) {}

public record DataSourceConfig(String url, String username, String password) {}

这种情况下，就不需要再手动编写getters/setters方法了。

使用 Spring Boot 3 的@ConstructorBinding

在Spring Boot 3之后，推荐通过构造函数来进行数据的绑定操作，如下所示。

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.bind.ConstructorBinding;

@ConfigurationProperties(prefix = "app")
@ConstructorBinding
public record AppConfig(
    String name,
    String version,
    int timeout,
    DataSourceConfig datasource,
    List<String> servers,
    Map<String, Boolean> features
) {}

这种方式，保证了配置的值只能在对象创建的时候被赋值，并且对象创建之后就不能被修改了，这就符合了不可变对象的设计理念。

总结

@ConfigurationProperties 适用于复杂结构的配置绑定，支持 对象、列表、Map 等类型。相比 @Value，@ConfigurationProperties 更适合批量绑定配置，并且易于管理。结合 @Validated 可进行参数校验，增强安全性。