@ConfigurationProperties可自动绑定YAML/properties嵌套配置到Java对象树，需保证属性名与字段名按kebab-case→camelCase规则松散匹配、类型可转换，并通过@EnableConfigurationProperties或@Bean注册启用；支持静态嵌套类、JSR-303校验、默认值及List/Map/Duration等类型自动转换。
直接用 @ConfigurationProperties 就能将 YAML 或 properties 中的嵌套配置，自动绑定到 Java 对象树上，关键是要保证属性名和字段名严格匹配、类型可转换，并启用配置类扫描。
定义层级对应的 POJO 类
每个层级对应一个类，用标准 getter/setter（Lombok 的 @Data 也行），字段名必须与配置键小写+中划线风格（kebab-case）一一对应。例如：
// application.yml 中有：
app:
database:
url: jdbc:h2:mem:testdb
username: sa
password: ""
features:
enable-cache: true
timeout-seconds: 30
// 对应 Java 类：
立即学习“Java免费学习笔记（深入）”；
@ConfigurationProperties(prefix = "app")
@Data
public class AppProperties {
private Database database;
private Features features;
@Data
public static class Database {
private String url;
private String username;
private String password;
}
@Data
public static class Features {
private boolean enableCache; // 自动映射 enable-cache
private int timeoutSeconds; // 自动映射 timeout-seconds
}
}
启用并注册配置类
两种方式任选其一：
- 在主启动类或配置类上加
@EnableConfigurationProperties(AppProperties.class) - 把
AppProperties声明为@Bean，并加上@ConfigurationProperties("app")注解
推荐后者，更灵活：
@Configuration
public class AppConfig {
@Bean
@ConfigurationProperties("app")
public AppProperties appProperties() {
return new AppProperties();
}
}
校验和默认值支持
可以在字段上加 JSR-303 注解（如 @NotBlank、@Min），配合 @Validated 启用校验：
@ConfigurationProperties(prefix = "app")
@Validated
@Data
public class AppProperties {
private Database database;
@Data
public static class Database {
@NotBlank
private String url;
@Min(1)
private int port = 5432; // 提供默认值
}
}
启动时若配置缺失或不合法，会抛出 BindException，便于早期发现问题。
注意命名规范和类型转换
Spring Boot 默认按以下规则绑定：
- YAML 中的
enable-cache→ Java 字段enableCache（驼峰转连字符） - 支持 List/Map 嵌套：如
app.servers[0].host可映射为List<server></server> - 枚举、Duration、DataSize 等类型自动转换（如
10MB→DataSize.ofMegabytes(10)） - 避免使用基本类型（如
int）而不用包装类（Integer），否则缺省时会报错
不复杂但容易忽略。
