Spring Boot测试报错：@ComponentScan注解过滤器需注解类型排查

问题描述 #

我有一个基于spring-boot-starter-parent 2.7.7的Spring Boot应用，生产环境使用PostgreSQL数据库，测试阶段计划用H2嵌入式数据库。其中UserRepository继承JpaRepository并标注了@Repository注解。编写的UserRepositoryTest测试类代码如下：

@ActiveProfiles("test")
@ExtendWith(SpringExtension.class)
@DataJpaTest
class UserRepositoryTest {
    @Autowired
    private UserRepository userRepository;

    @Test
    void testFindByUsername_Ok() {
        // 测试逻辑
    }
}

测试环境配置文件application-test.yaml内容：

spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driver-class-name: org.h2.Driver
    username: user
    password: pwd
  jpa:
    database-platform: org.hibernate.dialect.H2Dialect

项目依赖包括h2 2.1.214、postgresql 42.6.0、junit-jupiter-engine 5.9.2。

错误信息 #

启动测试用例时抛出如下异常：

Failed to load ApplicationContext. @ComponentScan ANNOTATION type filter requires an annotation type: UserRepository.

我并未在测试类中使用@ComponentScan或@SpringBootApplication注解。

已尝试的无效方案 #

• 在测试类添加以下注解，问题未解决：

  @EnableJpaRepositories("my.base.package.dao.repository")
  @EntityScan("my.base.package.dao.model.")
  @AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
  

• 测试类与UserRepository的包路径一致，但无法添加@SpringBootTest，会触发冲突：

  Configuration error: found multiple declarations of @BootstrapWith for test class UserRepositoryTest.

解决方法 #

1. 定位错误根源 #

这个异常的核心原因是：项目中某个配置类的@ComponentScan（或@SpringBootApplication内置的扫描配置）里，错误地将UserRepository接口当作注解类型来使用。比如出现了类似下面的错误配置：

@SpringBootApplication(
    scanFilters = @ComponentScan.Filter(
        type = FilterType.ANNOTATION,
        classes = UserRepository.class
    )
)

FilterType.ANNOTATION要求传入的是注解类，但UserRepository是继承JpaRepository的接口，并非注解，因此触发错误。

2. 修正扫描配置 #

• 全局搜索项目中所有@Filter(type = FilterType.ANNOTATION, classes = ...)代码块，找到包含UserRepository.class的错误配置并删除或修正：
  • 如果是想扫描Repository接口，不需要额外配置ANNOTATION类型过滤器，@EnableJpaRepositories会自动识别继承JpaRepository的接口；
  • 如果是要过滤特定注解，需传入真正的注解类（比如org.springframework.stereotype.Repository或自定义注解）。

3. 简化测试类配置 #

@DataJpaTest作为Spring Boot的切片测试注解，默认会自动配置JPA相关组件，且会自动扫描同包或子包下的Repository接口。因此可以简化测试类，移除多余注解：

@ActiveProfiles("test")
@DataJpaTest
class UserRepositoryTest {
    @Autowired
    private UserRepository userRepository;

    @Test
    void testFindByUsername_Ok() {
        // 测试逻辑
    }
}

注：Spring Boot 2.7+版本中，@ExtendWith(SpringExtension.class)已被@DataJpaTest包含，可省略。

4. 验证Repository注解 #

确保UserRepository上的@Repository是Spring官方的org.springframework.stereotype.Repository，而非自定义的同名注解（若有自定义注解，需检查扫描配置是否正确）。

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