一文彻底搞懂 @RequestBody 和 @RequestParam 的区别（附实战示例）

在Spring Boot开发中，@RequestBody和@RequestParam是两个最常用的参数绑定注解，它们用于处理HTTP请求中的不同数据格式。虽然它们都用于接收前端传递的参数，但使用场景和数据格式完全不同。本文将深入解析这两个注解的区别，并通过实战示例帮助开发者正确使用。

基本概念对比

@RequestParam 详解

@RequestParam用于获取URL中的查询参数，适用于GET请求或POST请求中的表单数据。

基本用法

@GetMapping("/users")
public List<User> getUsers(
    @RequestParam String name,
    @RequestParam int age,
    @RequestParam(defaultValue = "0") int page,
    @RequestParam(defaultValue = "10") int size) {
   

    return userService.findUsers(name, age, page, size);
}

参数配置

@RequestParam注解支持多个属性配置：

@RequestParam(
    value = "user_name",     // 参数名
    required = true,         // 是否必需
    defaultValue = "default" // 默认值
) String name

处理数组和列表

@RequestParam也支持接收数组和列表参数：

@GetMapping("/products")
public List<Product> getProducts(@RequestParam List<Long> ids) {
   
    return productService.findByIds(ids);
}

实战示例

@RestController
public class SearchController {
   

    @GetMapping("/search")
    public SearchResult search(
        @RequestParam(required = false) String keyword,
        @RequestParam(defaultValue = "0") int category,
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "20") int pageSize,
        @RequestParam(required = false) List<String> tags) {
   

        SearchRequest request = new SearchRequest();
        request.setKeyword(keyword);
        request.setCategory(category);
        request.setPage(page);
        request.setPageSize(pageSize);
        request.setTags(tags);

        return searchService.search(request);
    }
}

@RequestBody 详解

@RequestBody用于接收请求体中的数据，通常用于POST、PUT等方法，接收JSON或XML格式的数据。

基本用法

@PostMapping("/users")
public User createUser(@RequestBody User user) {
   
    return userService.save(user);
}

复杂对象绑定

@RequestBody可以绑定复杂的嵌套对象：

@PostMapping("/orders")
public Order createOrder(@RequestBody OrderRequest orderRequest) {
   
    return orderService.createOrder(orderRequest);
}

// OrderRequest类定义
public class OrderRequest {
   
    private String customerName;
    private String customerPhone;
    private Address deliveryAddress;
    private List<OrderItem> items;

    // getters and setters
}

集合类型处理

@RequestBody也可以处理集合类型：

@PostMapping("/batch-users")
public List<User> createUsers(@RequestBody List<User> users) {
   
    return userService.saveAll(users);
}

实战示例

@RestController
@RequestMapping("/api/orders")
public class OrderController {
   

    @PostMapping
    public ResponseEntity<OrderResponse> createOrder(@RequestBody CreateOrderRequest request) {
   
        try {
   
            Order order = orderService.createOrder(request);
            OrderResponse response = new OrderResponse();
            response.setOrderId(order.getId());
            response.setStatus("SUCCESS");
            response.setMessage("订单创建成功");

            return ResponseEntity.ok(response);
        } catch (Exception e) {
   
            return ResponseEntity.badRequest()
                .body(OrderResponse.error("订单创建失败: " + e.getMessage()));
        }
    }

    @PutMapping("/{id}")
    public ResponseEntity<Order> updateOrder(
        @PathVariable Long id, 
        @RequestBody UpdateOrderRequest request) {
   

        Order updatedOrder = orderService.updateOrder(id, request);
        return ResponseEntity.ok(updatedOrder);
    }
}

实际应用场景对比

场景一：用户注册

// 使用@RequestBody - 传递复杂用户信息
POST /api/users
Content-Type: application/json

{
   
    "username": "john",
    "email": "john@example.com",
    "password": "password123",
    "profile": {
   
        "firstName": "John",
        "lastName": "Doe",
        "age": 25
    }
}

对应的控制器方法：

@PostMapping("/api/users")
public User registerUser(@RequestBody CreateUserRequest request) {
   
    return userService.register(request);
}

场景二：用户查询

// 使用@RequestParam - 查询参数
GET /api/users?name=john&status=active&page=1&size=10

对应的控制器方法：
@GetMapping("/api/users")
public Page<User> getUsers(
    @RequestParam(required = false) String name,
    @RequestParam(required = false) String status,
    @RequestParam(defaultValue = "0") int page,
    @RequestParam(defaultValue = "10") int size) {
   

    return userService.findUsers(name, status, page, size);
}

数据格式差异

@RequestParam 数据格式

URL: /api/search?name=john&age=25&tags=java&tags=spring

在请求中，参数以键值对形式出现在URL中，多个同名参数可以传递数组值。

@RequestBody 数据格式

POST /api/search
Content-Type: application/json

{
   
    "name": "john",
    "age": 25,
    "tags": ["java", "spring"],
    "address": {
   
        "city": "Beijing",
        "district": "Haidian"
    }
}

验证和错误处理

结合验证注解

public class UserRequest {
   

    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度必须在3-20之间")
    private String username;

    @Email(message = "邮箱格式不正确")
    private String email;

    @Min(value = 18, message = "年龄不能小于18岁")
    private Integer age;

    // getters and setters
}

使用@Valid进行参数验证：

@PostMapping("/users")
public ResponseEntity<User> createUser(@Valid @RequestBody UserRequest request, BindingResult result) {
   
    if (result.hasErrors()) {
   
        List<String> errors = result.getFieldErrors().stream()
            .map(error -> error.getField() + ": " + error.getDefaultMessage())
            .collect(Collectors.toList());
        return ResponseEntity.badRequest().body(errors.toString());
    }

    User user = userService.createUser(request);
    return ResponseEntity.ok(user);
}

查询参数验证

@GetMapping("/users")
public ResponseEntity<List<User>> searchUsers(
    @RequestParam @Pattern(regexp = "^[A-Za-z0-9_]{3,20}$", message = "用户名格式不正确") 
    String username,
    @RequestParam @Min(18) @Max(100) Integer minAge) {
   

    List<User> users = userService.search(username, minAge);
    return ResponseEntity.ok(users);
}

性能考虑

@RequestParam 性能特点

• 适用于简单参数传递
• URL长度有限制（通常为2048字符）
• 参数明文显示在URL中，不适合传递敏感信息
• 便于浏览器缓存和书签

@RequestBody 性能特点

• 适合传递复杂数据结构
• 无长度限制（受服务器配置影响）
• 数据在请求体中，适合传递敏感信息
• 不能被浏览器缓存

常见错误和解决方案

错误1：在GET请求中使用@RequestBody

// 错误示例
@GetMapping("/users")
public List<User> getUsers(@RequestBody SearchCriteria criteria) {
   
    // 这样无法正常工作，GET请求没有请求体
}

// 正确做法
@GetMapping("/users")
public List<User> getUsers(
    @RequestParam(required = false) String name,
    @RequestParam(required = false) String email) {
   
    // 使用@RequestParam
}

错误2：参数类型不匹配

// 错误示例
@PostMapping("/users")
public User createUser(@RequestBody String userData) {
   
    // 直接接收为字符串，需要手动解析
}

// 正确做法
@PostMapping("/users")
public User createUser(@RequestBody User user) {
   
    // Spring Boot自动转换为User对象
}

组合使用示例

在某些场景下，可能需要同时使用@RequestBody和@RequestParam：

@PutMapping("/users/{id}")
public User updateUser(
    @PathVariable Long id,
    @RequestParam(required = false, defaultValue = "false") boolean sendNotification,
    @RequestBody UpdateUserRequest request) {
   

    return userService.updateUser(id, request, sendNotification);
}

最佳实践

1. 选择合适的注解：GET请求使用@RequestParam，POST/PUT请求使用@RequestBody
2. 参数验证：结合@Valid注解进行参数验证
3. 安全性考虑：敏感信息使用@RequestBody，避免在URL中暴露
4. 性能优化：根据数据复杂度选择合适的参数传递方式
5. 错误处理：提供良好的错误提示信息

总结

@RequestBody和@RequestParam虽然都是参数绑定注解，但它们的使用场景完全不同。@RequestParam用于处理URL查询参数，适用于简单的参数传递；@RequestBody用于处理请求体数据，适用于复杂的对象传递。正确理解它们的区别和使用场景，能够帮助开发者构建更加高效、安全的Web应用。在实际开发中，应该根据具体的业务需求和数据特点，选择最合适的参数绑定方式。