本文介绍如何在 Spring Boot 中正确注入泛型组件（如 ListMapper），解决因多个 Mapper 实现导致的 Bean 冲突问题，核心方法是结合 @Qualifier 显式绑定具体实现，并通过 @Bean 方法手动注册类型安全的泛型 Bean。

本文介绍如何在 spring boot 中正确注入泛型组件（如 `listmapper`），解决因多个 `mapper` 实现导致的 bean 冲突问题，核心方法是结合 `@qualifier` 显式绑定具体实现，并通过 `@bean` 方法手动注册类型安全的泛型 bean。

在 Spring Boot 中，直接将泛型类声明为 @Component（如 ListMapper）会导致容器无法区分不同类型的实例——因为 Spring 的 Bean 工厂在运行时会擦除泛型信息（type erasure），所有 ListMapper 和 ListMapper 在容器中都被视为同一原始类型 ListMapper，而其构造器依赖的 Mapper 又存在多个实现，最终触发 “expected single bean but found 3” 的注入异常。

根本原因在于：Spring 不支持基于泛型参数的自动 Bean 分辨。即使你用 @RequiredArgsConstructor 声明 private final ListMapper mapper;，Spring 仍无法据此匹配到唯一候选 Bean。

✅ 正确做法是：移除 ListMapper 的 @Component 注解，改用 @Configuration 类配合 @Bean 方法显式创建类型特化的 Bean，并通过 @Qualifier 精准关联对应的 Mapper 实现。

例如，定义带语义标识的 Mapper 实现：

@Component
@Qualifier("fooToBarMapper")
public class FooToBarMapper implements Mapper<foo bar> {
    @Override
    public Bar map(Foo from) {
        return new Bar(from.getId(), from.getName());
    }
}

@Component
@Qualifier("userToDtoMapper")
public class UserToDtoMapper implements Mapper<user userdto> {
    @Override
    public UserDto map(User from) {
        return new UserDto(from.getUsername(), from.getEmail());
    }
}</user></foo>

随后在配置类中按需声明强类型 ListMapper Bean：

@Configuration
public class MapperConfig {

    @Bean
    public ListMapper<foo bar> fooBarListMapper(
            @Qualifier("fooToBarMapper") Mapper<foo bar> mapper) {
        return new ListMapper(mapper);
    }

    @Bean
    public ListMapper<user userdto> userListMapper(
            @Qualifier("userToDtoMapper") Mapper<user userdto> mapper) {
        return new ListMapper(mapper);
    }
}</user></user></foo></foo>

此时，MyClass1 和 MyClass2 即可安全注入对应类型：

@Component
@RequiredArgsConstructor
public class MyClass1 {
    private final ListMapper<foo bar> mapper; // ✅ 匹配 fooBarListMapper Bean

    public List<bar> transform(List<foo> foos) {
        return mapper.mapList(foos);
    }
}

@Component
@RequiredArgsConstructor
public class MyClass2 {
    private final ListMapper<user userdto> mapper; // ✅ 匹配 userListMapper Bean

    public List<userdto> convert(List<user> users) {
        return mapper.mapList(users);
    }
}</user></userdto></user></foo></bar></foo>

⚠️ 注意事项：

• 切勿为 ListMapper 添加 @Component 或作用域注解（如 @Scope("prototype")），否则将引发重复注册或类型混淆；
• @Qualifier 的值必须与 Mapper 实现类上的 @Qualifier("xxx") 严格一致；
• 若项目使用 Lombok 的 @RequiredArgsConstructor，确保构造器参数名与 @Bean 方法参数名一致（或启用 lombok.config 中的 lombok.anyConstructor.addConstructorProperties = true 以兼容 Spring）；
• 对于大量映射场景，可进一步封装为泛型 @Bean 工厂方法或结合 ApplicationContext 动态获取，但需权衡可读性与灵活性。

该方案兼顾类型安全性、可测试性与 Spring 容器规范，是处理泛型组件依赖注入的最佳实践。