Spring Boot自定义@ConfigurationPropertiesBinding转换器失效排查

报错核心原因 #

1. @ConstructorBinding 导致转换器加载时机滞后
   使用@ConstructorBinding时，Spring会在Bean构造阶段就执行属性绑定逻辑，但你通过@Component标注的自定义StringToMapConverter是在后续组件扫描阶段才被注册到ConversionService中，导致构造绑定时找不到对应的转换器，触发ConverterNotFoundException。

2. （次要）YML配置的字符串转义冗余
   配置中applicationKeys的JSON字符串使用了转义双引号（"），虽然转换器能处理，但写法不够简洁，容易出错。

解决方案 #

方案一：移除@ConstructorBinding（推荐） #

去掉PushProperties上的@ConstructorBinding注解，让Spring通过属性绑定（而非构造绑定）的方式注入配置，此时Converter已经完成注册，能被正常识别：

@ConfigurationProperties("app.push")
data class PushProperties(
    val errorCallbackUrl: String,
    val firebase: FirebaseProperties
)

data class FirebaseProperties(
    val applicationKeys: Map<Application,String>,
    val defaultKey: String
)

方案二：保留@ConstructorBinding，通过@Bean注册转换器 #

如果必须使用构造绑定，需要将转换器以@Bean的方式显式注册，确保在构造绑定阶段就能被加载：

1. 移除StringToMapConverter上的@Component注解
2. 添加配置类注册转换器：

@Configuration
class ConverterConfig {
    @Bean
    @ConfigurationPropertiesBinding
    fun stringToMapConverter(): Converter<String, Map<Application, String>> {
        return StringToMapConverter()
    }
}

优化YML配置写法 #

将applicationKeys的JSON字符串用单引号包裹，避免转义双引号，提升可读性：

app:
  use-dev-apns: true
  kafka.consumer.group: 'local'
  push:
    errorCallbackUrl: 'callback-url'
    firebase:
      applicationKeys: '{"applicationOne": "api=key-one","applicationTwo": "api=key-two"}'
      defaultKey: 'api-key'

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