Spring Boot 3配置属性绑定Map时出现重复键问题求助

问题现象 #

使用Spring Boot 3.1.4/3.0.5开发多租户应用时，通过DataSourceProperties读取spring.datasource.xa.properties下的配置会出现以下异常情况：

• 仅从application.properties读取时，Map键会严格保留配置文件中的格式（如my-first-property），无任何问题。
• 当用环境变量（如SPRING_DATASOURCE_XA_PROPERTIES_MYFIRSTPROPERTY=newValue）覆盖部分属性后，Map中会生成重复键：一个是原配置的短横线格式，另一个是环境变量转换后的全小写无短横线格式，两者值均为环境变量指定的内容。

示例代码 #

@Configuration
public class MySimpleConfiguration {

    @Autowired
    DataSourceProperties dataSourceProperties;

    @Bean
    public String myDummyBean() {
        Map<String, String> xaProperties = dataSourceProperties.getXa().getProperties();

        System.out.println("XA PROPERTY:\n" + xaProperties);
        
        return "myDummyBean";
    }
}

配置文件（application.properties） #

spring.datasource.xa.properties.my-first-property=firstValue
spring.datasource.xa.properties.my-second-property=secondValue

运行日志输出 #

2023-11-09 12:02:47,320 [,] DEBUG o.s.b.f.s.DefaultListableBeanFactory Creating shared instance of singleton bean 'myDummyBean'
XA PROPERTY:
{myfirstproperty=newFirstValue, my-first-property=newFirstValue, my-second-property=secondValue}

这种重复键会导致IBM DB2驱动参数绑定失败，因为驱动无法识别全小写无短横线格式的键。

原因分析 #

这是Spring Boot宽松绑定（Relaxed Binding）的设计逻辑导致的：

• 对于Map类型的属性，Spring Boot不会自动合并语义相同的键（如my-first-property和myfirstproperty）。因为Map的键是字符串类型，框架无法默认判断哪些键属于“语义等价”范畴——只有JavaBean字段这类有明确绑定规则的场景，才会自动处理驼峰、短横线格式的转换。
• 环境变量会被统一转换为全小写无短横线的键格式存入Map，而原配置文件中的键会保留原有格式，最终导致两个键共存。

解决方案 #

1. 统一配置键格式 #

在application.properties中直接使用与环境变量转换后一致的全小写无短横线格式：

spring.datasource.xa.properties.myfirstproperty=firstValue
spring.datasource.xa.properties.mysecondproperty=secondValue

这样环境变量覆盖后只会保留一个键，从根源避免重复。

2. 手动合并重复键 #

在获取XA属性Map后，手动将语义相同的键合并，保留业务需要的格式（比如原短横线格式）：

@Bean
public String myDummyBean() {
    Map<String, String> xaProperties = dataSourceProperties.getXa().getProperties();
    Map<String, String> cleanedProperties = new HashMap<>();

    for (Map.Entry<String, String> entry : xaProperties.entrySet()) {
        // 将全小写无短横线的键转换为短横线格式，优先保留原短横线键
        String normalizedKey = entry.getKey().contains("-") ? entry.getKey() : convertToHyphenCase(entry.getKey());
        cleanedProperties.put(normalizedKey, entry.getValue());
    }

    // 使用清理后的Map替代原xaProperties
    System.out.println("CLEANED XA PROPERTY:\n" + cleanedProperties);
    return "myDummyBean";
}

// 辅助方法：将全小写无短横线的键转换为短横线格式（如myfirstproperty -> my-first-property）
private String convertToHyphenCase(String key) {
    StringBuilder sb = new StringBuilder();
    for (char c : key.toCharArray()) {
        if (Character.isUpperCase(c)) {
            sb.append('-').append(Character.toLowerCase(c));
        } else {
            sb.append(c);
        }
    }
    return sb.toString();
}

3. 自定义属性绑定 #

如果需要长期解决这类问题，可以自定义Converter或PropertyEditor，让Spring Boot在绑定Map属性时自动统一键的格式，避免重复键生成。

总结 #

该现象并非Spring Boot Bug，而是宽松绑定针对Map类型属性的设计特性。通过统一键格式、手动清理或自定义绑定，可有效解决下游数据库驱动的参数绑定问题。

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