Spring项目启动成功但访问接口报404错误是什么原因？

在Spring项目的开发旅程中,HTTP 404 Not Found错误无疑是开发者最常遇到的“拦路虎”之一，它明确地告诉客户端：服务器无法找到你所请求的资源，尽管错误信息简洁，但其背后的原因却千差万别，足以让初学者甚至有经验的开发者感到困惑，本文旨在系统性地梳理Spring项目中导致404错误的常见原因，并提供一套行之有效的排查思路，帮助你快速定位并解决问题。

URL路径与请求基础问题

这是最直观也最容易被忽视的一类问题,在深入代码之前，首先应确保你的请求本身是正确的。

• URL拼写错误或大小写敏感：检查浏览器地址栏中的URL是否存在拼写错误，更重要的是，Spring的@RequestMapping默认是区分大小写的，/user/list和/User/List是两个完全不同的路径。
• 端口号错误：确认你的应用服务器（如Tomcat）运行在哪个端口上，Spring Boot默认端口是8080，但如果在application.properties中修改过，或者使用外部服务器，就必须使用正确的端口号。
• 项目上下文路径（Context Path）问题：如果你的项目部署在一个特定的上下文路径下（打包成WAR包部署到Tomcat时，应用名称为my-spring-app），那么所有请求都必须带上此前缀，正确的URL应该是http://localhost:8080/my-spring-app/your/api/path，在Spring Boot中，可以通过server.servlet.context-path来配置它。

为了更清晰地展示,可以参考下表：

常见现象	可能原因	排查方向
访问 localhost:8080/api/... 失败	请求URL与Controller映射路径不匹配	仔细核对Controller中的@RequestMapping注解，注意大小写和斜杠。
应用已启动，但任何请求都404	端口号或上下文路径错误	查看控制台启动日志，确认Tomcat监听的端口和Context Path。
Postman请求成功，浏览器404	浏览器缓存或URL拼写错误	清除浏览器缓存，或使用无痕模式，仔细检查URL。

控制器注解与配置问题

当确认URL无误后,问题通常出在Spring MVC的核心组件——控制器上。

• 缺少核心注解：确保你的处理类上添加了@Controller或@RestController注解，前者用于返回视图（如JSP），后者通常用于返回JSON/XML等数据，如果没有这个注解，Spring容器将不会识别它为一个处理器，自然无法处理请求。
• 映射注解缺失或错误：处理方法上必须使用@RequestMapping、@GetMapping、@PostMapping等注解来定义其所能处理的URL路径，检查这些注解的value或path属性是否与你的请求意图相符。
• 组件扫描范围不正确：Spring需要通过组件扫描（@ComponentScan）来发现并注册带有注解的Bean，如果你的Controller类所在的包没有被Spring Boot主启动类（带有@SpringBootApplication注解的类）扫描到，那么这个Controller就不会生效，默认情况下，@SpringBootApplication会扫描其所在包及其所有子包，如果Controller位于其他平级或更上层的包中，需要在主启动类上手动配置@ComponentScan。

视图解析器配置问题（针对MVC项目）

如果你开发的是传统的Spring MVC项目，而非前后端分离的RESTful API，那么404也可能与视图有关。

• 视图解析器未配置：对于返回字符串（视图名）的Controller方法，Spring需要一个ViewResolver来将逻辑视图名（如"user/detail"）解析为实际的物理视图资源（如/WEB-INF/views/user/detail.jsp），如果缺少InternalResourceViewResolver等视图解析器的配置，Spring就不知道去哪里找这个文件。
• 视图文件不存在或路径错误：确认视图解析器配置的前缀（prefix）和后缀（suffix）与你的实际文件存放路径和文件名完全匹配，配置为prefix="/WEB-INF/views/", suffix=".jsp"，那么返回"index"时，就必须在/WEB-INF/views/目录下存在index.jsp文件。

系统化排查流程

面对404错误,切忌盲目尝试，应遵循一套系统化的排查流程：

1. 确认基础信息：检查服务器是否正常启动，有无报错，在浏览器开发者工具的Network面板中查看请求的URL、方法和状态码，确保请求本身无误。
2. 检查Controller层：定位到目标Controller类，确认@Controller/@RestController注解存在，再检查处理方法上的@GetMapping等映射注解，确保其路径、方法（GET/POST等）与请求一致。
3. 验证组件扫描：确认Controller类所在的包是否在Spring Boot主启动类的扫描范围内，可以在主启动类上通过@ComponentScan("com.yourpackage.controllers")明确指定。
4. 审查启动日志：Spring Boot启动时会打印出所有映射的端点信息，例如Mapped "{[/user/list],methods=[GET]}" ...，仔细检查控制台日志，看你的API路径是否被成功映射，如果没有，说明Spring根本没有识别到你的处理方法。

---

相关问答 (FAQs)

Q1: 我的Controller类、注解和URL路径都检查过了，完全正确，为什么还是404？

A: 这是一个非常经典的问题，通常指向“组件扫描”的陷阱，请确认你的Controller类所在的包路径是否被@SpringBootApplication注解所在的启动类扫描到，你的启动类在com.example.app包下，它能自动扫描com.example.app.controller、com.example.app.service等子包，但如果你的Controller放在了com.example.other包下，它就不会被扫描，解决方法有两种：一是调整包结构，将Controller移到启动类的子包下；二是在启动类上显式添加@ComponentScan(basePackages = {"com.example.app", "com.example.other"})来扩大扫描范围。

Q2: 在Spring Boot项目中，为什么我的静态资源（如CSS、JavaScript、图片）访问不到，返回404？

A: Spring Boot对静态资源有一套默认的约定，它会自动从classpath下的以下几个目录中提供静态资源：/static、/public、/resources和/META-INF/resources，请检查你的静态文件是否放置在了这些目录中的任意一个，如果你有一个style.css文件，它应该位于src/main/resources/static/style.css，这样，你就可以直接通过http://localhost:8080/style.css访问它，如果文件放在了其他位置（如/templates），Spring Boot默认不会将其作为静态资源暴露，需要额外配置静态资源映射。