Spring扫描jar包测试类触发NoUniqueBeanDefinitionException解决方案

你遇到的org.springframework.beans.factory.NoUniqueBeanDefinitionException，核心原因是Spring组件扫描时命中了两个同类型的Bean：通用模块测试目录下的模拟实现fakeMethodA、业务模块的正式实现methodAImplementation。
按照构建工具的默认约定，src/test/java目录下的测试代码本不应该被打包进正式发布的.jar依赖，出现这个问题首先要排查通用模块的构建配置，是否错误将测试目录的编译产物打进了生产依赖包，这类配置错误是该问题最高发的诱因。

• 修正构建配置，从源头隔离测试代码
  检查Maven/Gradle的打包配置，删除将test目录加入主源码集、将test编译产物打入生产jar的自定义配置，回归构建工具默认约定：生产jar只包含src/main/java下的代码，测试代码仅在本模块执行测试时生效，不会随依赖传递到下游项目。
• 用组件扫描规则过滤测试模拟类
  如果暂时无法修正jar包内容，可以在业务模块的启动配置类上添加扫描排除规则，直接跳过模拟类的加载：

  @SpringBootApplication
  @ComponentScan(excludeFilters = {
      @ComponentScan.Filter(
          type = FilterType.ASSIGNABLE_TYPE,
          classes = fakeMethodA.class
      )
  })
  public class BusinessApplication {
      public static void main(String[] args) {
          SpringApplication.run(BusinessApplication.class, args);
      }
  }
  

• 给测试模拟类绑定专属Profile
  给通用模块下的fakeMethodA类添加@Profile("common-module-test")注解，通用模块自身的测试类上通过@ActiveProfiles("common-module-test")激活该Profile，业务模块正常运行时不会激活这个专属Profile，对应的模拟Bean就不会被注册到Spring容器中。

这个场景的核心矛盾是测试代码和生产代码边界不清晰，更规范的实现可以从以下方向调整：

• 用Mock框架生成测试用模拟对象，不要写带Spring组件注解的硬编码模拟类
  通用模块写单元测试时，直接通过@MockBean等注解生成trait的模拟对象，在测试代码内完成打桩、注入逻辑，不需要额外写标注@Component的模拟实现类，从根源上避免测试Bean进入生产上下文。示例写法：

  @SpringBootTest
  public class CommonTraitTest {
      // 直接生成模拟对象注入测试上下文，不需要额外写实现类
      @MockBean
      private YourDefineTrait yourTrait;
  
      @Test
      void testLogic() {
          // 给模拟对象打桩返回测试预期值
          when(yourTrait.doSomething()).thenReturn("testResult");
          // 执行测试逻辑
      }
  }
  

• 用测试夹具（Test Fixtures）管理可复用的测试实现
  如果模拟实现需要在多个模块的测试场景复用，不要把模拟实现放在主源码目录或者普通test目录，用构建工具原生的test-fixtures机制单独管理测试代码：这部分代码不会被打入生产jar，只有其他模块显式声明依赖测试夹具时才会引入，完全不会污染生产环境的Spring上下文。
• 通用模块配置增加Bean条件判断
  如果通用模块需要提供默认实现，给默认实现的Bean添加@ConditionalOnMissingBean注解，Spring容器只有在找不到同类型Bean的时候才会注册默认实现，下游业务模块提供正式实现时，会自动覆盖默认实现，不会出现Bean重复的冲突。

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