spring boot 应用启动成功但自定义 rest 接口返回 404，通常并非代码逻辑错误，而是项目包结构与物理目录结构不一致导致组件扫描失败——这是新手最易忽视却影响最直接的配置陷阱。
spring boot 应用启动成功但自定义 rest 接口返回 404，通常并非代码逻辑错误，而是项目包结构与物理目录结构不一致导致组件扫描失败——这是新手最易忽视却影响最直接的配置陷阱。
在 Spring Boot 中，@SpringBootApplication 注解默认启用 组件扫描（Component Scan），其扫描范围由主启动类所在包路径决定：它会自动扫描主类所在包及其所有子包下的 @Controller、@RestController、@Service、@Repository 等注解类。
观察你提供的项目结构：
src/
└── main/
└── java/
└── com/
└── clubmgmt/
└── clubmgmtstudentservice/
├── Service.java ← 主启动类（包路径：com.clubmgmt.clubmgmtstudentservice）
└── student/
└── StudentController.java ← 当前包路径：com.clubmgmt.clubmgmtstudentservice.student表面上看，StudentController 位于 com.clubmgmt.clubmgmtstudentservice.student，是 com.clubmgmt.clubmgmtstudentservice 的子包，理应被扫描到。但关键问题在于：你的源文件实际物理路径与声明的包路径不匹配。
你提到：
- Service.java 文件路径为 demo/Service.java
- StudentController.java 文件路径为 demo/student/StudentController.java
⚠️ 这意味着：
- Service.java 物理上在 demo/ 目录下，却声明了 package com.clubmgmt.clubmgmtstudentservice;
- StudentController.java 物理上在 demo/student/ 下，却声明了 package com.clubmgmt.clubmgmtstudentservice.student;
→ Java 编译器和 Spring Boot 的类路径加载机制严格依赖“包名 = 目录层级”这一约定。若物理路径（如 demo/）与包名（如 com.clubmgmt...）不一致，编译后 .class 文件将被放置在错误的 classpath 位置，导致 Spring 启动时无法通过包扫描发现该 Controller —— 即使日志显示 “2 mappings in 'requestMappingHandlerMapping'”，那也极可能是其他内置端点（如 /actuator），而非你的 @GetMapping("/get")。
✅ 正确做法：严格对齐包声明与文件系统路径
| 声明的 Java 包名 | 对应的物理路径（从 src/main/java/ 开始） |
|---|---|
| com.clubmgmt.clubmgmtstudentservice | src/main/java/com/clubmgmt/clubmgmtstudentservice/ |
| com.clubmgmt.clubmgmtstudentservice.student | src/main/java/com/clubmgmt/clubmgmtstudentservice/student/ |
因此，请立即执行以下修正：
-
移动文件至标准 Maven 目录结构：
# 创建标准目录 mkdir -p src/main/java/com/clubmgmt/clubmgmtstudentservice/student # 将文件移入正确位置 mv demo/Service.java src/main/java/com/clubmgmt/clubmgmtstudentservice/ mv demo/student/StudentController.java src/main/java/com/clubmgmt/clubmgmtstudentservice/student/
-
确认 Service.java 内容无误（已正确）：
package com.clubmgmt.clubmgmtstudentservice; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class Service { public static void main(String[] args) { SpringApplication.run(Service.class, args); } } -
确认 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"); } } -
清理并重建项目（关键！）：
# 清理旧编译产物 mvn clean # 重新编译并运行 mvn spring-boot:run
? 验证是否生效：
启动日志中应出现类似行（注意 RequestMappingHandlerMapping 的 mapping 数量增加）：
DEBUG ... s.w.s.m.m.a.RequestMappingHandlerMapping : 3 mappings in 'requestMappingHandlerMapping'
同时访问 http://localhost:8080/test/get 将返回 JSON：["Please","Work"]，而非 Whitelabel Error Page。
? 额外建议与注意事项：
- ✅ 永远使用 IDE 的「Move Class」功能（如 IntelliJ 的 Refactor → Move 或 VS Code 的 Java 插件重命名支持），它会同步更新包声明与文件路径，避免手动出错；
- ❌ 不要为绕过结构问题而添加 @ComponentScan(basePackages = "...") —— 这违背 Spring Boot 约定优于配置（Convention over Configuration）原则，且易引入维护隐患；
- ? 若仍 404，检查 application.properties 是否意外设置了 server.servlet.context-path=/api 等上下文路径，此时真实地址应为 http://localhost:8080/api/test/get；
- ?️ Spring Boot 3.x（如你使用的 v3.0.3）要求 Java 17+，请确保 JAVA_HOME 指向兼容 JDK（你日志中为 JDK 19，符合要求）。
遵循“包即路径”这一 Java 核心规范，是保障 Spring Boot 自动装配可靠性的基石。结构对齐后，一切 REST 端点将自然浮现于 DispatcherServlet 的映射表中。
