Spring MVC 404 'No mapping found' 错误排查指南

1. 引言

Spring MVC 是基于前端控制器（Front Controller）模式构建的经典 Web 框架。其中，DispatcherServlet 作为核心的前端控制器，负责请求的分发与处理流程。

和所有 Web 应用一样，当请求的资源无法找到时，Spring MVC 会返回 HTTP 404 状态码。但有时候，明明写了接口，却始终返回 404，让人一头雾水。

本文聚焦于 Spring MVC 中 404 “No mapping found” 错误的常见原因和解决方案，帮你快速定位问题，少走弯路。

2. 404 响应的常见原因

2.1 URI 路径错误 ✅

这是最直观也最常见的 404 原因——请求路径写错了。

假设我们有一个 GreetingController，映射路径为 /greeting，返回 greeting.jsp 视图：

@Controller
public class GreetingController {

    @RequestMapping(value = "/greeting", method = RequestMethod.GET)
    public String get(ModelMap model) {
        model.addAttribute("message", "Hello, World!");
        return "greeting";
    }
}

对应的 JSP 视图文件 greeting.jsp 内容如下：

<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<html>
    <head>
        <title>Greeting</title>
    </head>
    <body>
        <h2>${message}</h2>
    </body>
</html>

此时，发起 GET 请求访问 /greeting 是正常的：

curl http://localhost:8080/greeting

返回内容为：

<html>
    <head>
        <title>Greeting</title>
    </head>
    <body>
        <h2>Hello, World!</h2>
    </body>
</html>

但如果你手一抖，把路径写成了 /greetings：

curl http://localhost:8080/greetings

服务器日志就会出现警告：

[http-nio-8080-exec-6] WARN  o.s.web.servlet.PageNotFound - 
  No mapping found for HTTP request with URI [/greetings] in DispatcherServlet with name 'mvc'

客户端则收到 404 页面：

<html>
    <head>
        <title>Home</title>
    </head>
    <body>
        <h1>Http Error Code : 404. Resource not found</h1>
    </body>
</html>

⚠️ 踩坑提示：这种错误通常发生在路径拼写、大小写、复数形式等细节上。建议使用 Swagger 或 Postman 等工具固化接口路径，避免手动输入出错。

2.2 DispatcherServlet 映射配置错误 ❌

DispatcherServlet 是 Spring MVC 的入口，必须在 web.xml 中正确配置其映射路径。

常见错误是将 url-pattern 配置为 /*（带星号）：

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee 
         http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
         version="3.1">
    
    <servlet>
        <servlet-name>mvc</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    
    <servlet-mapping>
        <servlet-name>mvc</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
    
</web-app>

此时，即使访问正确的 /greeting 接口：

curl http://localhost:8080/greeting

日志中会出现如下警告：

WARN  o.s.web.servlet.PageNotFound - No mapping found for HTTP request with URI 
  [/WEB-INF/view/greeting.jsp] in DispatcherServlet with name 'mvc'

页面显示为空白，或者直接 404。

❌ 问题根源：
当 url-pattern 设置为 /* 时，所有请求（包括静态资源、JSP 文件等）都会被 DispatcherServlet 拦截。而 DispatcherServlet 本身并不知道如何处理 JSP 文件，它需要依赖 ViewResolver 来解析视图。但由于请求被错误地再次转发到 /WEB-INF/view/greeting.jsp，而这个路径并没有对应的 Controller 映射，最终导致 404。

✅ 正确做法：
应将 DispatcherServlet 映射到 /（根路径，不带星号）：

<servlet-mapping>
    <servlet-name>mvc</servlet-name>
    <url-pattern>/</url-pattern>
</servlet-mapping>

这样，DispatcherServlet 会处理所有“无后缀”或“符合 MVC 路由规则”的请求，而静态资源（如 .jsp, .css, .js）则由容器默认的 DefaultServlet 处理，避免冲突。

修复后，再次请求 /greeting：

curl http://localhost:8080/greeting

返回正常：

<html>
    <head>
        <title>Greeting</title>
    </head>
    <body>
        <h2>Hello, World!</h2>
    </body>
</html>

📌 总结对比：

配置方式	`url-pattern`	行为	是否推荐
`/*`	拦截所有请求	JSP 被错误转发，导致 404	❌ 不推荐
`/`	拦截根路径请求	MVC 正常处理，静态资源由容器处理	✅ 推荐

3. 总结

本文梳理了 Spring MVC 中 404 “No mapping found” 错误的两个高频原因：

✅ URI 路径错误：检查请求路径是否与 @RequestMapping 完全匹配，注意大小写和拼写。
✅ DispatcherServlet 映射错误：确保 web.xml 中的 url-pattern 配置为 /，而非 /*，避免请求被错误拦截。

这两个问题看似简单，但在实际项目中极易踩坑，尤其是老项目维护或从零搭建时。建议开发时开启 DEBUG 日志，观察 DispatcherServlet 的 dispatch 流程，能更快定位问题。

示例代码已托管至 GitHub：https://github.com/baeldung/spring-web-modules/tree/master/spring-mvc-xml-2

Persistence

REST

Security

1. 引言

2. 404 响应的常见原因

2.1 URI 路径错误 ✅

2.2 DispatcherServlet 映射配置错误 ❌

3. 总结