【SpringMVC笔记】 - 2 - @RequestMapping

1. RequestMapping 的作用

@RequestMapping 注解是 Spring MVC 框架中的控制器映射注解，用于将请求映射到相应的处理方法上。具体来说，它可以将指定 URL 的请求绑定到一个特定的方法或类上，从而实现对请求的处理和响应。

2. RequestMapping 的出现位置

通过查看 @RequestMapping 的源码可以看到，该注解只能出现在类上或者方法上。

3. 类上与方法上结合使用

3.1 映射唯一性问题

在同一个 web 应用中，RequestMapping 必须具有唯一性，否则会出现 "不明确的映射" 异常。

错误示例：

java 复制代码

@Controller
public class UserController {
    @RequestMapping("/detail")
    public String toDetail(){
        return "detail";
    }
}

@Controller
public class ProductController {
    @RequestMapping("/detail")
    public String toDetail(){
        return "detail";
    }
}

异常信息：

text 复制代码

org.springframework.beans.factory.BeanCreationException: 
Error creating bean with name 'org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping': 
Ambiguous mapping. Cannot map 'userController' method 
com.zzz.springmvc.controller.UserController#toDetail()
to { [/detail]}: There is already 'productController' bean method
com.zzz.springmvc.controller.ProductController#toDetail() mapped.

3.2 解决方案一：修改方法级路径

将方法上 @RequestMapping 的映射路径修改为不同的值：

java 复制代码

// UserController
@RequestMapping("/user/detail")
public String toDetail(){
    return "/user/detail";
}

// ProductController
@RequestMapping("/product/detail")
public String toDetail(){
    return "/product/detail";
}

对应的视图页面：

/user/detail.html
/product/detail.html

首页链接：

html 复制代码

<!DOCTYPE html>
<html lang="en" xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>index page</title>
</head>
<body>
    <h1>index page</h1>
    <a th:href="@{/user/detail}">用户详情</a><br>
    <a th:href="@{/product/detail}">商品详情</a><br>
</body>
</html>

3.3 解决方案二：类上添加命名空间

在类上和方法上都使用 @RequestMapping 注解，类上的路径作为命名空间，方法上的路径作为子路径。最终的完整路径是：类路径 + 方法路径。

java 复制代码

@Controller
@RequestMapping("/user")
public class UserController {
    @RequestMapping("/detail")
    public String toDetail(){
        return "/user/detail";
    }
}

@Controller
@RequestMapping("/product")
public class ProductController {
    @RequestMapping("/detail")
    public String toDetail(){
        return "/product/detail";
    }
}

这种方式可以避免在每个方法路径前都重复相同的前缀，使代码更加简洁。

4. RequestMapping 注解的 value 属性

4.1 value 属性的基本使用

value 属性是 @RequestMapping 注解最核心的属性，用于指定请求路径。value 属性是一个字符串数组 ，这意味着多个不同的请求路径可以映射到同一个控制器方法。

java 复制代码

@Controller
public class RequestMappingTestController {
    @RequestMapping(value = {"/testValue1", "/testValue2"})
    public String testValue(){
        return "testValue";
    }
}

首页链接：

html 复制代码

<a th:href="@{/testValue1}">testValue1</a><br>
<a th:href="@{/testValue2}">testValue2</a><br>

点击这两个链接都会访问到同一个 testValue() 方法。

4.2 Ant 风格的 value（模糊匹配）

value 属性支持 Ant 风格的模糊匹配，使用以下通配符：

通配符	说明
`?`	代表任意一个字符
`*`	代表0 到 N 个任意字符（不能包含路径分隔符 `/`）
`**`	代表0 到 N 个任意字符，并且可以包含路径分隔符 `/`

注意：

** 通配符在使用时，左右不能出现其他字符，只能是 /
Spring6 中严格规定 ：** 通配符只能出现在路径的末尾

示例：

java 复制代码

// 匹配 /xyz/testValueAnt、/xaz/testValueAnt 等
@RequestMapping("/x?z/testValueAnt")
public String testValueAnt(){
    return "testValueAnt";
}

// 匹配 /xz/testValueAnt、/xyz/testValueAnt、/xyzzz/testValueAnt 等
@RequestMapping("/x*z/testValueAnt")
public String testValueAnt(){
    return "testValueAnt";
}

// 匹配 /testValueAnt、/a/testValueAnt、/a/b/testValueAnt 等
@RequestMapping("/**/testValueAnt") // Spring5支持，Spring6不支持
public String testValueAnt(){
    return "testValueAnt";
}

// Spring6正确写法：**只能在末尾
@RequestMapping("/testValueAnt/**")
public String testValueAnt(){
    return "testValueAnt";
}

4.3 value 中的占位符（RESTful 风格）

RESTful 风格的请求路径将参数直接嵌入到 URL 中，格式为：uri/value1/value2/value3，而不是传统的 uri?name1=value1&name2=value2。

传统请求路径 ：http://localhost:8080/springmvc/login?username=admin&password=123&age=20

RESTful 请求路径 ：http://localhost:8080/springmvc/login/admin/123/20

在 SpringMVC 中，可以使用 {} 占位符来接收 RESTful 风格的参数，并通过 @PathVariable 注解将参数绑定到方法参数上。

java 复制代码

@RequestMapping(value="/testRESTful/{id}/{username}/{age}")
public String testRESTful(
    @PathVariable("id") int id,
    @PathVariable("username") String username,
    @PathVariable("age") int age){
    
    System.out.println(id + "," + username + "," + age);
    return "testRESTful";
}

首页链接：

html 复制代码

<a th:href="@{/testRESTful/1/zhangsan/20}">测试value属性使用占位符</a>

5. RequestMapping 注解的 method 属性

5.1 method 属性的作用

method 属性用于限制客户端的请求方式，只有当客户端发送的请求方式与 method 属性指定的方式一致时，才能成功映射到对应的方法。

如果请求方式不匹配，会返回 HTTP 405 错误（方法不允许）。

method 属性是一个 RequestMethod 枚举类型的数组，可以指定多个请求方式。

java 复制代码

// 只接受POST请求
@RequestMapping(value = "/login", method = RequestMethod.POST)
public String login(){
    return "success";
}

// 同时接受GET和POST请求
@RequestMapping(value = "/login", method = {RequestMethod.GET, RequestMethod.POST})
public String login(){
    return "success";
}

5.2 衍生 Mapping 注解

SpringMVC 提供了更简洁的衍生注解，专门用于处理特定的 HTTP 请求方式：

注解	等价于	说明
`@GetMapping`	`@RequestMapping(method = RequestMethod.GET)`	处理 GET 请求
`@PostMapping`	`@RequestMapping(method = RequestMethod.POST)`	处理 POST 请求
`@PutMapping`	`@RequestMapping(method = RequestMethod.PUT)`	处理 PUT 请求
`@DeleteMapping`	`@RequestMapping(method = RequestMethod.DELETE)`	处理 DELETE 请求
`@PatchMapping`	`@RequestMapping(method = RequestMethod.PATCH)`	处理 PATCH 请求

示例：

java 复制代码

// 等价于 @RequestMapping(value="/login", method = RequestMethod.POST)
@PostMapping("/login")
public String testMethod(){
    return "testMethod";
}

5.3 Web 的 9 种请求方式

HTTP 协议定义了 9 种请求方式，前 5 种较为常用：

GET：获取资源，只读取数据，不修改服务器状态。参数放在 URL 中。
POST：向服务器提交资源，可能修改服务器状态。参数放在请求体中。
PUT：更新资源，用于替换指定资源的全部内容。
DELETE：删除指定的资源。
HEAD：与 GET 类似，但只返回响应头，不返回响应体。用于资源检测和缓存控制。
PATCH：部分更新资源，只更新资源的部分内容。
OPTIONS：查询服务器支持的请求方法。
TRACE：回显服务器收到的请求，用于调试。
CONNECT：建立网络连接，通常用于 HTTPS。

重要注意事项：

超链接和原生 HTML 表单只能发送 GET 和 POST 请求
即使在 form 表单中设置 method="put" 或 method="delete"，浏览器仍然会以 GET 方式发送请求
要发送 PUT、DELETE 等请求，需要使用 AJAX

5.4 GET 和 POST 的区别

5.4.1 核心区别

特性	GET	POST
参数位置	放在 URL 中，会显示在地址栏	放在请求体中，不会显示在地址栏
数据类型	只能发送普通字符串	可以发送任何类型的数据（文本、文件等）
数据长度	有限制（不同浏览器不同）	理论上无限制
安全性	相对不安全（参数可见）	相对安全（参数不可见）
用途	从服务器获取数据	向服务器提交数据
缓存	支持缓存	不支持缓存
书签	可以收藏为书签	不可以收藏为书签
历史记录	会保存在浏览器历史记录中	不会保存在浏览器历史记录中

5.4.2 如何选择

使用 GET：当你需要从服务器获取数据，且不修改服务器状态时
使用 POST ：
- 向服务器提交数据（如表单提交）
- 提交敏感信息（如密码）
- 上传文件
- 数据量较大时

6. RequestMapping 注解的 params 属性

6.1 params 属性的理解

params 属性用于通过请求参数来映射请求。只有当客户端发送的请求参数满足 params 属性指定的所有条件时，才能成功映射到对应的方法。

注意：

value 和 method 是 "或" 的关系（满足数组中任意一个即可）
params 是 "与" 的关系（必须满足数组中所有条件）

如果请求参数不匹配，会返回 HTTP 400 错误（请求参数格式不正确）。

6.2 params 属性的 4 种用法

java 复制代码

// 1. 请求参数必须包含username和password
@RequestMapping(value="/login", params={"username", "password"})

// 2. 请求参数不能包含username，但必须包含password
@RequestMapping(value="/login", params={"!username", "password"})

// 3. 请求参数必须包含username且值为admin，同时必须包含password
@RequestMapping(value="/login", params={"username=admin", "password"})

// 4. 请求参数必须包含username但值不能为admin，同时必须包含password
@RequestMapping(value="/login", params={"username!=admin", "password"})

6.3 测试 params 属性

java 复制代码

@RequestMapping(value="/testParams", params = {"username", "password"})
public String testParams(){
    return "testParams";
}

首页链接：

html 复制代码

<!-- 正确写法（Thymeleaf推荐） -->
<a th:href="@{/testParams(username='admin',password='123')}">测试params属性</a>

<!-- 也可以这样写（IDEA可能会报错，但不影响运行） -->
<a th:href="@{/testParams?username=admin&password=123}">测试params属性</a>

如果缺少 username 参数，会返回 400 错误。

7. RequestMapping 注解的 headers 属性

7.1 认识 headers 属性

headers 属性与 params 属性原理和用法相同，不同之处在于：

params 检查的是请求参数
headers 检查的是请求头信息

只有当客户端发送的请求头信息满足 headers 属性指定的所有条件时，才能成功映射到对应的方法。

如果请求头不匹配，会返回 HTTP 404 错误（资源未找到）。

7.2 headers 属性的 4 种用法

java 复制代码

// 1. 请求头必须包含Referer和Host
@RequestMapping(value="/login", headers={"Referer", "Host"})

// 2. 请求头必须包含Referer，但不包含Host
@RequestMapping(value="/login", headers={"Referer", "!Host"})

// 3. 请求头必须包含Referer且值为指定URL，同时必须包含Host
@RequestMapping(value="/login", headers={"Referer=http://localhost:8080/springmvc/", "Host"})

// 4. 请求头必须包含Referer但值不能为指定URL，同时必须包含Host
@RequestMapping(value="/login", headers={"Referer!=http://localhost:8080/springmvc/", "Host"})

7.3 测试 headers 属性

java 复制代码

@RequestMapping(value="/testHeaders", headers = {"Referer=http://localhost:8080/springmvc/"})
public String testHeaders(){
    return "testHeaders";
}

首页链接：

html 复制代码

<a th:href="@{/testHeaders}">测试headers属性</a>

如果将 Referer 的值修改为其他值（如http://localhost:8888/springmvc/），则会返回 404 错误。

常见 HTTP 状态码总结

一、20x 成功类

请求已被服务器成功接收、理解并处理。

状态码	英文名称	说明
200	OK	请求成功，是最常用的状态码，正常返回响应数据
201	Created	请求成功，服务器已创建新资源（多用于新增接口 POST/PUT）
202	Accepted	服务器已接受请求，但尚未处理完成（异步任务常用）
204	No Content	请求成功，但无响应体返回（多用于删除、修改操作）
206	Partial Content	部分请求成功，多用于断点续传、分片下载

二、30x 重定向类

需要客户端进一步操作才能完成请求，一般是地址跳转。

状态码	英文名称	说明
301	Moved Permanently	永久重定向，旧地址废弃，浏览器会缓存新地址
302	Found	临时重定向，本次跳转，下次仍可使用原地址
303	See Other	可通过 GET 获取资源，常用于表单提交后跳转
304	Not Modified	资源未修改，直接使用客户端缓存，无需重新传输
307	Temporary Redirect	临时重定向，会保留原请求方法（不会把 POST 转为 GET）
308	Permanent Redirect	永久重定向，保留原请求方法

三、4xx 客户端错误类

请求语法、参数、权限等存在问题，服务器无法处理。

状态码	英文名称	说明
400	Bad Request	请求参数错误、格式不合法，SpringMVC 中 params 不匹配
401	Unauthorized	未认证，需要登录 / 身份验证才能访问
403	Forbidden	服务器拒绝访问，权限不足，与登录无关
404	Not Found	请求资源不存在，路径错误或页面已删除
405	Method Not Allowed	请求方式不允许，如接口只支持 POST 却用 GET 访问
406	Not Acceptable	请求的格式不支持，如只返回 JSON 却要求 XML
415	Unsupported Media Type	不支持的媒体类型，如接口只接收 JSON 却传了表单
429	Too Many Requests	请求过于频繁，触发限流

四、50x 服务器错误类

服务器自身出现异常，无法完成正常请求处理。

状态码	英文名称	说明
500	Internal Server Error	服务器内部错误，代码异常、空指针、运行时异常
501	Not Implemented	服务器不支持该请求功能
502	Bad Gateway	网关错误，服务器作为网关收到无效响应
503	Service Unavailable	服务不可用，服务器过载、维护、停机
504	Gateway Timeout	网关超时，上游服务器未及时响应

@RequestMapping 注解核心知识点总结

@RequestMapping 是 Spring MVC 实现请求与控制器方法映射的核心注解，本章围绕其使用规则、核心属性及配套知识点展开，核心总结如下：

一、核心定位与使用约束

作用：将指定 URL 请求绑定到控制器类 / 方法，是请求处理的核心映射入口。
使用位置：仅可标注在类或方法上；类上路径作为 "命名空间"，方法上路径作为 "子路径"，最终映射路径为「类路径 + 方法路径」，可避免路径前缀重复，提升代码简洁性。
唯一性约束：同一 Web 应用中映射路径必须唯一，否则会抛出 "不明确的映射" 异常，可通过为不同控制器添加路径前缀（类级别）或修改方法路径解决。

二、核心属性详解

1. value 属性（请求路径）

核心作用：指定映射的请求路径，支持字符串数组（多个路径映射同一方法）。
高级用法：
- Ant 风格模糊匹配：?（单个任意字符）、*（0-N 个非 / 字符）、**（0-N 个含 / 字符，Spring6 要求仅能出现在路径末尾）；
- RESTful 风格：通过 {占位符} 嵌入参数，配合 @PathVariable 绑定到方法参数，简化参数传递（替代传统 ?key=value 格式）。

2. method 属性（请求方式）

作用：限制请求的 HTTP 方法，不匹配则返回 405 错误（方法不允许）；支持数组格式，可指定多个允许的请求方式。
简化注解：SpringMVC 提供 @GetMapping/@PostMapping/@PutMapping 等衍生注解，替代 method 属性的繁琐写法。
关键注意：超链接 / 原生 HTML 表单仅支持 GET/POST，PUT/DELETE 需通过 AJAX 实现；GET（查）与 POST（增 / 改 / 提交敏感数据）需根据场景合理选择。

3. params 属性（请求参数）

作用：通过请求参数规则过滤请求，不满足则返回 400 错误（请求参数错误）；支持 "包含 / 不包含 / 等于 / 不等于" 四种规则，且需满足所有规则（与关系）。

4. headers 属性（请求头）

作用：通过请求头信息过滤请求，不满足则返回 404 错误（资源未找到）；用法与 params 完全一致，仅校验目标为请求头（如 Referer、Host 等）。

三、配套核心知识点：HTTP 状态码

需重点掌握与 @RequestMapping 相关的状态码：

400：params 属性不匹配、请求参数格式错误；
404：headers 属性不匹配、请求路径错误；
405：method 属性指定的请求方式不匹配；
200：请求映射成功，正常响应。

四、核心设计思想

/ 原生 HTML 表单仅支持 GET/POST，PUT/DELETE 需通过 AJAX 实现；GET（查）与 POST（增 / 改 / 提交敏感数据）需根据场景合理选择。

3. params 属性（请求参数）

作用：通过请求参数规则过滤请求，不满足则返回 400 错误（请求参数错误）；支持 "包含 / 不包含 / 等于 / 不等于" 四种规则，且需满足所有规则（与关系）。

4. headers 属性（请求头）

作用：通过请求头信息过滤请求，不满足则返回 404 错误（资源未找到）；用法与 params 完全一致，仅校验目标为请求头（如 Referer、Host 等）。

三、配套核心知识点：HTTP 状态码

需重点掌握与 @RequestMapping 相关的状态码：

400：params 属性不匹配、请求参数格式错误；
404：headers 属性不匹配、请求路径错误；
405：method 属性指定的请求方式不匹配；
200：请求映射成功，正常响应。

四、核心设计思想

@RequestMapping 通过 "路径 + 方法 + 参数 + 请求头" 的多维度匹配，实现了请求到方法的精准映射，既支持灵活的路径匹配（Ant/RESTful），也通过严格的约束（唯一性、参数 / 请求头校验）保证请求处理的准确性，是 Spring MVC 实现 "约定优于配置" 的核心体现，合理使用可大幅提升控制器代码的规范性和可维护性。