Spring Boot REST API 返回 404 的常见原因与解决方案-java教程-PHP中文网

Spring Boot REST API 返回 404 的常见原因与解决方案

Spring Boot 应用返回 404 通常不是路由配置错误，而是控制器类未被 Spring 正确扫描到——最常见原因是包结构不规范，导致 @RestController 类未被组件扫描覆盖。

spring boot 应用返回 404 通常不是路由配置错误，而是控制器类未被 spring 正确扫描到——最常见原因是包结构不规范，导致 `@restcontroller` 类未被组件扫描覆盖。

在 Spring Boot 中，组件扫描（Component Scanning）默认仅作用于主启动类（@SpringBootApplication 注解所在类）所在的包及其子包。你的 PhotoController 若未位于 com.example.demo 包或其子包下（如图中显示其处于根包或平行包），Spring 启动时将完全忽略该类，即使路径 /api/photos 配置正确，请求也会因无匹配处理器而返回 404。

✅ 正确的包结构应如下：

src/main/java/com/example/demo/
├── DemoApplication.java          ← 主启动类（含 @SpringBootApplication）
├── controller/
│   └── PhotoController.java      ← 必须在此包或 com.example.demo 下任意子包中
├── model/
└── service/

⚠️ 错误示例（导致 404）：

PhotoController 在 src/main/java/PhotoController.java（默认包）
或在 src/main/java/com/example/PhotoController.java（与 demo 同级，非子包）

? 验证与修复步骤：

Spring Boot Actuator Analyzer

分析Spring Boot Actuator端点的安全性、健康检查、指标暴露及生产配置——审计信息、健康状态和自定义端点。

下载

检查主启动类位置与包声明
确保 DemoApplication.java 位于 com.example.demo 包中，且顶部声明为：

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication // 默认扫描 com.example.demo 及其子包
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

将控制器移入子包
将 PhotoController 移至 com.example.demo.controller 包，并更新包声明：

package com.example.demo.controller; // ✅ 关键：必须是 com.example.demo 的子包

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class PhotoController {
    @GetMapping(path = "/api/photos", produces = "application/json")
    public String getAll() {
        return "finito";
    }
}

可选：显式指定扫描包（仅当结构无法调整时）
若因历史原因需保留非标准包结构，可在 @SpringBootApplication 中强制指定：
```
@SpringBootApplication(scanBasePackages = {"com.example.demo", "com.otherpackage.controller"})
public class DemoApplication { ... }
```
但不推荐，违背 Spring Boot “约定优于配置”原则。

? 补充调试建议：

启动日志中搜索 Mapped，正常应看到类似输出：
Mapped "{[/api/photos],methods=[GET]}" onto public java.lang.String com.example.demo.controller.PhotoController.getAll()
若未出现，说明控制器未被扫描；
检查 IDE 是否已刷新 Maven 依赖并重新编译（尤其 IntelliJ 需右键项目 → Reload project）；
确保访问 URL 为 http://localhost:8080/api/photos（默认端口 8080，注意无多余路径前缀）。

? 总结：Spring Boot 的 404 很少源于 @GetMapping 写错，绝大多数是“类存在但 Spring 不知道它存在”。统一包层级、遵循 com.example.demo 主包约定，是避免此类问题最有效、最符合生态的做法。