本文详解 spring boot 应用中控制器（@restcontroller）未被正确扫描导致 404 的根本原因，重点剖析包路径、源码目录结构与 spring 组件扫描范围之间的严格对应关系，并提供可立即验证的修复步骤与最佳实践。
本文详解 spring boot 应用中控制器（@restcontroller）未被正确扫描导致 404 的根本原因，重点剖析包路径、源码目录结构与 spring 组件扫描范围之间的严格对应关系，并提供可立即验证的修复步骤与最佳实践。
在 Spring Boot 中，@SpringBootApplication 注解默认启用组件扫描（component scanning），其扫描范围由主启动类所在包及其子包决定。这意味着：只有位于 com.clubmgmt.clubmgmtstudentservice 包或其任意子包（如 com.clubmgmt.clubmgmtstudentservice.student）下的 @RestController、@Service、@Component 等注解类，才会被自动注册为 Spring Bean 并参与请求路由映射。
然而，一个极易被忽视但致命的问题是：Java 源文件的物理路径必须严格匹配其声明的 package 结构。否则，即使编译通过、日志显示“无错误”，Spring 的类路径扫描器（ClassPathBeanDefinitionScanner）也无法定位到该类——因为它依赖标准的 Maven/Gradle 目录约定（src/main/java 下的目录层级 = Java 包层级）进行字节码扫描。
观察你提供的项目结构：
src/
└── main/
└── java/
└── com/
└── clubmgmt/
└── clubmgmtstudentservice/
├── Service.java ← 正确：package com.clubmgmt.clubmgmtstudentservice
└── student/
└── StudentController.java ← ❌ 错误：声明 package com.clubmgmt.clubmgmtstudentservice.student，但实际路径为 demo/student/关键矛盾点在于：StudentController.java 文件顶部声明了
package com.clubmgmt.clubmgmtstudentservice.student;
但其真实文件路径却是 demo/student/StudentController.java（而非符合约定的 src/main/java/com/clubmgmt/clubmgmtstudentservice/student/StudentController.java）。这导致编译后生成的 .class 文件被放置在错误的类路径位置，Spring 启动时根本无法加载该 Controller 类——因此 /test/get 路由不会被注册，访问时自然返回 Whitelabel 404 页面。
✅ 正确的物理路径必须与 package 声明完全一致：
package com.clubmgmt.clubmgmtstudentservice.student;
→ 对应路径：src/main/java/com/clubmgmt/clubmgmtstudentservice/student/StudentController.java
✅ 修复步骤（三步到位）
调整文件位置
将 StudentController.java 移动至标准源码路径：
src/main/java/com/clubmgmt/clubmgmtstudentservice/student/StudentController.java-
确认主启动类位置与包名一致
Service.java 应位于：
src/main/java/com/clubmgmt/clubmgmtstudentservice/Service.java
且其 package 声明为：package com.clubmgmt.clubmgmtstudentservice;
-
验证 Controller 定义完整性（补充缺失部分）
你提供的 StudentController.java 片段缺少右大括号和 import，完整修正版如下：package com.clubmgmt.clubmgmtstudentservice.student; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; import org.springframework.web.bind.annotation.RequestMapping; import java.util.List; @RestController @RequestMapping(path = "/test") public class StudentController { @GetMapping("/get") public List<String> getStudents() { return List.of("Please", "Work"); } }
? 验证是否生效
启动应用后，检查控制台日志中是否出现类似关键行：
s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped POST "/test/get" onto public java.util.List<java.lang.String> com.clubmgmt.clubmgmtstudentservice.student.StudentController.getStudents()
⚠️ 注意：Spring Boot 3.x 默认使用 GET 映射，@GetMapping 已隐含 HTTP 方法，无需额外配置。
同时，可访问 Actuator 的端点映射查看（需添加 spring-boot-starter-actuator 依赖）：
GET http://localhost:8080/actuator/mappings
搜索 /test/get，确认其已注册在 requestMappingHandlerMapping 中。
? 重要注意事项
- 切勿仅修改 package 声明而不移动文件：这是新手高频误区。IDE（如 IntelliJ IDEA 或 VS Code + Extension）的「Refactor → Move」功能会同步更新 package 和文件路径，强烈推荐使用。
- Maven/Gradle 构建工具严格依赖目录结构：src/main/java 是默认源根（source root），任何偏离此结构的 .java 文件均不会被编译进 target/classes，Spring 自然无法扫描。
- 检查 IDE 是否识别了正确的源根：在 IntelliJ 中右键 src/main/java → Mark Directory as → Sources Root；VS Code 需确保 Java 插件已加载项目并识别 pom.xml 或 build.gradle。
- Spring Boot 3.x 兼容性提示：你使用的是 Spring Boot 3.0.3，需确保 JDK 版本 ≥ 17（你使用 JDK 19 符合要求），且所有依赖（如 Spring Web）版本与之对齐。
遵循以上规范后，localhost:8080/test/get 将成功返回 JSON 数组 ["Please","Work"]，Whitelabel 404 错误将彻底消失。归根结底，Spring Boot 的“约定优于配置”不是口号——它是可靠运行的基石。
