本文详解 Spring Boot 多模块 Gradle 项目中因 @ComponentScan 配置不当导致 Controller 未被扫描、接口返回 404 的根本原因，并提供标准化配置方案与最佳实践。
本文详解 spring boot 多模块 gradle 项目中因 `@componentscan` 配置不当导致 controller 未被扫描、接口返回 404 的根本原因，并提供标准化配置方案与最佳实践。
在构建基于 Spring Boot 的多模块 Gradle 项目（如 domain + task-service）时，常见错误之一是服务启动成功（Tomcat 正常监听 8080 端口），但所有 REST 接口均返回 404 Not Found。该问题并非路由路径、端口或上下文路径配置错误，而是 Spring 容器未能加载 Controller 类——其根源几乎总是 @SpringBootApplication 上的自定义 @ComponentScan 干扰了默认扫描机制。
? 根本原因：@ComponentScan 覆盖默认行为
@SpringBootApplication 是一个组合注解，隐含 @ComponentScan，其默认扫描范围为当前类所在包及其子包。例如，若 TaskServiceApplication.java 位于 com.nyuro.taskservice 包下，则 Spring 会自动扫描 com.nyuro.taskservice.* 下的所有 @Controller、@Service、@Repository 等组件。
然而，你在启动类中显式添加了：
@ComponentScan({"com.nyuro.domain"})
@SpringBootApplication
public class TaskServiceApplication { ... }
这将完全覆盖默认扫描路径，导致 Spring 只扫描 com.nyuro.domain 包（该包实际仅含 JPA 实体，无 Controller），而真正存放控制器的 com.nyuro.taskservice.controllers 包被彻底忽略 —— 因此所有 HTTP 请求均无法匹配到处理器，返回 404。
✅ 正确做法：移除冗余 @ComponentScan，依赖默认行为
// ✅ 删除 @ComponentScan，保留纯净 @SpringBootApplication
@SpringBootApplication
// @EntityScan 和 @EnableJpaRepositories 同理，通常也不需显式声明（见下文）
public class TaskServiceApplication {
public static void main(String[] args) {
SpringApplication.run(TaskServiceApplication.class, args);
}
}
? 关于 @EntityScan 与 @EnableJpaRepositories 的说明
- @EntityScan({"com.nyuro.domain"})：仅当实体类不在 @SpringBootApplication 默认扫描路径内时才需指定。由于 domain 模块是独立 JAR（通过 implementation project(':domain') 引入），其包路径 com.nyuro.domain 不属于 task-service 的源码结构，因此该注解仍需保留。
- @EnableJpaRepositories({"com.nyuro.domain"})：同理，若 domain 模块中定义了 @Repository 接口（如 TaskRepository），且其包路径不被默认扫描覆盖，则需显式启用。但注意：JPA Repository 接口必须位于 domain 模块中，且 task-service 的 build.gradle 已正确定义依赖 implementation project(':domain')，因此该注解可保留（前提是 domain 中确有 repository 接口）。
修正后的启动类应为：
@EntityScan("com.nyuro.domain")
@EnableJpaRepositories("com.nyuro.domain")
@SpringBootApplication // ← 无 @ComponentScan！
public class TaskServiceApplication {
public static void main(String[] args) {
SpringApplication.run(TaskServiceApplication.class, args);
}
}
⚙️ 其他关键配置建议（避免衍生问题）
-
Gradle 结构优化
- 删除 task-service/settings.gradle（根项目 settings.gradle 已声明 include 'domain', 'task-service'）；
- 删除 task-service/gradlew 及 gradlew.bat（仅保留根目录下的 Gradle Wrapper）；
- 将 .gitignore 移至项目根目录，统一忽略 **/build/, .gradle/, .idea/, *.iml 等。
-
Domain 模块的 build.gradle 应精简
domain 是纯 Java 模块，不应应用 application 插件（它用于可执行 JAR，而 domain 仅为库）。改为：plugins { id 'java' // ❌ 移除 id 'application' } -
数据库配置临时验证
若启动时报 JPA/Hibernate 初始化异常（如找不到数据源），可先在 application.yml 中禁用自动配置以聚焦 Controller 问题：spring: autoconfigure: exclude: org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration
✅ 验证步骤
- 清理并重建：
./gradlew clean :task-service:build
- 启动服务：
./gradlew :task-service:bootRun
- 检查控制台日志，确认类似输出：
Mapping servlet: 'dispatcherServlet' to [/] Mapped to com.nyuro.taskservice.controllers.TaskController#hello()
- 使用 Postman 访问 GET http://localhost:8080/tasks/hello，应返回预期响应。
? 总结：多模块 Spring Boot 项目中，@SpringBootApplication 的默认扫描逻辑是可靠基础；任何手动 @ComponentScan 都需谨慎评估是否必要。优先利用包结构约定（如启动类置于顶层包），再按需补充 @EntityScan 或 @EnableJpaRepositories 扫描外部模块，才能兼顾清晰性与健壮性。
