如何隔离Spring Boot自动配置模块扫描，避免影响主应用@Repository检测

问题描述 #

使用Spring Boot 3.4.4搭建多模块Maven项目，其中lib-model是即插即用的自动配置模块，原通过@EnableJpaRepositories和@EntityScan实现自身JPA组件的自动配置。添加该模块依赖后，主应用app-main的Repository和实体无法被自动扫描，报错缺少OtherRepository类型的Bean。手动在主应用启动类添加@EnableJpaRepositories和@EntityScan可恢复，但希望避免显式配置。

项目结构：

my-project/
├── pom.xml
├── lib-model/
│   ├── pom.xml
│   ├── src/main/java/com/example/libmodel/
│   │   ├── Model.java
│   │   ├── ModelRepository.java
│   │   ├── ModelController.java
│   │   └── LibModelAutoConfiguration.java
│   └── src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
├── app-main/
│   ├── pom.xml
│   ├── src/main/java/com/example/app/
│   │   ├── AppMainApplication.java
│   │   ├── Other.java
│   │   ├── OtherRepository.java
│   │   └── OtherController.java
│   └── src/main/resources/application.properties

原自动配置类：

@Configuration
@EntityScan(basePackages = "com.example.libmodel")
@EnableJpaRepositories(basePackages = "com.example.libmodel")
public class LibModelAutoConfiguration {
}

核心原因 #

Spring Boot的默认JPA自动配置（JpaRepositoriesAutoConfiguration、HibernateJpaAutoConfiguration）会扫描主应用启动类所在包及其子包的组件。但当自定义自动配置类中使用@EnableJpaRepositories或@EntityScan时，会触发条件判断，导致默认自动配置类失效，仅扫描自定义注解指定的包，从而忽略主应用的组件。

解决方案 #

1. 扩展AutoConfigurePackages实现Repository扫描范围合并 #

通过AutoConfigurePackages.Registrar将lib-model的包注册到Spring Boot的自动配置包列表中，让默认的JpaRepositoriesAutoConfiguration同时扫描主应用和lib-model的Repository：

// com.example.libmodel.LibModelAutoConfigurePackagesRegistrar
public class LibModelAutoConfigurePackagesRegistrar implements AutoConfigurePackages.Registrar {
    @Override
    public void registerBeanDefinitions(AnnotationMetadata metadata, BeanDefinitionRegistry registry) {
        // 注册当前模块的包到自动配置扫描列表
        AutoConfigurePackages.register(registry, getClass().getPackageName());
    }
}

2. 修改自动配置类，移除冲突注解并添加实体扫描合并逻辑 #

移除原有的@EnableJpaRepositories和@EntityScan，改用自定义EntityManagerFactoryBuilderCustomizer合并主应用与lib-model的实体扫描范围：

// com.example.libmodel.LibModelAutoConfiguration
@Configuration
@Import(LibModelAutoConfigurePackagesRegistrar.class)
public class LibModelAutoConfiguration {

    @Autowired
    private AutoConfigurePackages autoConfigurePackages;

    @Bean
    public EntityManagerFactoryBuilderCustomizer entityManagerFactoryBuilderCustomizer() {
        return builder -> {
            // 合并主应用包与lib-model包作为实体扫描范围
            List<String> scanPackages = new ArrayList<>(autoConfigurePackages.getPackageNames());
            scanPackages.add(getClass().getPackageName());
            builder.persistenceUnit(pu -> pu.packagesToScan(scanPackages.toArray(new String[0])));
        };
    }
}

3. 验证效果 #

修改后，主应用无需添加任何JPA相关的显式注解，Spring Boot会自动扫描：

• 主应用com.example.app包下的Other实体和OtherRepository
• lib-model模块com.example.libmodel包下的Model实体和ModelRepository

关键优势 #

• 完全保留Spring Boot的自动配置特性，主应用无需额外配置
• lib-model模块实现真正的即插即用，不干扰主应用的原有逻辑
• 避免硬编码包名，通过类引用动态获取模块包路径，提升可维护性

内容的提问来源于stack exchange，提问作者Marc de Verdelhan