Spring Boot @ConditionalOnMissingBean泛型多类型使用异常排查

问题场景 #

在Spring Boot 3.2.3 Starter项目中，我们定义了默认的Integer转String的Converter Bean，并通过@ConditionalOnMissingBean注解实现按需加载：

• 直接替换该Bean的实现时无问题；
• 但项目中存在其他类型的Converter Bean（如String转String）时，默认Bean无法初始化，注入时抛出UnsatisfiedDependencyException；
• 尝试为@ConditionalOnMissingBean添加泛型类型信息后，应用启动抛出IllegalStateException，错误日志核心内容如下：

java.lang.IllegalStateException: 处理io.d4e.starter.ExampleAutoConfiguration.exampleConverter上的条件时出错
...
Caused by: java.lang.IllegalArgumentException: 为公共抽象接口org.springframework.core.convert.converter.Converter<S,T>指定的泛型数量不匹配

目前采用按Bean名称限制的临时方案，但不够理想，疑问在于：是泛型条件配置有误，还是Spring Boot存在Bug？

问题原因分析 #

1. 未指定泛型时的逻辑问题
   最初的@ConditionalOnMissingBean(Converter.class)会匹配所有实现Converter接口的Bean，无论泛型类型。只要项目中存在任意Converter Bean，默认的Integer转String Converter就不会被创建，导致依赖注入时找不到对应类型的Bean，触发UnsatisfiedDependencyException。

2. 泛型配置错误导致的异常
   尝试添加泛型时出现的IllegalArgumentException，是因为Converter<S,T>接口需要两个泛型参数（源类型S、目标类型T），如果配置时指定的泛型数量不匹配（比如只传一个类型），就会触发“泛型数量不匹配”的错误。

正确的泛型条件配置方式 #

要实现仅当没有Integer转String类型的Converter时才创建默认Bean，有两种正确的配置方式：

方式一：通过type指定带泛型的完整类型 #

@Configuration
public class ExampleAutoConfiguration {
    @Bean
    @ConditionalOnMissingBean(type = "org.springframework.core.convert.converter.Converter<java.lang.Integer, java.lang.String>")
    public Converter<Integer, String> exampleConverter() {
        return String::valueOf;
    }
}

方式二：通过generic属性指定泛型参数 #

@Configuration
public class ExampleAutoConfiguration {
    @Bean
    @ConditionalOnMissingBean(
        value = Converter.class,
        generic = {Integer.class, String.class}
    )
    public Converter<Integer, String> exampleConverter() {
        return String::valueOf;
    }
}

注意：generic参数必须传入与Converter接口泛型数量一致的类型（2个），否则会再次触发泛型数量不匹配的异常。

临时方案的不足 #

按Bean名称限制的方案（如@ConditionalOnMissingBean(name = "exampleConverter")）存在明显缺陷：

• 依赖Bean名称的强约定，用户自定义Converter时如果不使用指定名称，会导致默认Bean与自定义Bean共存，引发类型冲突；
• 不符合Spring类型驱动注入的设计理念，灵活性差。

结论 #

这并非Spring Boot的Bug，而是泛型条件配置时的参数错误。只要正确指定与Converter<S,T>匹配的两个泛型参数，就能实现预期的按需加载逻辑。

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