本文详解 Spring Boot 多模块 Gradle 项目中因错误使用 @ComponentScan 导致 Controller 未被扫描、接口返回 404 的典型问题，并提供标准化的模块结构、依赖配置与注解用法。
本文详解 spring boot 多模块 gradle 项目中因错误使用 `@componentscan` 导致 controller 未被扫描、接口返回 404 的典型问题，并提供标准化的模块结构、依赖配置与注解用法。
在构建基于 Spring Boot 的多模块 Gradle 项目时，404 Not Found（如 /tasks/hello 返回 status: 404）往往并非路由或端口问题，而是 Spring 容器未能成功加载 Controller 类——根本原因通常是 组件扫描范围配置不当，尤其在跨模块引用场景下极易踩坑。
? 根本原因：@ComponentScan 覆盖了默认扫描行为
你的 TaskServiceApplication 类上显式添加了：
@ComponentScan({"com.nyuro.domain"})
@SpringBootApplication
public class TaskServiceApplication { ... }
⚠️ 这是关键错误：@SpringBootApplication 本身已隐含 @ComponentScan，其默认行为是从当前类所在包及其子包递归扫描所有 @Controller、@Service、@Repository 等组件。
而你手动指定 @ComponentScan({"com.nyuro.domain"}) 后，Spring 完全忽略默认扫描逻辑，仅扫描 com.nyuro.domain 包——但你的 Controller 实际位于 com.nyuro.taskservice.controllers（或类似路径），自然无法被发现，导致所有 HTTP 接口 404。
✅ 正确做法：移除冗余 @ComponentScan，让 @SpringBootApplication 自动完成扫描：
// ✅ 正确：仅保留 @SpringBootApplication
@SpringBootApplication
// ❌ 删除：@ComponentScan({"com.nyuro.domain"})
// ❌ 删除：@EntityScan({"com.nyuro.domain"})
// ❌ 删除：@EnableJpaRepositories({"com.nyuro.domain"})
public class TaskServiceApplication {
public static void main(String[] args) {
SpringApplication.run(TaskServiceApplication.class, args);
}
}
? 补充说明：@EntityScan 和 @EnableJpaRepositories 同样非必需——只要 domain 模块中的实体类（如 Task）和 Repository 接口（若存在）遵循标准包结构（例如 com.nyuro.domain.entity），且 task-service 通过 implementation project(':domain') 正确依赖，Spring Boot 的自动配置会自动识别 JPA 实体与仓库。
?️ 必须同步修正的 Gradle 配置问题
除注解外，以下 Gradle 结构问题也会间接引发启动异常或扫描失败：
-
根项目 build.gradle 中不应声明 Spring Boot 插件
只有 task-service（即启动模块）需应用 Spring Boot 插件。根项目只需定义通用配置（如 Java 版本、仓库）：// nyuro-backend/build.gradle（根） plugins { id 'java' id 'maven-publish' // 可选：用于发布模块 } java { toolchain { languageVersion = JavaLanguageVersion.of(17) } } repositories { mavenCentral() } -
domain 模块应为纯 Java 库，禁用 application 插件
application 插件用于可执行应用，domain 是共享模型层，应精简：// domain/build.gradle plugins { id 'java' // ✅ 仅需 java 插件 } dependencies { // JPA API 是编译时契约，无需 runtime compileOnly 'jakarta.persistence:jakarta.persistence-api:3.1.0' // 若需 Lombok 等工具，可在此添加 } -
task-service 的依赖声明必须精准
确保 domain 模块被正确引入，且无版本冲突：// task-service/build.gradle dependencies { implementation 'org.springframework.boot:spring-boot-starter-web' implementation 'org.springframework.boot:spring-boot-starter-data-jpa' implementation project(':domain') // ✅ 关键：正确引用 developmentOnly 'org.springframework.boot:spring-boot-devtools' runtimeOnly 'com.mysql:mysql-connector-j' testImplementation 'org.springframework.boot:spring-boot-starter-test' }
? Controller 位置与包结构规范（验证要点）
确保你的 Controller 类满足以下条件：
- 位于 task-service 模块内（如 src/main/java/com/nyuro/taskservice/controllers/TaskController.java）
- 类上标注 @RestController 或 @Controller
- 方法使用 @GetMapping("/hello") 等映射注解
- 包路径是 TaskServiceApplication 所在包的子包（例如 TaskServiceApplication 在 com.nyuro.taskservice，则 Controller 应在 com.nyuro.taskservice.* 下）
示例结构：
task-service/ ├── src/main/java/com/nyuro/taskservice/ │ ├── TaskServiceApplication.java // package com.nyuro.taskservice; │ └── controllers/ │ └── TaskController.java // package com.nyuro.taskservice.controllers;
? 其他易忽略的工程规范建议
- .gitignore 放在根目录：避免提交 .gradle/, build/, .idea/ 等生成文件，统一管理。
- 删除冗余 settings.gradle：仅根项目需 settings.gradle，子模块（如 task-service/settings.gradle）应删除。
- 统一 Gradle Wrapper：只保留根目录下的 gradlew，删除子模块中的副本，避免版本不一致。
✅ 验证步骤
- 清理并重启：./gradlew clean && ./gradlew :task-service:bootRun
- 观察控制台日志，确认类似输出：
Mapping URL [/tasks/hello] -> com.nyuro.taskservice.controllers.TaskController.hello() Tomcat started on port(s): 8080 (http) with context path ''
- 使用 curl http://localhost:8080/tasks/hello 或 Postman 测试，应返回预期响应。
⚠️ 注意：若仍报错，请检查 application.properties 是否配置了 server.servlet.context-path 或 spring.mvc.servlet.path，这些前缀会改变实际访问路径。
通过以上调整，你的多模块 Spring Boot 项目将回归标准行为：@SpringBootApplication 自动扫描启动类所在包树，domain 模块作为纯依赖被无缝集成，Controller 正常注册，404 问题彻底解决。
