@RequestBody注解-CFANZ编程社区

@RequestBody 是 Spring 框架中的一个注解，主要用于将 HTTP 请求体中的数据绑定到控制器方法的参数上。它在处理 RESTful API 时尤为重要，特别是在需要处理 JSON、XML 等格式的请求数据时。

核心作用

自动反序列化请求体
- 当客户端发送 JSON 或 XML 格式的数据时，@RequestBody 会自动将这些数据转换为 Java 对象。
- 依赖于 Spring 的消息转换器（如 MappingJackson2HttpMessageConverter）来完成转换。
处理 POST/PUT 请求
- 通常与 @PostMapping、@PutMapping 等注解配合使用，因为这些 HTTP 方法常用来提交数据。
替代手动解析请求体
- 无需手动从 HttpServletRequest 中获取输入流并解析，简化了代码。

使用示例

假设有一个 JSON 请求：

{
  "id": 1,
  "name": "示例材料",
  "quantity": 100
}

后端控制器可以这样处理：

@PostMapping("/materials")
public ResponseEntity<?> createMaterial(@RequestBody Material material) {
    // material 对象已自动填充请求体中的数据
    materialService.save(material);
    return ResponseEntity.ok().build();
}

对应的实体类：

public class Material {
    private Long id;
    private String name;
    private Integer quantity;
    
    // 必须有默认构造函数和 getter/setter
    public Material() {}
    
    // getters and setters
}

关键注意事项

请求头必须正确设置
- 客户端需要设置 Content-Type 头，例如：
  - application/json 对应 JSON 数据
  - application/xml 对应 XML 数据
方法参数类型限制
- @RequestBody 只能用于方法的参数，不能用于字段或类。
处理复杂对象
- 支持嵌套对象、集合等复杂结构，只要 JSON 格式与 Java 类结构匹配。
异常处理
- 如果请求体格式不匹配（如 JSON 字段与 Java 类字段不一致），会抛出 HttpMessageNotReadableException。

常见错误场景

忘记添加 @RequestBody
- 若省略该注解，Spring 会尝试从请求参数（URL 参数）中绑定数据，而非请求体。
请求体为空
- 若接口标注了 @RequestBody，但客户端未发送请求体，会抛出 400 Bad Request。
JSON 与 Java 类结构不匹配
- 例如：Java 类中有 username 字段，但 JSON 中是 userName（大小写不一致）。

与其他注解的对比

注解	数据来源	适用场景
`@RequestBody`	HTTP 请求体	处理 JSON/XML 等格式的请求
`@RequestParam`	URL 参数（如 `?id=1`）	处理简单参数（GET 请求）
`@PathVariable`	URL 路径变量（如 `/user/{id}`）	RESTful 路径参数