Spring Boot 请求参数绑定注解

1. @RequestBody- 处理复杂结构化数据

使用场景：接收 JSON/XML 格式的请求体

@PostMapping("/user")
public User createUser(@RequestBody @Valid User user) {
    // 直接获取前端传来的完整用户对象
    return userService.save(user);
}

特点：

• 通常与 POST、PUT 请求一起使用

• 需要设置 Content-Type: application/json

• 支持嵌套对象、列表等复杂数据结构

2. @RequestParam- 获取简单查询参数

使用场景：URL 查询参数和表单提交

@GetMapping("/search")
public List<User> searchUsers(
    @RequestParam("keyword") String keyword,
    @RequestParam(value = "page", defaultValue = "1") int page,
    @RequestParam(value = "size", required = false) Integer size
) {
    // 处理分页搜索
    return userService.search(keyword, page, size);
}

特性：

• 参数可通过 required=false设置为可选

• 支持默认值设置

• 适合 GET 请求和简单表单提交

3. @PathVariable- 获取 RESTful 路径参数

使用场景：RESTful 风格 API

@GetMapping("/users/{userId}/orders/{orderId}")
public Order getOrder(
    @PathVariable Long userId,
    @PathVariable("orderId") Long orderNo
) {
    // 获取用户ID为 userId，订单ID为 orderNo 的订单
    return orderService.findByUserAndOrder(userId, orderNo);
}

注意：路径变量是 RESTful API 设计的核心，使 URL 更加语义化。

4. @RequestHeader- 获取 HTTP 头信息

使用场景：获取认证信息、客户端信息等

@GetMapping("/profile")
public Profile getUserProfile(
    @RequestHeader("Authorization") String token,
    @RequestHeader(value = "User-Agent", required = false) String userAgent
) {
    // 验证 token 并记录客户端信息
    return userService.getProfile(token, userAgent);
}

5. @CookieValue- 获取 Cookie 值

使用场景：会话管理、用户追踪

@GetMapping("/cart")
public Cart getShoppingCart(
    @CookieValue("SESSION_ID") String sessionId,
    @CookieValue(value = "USER_TOKEN", defaultValue = "") String userToken
) {
    return cartService.getCart(sessionId, userToken);
}

6. @ModelAttribute- 传统表单绑定

使用场景：服务端渲染页面

@PostMapping("/register")
public String registerUser(@ModelAttribute UserForm form, Model model) {
    User user = userService.register(form);
    model.addAttribute("user", user);
    return "register-success"; // 返回视图名称
}

与现代前端开发的区别 ：@ModelAttribute主要用于传统 Web 应用，而 @RequestBody更适合前后端分离架构。

7. @Valid/ @Validated- 参数校验

使用场景：确保数据合法性

public class UserDTO {
    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度3-20字符")
    private String username;
    
    @Email(message = "邮箱格式不正确")
    private String email;
    
    @Min(value = 18, message = "年龄必须大于18岁")
    @Max(value = 100, message = "年龄必须小于100岁")
    private Integer age;
}

@PostMapping("/create")
public Result createUser(@RequestBody @Valid UserDTO user) {
    // 校验通过才会执行到这里
    return Result.success(userService.save(user));
}

示例

@RestController
@RequestMapping("/api/v1/users")
public class UserController {
    
    @PutMapping("/{userId}")
    public ResponseEntity<User> updateUser(
        @PathVariable Long userId,                    // 从路径获取用户ID
        @RequestHeader("Authorization") String token, // 获取认证token
        @RequestBody @Valid UpdateUserRequest request // 获取更新数据并校验
    ) {
        // 1. 验证token
        authService.validateToken(token);
        
        // 2. 更新用户信息
        User updatedUser = userService.update(userId, request);
        
        return ResponseEntity.ok(updatedUser);
    }
}

数据来源	使用注解	适用请求类型
JSON/XML 请求体	@RequestBody	POST, PUT, PATCH
URL 查询参数	@RequestParam	GET, 也可用于 POST
URL 路径变量	@PathVariable	所有类型
HTTP 请求头	@RequestHeader	所有类型
Cookie 值	@CookieValue	所有类型
传统表单	@ModelAttribute	POST（表单提交）

❌ 常见错误

1. 混淆 @RequestParam和 @PathVariable

   // 错误：期望从查询参数获取，但实际上应该用路径变量
   @GetMapping("/users/{id}")  // URL: /users/123
   public User getUser(@RequestParam Long id) { ... }  // id 应该是 null
   
   // 正确
   public User getUser(@PathVariable Long id) { ... }

2. 忘记添加 @Valid

   // 错误：校验注解不会生效
   public User create(@RequestBody UserDTO user) { ... }
   
   // 正确
   public User create(@RequestBody @Valid UserDTO user) { ... }

总结

1. @RequestBody ​ 用于复杂数据，**@RequestParam**​ 用于简单参数

2. **@PathVariable**​ 是 RESTful API 的必备

3. **@Valid**​ 是保证数据质量的守护者