1. 注解出处
@RequestBody 是 Spring 框架 提供的注解，属于 org.springframework.web.bind.annotation 包，首次发布于 Spring 3.0 版本。它是 Spring MVC 处理 HTTP 请求体的核心注解，用于将请求体中的数据（如 JSON、XML）反序列化为后端 Java 对象，简化复杂数据结构的接收。
2. 核心功能
• 数据绑定：自动将 HTTP 请求体中的内容（如 JSON、XML）转换为 Java 对象。
• 支持多种格式：通过配置消息转换器（如 Jackson、Gson），支持 JSON、XML 等数据格式。
• 与 RESTful 结合：常用于接收前端通过 POST/PUT 请求提交的复杂数据。
3. 使用场景
• 提交表单或 JSON 数据：例如用户注册、订单创建等操作。
• 微服务间通信：服务间通过 REST API 传递复杂对象。
• 替代传统表单提交：替代 application/x-www-form-urlencoded 格式，支持嵌套数据结构。
二、用法详解与代码示例
1. 基础用法
在控制器方法的参数上添加 @RequestBody，Spring 会自动解析请求体内容到对象。
示例代码：
@RestController
@RequestMapping("/api/users")
public class UserController {
@PostMapping
public ResponseEntity
User savedUser = userService.save(user);
return ResponseEntity.ok(savedUser);
}
}
• 请求示例：
POST /api/users HTTP/1.1
Content-Type: application/json
{
"name": "Alice",
"email": "alice@example.com"
}
• 结果：将 JSON 数据转换为 User 对象，并保存到数据库。
2. 结合数据校验
配合 @Valid 注解实现自动参数校验（需引入 spring-boot-validation）。
示例代码：
@PostMapping("/validate")
public ResponseEntity
// 校验通过后才会执行此方法
return ResponseEntity.ok(userService.save(user));
}
// User 类的字段校验注解
public class User {
@NotBlank(message = "姓名不能为空")
private String name;
@Email(message = "邮箱格式错误")
private String email;
}
• 校验失败响应（HTTP 400）：
{
"timestamp": "2023-10-05T08:15:30",
"status": 400,
"error": "Bad Request",
"message":格式错误"
}
3. 处理复杂数据结构
支持嵌套对象、集合等复杂数据格式的绑定。
示例代码：
@PostMapping("/orders")
public ResponseEntity
Order order = orderService.create(request);
return ResponseEntity.ok(order);
}
//对象定义
public class OrderRequest {
private Long userId;
private List
}
public class OrderItem {
private Long productId;
private Integer quantity;
}
• 请求体示例：
{
"userId": 123,
"items": [
{ "productId": 456, "quantity": 2 },
{ "productId": 789, "quantity": 1 }
]
}
三、底层原理与关键配置
1. 消息转换器（MessageConverter）
Spring 通过 HttpMessageConverter 接口实现请求体到对象的转换。常用实现类：
• MappingJackson2HttpMessageConverter：处理 JSON 格式（需引入 jackson-databind）。
• Jaxb2RootElementHttpMessageConverter：处理 XML 格式。
配置示例（Spring Boot 默认无需配置）：
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void configureMessageConverters(List
converters.add(new MappingJackson2XmlHttpMessageConverter()); // 添加 XML 支持
}
}
2. 请求匹配规则
• Content-Type 头部：必须与消息转换器支持的媒体类型匹配（如 application/json）。
• 请求体读取：仅允许读取一次（不可重复读取），需避免在过滤器中提前消费输入流。
四、常见问题与解决方案
1. 请求体解析失败
• 错误现象：HttpMessageNotReadableException（如 JSON 字段与 Java 对象不匹配）。
• 解决方式：
• 检查字段名和类型是否一致。
• 使用 @JsonIgnoreProperties(ignoreUnknown = true) 忽略未知字段。
2. 多级嵌套对象空指针
• 错误现象：嵌套对象字段为 null。
• 解决方式：确保请求体包含完整的嵌套结构，或设置默认值：
public class OrderRequest {
private List
}
3. 大文件上传不适用
• 问题：@RequestBody 要求一次性读取整个请求体，不适合上传大文件。
• 替代方案：使用 MultipartFile 处理文件上传。
五、与其他注解的对比
注解数据来源适用场景@RequestBodyHTTP 请求体接收 JSON/XML 等复杂数据@RequestParamURL 查询参数简单参数过滤（如 ?name=Alice）@PathVariableURI 路径变量资源标识（如 /users/123）
六、总结
• 核心价值：@RequestBody 简化了复杂数据结构的接收，是 RESTful API 开发的关键注解。
• 最佳实践：
• 始终明确指定 Content-Type（如 application/json）。
• 结合 @Valid 实现自动化校验。
• 避免用于大文件或流式数据处理。
• 适用框架：Spring MVC、Spring Boot 及其他基于 Spring 的 Web 项目。