使用@MockBean+@Qualifier配合@WebFluxTest触发NoUniqueBeanDefinitionException

问题根源 #

你的场景中，ReadWriteService继承了ReadService，两个Bean（readWrite类型为ReadWriteService、readOnly类型为ReadService）本质上都属于ReadService的实现类。而@WebFluxTest作为切片测试，其上下文的Bean匹配逻辑会优先基于类型扫描，即使给@MockBean添加了@Qualifier，Spring仍可能因为识别到多个ReadService类型的Bean（原始Bean或mock Bean）而抛出NoUniqueBeanDefinitionException。此外，@MockBean在切片测试中对@Qualifier的优先级处理，不如常规Spring上下文那样严格。

具体解决方案 #

方案1：给@MockBean指定精确匹配的Bean类型 #

核心是让mock的类型与你原始Bean定义的类型完全一致：

• 针对@Qualifier("readOnly")的Bean，mock时指定类型为ReadService
• 针对@Qualifier("readWrite")的Bean，mock时指定类型为ReadWriteService

示例代码：

@WebFluxTest(YourTargetController.class)
public class ControllerTest {
    // Mock只读服务：类型严格对应原始Bean的ReadService
    @MockBean
    @Qualifier("readOnly")
    private ReadService readOnlyService;

    // Mock读写服务：类型严格对应原始Bean的ReadWriteService
    @MockBean
    @Qualifier("readWrite")
    private ReadWriteService readWriteService;

    // 注入控制器并编写测试用例
    @Autowired
    private WebTestClient webTestClient;

    // ... 测试逻辑
}

这种方法直接避免了Spring将两个mock识别为同类型Bean，从根源上解决冲突。

方案2：自定义测试配置类显式定义Mock Bean #

如果方案1不生效，可以通过@TestConfiguration手动在测试上下文定义带@Qualifier的mock Bean，完全控制Bean的创建逻辑：

@WebFluxTest(YourTargetController.class)
public class ControllerTest {

    @TestConfiguration
    static class TestServiceConfig {
        @Bean
        @Qualifier("readOnly")
        public ReadService readOnlyService() {
            return Mockito.mock(ReadService.class);
        }

        @Bean
        @Qualifier("readWrite")
        public ReadWriteService readWriteService() {
            return Mockito.mock(ReadWriteService.class);
        }
    }

    // 注入自定义的mock Bean
    @Autowired
    @Qualifier("readOnly")
    private ReadService readOnlyService;

    @Autowired
    private WebTestClient webTestClient;

    // ... 测试逻辑
}

此方法完全绕过@MockBean的自动处理，确保测试上下文只有你定义的mock Bean，无重复冲突。

方案3：限制@WebFluxTest的扫描范围 #

如果@WebFluxTest自动扫描到了原始的Service配置类，导致原始Bean与mock Bean共存，可以通过excludeAutoConfiguration或controllers参数缩小扫描范围：

@WebFluxTest(
    controllers = YourTargetController.class,
    excludeAutoConfiguration = ServiceConfig.class // 排除原始服务配置类
)
public class ControllerTest {
    // 按方案1定义mock Bean即可
}

注意：排除配置类时要确保不会影响控制器的正常注入。

额外注意事项 #

• 不要同时使用@MockBean和原始Bean：如果测试上下文同时存在原始Bean和mock Bean，即使加了@Qualifier，仍可能触发类型匹配冲突。
• 避免滥用@Primary：虽然@Primary可以指定优先Bean，但会影响其他测试用例的上下文，不推荐作为通用解决方案。

内容的提问来源于stack exchange，提问作者Akash Gupta