当前位置：首页 > news >正文

Spring MVC @RequestBody 注解怎么用？接收什么格式的数据？

news 来源：原创 2025/7/16 10:05:24

`@RequestBody` 注解的作用

@RequestBody 将方法上的参数绑定到 HTTP 请求的 Body（请求体）的内容上。

当客户端发送一个包含数据的请求体（通常在 POST, PUT, PATCH 请求中）时，@RequestBody 告诉 Spring MVC 读取这个请求体，并使用已注册的 HttpMessageConverter 将其内容**反序列化（Deserialize）**为一个 Java 对象。

简单来说，它允许我们直接将请求中发送的 JSON、XML 或其他格式的数据映射到一个 Java 对象（通常是一个 POJO - Plain Old Java Object）。

`@RequestBody` 的工作机制

读取请求体: Spring MVC 获取 HTTP 请求的输入流。
检查 Content-Type Header: 查看请求头中的 Content-Type，例如 application/json 或 application/xml。这个 Header 会告诉服务器客户端发送的是什么格式的数据。
选择 HttpMessageConverter: Spring MVC 会查找已注册的、能够处理该 Content-Type 的请求体内容转换为方法参数指定类型的 HttpMessageConverter。
反序列化: HttpMessageConverter 读取请求体内容，并将其转换为目标 Java 对象。
参数绑定: 转换后的 Java 对象会传递给带有 @RequestBody 注解的方法参数。

常用场景：接收 JSON 或 XML 数据

@RequestBody 最常用于接收客户端发送的 JSON 或 XML 数据，尤其是在构建 RESTful API 时。

示例：接收 JSON 数据

假设客户端发送一个 POST 请求到 /api/users，请求体包含以下 JSON 数据：

{"username": "john.doe","email": "john.doe@example.com","age": 30
}

并且请求头中设置了 Content-Type: application/json。

我们可以定义一个对应的 Java POJO：

// User.java (POJO)
public class User {private String username;private String email;private int age;// Getters and Setters (必需，供 Jackson 等库使用)public String getUsername() { return username; }public void setUsername(String username) { this.username = username; }public String getEmail() { return email; }public void setEmail(String email) { this.email = email; }public int getAge() { return age; }public void setAge(int age) { this.age = age; }@Overridepublic String toString() {return "User{" +"username='" + username + '\'' +", email='" + email + '\'' +", age=" + age +'}';}
}

然后在 Controller 中这样使用 @RequestBody：

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.http.ResponseEntity;
import org.springframework.http.HttpStatus;@RestController
@RequestMapping("/api/users")
public class UserController {@PostMappingpublic ResponseEntity<String> createUser(@RequestBody User user) {// 此时，Spring MVC 已经使用 HttpMessageConverter (通常是 Jackson)// 将请求体中的 JSON 数据转换为了一个 User 对象实例 'user'System.out.println("Received user: " + user);// 在这里可以进行保存用户等业务逻辑...// userService.save(user);return ResponseEntity.status(HttpStatus.CREATED).body("User created successfully: " + user.getUsername());}
}

所需依赖

Spring MVC 依赖 HttpMessageConverter 来实现 @RequestBody 的功能。

处理 JSON (最常用):
- 依赖库: Jackson Databind (jackson-databind) 是 Spring Boot 和 Spring MVC 处理 JSON 的默认库。
- 如何添加: 如果使用 Spring Boot，spring-boot-starter-web starter 会自动包含 jackson-databind。通常不需要手动添加它。
- Maven 示例 (如果未使用 Spring Boot Starter 或需要特定版本):
```
<dependency><groupId>com.fasterxml.jackson.core</groupId><artifactId>jackson-databind</artifactId> 
</dependency>
```
- 替代库: 虽然不常用，但也可以配置使用其他 JSON 库，如 Gson (com.google.code.gson:gson) 或 JSON-B。
处理 XML:
- 依赖库:
  - JAXB (Java Architecture for XML Binding): 这是 Java 标准库的一部分（直到 Java 10，Java 11 及以后需要单独添加依赖）。Spring 对 JAXB 有内建支持。
  - Jackson XML extension (jackson-dataformat-xml): 这是 Jackson 提供的用于处理 XML 的模块，与处理 JSON 的方式非常相似，通常更受欢迎，因为它与 Jackson 的其他功能（如注解）集成得更好。
- 如何添加 (Jackson XML): 如果你想使用 Jackson 处理 XML，需要手动添加 jackson-dataformat-xml 依赖。spring-boot-starter-web 不包含它。
- Maven 示例 (Jackson XML):
```
<dependency><groupId>com.fasterxml.jackson.dataformat</groupId><artifactId>jackson-dataformat-xml</artifactId> 
</dependency>
```
- POJO 注解: 如果使用 JAXB 或 Jackson XML，需要在 POJO 上添加特定的注解（如 @XmlRootElement, @XmlElement for JAXB，或者 Jackson 也可以使用 JAXB 注解或其自己的注解）映射 XML 结构。不过，对于简单的结构，Jackson XML 也能在没有额外注解的情况下工作。

示例：Controller 处理 XML (假设已添加 jackson-dataformat-xml)

如果客户端发送 Content-Type: application/xml 和以下 XML 请求体：

<User><username>jane.doe</username><email>jane.doe@example.com</email><age>28</age>
</User>

上面的 createUser 方法无需修改（只要 User POJO 的结构匹配），Spring MVC 会自动选择 MappingJackson2XmlHttpMessageConverter（如果 jackson-dataformat-xml 在 classpath 中）来处理请求。

关键点和注意事项

Content-Type Header: 客户端必须发送正确的 Content-Type 请求头，以便 Spring MVC 知道如何解析请求体并选择合适的 HttpMessageConverter。如果 Content-Type 不匹配或缺失，通常会导致 HTTP 415 (Unsupported Media Type) 错误。
必需性: @RequestBody 标注的参数默认是必需的。如果请求体为空或无法转换为目标类型，会抛出 HttpMessageNotReadableException，通常导致 HTTP 400 (Bad Request) 错误。
唯一性: 一个 Controller 方法只能有一个参数使用 @RequestBody 注解，因为一个 HTTP 请求只有一个请求体。
不要与 @RequestParam 混淆: @RequestParam 用于获取 URL 查询参数或表单数据（application/x-www-form-urlencoded），而 @RequestBody 用于获取整个请求体的内容（通常是 JSON 或 XML）。
Validation: 通常会结合 Java Bean Validation API (JSR 380/303) 使用 @RequestBody。通过在 @RequestBody 参数前添加 @Valid 注解，可以自动触请求体反序列化后的对象的校验。

import javax.validation.Valid;
import javax.validation.constraints.Email;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotBlank;// User.java (带校验注解)
public class User {@NotBlank(message = "Username cannot be blank")private String username;@NotBlank@Email(message = "Invalid email format")private String email;@Min(value = 0, message = "Age must be positive")private int age;// ... Getters and Setters ...
}// Controller 方法
@PostMapping
public ResponseEntity<String> createUser(@Valid @RequestBody User user) {// 如果校验失败，Spring 会自动返回 400 Bad Request// 如果校验成功，代码继续执行System.out.println("Received valid user: " + user);// ...return ResponseEntity.status(HttpStatus.CREATED).body("User created successfully: " + user.getUsername());
}

要使 @Valid 生效，需要添加 spring-boot-starter-validation 依赖（如果使用 Spring Boot）或相应的 hibernate-validator 依赖。

总结

@RequestBody 用于将 HTTP 请求的完整 Body 反序列化为一个 Java 对象。
主要用于接收 POST, PUT, PATCH 请求中的 JSON 或 XML 数据。
依赖于 HttpMessageConverter 和相应的库（如 jackson-databind for JSON，jackson-dataformat-xml or JAXB for XML）。
spring-boot-starter-web 默认包含 Jackson JSON 支持。处理 XML 需要手动添加依赖。
客户端必须发送正确的 Content-Type Header。
一个方法只能有一个 @RequestBody 参数。
常与 @Valid 结合进行自动数据校验。

@RequestBody 注解的作用

@RequestBody 的工作机制

常用场景：接收 JSON 或 XML 数据

所需依赖

关键点和注意事项

总结

相关文章：

`@RequestBody` 注解的作用

`@RequestBody` 的工作机制