@ConfigurationProperties 是 Spring Boot 中批量绑定配置的推荐方式，可将 yml/properties 中前缀相同的配置自动映射为 Java Bean，支持校验、类型安全和嵌套结构。
在 Spring Boot 中，@ConfigurationProperties 是批量绑定配置最常用、最推荐的方式。它能把 application.yml 或 application.properties 中的一组前缀相同的配置，自动映射到一个 Java Bean 中，避免逐个用 @Value 注入，更安全、可校验、易维护。
1. 定义配置类并启用属性绑定
创建一个普通 Java 类（如 AppConfig），用 @ConfigurationProperties 指定配置前缀，并加上 @Component 或通过 @EnableConfigurationProperties 显式注册：
- 推荐方式：加
@Component+@ConfigurationProperties("app") - 必须搭配
@EnableConfigurationProperties（如果没用@Component）或启用配置类扫描 - 类中字段名需与配置项小写短横线（kebab-case）风格一一对应，如
max-connections→ 字段maxConnections
示例：
<font size="2">@Component<br>@ConfigurationProperties(prefix = "app")<br>public class AppConfig {<br> private String name;<br> private int port;<br> private List<String> servers = new ArrayList<>();<br> private Map<String, Integer> timeout = new HashMap<>();<br> // getter/setter 必须有（Lombok 的 @Data 也可）<br>}</font>2. 在配置文件中写对应结构
支持 yml 和 properties，yml 更直观。注意缩进和类型表达：
立即学习“Java免费学习笔记（深入）”；
- yml 中 list 用
-，map 用键值对，嵌套对象用缩进 - properties 中 list 用
[0],[1]索引；map 用.key后缀
yml 示例（application.yml）：
<font size="2">app:<br> name: demo-service<br> port: 8080<br> servers:<br> - 192.168.1.10<br> - 192.168.1.11<br> timeout:<br> db: 5000<br> redis: 2000</font>
3. 启用 JSR-303 校验（可选但强烈建议）
在配置类上加 @Validated，字段上加 @NotBlank、@Min 等注解，Spring Boot 启动时会校验配置合法性：
- 校验失败会直接抛出
BindException，应用启动失败，避免运行时出错 - 嵌套对象也支持校验，只需在对应字段加
@Valid
示例：
<font size="2">@Component<br>@ConfigurationProperties(prefix = "app")<br>@Validated<br>public class AppConfig {<br> @NotBlank<br> private String name;<br> @Min(1024)<br> @Max(65535)<br> private int port;<br> // ...<br>}</font>4. 注意事项和常见问题
实际使用中容易踩坑，需留意以下几点：
- 必须有无参构造器（Lombok
@Data默认提供） - 字段必须有 setter 方法（
@Data或手动写） - 配置类不能是
final类（否则 CGLIB 代理失败） - 不支持静态字段绑定
- 若用
@ConfigurationProperties在非@Configuration类上，需确保该类被 Spring 扫描到（如加@Component） - IDE 可能提示“Configuration properties not bound”，需添加
spring-boot-configuration-processor依赖以支持元数据提示（开发体验优化，非运行必需）
