@ConfigurationProperties是Spring Boot推荐的批量绑定配置方式，通过指定前缀将application.yml/properties中结构化配置自动映射到Java Bean，支持松散绑定、类型安全、校验（@Validated）及IDE提示，显著提升可读性与可维护性。
在 Java Spring Boot 项目中，@ConfigurationProperties 是批量绑定配置属性最常用、最推荐的方式。它能把 application.yml 或 application.properties 中的一组结构化配置，自动映射到一个 Java Bean 中，避免逐个用 @Value 注入，提升可读性和可维护性。
1. 添加依赖并启用配置绑定
确保项目已引入 spring-boot-configuration-processor（非必须但强烈建议），用于生成配置元数据，支持 IDE 提示和校验：
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-configuration-processor</artifactId> <optional>true</optional> </dependency>
Spring Boot 2.2+ 默认开启配置绑定，无需额外启用；若使用较老版本，需在主类或配置类上加 @EnableConfigurationProperties(YourConfigClass.class)。
2. 定义配置类并绑定前缀
创建一个普通 Java 类，用 @ConfigurationProperties 指定配置前缀，并用 @Component 或 @Configuration 声明为 Spring Bean：
立即学习“Java免费学习笔记（深入）”；
@Component
@ConfigurationProperties(prefix = "app.db")
@Data // Lombok，也可手写 getter/setter
public class DatabaseProperties {
private String url;
private String username;
private String password;
private int maxPoolSize = 10;
private List<String> allowedHosts = new ArrayList<>();
}对应 application.yml 示例：
app:
db:
url: jdbc:mysql://localhost:3306/mydb
username: root
password: secret
max-pool-size: 20
allowed-hosts:
- 127.0.0.1
- 192.168.1.100注意：YAML 中的短横线（max-pool-size）会自动匹配 Java 的驼峰命名（maxPoolSize）。
3. 启用松散绑定与类型安全校验
@ConfigurationProperties 默认支持松散绑定（kebab-case、snake_case、camelCase 等均可识别）。如需校验，可结合 Bean Validation 注解：
- 在字段上添加
@NotBlank、@Min(1)、@Email等注解 - 类上加
@Validated（必须，否则校验不生效） - 启动时自动校验，失败则抛出
BindException，应用无法启动
例如：
@Component
@ConfigurationProperties(prefix = "app.mail")
@Validated
@Data
public class MailProperties {
@NotBlank
private String host;
@Min(1)
@Max(65535)
private int port = 587;
@Email
private String from;
}4. 在其他 Bean 中注入使用
像普通 Spring Bean 一样通过构造器或字段注入即可：
@Service
public class UserService {
private final DatabaseProperties dbProps;
<pre class="brush:php;toolbar:false;">public UserService(DatabaseProperties dbProps) {
this.dbProps = dbProps;
}
public void connect() {
System.out.println("Connecting to: " + dbProps.getUrl());
System.out.println("Max pool: " + dbProps.getMaxPoolSize());
}}
也可用 @Autowired 字段注入（不推荐，不利于单元测试）。
不复杂但容易忽略：确保配置类有无参构造器（Lombok @Data 自带）、字段可写（有 setter 或用 Lombok @Setter），且配置前缀在 YAML/properties 中拼写正确——这是绑定失败最常见的原因。
