SpringBoot3依赖注入实战：@Autowired遇到多个Bean时如何解决

在上一节中，我们探讨了控制反转（IoC）的基本概念以及三种常见的依赖注入方式。其中，@Autowired 注解是 Spring 进行自动化依赖注入的核心，它主要为我们完成了以下几项工作：

1. 自动寻找并注入一个实现了指定接口（例如 Coach）的 Bean。
2. 在应用上下文中扫描所有被 @Component（或其派生注解）标记的类。
3. 查找哪些被扫描到的类实现了目标接口。
4. 若找到一个匹配的实现，则自动将其注入到当前依赖它的类中。

这个过程可以参照下图来理解：

然而，这里有一个关键问题我们之前没有讨论：当 Spring 在上下文中找到多个符合要求的 Coach 实现类时，它应该将哪一个注入给依赖方呢？这正是本节要解决的核心问题，即 Spring Boot 如何处理依赖注入时的多实现类冲突。

1. 多实现类导致的注入歧义

为了模拟这个场景，我们创建多个 Coach 接口的实现类，并都用 @Component 注解标记，使它们成为 Spring 容器管理的 Bean。项目结构可能如下所示：

与此同时，我们的 Controller 通过构造器注入的方式依赖 Coach 接口：

package com.greenbook.springbootdemo.rest;

import com.greenbook.springbootdemo.service.Coach;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class FunRestController {

    private Coach coach;

    @Autowired
    public FunRestController(Coach coach) {
        this.coach = coach;
    }

    @GetMapping("/workout")
    public String getDailyWorkout() {
        return coach.getDailyWorkout();
    }
}

此时，如果你尝试启动应用，Spring Boot 会抛出一个明确的启动错误：

Description:

Parameter 0 of constructor in com.greenbook.springbootdemo.rest.FunRestController required a single bean, but 4 were found:
    - baseballCoach: defined in file [/Users/xyz/local/springbootdemo/target/classes/com/greenbook/springbootdemo/service/impl/BaseballCoach.class]
    - cricketCoach: defined in file [/Users/xyz/local/springbootdemo/target/classes/com/greenbook/springbootdemo/service/impl/CricketCoach.class]
    - tennisCoach: defined in file [/Users/xyz/local/springbootdemo/target/classes/com/greenbook/springbootdemo/service/impl/TennisCoach.class]
    - trackCoach: defined in file [/Users/xyz/local/springbootdemo/target/classes/com/greenbook/springbootdemo/service/impl/TrackCoach.class]

Action:

Consider marking one of the beans as @Primary, updating the consumer to accept multiple beans, or using @Qualifier to identify the bean that should be consumed

错误信息清晰地指出：FunRestController 的构造函数期望注入一个 Coach 类型的 Bean，但实际在容器中找到了四个符合条件的候选者（baseballCoach， cricketCoach， tennisCoach， trackCoach）。这导致 Spring Boot 无法做出选择，因此应用启动失败。幸运的是，框架的错误提示已经为我们指明了解决方案：使用 @Primary 注解或 @Qualifier 注解。

2. 使用 @Qualifier 精确指定

@Qualifier 注解的作用是充当一个“限定符”，允许我们明确指定要注入的 Bean 的 ID（默认是类名首字母小写）。我们可以在注入点（如构造器参数、Setter方法参数或字段上）使用它。

构造器注入结合@Qualifier：

package com.greenbook.springbootdemo.rest;

import com.greenbook.springbootdemo.service.Coach;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class FunRestController {

    private Coach coach;

    @Autowired
    public FunRestController(@Qualifier("cricketCoach") Coach coach) {
        this.coach = coach;
    }

    @GetMapping("/workout")
    public String getDailyWorkout() {
        return coach.getDailyWorkout();
    }
}

这里，@Qualifier(“cricketCoach”) 指定了 Bean 的 ID 为 cricketCoach，这对应于 CricketCoach 类（Spring 默认将类名首字母小写作为其 Bean ID）。这样，Spring 就会精确地注入 CricketCoach 的实例。

Setter注入同样适用@Qualifier：

package com.greenbook.springbootdemo.rest;

import com.greenbook.springbootdemo.service.Coach;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class FunRestController {

    private Coach coach;

    @Autowired
    public void setCoach(@Qualifier("cricketCoach") Coach coach) {
        this.coach = coach;
    }

    @GetMapping("/workout")
    public String getDailyWorkout() {
        return coach.getDailyWorkout();
    }
}

@Qualifier 提供了一种非常直接和明确的依赖指定方式，尤其适合在需要动态切换或明确指定某个具体实现的场景中使用。掌握这类依赖管理的技巧是高效使用 Java 技术栈进行后端开发的重要基础。

3. 使用 @Primary 设置默认首选

除了精确指定，Spring 还提供了另一种更“含蓄”的解决方案：@Primary 注解。这个注解标记在某个具体的实现类上，表明当存在多个同类型 Bean 候选时，被标记 @Primary 的 Bean 应被优先选择。

在实现类上使用@Primary：

package com.greenbook.springbootdemo.service.impl;

import com.greenbook.springbootdemo.service.Coach;
import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Component;

@Primary // 标记此类为首选Bean
@Component
public class TrackCoach implements Coach {

    @Override
    public String getDailyWorkout() {
        return “Run a hard 5K!”;
    }
}

这样配置之后，Controller 中就不需要再使用 @Qualifier 注解了，Spring 会自动注入 TrackCoach 的实例。当然，如果同时使用了 @Qualifier，Spring 会优先遵从 @Qualifier 的明确指示。

不过，@Primary 注解有一个重要的限制：对于同一个接口，最多只能有一个实现类被标记为 @Primary。如果多个实现类都加上了 @Primary，Spring 会再次陷入选择困难，抛出类似以下的错误：

No qualifying bean of type ‘com.greenbook.springbootdemo.service.Coach’ available: more than one ‘primary’ bean found among candidates: [baseballCoach, cricketCoach, tennisCoach, trackCoach]

这种情况在多模块或大型项目中需要特别注意。因此，从代码的清晰度和可控性角度出发，@Qualifier 通常比 @Primary 更受推荐，因为它显式地声明了依赖关系，避免了潜在的隐式冲突。并且，@Qualifier 的优先级高于 @Primary，当两者共存时，以 @Qualifier 的指定为准。理解这些注解的优先级是构建稳定 Spring Boot 应用的关键之一。