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

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

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


一、为什么需要进阶?

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

二、10 个高级用法速查表

功能关键代码场景
扁平前缀@ConfigurationProperties(prefix="app")统一命名空间
嵌套对象private Security security;复杂层级
List / Mapprivate 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-nameapp_nameappName 均可映射减少拼写焦虑
JSR-303 校验@Validated + @NotBlank启动即报错
元数据提示spring-boot-configuration-processorIDEA 自动补全
多环境覆盖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

六、一句话总结

@ConfigurationProperties = 类型安全 + 结构化 + 校验 + IDE 友好
配合 构造器绑定@ConfigurationPropertiesScan自定义转换器,让它成为你配置管理的终极武器!

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

半部论语

如果觉得有帮助,打赏鼓励一下

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值