本文详解如何在 spring boot 中解决泛型接口（如 mapper<from, to>）与泛型组件（如 listmapper<from, to>）协同使用的依赖注入歧义问题，通过 @qualifier + 显式 @bean 定义实现类型安全、可复用的泛型 bean 注入。
本文详解如何在 spring boot 中解决泛型接口（如 mapper<from, to>）与泛型组件（如 listmapper<from, to>）协同使用的依赖注入歧义问题，通过 @qualifier + 显式 @bean 定义实现类型安全、可复用的泛型 bean 注入。
在 Spring Boot 中，直接将泛型类标记为 @Component（如 ListMapper<FROM, TO>）并期望其按具体类型参数自动注入，往往会导致 “No unique bean of type X found” 错误。根本原因在于：Spring 的 IoC 容器在运行时会擦除泛型类型信息（Type Erasure），因此所有 ListMapper<Foo1, Bar1>、ListMapper<Foo2, Bar2> 在容器中最终都被视为同一原始类型 ListMapper，而其构造器依赖的 Mapper<FROM, TO> 又存在多个实现，导致 Spring 无法区分应注入哪一个。
✅ 正确解法是放弃泛型组件的自动扫描注册，转为显式、类型特化的 @Bean 声明，并结合 @Qualifier 精准绑定具体 Mapper 实现。以下是完整实践步骤：
1. 保持 Mapper 接口及其实现的限定化声明
为每个具体映射器添加语义化 @Qualifier，避免歧义：
@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.getEmail(), from.getFullName());
}
}2. 移除 ListMapper 的 @Component，改为配置类中按需定义 Bean
ListMapper 不再作为通用组件被扫描，而是由配置类根据具体类型对创建专属实例：
@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);
}
}? 注意：ListMapper 构造器需修正为 public ListMapper(Mapper<FROM, TO> mapper)（原文中缺少 public 修饰符，否则无法被 Spring 反射调用）。
3. 在业务组件中安全注入特化类型
此时 MyClass1 和 MyClass2 可无歧义地注入对应泛型实例：
@Component
@RequiredArgsConstructor
class MyClass1 {
private final ListMapper<Foo, Bar> mapper; // ✅ 匹配 fooBarListMapper Bean
public List<Bar> transform(List<Foo> foos) {
return mapper.mapList(foos);
}
}
@Component
@RequiredArgsConstructor
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") —— 泛型擦除使其无法被 Spring 正确区分；
- ✅ @Qualifier 必须作用于 Mapper 实现类（而非接口），且 @Bean 方法中需显式使用该 qualifier 注入；
- ✅ 若项目使用 Lombok 的 @RequiredArgsConstructor，确保 ListMapper 构造器为 public，否则编译/反射失败；
- ? 进阶可封装为 @MapperModule 自定义注解 + ImportBeanDefinitionRegistrar 实现自动化注册，但对多数场景，显式 @Bean 已足够清晰、可控、可测试。
通过该模式，你既保留了泛型带来的编译期类型安全，又规避了 Spring 运行时泛型擦除导致的 DI 混淆，是 Spring 生态中处理“泛型组件依赖”的推荐工程实践。
