Spring注解@Requestbody、@Requestparam、@PathVariable

在 Spring Boot 和 Spring MVC 的开发中，@RequestBody、@RequestParam 和 @PathVariable 是处理 HTTP 请求参数时最基础也最核心的三个注解。很多新手在前后端联调时，经常因为用错注解导致 400 报错或接收参数为 null。

为了帮你彻底搞懂它们的区别，这篇教程将从数据位置、适用场景、代码示例 以及避坑指南四个维度进行详细拆解。

一、核心区别速览表

为了让你一眼看清它们的差异，我们先通过一张表格来总结：

特性	@PathVariable	@RequestParam	@RequestBody
数据位置	URL 路径中	URL 查询字符串 (?) 或表单数据	HTTP 请求体 (Request Body)
传参格式	`/user/101`	`/user?id=101` 或表单	JSON、XML 等 (通常用 JSON)
适用请求	GET, DELETE, POST, PUT	GET, POST	POST, PUT
适用场景	获取路径中的特定资源（如ID）	分页、搜索、简单表单提交	提交复杂对象、新增/修改数据
参数数量	可以有多个	可以有多个	一个接口只能有一个

️ 二、@PathVariable：路径变量

1. 核心概念
@PathVariable 用于提取 URL 路径（Path）中的占位符数据。它是实现 RESTful 风格接口的核心注解，通常用来标识一个特定的资源。

2. 适用场景

当你需要通过 URL 直接定位到某一个具体的资源时，比如"根据 ID 查询用户"、"根据 ID 删除文档"。

3. 代码示例

后端接口定义：

复制代码

// 这里的 {id} 就是路径占位符
@GetMapping("/user/{id}")
public Result getUserById(@PathVariable("id") Long userId) {
    // userId 会接收到 URL 中 {id} 对应的值
    return Result.success("获取用户ID: " + userId);
}

前端请求地址：
GET http://localhost:8080/user/101

此时，后端接收到的 userId 就是 101。

4. 细节补充

如果方法参数名和路径占位符名称完全一致（如都叫 id），可以省略括号里的名字，直接写 @PathVariable Long id。
路径变量通常是必传的，如果缺失会报 404 错误。

三、@RequestParam：查询/表单参数

1. 核心概念
@RequestParam 用于提取 URL 问号（?）后面的查询参数，或者传统的表单（Form Data）提交的数据。

2. 适用场景

适用于参数较少、结构简单的场景，例如：分页查询、条件搜索、简单的登录表单等。

3. 代码示例

后端接口定义：

复制代码

@GetMapping("/user/page")
public Result pageUsers(
    @RequestParam(value = "current", defaultValue = "1") Integer current, // 设置默认值
    @RequestParam(value = "username", required = false) String username    // 设置为非必传
) {
    return Result.success("当前页: " + current + ", 搜索用户: " + username);
}

前端请求地址：
GET http://localhost:8080/user/page?current=2&username=zhangsan

4. 细节补充

required：默认为 true（必传）。如果设为 false，前端不传该参数时后端接收为 null。
defaultValue：如果前端没传该参数，使用指定的默认值。
如果前端提交的表单字段非常多，可以直接用一个实体类（POJO）来接收，此时不需要加 @RequestParam，Spring 会自动映射同名字段。

四、@RequestBody：请求体参数

1. 核心概念
@RequestBody 用于接收 HTTP 请求体（Request Body）中的数据。Spring 会通过消息转换器（如 Jackson）将前端传来的 JSON 或 XML 数据自动反序列化为后端的 Java 对象。

2. 适用场景

适用于参数较多、结构复杂的场景，例如：新增用户、修改资料、用户登录、传递嵌套的复杂对象等。

3. 代码示例

后端接口定义：

复制代码

@PostMapping("/user/login")
public Result login(@RequestBody User user) {
    // Spring 自动将 JSON 转为 User 对象
    return Result.success("登录用户: " + user.getUsername());
}

前端请求（JSON 格式）：

请求头必须包含：Content-Type: application/json
请求体（Body）内容：

{
"username": "zhangsan",
"password": "123456"
}

4. 细节补充

一个接口方法中，最多只能有一个 @RequestBody 注解。
默认情况下 required = true，如果请求体为空，会报 400 错误。
前端的 JSON 字段名必须与后端实体类的属性名保持一致，否则接收到的字段会是 null。

五、开发最佳实践与避坑指南

为了让你在实际开发中少走弯路，这里总结了几个核心原则和常见错误：

1. 最佳实践口诀

查单个资源（带ID） ：用 @PathVariable（如 /order/1001）。
分页、筛选、搜索 ：用 @RequestParam（如 /order/list?status=1&page=1）。
新增、修改、复杂查询 ：用 @RequestBody（传递完整的 JSON 对象）。

2. 常见避坑点

GET 请求不要用 @RequestBody ：虽然 HTTP 协议没有绝对禁止，但在实际开发中，GET 请求的标准做法是使用 @RequestParam 或 @PathVariable。使用 @RequestBody 接收 GET 请求极易导致部分网关或浏览器兼容性问题。
参数名不一致 ：前端传 user_name，后端实体类是 username，会导致接收为 null。解决办法是统一命名规范，或者在后端使用 @JsonProperty("user_name") 进行映射。
必传参数未传 ：@RequestParam 默认是必传的，如果前端漏传且后端没做非空判断，很容易引发空指针异常。建议在开发时明确哪些是必传，哪些是选传（required = false）。