Spring 控制器参数注解

在 Java Spring（特别是 Spring MVC 和 Spring Boot）中，控制器方法的参数注解用于绑定请求数据（如 URL 参数、表单数据、JSON 等）到方法参数。以下是常见的参数注解及其区别的详细解析。

1. 核心参数注解列表

注解	作用域	主要用途	支持的请求类型
@RequestParam	方法参数	获取 URL 查询参数或表单数据	GET/POST (表单/查询参数)
@PathVariable	方法参数	从 URL 路径中提取变量	所有 HTTP 方法
@RequestBody	方法参数	解析 HTTP 请求体（如 JSON/XML）	POST/PUT/PATCH (Body)
@ModelAttribute	方法参数/方法声明	绑定请求参数到对象（表单/查询参数）	GET/POST (表单/查询参数)
@RequestHeader	方法参数	获取 HTTP 请求头字段	所有 HTTP 方法
@CookieValue	方法参数	获取 Cookie 值	所有 HTTP 方法
@SessionAttribute	方法参数	从会话（Session）中读取属性	所有 HTTP 方法
@RequestPart	极速方法参数	处理文件上传（multipart/form-data）	POST (文件上传)

2. 注解详解与对比

（1）@RequestParam

• 用途：获取 URL 查询参数 或 表单数据（application/x-www-form-urlencoded）。
• 示例：

  
  @GetMapping("/user")public String getUser(@RequestParam("id") Long userId) {return "User ID: " + userId;}
  

• 请求 /user?id=123 时，userId 值为 123。
• 关键特性：
• 默认必传（可通过 required = false 设为可选）。
• 支持默认值（defaultValue = "0"）。
• 若参数名与方法参数名一致，可省略注解值（@RequestParam Long id）。

（2）@PathVariable

• 用途：从 URL 路径模板 中提取变量。
• 示例：

  
  @GetMapping("/user/{id}")public String getUser(@PathVariable("id") Long userId) {return "User ID: " + userId;}
  

• 请求 /user/123 时，userId 值为 123。
• 关键特性：
• 必须与 @GetMapping 等映射注解中的路径变量名匹配。
• 支持可选路径变量（需结合 required = false）。

（3）@RequestBody

• 用途：解析 HTTP 请求体（如 JSON、XML）为 Java 对象。
• 示例：

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

• 请求体 {"name": "Alice", "age": 25} 会被转换为 极速User 对象。
• 关键特性：
• 通常与 @RestController 或 @ResponseBody 配合使用。
• 依赖 HttpMessageConverter（如 MappingJackson2HttpMessageConverter 处理 JSON）。

（4）@ModelAttribute

• 用途：
• 方法参数：自动绑定表单/查询参数到对象（非 JSON）。
• 方法声明：在控制器方法调用前初始化模型属性。
• 示例：

  
  @PostMapping("/user")public String saveUser(@ModelAttribute User user) {// user 的属性自动从表单或查询参数填充return "success";}
  

• 请求 /user?name=Alice&age=25 时，User 对象的 name 和 age 被自动赋值。
• 关键特性：
• 支持级联绑定（如 user.address.city）。
• 与 Thymeleaf 等模板引擎配合时，可自动填充模型数据。

（5）@RequestHeader

• 用途：获取 HTTP 请求头 的值。
• 示例：

  
  @GetMapping("/info")public String getInfo(@RequestHeader("User-Agent") String userAgent) {return "User Agent: " + userAgent;}
  

• 关键特性：
• 支持默认极速值（defaultValue）。
• 可绑定到 Map 获取所有请求头：

  
  public void handle(@RequestHeader Map<String, String> headers)
  

（6）@CookieValue

• 用途：获取 Cookie 的值。
• 示例：

  
  @GetMapping("/cookie")public String readCookie(@CookieValue("JSESSIONID") String sessionId) {return "Session ID: " + sessionId;}
  

（7）@SessionAttribute

• 用途：从 HTTP 会话（Session） 中读取属性。
• 示例：

  
  @GetMapping("/profile")public String profile(@SessionAttribute("user") User user极速) {return "Profile: " + user.getName();}
  

• 需确保会话中已存在 user 属性（如通过 @SessionAttributes 声明）。

（8）@RequestPart

• 用途：处理 文件上传（multipart/form-data）。
• 示例：

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

• 关键特性：
• 适用于 <input type="file"> 表单提交。
• 可同时绑定其他非文件参数：

  
  public String upload(@RequestPart("file") MultipartFile file,@RequestParam("desc") String description)
  

3. 注解对比与选择

场景	推荐注解	理由
获取 URL 查询参数	@RequestParam	专为查询参数设计，支持可选参数和默认值。
从 URL 路径中提取变量	@PathVariable	直接绑定 RESTful 风格的路径变量。
解析 JSON/XML 请求体	@RequestBody	唯一支持复杂请求体（如 POJO）的注解。
绑定表单数据到对象	@ModelAttribute	自动填充对象属性，适合传统表单提交。
获取请求头	@RequestHeader	精确访问特定请求头字段。
处理文件上传	@RequestPart	专为 multipart/form-data 设计，支持 MultipartFile。

4. 常见问题

（1）@RequestParam vs @ModelAttribute

• 相同点：均可处理表单数据。
• 区别：
• @RequestParam：逐个绑定简单类型（如 String, int）。
• @ModelAttribute：自动绑定到对象的字段（如 User 的 name 属性）。

（2）@RequestBody vs @ModelAttribute

• @RequestBody：
• 处理 结构化数据（JSON/XML）。
• 通常用于 API 开发。
• @ModelAttribute：
• 处理 表单数据（application/x-www-form-urlencoded）。
• 适合传统 Web 应用（如 Thymeleaf + 表单提交）。

（3）何时用 @PathVariable？

• 在 RESTful API 中标识资源时：

  
  @DeleteMapping("/user/{id}")public void deleteUser(@PathVariable Long id) {// ...}
  

5. 完整示例

@RestController@RequestMapping("/api")public class UserController {// 1. 路径变量 + 查询参数@GetMapping("/user/{id}")public String getUser(@PathVariable Long id,@RequestParam(required = false, defaultValue = "false") Boolean details) {return "ID: " + id + ", Details: " + details;}// 2. JSON 请求体@PostMapping("/user")public User createUser(@RequestBody User user) {return userService.save(user);}// 3. 文件上传@PostMapping("/upload")public String upload(@RequestPart MultipartFile file,@RequestParam String description) {return "File: " + file.getOriginalFilename() + ", Desc: " + description;}// 4. 请求头 + Cookie@GetMapping("/meta")public String getMeta(@RequestHeader("User-Agent") String userAgent,@CookieValue("JSESSIONID") String sessionId) {return "UA: " + userAgent + ", Session: " + sessionId;}
}