本文介绍如何在 Spring Boot 中正确注入泛型组件（如 ListMapper<FROM, TO>），解决因多个 Mapper 实现导致的 Bean 冲突问题，核心方法是结合 @Qualifier 显式绑定具体实现，并通过 @Bean 方法手动注册类型安全的泛型 Bean。
本文介绍如何在 spring boot 中正确注入泛型组件（如 `listmapper
在 Spring Boot 中，直接将泛型类声明为 @Component（如 ListMapper<FROM, TO>）会导致容器无法区分不同类型的实例——因为 Spring 的 Bean 工厂在运行时会擦除泛型信息（type erasure），所有 ListMapper<Foo1, Bar1> 和 ListMapper<Foo2, Bar2> 在容器中都被视为同一原始类型 ListMapper，而其构造器依赖的 Mapper<FROM, TO> 又存在多个实现，最终触发 “expected single bean but found 3” 的注入异常。
根本原因在于：Spring 不支持基于泛型参数的自动 Bean 分辨。即使你用 @RequiredArgsConstructor 声明 private final ListMapper<Foo1, Bar1> 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());
}
}随后在配置类中按需声明强类型 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);
}
}此时，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);
}
}⚠️ 注意事项：
- 切勿为 ListMapper 添加 @Component 或作用域注解（如 @Scope("prototype")），否则将引发重复注册或类型混淆；
- @Qualifier 的值必须与 Mapper 实现类上的 @Qualifier("xxx") 严格一致；
- 若项目使用 Lombok 的 @RequiredArgsConstructor，确保构造器参数名与 @Bean 方法参数名一致（或启用 lombok.config 中的 lombok.anyConstructor.addConstructorProperties = true 以兼容 Spring）；
- 对于大量映射场景，可进一步封装为泛型 @Bean 工厂方法或结合 ApplicationContext 动态获取，但需权衡可读性与灵活性。
该方案兼顾类型安全性、可测试性与 Spring 容器规范，是处理泛型组件依赖注入的最佳实践。
