进阶 | 玩转 @ConfigurationProperties 的 10 个高级技巧-CSDN博客

本文链接：https://blog.csdn.net/RodJohnsonDoctor/article/details/149484418

进阶 | 玩转 @ConfigurationProperties 的 10 个高级技巧

适用版本：Spring Boot 2.2+
读完本文，你能写出 类型安全、结构优雅、支持校验、可扩展 的配置绑定代码。

一、为什么需要进阶？

痛点	传统写法	进阶写法
大量 `@Value("${x.y.z}")`	重复、易错	零注解、结构映射
不支持嵌套 / 集合	手写解析	自动绑定
无法校验 / 文档化	运行时才发现问题	启动即校验 + IDE 提示

二、10 个高级用法速查表

功能	关键代码	场景
① 扁平前缀	`@ConfigurationProperties(prefix="app")`	统一命名空间
② 嵌套对象	`private Security security;`	复杂层级
③ List / Map	`private List<String> ips;`	多值配置
④ 第三方 Bean	`@Bean @ConfigurationProperties(prefix="datasource") public DataSource ds(){...}`	无法改源码的类
⑤ 不可变对象	`@ConstructorBinding` + `@ConfigurationProperties(prefix="mail.credentials")`	final 字段、线程安全
⑥ 自定义转换器	`@Component @ConfigurationPropertiesBinding Converter<String, Jwt>`	JSON/YAML → POJO
⑦ 宽松绑定	`app-name`、`app_name`、`appName` 均可映射	减少拼写焦虑
⑧ JSR-303 校验	`@Validated` + `@NotBlank`	启动即报错
⑨ 元数据提示	`spring-boot-configuration-processor`	IDEA 自动补全
⑩ 多环境覆盖	`application-prod.yml`	零代码切换

三、核心示例

1. 嵌套 + 集合 + 校验

# application.yml
app:
  name: "Demo"
  security:
    api-key: "abc123"
    whitelist:
      - 10.0.0.1
      - 10.0.0.2
  retry:
    max-attempts: 3

@ConfigurationProperties(prefix = "app")
@Validated
@Data
public class AppProps {
    @NotBlank
    private String name;

    @Valid
    private Security security;

    @Valid
    private Retry retry;

    @Data
    public static class Security {
        @NotBlank
        private String apiKey;
        private List<@Pattern(regexp = IP_REGEX) String> whitelist;
    }

    @Data
    public static class Retry {
        @Min(1)
        private int maxAttempts;
    }
}

启动时若缺少 app.name 立即失败，IDE 自动提示 whitelist 为数组。

2. 不可变配置（构造器绑定）

@ConstructorBinding
@ConfigurationProperties(prefix = "mail.credentials")
public class ImmutableCredentials {
    private final String username;
    private final String password;

    public ImmutableCredentials(String username, String password) {
        this.username = username;
        this.password = password;
    }
    // 只有 getter，线程安全
}

需配合 @EnableConfigurationProperties(ImmutableCredentials.class) 或 @ConfigurationPropertiesScan。

3. 第三方组件配置注入

@Bean
@ConfigurationProperties(prefix = "datasource.druid")
public DataSource dataSource() {
    return new DruidDataSource();  // 零 setter 侵入
}

application.yml 中：

datasource:
  druid:
    url: jdbc:mysql://localhost:3306/db
    username: root

Spring Boot 会自动调用 setter 完成属性绑定。

4. 自定义 JSON 字符串 → POJO

jwt: '{"token":"xx","exp":123}'

@Data
public class Jwt { String token; Long exp; }

@Component
@ConfigurationPropertiesBinding
public class JwtConverter implements Converter<String, Jwt> {
    public Jwt convert(String source) {
        return JSONObject.parseObject(source, Jwt.class);
    }
}

四、注册方式 3+1

方式	代码	说明
`@Component`	直接扫描	最简单
`@EnableConfigurationProperties`	显式声明	适合无注解的类
`@ConfigurationPropertiesScan`	指定包	Spring Boot 2.2+ 推荐
`@Bean` + `@ConfigurationProperties`	绑定第三方 Bean	见示例 3

五、常见坑 & 排查清单

现象	原因	解决
属性不注入	缺 setter 或构造器	Lombok `@Data` 或显式 setter
IDEA 无提示	未引入 `spring-boot-configuration-processor`	添加依赖
字段为空	YAML 缩进错误	使用在线 YAML 校验
绑定失败	类型不匹配	自定义 `Converter`