当容器里有多个 Bean，@Qualifier 如何精准定位？

有一次改老项目，接口注入突然报错，控制台甩出一行熟悉的异常：

vbnet 复制代码

NoUniqueBeanDefinitionException: expected single matching bean but found 2

我一看代码------同一个接口，两个实现类，全都注册进了 Spring 容器。这时候你再靠 @Autowired，Spring 压根不知道你要哪一个！

很多人第一次遇到这种情况，第一反应是"Spring 崩了"，但真相是：**它根本不知道你想要哪个。**而这个时候，@Qualifier 就是你的"精准点名器"。

场景复盘：多实现一出场，`@Autowired` 就懵了

先看一个经典"翻车现场"：

java 复制代码

public interface PaymentService {
    void pay();
}

@Service
public class WeChatPaymentService implements PaymentService {
    public void pay() { System.out.println("微信支付"); }
}

@Service
public class AliPaymentService implements PaymentService {
    public void pay() { System.out.println("支付宝支付"); }
}

@Service
public class OrderService {
    @Autowired
    private PaymentService paymentService; // ❌ 报错：有两个实现
}

运行时直接炸掉：

vbnet 复制代码

NoUniqueBeanDefinitionException: No qualifying bean of type 'PaymentService' available: expected single matching bean but found 2

这就是 Spring 的"选择恐惧症"：它发现容器里有两个 PaymentService，根本不知道你要哪个。

解决问题的关键：`@Qualifier` 精准点名

当容器里有多个候选 Bean 时，@Qualifier 可以帮你明确告诉 Spring 要注入哪一个：

java 复制代码

@Service
public class OrderService {
    @Autowired
    @Qualifier("weChatPaymentService") // 精准点名
    private PaymentService paymentService;
}

Bean 名默认是类名首字母小写（也可以用 @Service("customName") 自定义），Spring 会按照这个名字精确注入。

一步进阶：构造器注入也能配合 `@Qualifier`

推荐的写法是构造器注入，既更安全，也更易测试：

java 复制代码

@Service
public class OrderService {

    private final PaymentService paymentService;

    public OrderService(@Qualifier("aliPaymentService") PaymentService paymentService) {
        this.paymentService = paymentService;
    }
}

这样你不仅注入精准，还能让 paymentService 变成 final，保证不可变性。

再进阶：集合注入 + `@Qualifier` 精准过滤

有时候你可能需要同时注入多个实现类，再在方法里挑选使用。比如支付网关需要支持多种支付方式：

java 复制代码

@Service
public class PaymentAggregator {

    @Autowired
    private List<PaymentService> paymentServices;

    public void payAll() {
        paymentServices.forEach(PaymentService::pay);
    }
}

这时候 Spring 会自动注入所有实现类 ，但如果你只想要其中一个，也可以配合 @Qualifier：

java 复制代码

@Autowired
@Qualifier("aliPaymentService")
private PaymentService paymentService;

甚至还能用 Map<String, PaymentService> 来按 Bean 名索引：

java 复制代码

@Autowired
private Map<String, PaymentService> paymentServiceMap;

public void pay(String type) {
    paymentServiceMap.get(type).pay();
}

这种写法在策略模式场景下非常常见（面试官也爱问！）。

小心几个"坑"

@Qualifier 名称必须和 Bean 名对得上
- 默认是类名首字母小写，比如 WeChatPaymentService → "weChatPaymentService"
- 自定义名称：@Service("wechatPay") → 那就得写 @Qualifier("wechatPay")
别和 @Primary 混为一谈
- @Primary 是"默认实现"，当有多个 Bean 但你没指定时，Spring 会选它。
- @Qualifier 是"点名"，优先级更高，会覆盖 @Primary 的选择。
java 复制代码
```
@Service
@Primary
public class AliPaymentService implements PaymentService { ... }
```
上面这段即便加了 @Primary，只要你用：
java 复制代码
```
@Qualifier("weChatPaymentService")
```
Spring 依然会选微信支付实现。
字段名 ≠ Bean 名
- 有人以为字段名和 Bean 名能自动匹配，其实那只是"歪打正着"。
- 如果 Bean 名和字段名不同，不写 @Qualifier 就绝对不会注入成功。

最佳实践：精准依赖的三件事

✅ 接口 + 多实现 的场景下一定写 @Qualifier，别让 Spring 自己"猜"
✅ 构造器注入 + final 是最推荐的写法，依赖关系清晰、可测试性强
✅ 需要默认实现时加 @Primary，但一旦点名就用 @Qualifier

总结一句话

"@Autowired 是'我有很多朋友'；@Qualifier 是'我只要这个朋友'。"

在多实现场景下，不加 @Qualifier 就像在地铁口喊"张三"一样模糊。Spring 不会猜你要哪个，实现类越多，风险越大。用好这把"点名器"，才能让注入既精准又优雅。

当容器里有多个 Bean，@Qualifier 如何精准定位？