配置绑定

十几个相关配置项用 @Value 逐个注入既啰嗦又难维护。@ConfigurationProperties 把一组配置绑定到一个类型安全的 Java 对象上，还支持校验与复用。

定义绑定类

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

@ConfigurationProperties(prefix = "app")
public class AppProperties {

    private String title = "未命名";
    private String baseUrl;
    private List<String> servers = new ArrayList<>();
    private Map<String, String> map = new HashMap<>();

    // getter / setter 省略（IDE 生成）
}

prefix = "app" 表示读取 app.* 下的所有配置项，字段名与配置 key 按宽松绑定对应：app.base-url 可以绑定到 baseUrl（kebab-case 写法最常用），环境变量等来源也遵循同一规则，完整对照表以官方文档为准。

推荐用不可变风格绑定：record 或「只有一个构造器 + final 字段」。Boot 3 起单个构造器会自动采用构造器绑定，无需额外注解（历史注解 @ConstructorBinding 已不再需要，以官方文档为准）。

启用绑定类

任选其一：

• 主类加 @ConfigurationPropertiesScan，自动注册所在包下的绑定类；
• @EnableConfigurationProperties(AppProperties.class) 显式注册；
• 给绑定类加 @Component（不推荐，耦合了扫描机制）。

与 04 章配置对接

04 章里的 app.title、app.servers、app.map 会自动填充到上面的对象：

@RestController
public class InfoController {

    private final AppProperties props;

    public InfoController(AppProperties props) {
        this.props = props;
    }

    @GetMapping("/app-info")
    public AppProperties info() {
        return props;   // 直接以 JSON 返回，方便检查绑定结果
    }
}

绑定校验

给类加 @Validated，字段上加 jakarta.validation 注解；嵌套对象属性要加 @Valid 才会递归校验：

@Validated
@ConfigurationProperties(prefix = "app")
public class AppProperties {

    @NotBlank
    private String title;

    @Size(max = 5)
    private List<String> servers = new ArrayList<>();
    // ...
}

校验失败会在启动阶段抛出异常、快速失败，避免带着错误配置上线。注意：类路径上需要存在 Bean Validation 实现（如 spring-boot-starter-validation，见 09 章）校验注解才会生效。

与 @Value 的取舍

场景	推荐方式
单个配置项、临时取值	@Value
一组相关配置、要类型与校验	@ConfigurationProperties
配置项可能来自多环境需要合并覆盖	@ConfigurationProperties（自动支持前缀下合并）

小结

绑定类把「魔法字符串配置」变成可读、可校验、可单测的普通对象，是配置管理的正解。后续 14–18 章的数据源、Redis 等连接配置，本质都是 Spring Boot 内部用同一机制绑定好的。