Spring MVC 请求类型注解详解

Spring MVC 请求类型注解详解

---

1. 核心注解分类

Spring MVC 中的请求处理注解分为以下几类：

类别	注解示例	作用范围
方法级注解	@RequestMapping, @GetMapping 等	方法级别
参数级注解	@RequestParam, @RequestBody	方法参数
模型/会话注解	@ModelAttribute, @SessionAttributes	方法或类级别

---

2. 方法级注解详解

@RequestMapping

功能：定义请求映射规则，支持所有 HTTP 方法。

属性列表：

属性	说明	示例
method	指定支持的 HTTP 方法（如 RequestMethod.GET）。	method = RequestMethod.POST
value	请求路径（可省略，与 path 等效）。	value = "/user" 或 path = "/user"
params	条件过滤：请求参数需满足指定条件（如 param1, !param2）。	params = {"name", "!age"}
headers	条件过滤：HTTP 头需满足指定条件（如 User-Agent:Chrome）。	headers = "Content-Type=application/json"
consumes	限制请求内容类型（如 MediaType.APPLICATION_JSON_VALUE）。	consumes = MediaType.APPLICATION_JSON_VALUE
produces	限制响应内容类型（如 text/html）。	produces = "text/html"

---

@GetMapping / @PostMapping 等

功能：@RequestMapping 的简化版，按 HTTP 方法分类：

• @GetMapping：对应 method = RequestMethod.GET
• @PostMapping：对应 method = RequestMethod.POST
• @PutMapping：对应 method = RequestMethod.PUT
• @DeleteMapping：对应 method = RequestMethod.DELETE
• @PatchMapping：对应 method = RequestMethod.PATCH

---

3. 参数级注解详解

@RequestParam

功能：绑定 URL 查询参数或表单参数到方法参数。

属性列表：

属性	说明	示例
value	参数名称（可省略，与 name 等效）。	value = "id" 或 name = "id"
required	是否必须（默认 true）。	required = false
defaultValue	参数缺失时的默认值。	defaultValue = "0"

示例：

@GetMapping("/user")
public String getUser(@RequestParam("id") int userId) { ... }

---

@PathVariable

功能：绑定 URL 路径中的变量到方法参数。

属性列表：

属性	说明	示例
value	路径变量名称。	value = "id"
required	是否必须（默认 true）。	required = false

示例：

@GetMapping("/user/{id}")
public String getUser(@PathVariable("id") String userId) { ... }

---

@RequestBody

功能：将 HTTP 请求体（如 JSON/XML）反序列化为 Java 对象。

属性：

• 无显式属性，直接用于方法参数。
• 依赖 MappingJackson2HttpMessageConverter（JSON）或自定义转换器。

示例：

@PostMapping("/user")
public User createUser(@RequestBody User user) { ... }

---

@RequestHeader

功能：绑定 HTTP 请求头到方法参数。

属性列表：

属性	说明	示例
value	请求头名称。	value = "User-Agent"
required	是否必须（默认 true）。	required = false
defaultValue	缺省值。	defaultValue = "unknown"

示例：

@GetMapping("/headers")
public String getHeaders(@RequestHeader("User-Agent") String userAgent) { ... }

---

@CookieValue

功能：绑定 Cookie 值到方法参数。

属性列表：

属性	说明	示例
value	Cookie 名称。	value = "JSESSIONID"
required	是否必须（默认 true）。	required = false
defaultValue	缺省值。	defaultValue = "not-set"

示例：

@GetMapping("/cookie")
public String getCookie(@CookieValue("theme") String theme) { ... }

---

4. 模型/会话注解

@ModelAttribute

功能：

1. 方法级：在目标方法执行前预处理模型数据（如填充对象）。
2. 参数级：将请求参数绑定到 Java 对象。

示例：

// 方法级：预加载数据
@ModelAttribute("user")
public User getUser() {
    return new User();
}

// 参数级：绑定参数到对象
@PostMapping("/user")
public String saveUser(@ModelAttribute User user) { ... }

@SessionAttributes

功能：将模型属性存储到 HTTP Session。

属性：

• value：需存储的属性名列表（如 {"user"}）。
• types：需存储的属性类型列表。

示例：

@Controller
@SessionAttributes({"user"})
public class UserController { ... }

---

5. 文件上传注解

@RequestPart

功能：处理多部分请求中的文件或参数（结合 @RequestParam）。

示例：

@PostMapping("/upload")
public String uploadFile(@RequestPart("file") MultipartFile file) { ... }

---

6. 总结表格

注解类型	注解名称	作用	参数示例
方法级	@RequestMapping	定义请求映射规则（路径、方法、条件等）。	method = POST, consumes = "application/json"
HTTP 方法专用	@GetMapping	仅处理 GET 请求。	/user/{id}
参数绑定	@RequestParam	绑定查询参数或表单参数。	@RequestParam("id") int userId
路径变量	@PathVariable	绑定 URL 路径中的变量。	@PathVariable("id") String userId
请求体	@RequestBody	反序列化请求体为对象。	@RequestBody User user
HTTP 头	@RequestHeader	绑定请求头值。	@RequestHeader("User-Agent") String agent
Cookie	@CookieValue	绑定 Cookie 值。	@CookieValue("theme") String theme
模型/会话	@ModelAttribute	绑定对象或预加载模型数据。	@ModelAttribute User user
文件上传	@RequestPart	处理多部分请求中的文件或参数。	@RequestPart("file") MultipartFile file

---

关键总结

1. 方法级注解：定义请求路径和条件，优先使用 @GetMapping 等 HTTP 方法专用注解。
2. 参数级注解：根据数据来源（路径、请求体、请求头等）选择对应注解。
3. 模型/会话：@ModelAttribute 用于对象绑定和预处理，@SessionAttributes 管理会话数据。
4. 最佳实践：
   • 使用 @RequestBody 处理 JSON/XML 请求体。
   • 通过 @RequestParam 或 @PathVariable 精确控制参数来源。
   • 结合 @Valid 注解实现参数校验（需 @ControllerAdvice 处理异常）。