spring boot 应用启动成功但自定义 rest 端点返回 404，通常源于包结构与物理目录结构不一致，导致组件扫描失败；本文将系统性分析该问题并提供可落地的修复方案。
spring boot 应用启动成功但自定义 rest 端点返回 404，通常源于包结构与物理目录结构不一致，导致组件扫描失败；本文将系统性分析该问题并提供可落地的修复方案。
在 Spring Boot 中，@SpringBootApplication 注解默认启用类路径下的组件自动扫描（component scanning），其扫描范围由主启动类所在包及其子包决定。若控制器类实际存放路径与声明的 package 不匹配，Spring 将完全忽略该类——即使编译通过、日志无报错、IDE 插件显示“已注册端点”，请求仍会触发 Whitelabel Error Page（404）。
? 根本原因：包声明与物理路径严重错位
从你提供的项目结构可见：
src/
└── main/
└── java/
└── com/
└── clubmgmt/
└── clubmgmtstudentservice/ ← 启动类 Service.java 在此目录
├── Service.java
└── student/
└── StudentController.java ← 物理位置正确但 StudentController.java 的包声明为：
package com.clubmgmt.clubmgmtstudentservice.student;
而其实际文件路径却是：
demo/student/StudentController.java ← ❌ 错误！这与 package 声明完全不对应
⚠️ 关键原则：Java 包名必须严格等于其在 src/main/java/ 下的相对路径。
即 package com.clubmgmt.clubmgmtstudentservice.student; 要求该文件必须位于：
src/main/java/com/clubmgmt/clubmgmtstudentservice/student/StudentController.java
当前你将其放在 demo/student/... 目录下，相当于告诉 JVM：“这个类属于 demo.student 包”，但代码却声明为 com.clubmgmt...student，造成编译期与运行期认知割裂，Spring 扫描器按包路径查找时自然找不到它。
✅ 正确修复步骤（推荐 IDE 辅助操作）
统一物理路径与包声明
将 StudentController.java 从 demo/student/ 移动至标准 Maven 路径：
src/main/java/com/clubmgmt/clubmgmtstudentservice/student/StudentController.java-
使用 IDE「Move Class」功能（强烈推荐）
- 在 IntelliJ IDEA 或 VS Code（配合 Java Extension Pack）中，右键点击 StudentController 类名 → 选择 "Refactor → Move..."
- 输入目标包名 com.clubmgmt.clubmgmtstudentservice.student
→ IDE 将自动同步更新 package 声明 + 移动文件到正确目录，杜绝手动出错。
-
验证启动类位置合理性
确保 Service.java 位于 src/main/java/com/clubmgmt/clubmgmtstudentservice/Service.java，且类名为 Service（非 ClubMgmtStudentServiceApplication —— 日志中显示的类名已不一致，需同步修正）：// ✅ 正确示例：src/main/java/com/clubmgmt/clubmgmtstudentservice/Service.java package com.clubmgmt.clubmgmtstudentservice; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication // 自动扫描 com.clubmgmt.clubmgmtstudentservice 及其子包 public class Service { public static void main(String[] args) { SpringApplication.run(Service.class, args); } } -
检查 Controller 完整性（补充缺失部分）
你提供的 StudentController 代码缺少右大括号和 import，完整版应为：// src/main/java/com/clubmgmt/clubmgmtstudentservice/student/StudentController.java 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"); } }
? 验证是否生效
启动应用后，观察控制台关键日志：
DEBUG ... RequestMappingHandlerMapping : 2 mappings in 'requestMappingHandlerMapping'
→ 若数字 ≥ 1（如 1 mappings），说明控制器已被加载。
再访问 http://localhost:8080/test/get，应返回 JSON 数组 ["Please","Work"]。
? 提示：可通过 Actuator 的 mappings 端点进一步确认：
启用 spring-boot-starter-actuator，访问 http://localhost:8080/actuator/mappings，搜索 /test/get，确认其绑定到 StudentController.getStudents()。
⚠️ 注意事项与最佳实践
- 勿手动修改 package 声明而不移动文件：这是初学者高频错误，务必依赖 IDE 重构工具。
- 避免使用 demo、test 等非标准顶层包名：它们易与测试源码目录（src/test/java/demo/...）混淆，建议始终遵循 groupId + artifactId 命名规范（如 com.clubmgmt.clubmgmtstudentservice）。
- 检查 Maven 构建输出：运行 mvn clean compile 后，确认 target/classes/com/clubmgmt/clubmgmtstudentservice/student/StudentController.class 存在。
- Spring Boot 3.x 兼容性：你使用的是 Spring Boot 3.0.3（基于 Jakarta EE 9+），确保所有依赖（如 spring-web）版本兼容，且未引入旧版 javax.* 包。
遵循以上规范，即可彻底解决“端点存在却 404”的典型扫描失效问题，让 Spring Boot 的约定优于配置（Convention over Configuration）真正发挥效力。
