深入剖析：Java 中 @RequestBody 注解的正确使用

news2024/11/20 9:53:38

在 Spring Web 开发中，@RequestBody 是一个常见而又强大的注解。它能够帮助我们轻松地将 HTTP 请求体中的 JSON 数据转换为 Java 对象，从而减少了繁琐的手工解析操作。但看似简单的注解，背后却隐藏着一些坑点和细节。今天，我们将深入探讨 @RequestBody 的使用方法和最佳实践！

一、@RequestBody 是什么？

官方解释：

@RequestBody 用于将 HTTP 请求体中的 JSON、XML 等数据，自动绑定到方法参数对应的 Java 对象上。

简单来说，它让你的控制器方法更优雅：

不用写复杂的解析逻辑。
自动完成反序列化。

常用场景

前端通过 POST 请求发送 JSON 数据。
后端通过 @RequestBody 将这些数据绑定到 Java 对象中。

二、@RequestBody 的基本使用

1. 基本例子

定义请求数据类

public class User {
    private String name;
    private int age;

    // Getter 和 Setter 方法
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }
}

定义控制器

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/users")
public class UserController {

    @PostMapping("/create")
    public String createUser(@RequestBody User user) {
        return "User " + user.getName() + " is " + user.getAge() + " years old!";
    }
}

前端发送的请求

POST /users/create
Content-Type: application/json

{
  "name": "Alice",
  "age": 25
}

后端返回的结果

User Alice is 25 years old!

三、@RequestBody 的重要特性

1. 自动反序列化

Spring 使用 Jackson（默认）或其他 JSON 库（如 Gson）将请求体中的 JSON 数据转换为 Java 对象。

2. 必须提供 Content-Type

前端必须在请求头中指定 Content-Type: application/json，否则 Spring 不知道如何处理。

3. 支持嵌套对象

如果 User 类中嵌套了另一个对象，@RequestBody 同样支持。

嵌套对象示例

public class Address {
    private String city;
    private String street;

    // Getter 和 Setter 方法
}

public class User {
    private String name;
    private int age;
    private Address address;

    // Getter 和 Setter 方法
}

JSON 请求：

{
  "name": "Bob",
  "age": 30,
  "address": {
    "city": "New York",
    "street": "5th Avenue"
  }
}

四、@RequestBody 的坑点与解决方法

1. 请求体为空时报错

如果前端发送了一个空的请求体，后端会抛出以下错误：

400 Bad Request: Required request body is missing

解决方法

可以通过设置 @RequestBody 为可选：

@PostMapping("/create")
public String createUser(@RequestBody(required = false) User user) {
    if (user == null) {
        return "Request body is empty!";
    }
    return "User " + user.getName() + " is " + user.getAge() + " years old!";
}

2. 参数校验

如果用户传递的参数不符合预期（比如 age 为负数），需要进行校验。

解决方法

可以配合 @Valid 和 @Validated 使用：

步骤 1：添加校验注解

import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotNull;

public class User {
    @NotNull(message = "Name cannot be null")
    private String name;

    @Min(value = 0, message = "Age must be non-negative")
    private int age;

    // Getter 和 Setter 方法
}

步骤 2：在控制器方法中启用校验

import org.springframework.validation.annotation.Validated;

@RestController
@RequestMapping("/users")
public class UserController {

    @PostMapping("/create")
    public String createUser(@Validated @RequestBody User user) {
        return "User " + user.getName() + " is " + user.getAge() + " years old!";
    }
}

步骤 3：全局处理校验异常

可以定义一个全局异常处理器来统一捕获校验错误：

import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public String handleValidationExceptions(MethodArgumentNotValidException ex) {
        return ex.getBindingResult()
                 .getAllErrors()
                 .get(0)
                 .getDefaultMessage();
    }
}

3. 大文件上传

@RequestBody 不适合用于上传大文件，比如图片或视频。

解决方法

对于大文件，建议使用 @RequestParam 和 MultipartFile：

@PostMapping("/upload")
public String uploadFile(@RequestParam("file") MultipartFile file) {
    return "Uploaded: " + file.getOriginalFilename();
}

4. 日志打印问题

如果请求体较大（比如 10MB），Spring 默认不会记录完整的请求内容，这对排查问题不太友好。

解决方法

使用过滤器记录完整请求体：

import org.springframework.stereotype.Component;

import javax.servlet.*;
import javax.servlet.http.HttpServletRequest;
import java.io.IOException;

@Component
public class RequestLoggingFilter implements Filter {

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        HttpServletRequest httpServletRequest = (HttpServletRequest) request;
        System.out.println("Request Body: " + httpServletRequest.getReader().lines().reduce("", String::concat));
        chain.doFilter(request, response);
    }
}