Spring Boot多模块项目子模块配置类未加载问题求助

我之前也碰到过几乎一模一样的多模块配置扫描坑，结合你的场景（api模块依赖persistence模块，ApiApplication在com.project.api，PersistenceConfig在com.project.persistence.config），给你梳理几个最常见的排查方向和解决办法：

1. 检查组件扫描范围是否覆盖到persistence模块的包 #

Spring Boot默认只会扫描@SpringBootApplication注解所在类的当前包及其子包，你的ApiApplication在com.project.api，而PersistenceConfig在同级的com.project.persistence.config，属于兄弟包，不在默认扫描范围内。

解决办法：
在ApiApplication的@SpringBootApplication注解里显式指定扫描的基础包：

@SpringBootApplication(scanBasePackages = {"com.project.api", "com.project.persistence"})
public class ApiApplication {
    public static void main(String[] args) {
        SpringApplication.run(ApiApplication.class, args);
    }
}

或者更简洁地直接用父包作为扫描范围：scanBasePackages = "com.project"

2. 确认PersistenceConfig类的注解是否正确 #

要让Spring识别这是一个配置类，必须给PersistenceConfig加上@Configuration注解，如果配置类里还有Bean定义（比如@Bean方法），也要确保注解完整：

@Configuration
// 如果涉及JPA持久化，可能还需要添加@EnableJpaRepositories等功能注解
public class PersistenceConfig {
    // 你的配置代码
}

3. 检查模块依赖的配置是否正确 #

确保api模块的构建文件里已经正确引入了persistence模块的依赖，并且依赖范围能让api模块加载到persistence的类：

Maven示例（pom.xml）： #

<dependencies>
    <dependency>
        <groupId>com.project</groupId>
        <artifactId>mypersistence</artifactId>
        <version>你的模块版本号</version>
    </dependency>
</dependencies>

Gradle示例（build.gradle）： #

dependencies {
    implementation project(':mypersistence')
}

4. 确认persistence模块的打包是否正常 #

有时候如果persistence模块打包时漏了配置类，也会导致api模块加载不到。可以去persistence模块的target（Maven）或build（Gradle）目录下，打开生成的jar包，检查是否包含com/project/persistence/config/PersistenceConfig.class文件。

如果发现缺失，执行mvn clean install（Maven）或clean build（Gradle）重新打包persistence模块，再重新构建api模块。

5. 排查是否存在@ComponentScan注解冲突 #

如果项目里其他地方手动添加了@ComponentScan注解，可能会覆盖@SpringBootApplication的默认扫描配置，导致persistence的包没被纳入扫描。这种情况下要确保所有@ComponentScan的范围都包含com.project.persistence。

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