Spring 控制器参数注解

1. 核心参数注解列表

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. 注解对比与选择

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;
	}
}