Spring Boot如何合并新旧前缀的ConfigurationProperties配置类为单个Bean？

解决方案 #

方案1：最简实现（无需维护两套配置类） #

Spring的Binder完全支持绑定到已实例化的对象，你之前的认知有误，通过Bindable.ofInstance()即可实现对已有对象的属性绑定。你可以直接抛弃废弃的配置类，通过两次绑定实现新旧前缀的优先级兼容：

@Configuration
public class PropertyConfig {
    @Bean
    public NewPropertyClass appProperties(Environment environment) {
        Binder binder = Binder.get(environment);
        // 注意修正原代码中类名首字母小写的不规范问题，统一使用大驼峰命名NewPropertyClass
        NewPropertyClass properties = new NewPropertyClass();
        // 先绑定旧前缀配置作为兜底
        binder.bind("com.myapp.deprecated", Bindable.ofInstance(properties));
        // 再绑定新前缀配置，会自动覆盖旧前缀的同名属性值，保证新前缀优先级更高
        binder.bind("com.myapp.newprefix", Bindable.ofInstance(properties));
        
        // 可选：检测到旧前缀配置时打印迁移提醒日志
        if (binder.bind("com.myapp.deprecated", Map.class).isBound()) {
            log.warn("配置前缀 com.myapp.deprecated 已废弃，请尽快迁移到新前缀 com.myapp.newprefix");
        }
        return properties;
    }
}

这种方案的优势：

• 代码极简，无需额外的属性合并工具类
• 上下文只有单个NewPropertyClass类型的Bean，不会出现同类型多Bean冲突
• 绑定逻辑完全复用Spring原生的Binder能力，支持类型转换、宽松绑定等所有@ConfigurationProperties的特性

方案2：保留两套配置类的合并实现 #

如果你必须保留现有的父子配置类结构，可以通过非空属性拷贝实现合并，旧配置仅作为新配置空属性的兜底：

第一步：编写非空属性合并工具

import org.springframework.beans.BeanUtils;
import org.springframework.beans.BeanWrapper;
import org.springframework.beans.BeanWrapperImpl;
import java.util.HashSet;
import java.util.Set;

public class PropertyMergeUtil {
    private static String[] getNullPropertyNames(Object source) {
        BeanWrapper wrapper = new BeanWrapperImpl(source);
        Set<String> nullProps = new HashSet<>();
        for (var pd : wrapper.getPropertyDescriptors()) {
            if (wrapper.getPropertyValue(pd.getName()) == null) {
                nullProps.add(pd.getName());
            }
        }
        return nullProps.toArray(new String[0]);
    }

    /**
     * 合并源对象非空属性到目标对象，不覆盖目标对象已有非空属性
     */
    public static void merge(Object source, Object target) {
        if (source == null || target == null) return;
        BeanUtils.copyProperties(source, target, getNullPropertyNames(source));
    }
}

第二步：声明合并后的Bean

@Configuration
public class PropertyConfig {
    @Bean
    public NewPropertyClass appProperties(Environment environment) {
        Binder binder = Binder.get(environment);
        // 优先加载新前缀配置
        NewPropertyClass newProps = binder.bind("com.myapp.newprefix", NewPropertyClass.class)
                .orElseGet(NewPropertyClass::new);
        // 加载旧前缀配置
        DeprecatedPropertyClass deprecatedProps = binder.bind("com.myapp.deprecated", DeprecatedPropertyClass.class)
                .orElse(null);
        // 合并属性
        PropertyMergeUtil.merge(deprecatedProps, newProps);
        return newProps;
    }
}

额外优化建议 #

可以在BasePropertyClass的属性对应的getter方法上添加@DeprecatedConfigurationProperty注解，IDE会自动提示用户配置已废弃，引导迁移：

public class BasePropertyClass {
    private String sharedProperty1;
    private String sharedProperty2;

    @DeprecatedConfigurationProperty(replacement = "com.myapp.newprefix.shared-property1", reason = "旧前缀已废弃")
    public String getSharedProperty1() {
        return sharedProperty1;
    }
    // sharedProperty2同理添加注解即可
}

内容的提问来源于stack exchange，提问作者swhite