Web层注解

注解名称	所属模块	功能描述	引入年份	版本	是否推荐使用	分类
@RequestParam	spring-webmvc	HTTP请求参数绑定到方法参数	2004	Spring 1.0	推荐	参数绑定
@PathVariable	spring-webmvc	提取 URI 中的路径变量	2009	Spring 3.0	推荐	参数绑定
@RequestBody	spring-webmvc	将请求体反序列化为对象（如 JSON/XML）	2009	Spring 3.0	推荐	参数绑定
@CookieValue	spring-webmvc	获取 Cookie 值	2009	Spring 3.0	推荐	参数绑定
@RequestHeader	spring-webmvc	获取请求头信息	2009	Spring 3.0	推荐	参数绑定
@MatrixVariable	spring-webmvc	支持 URL 矩阵变量解析	2013	Spring 3.2	推荐（RESTful API 可选）	参数绑定
@RequestMapping	spring-webmvc	映射 HTTP 请求到控制器方法（支持所有 HTTP 方法）	2004	Spring 1.0	推荐（但建议优先使用更具体的注解）	请求映射
@GetMapping	spring-webmvc	映射 HTTP GET 请求	2015	Spring 4.3	推荐（语义清晰）	请求映射
@PostMapping	spring-webmvc	映射 HTTP POST 请求	2015	Spring 4.3	推荐	请求映射
@PutMapping	spring-webmvc	映射 HTTP PUT 请求	2015	Spring 4.3	推荐	请求映射
@PatchMapping	spring-webmvc	映射 HTTP PATCH 请求	2015	Spring 4.3	推荐	请求映射
@DeleteMapping	spring-webmvc	映射 HTTP DELETE 请求	2015	Spring 4.3	推荐	请求映射
@ResponseStatus	spring-webmvc	设置 HTTP 响应状态码	2009	Spring 3.0	推荐	返回处理
@ResponseBody	spring-webmvc	将返回值序列化为响应体（如 JSON/XML）	2009	Spring 3.0	推荐（常用于 REST 控制器）	返回处理
@InitBinder	spring-webmvc	初始化 WebDataBinder，用于自定义数据绑定	2004	Spring 1.0	推荐（用于参数格式化）	全局处理与异常
@ExceptionHandler	spring-webmvc	处理控制器内的异常	2009	Spring 3.0	推荐（配合 @ControllerAdvice 使用）	全局处理与异常
@ControllerAdvice	spring-webmvc	全局异常处理和数据绑定	2013	Spring 3.2	推荐	全局处理与异常
@SessionAttributes	spring-webmvc	在会话中存储模型属性	2004	Spring 1.0	不推荐（Spring Boot 中不推荐使用）	其他功能
@CrossOrigin	spring-webmvc	启用跨域请求支持	2015	Spring 4.2	推荐（开发环境可用，生产建议配置 CORS Filter）	其他功能

参数绑定

[Q&A] @RequestParam 引入背景
在早期的 Java Web 开发中（如使用 Servlet API），开发者需要通过 HttpServletRequest 手动获取请求参数：

String name = request.getParameter("name");

为了提升开发效率和代码可读性，Spring 在其 Web 模块中引入了 @RequestParam 注解，使得控制器方法可以直接声明参数并自动绑定请求值。

[Q&A] @PathVariable 引入背景
在 RESTful 风格的 Web API 设计中，URL 通常包含具有语义的路径变量（Path Variable），例如：

/products/456/details → 代表资源 ID 或其他关键信息

在 Spring 3.0 之前，开发者需要通过 HttpServletRequest 手动解析路径变量，为了解决这些问题，Spring 在 3.0 版本 中引入了 @PathVariable 注解，使得控制器方法可以直接声明路径变量作为方法参数，并由框架自动完成绑定。

[Q&A] @RequestBody 引入背景
在 Spring 3.0 之前，开发者如果想从请求体中读取数据（例如处理 POST 请求中的 JSON 数据），需要手动操作 HttpServletRequest 的输入流，并使用第三方库（如 Jackson、Gson）进行反序列化：

BufferedReader reader = request.getReader();
String json = reader.readLine();
User user = new ObjectMapper().readValue(json, User.class);

为了简化这一过程，提高开发效率和可维护性，Spring 在 3.0 版本 中引入了 @RequestBody 注解，配合 HttpMessageConverter 接口，实现了自动将请求体内容转换为 Java 对象的能力。

[Q&A] @CookieValue 引入背景
在 Web 开发中，Cookie 是客户端与服务端之间维持状态的一种常见机制，在早期的 Servlet 开发中，开发者需要手动从 HttpServletRequest 获取 Cookie，并遍历查找目标 Cookie 值：

Cookie[] cookies = request.getCookies();
if (cookies != null) {for (Cookie cookie : cookies) {if ("auth_token".equals(cookie.getName())) {String token = cookie.getValue();// 使用 token...}}
}

为了解决这些问题，Spring 在 3.0 版本中引入了 @CookieValue 注解，使得控制器方法可以直接声明要获取的 Cookie 名称，并由框架自动注入对应的值。

[Q&A] @RequestHeader引入背景
在传统的 Web 开发中，HTTP 请求头（Request Headers）是客户端与服务端通信的重要组成部分，常用于传递元信息，在 Spring 3.0 之前，开发者需要手动从 HttpServletRequest 中获取请求头信息：

String contentType = request.getHeader("Content-Type");

为了解决这些问题，Spring 在 3.0 版本中引入了 @RequestHeader 注解，使得控制器方法可以直接声明要获取的请求头名称，并由框架自动注入对应的值。

[Q&A] @MatrixVariable 引入背景
HTTP URI 中的 Matrix 参数是什么？
Matrix参数是一种在 URI 路径段中嵌入键值对的方式。它不是查询参数（Query Parameters），而是直接出现在路径段中，格式如下：

/bookstore;color=red;price=100

color=red 和 price=100 是两个 Matrix 参数。它们属于路径段 /bookstore，而不是整个 URL 的查询字符串。
在没有 @MatrixVariable 之前，开发者需要手动解析 URI 或使用 HttpServletRequest 获取原始 URI 并拆分路径段，代码复杂且容易出错。

String uri = request.getRequestURI();
// 手动解析 matrix 参数...

请求映射

[Q&A] @RequestMapping 引入背景
在 Spring 2.5 之前，开发者通常通过以下方式处理 HTTP 请求：
1、实现 Controller 接口（如 AbstractController、SimpleFormController 等）

public class HelloController implements Controller {public ModelAndView handleRequest(HttpServletRequest request, HttpServletResponse response) {// 处理逻辑}
}

2、在 XML 配置文件中定义 URL 映射关系

<bean name="/hello.htm" class="com.example.HelloController"/>

为了解决上述问题，Spring Framework 2.5 引入了基于注解的控制器编程模型，其中 @RequestMapping 是最核心的注解之一。

[Q&A] @GetMapping @PostMapping @PutMapping @DeleteMapping @PatchMapping 引入背景
在 Spring 4.3 之前，开发者需要使用 @RequestMapping 并指定 method = RequestMethod.XXX 来限制请求方法：

@RequestMapping(value = "/users", method = RequestMethod.GET)
public String listUsers() {return "user-list";
}

为了解决这些问题，Spring Framework 4.3 引入了这些专门的注解，使代码更加语义化和简洁。

注解	适用场景	是否常用	所属模块	功能	引入年份	版本	是否推荐使用	返回状态码（常规）	返回值介绍（默认行为）
@GetMapping	查询资源	✔️ 高频使用	spring-webmvc	映射 HTTP GET 请求	2015	Spring 4.3	✔️ 推荐（语义清晰）	200 OK（成功查询）	通常返回 JSON/XML 或视图渲染结果（视配置而定）
@PostMapping	创建资源	✔️ 高频使用	spring-webmvc	映射 HTTP POST 请求	2015	Spring 4.3	✔️ 推荐	201 Created（成功创建）	可返回新增资源详情（如 ID、完整数据）
@PutMapping	全量更新	✔️ 中高频	spring-webmvc	映射 HTTP PUT 请求	2015	Spring 4.3	✔️ 推荐	200 OK（更新成功）/ 204 No Content（无内容返回）	返回更新后完整资源或空（按需设计）
@PatchMapping	部分更新	⚠️ 视需求而定	spring-webmvc	映射 HTTP PATCH 请求	2015	Spring 4.3	✔️ 推荐（需 REST 规范场景）	200 OK（更新成功）	通常返回部分更新后的资源片段或状态确认
@DeleteMapping	删除资源	✔️ 高频使用	spring-webmvc	映射 HTTP DELETE 请求	2015	Spring 4.3	✔️ 推荐	204 No Content（删除成功，无内容返回）	一般无返回体（或返回删除确认消息）

返回处理

[Q&A] @ResponseStatus 引入背景
在传统的 MVC 应用中，通常只关注页面跳转或简单的成功/失败响应，HTTP 状态码的作用并不突出。但随着 RESTful API 的普及，客户端（如前端、移动端）越来越依赖于明确的 HTTP 状态码来判断请求结果，例如：
200 OK：成功获取资源
201 Created：资源创建成功
404 Not Found：资源不存在
500 Internal Server Error：服务端异常
因此，Spring 需要一种更清晰的方式来为每个控制器方法指定返回的状态码。
在没有 @ResponseStatus 之前，开发者需要通过 HttpServletResponse 或 ResponseEntity 手动设置状态码，这会增加代码复杂度，降低可读性。

@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody User user) {return new ResponseEntity<>(userService.save(user), HttpStatus.CREATED);
}

而使用 @ResponseStatus 可以将状态码语义直接绑定到方法上，提升代码简洁性和可维护性。

[Q&A] @ResponseBody 引入背景
在传统的 Spring MVC 应用中，控制器方法通常返回的是视图名称（如 JSP 页面），例如：

@GetMapping("/users")
public String listUsers(Model model) {model.addAttribute("users", userService.findAll());return "userList"; // 返回视图名
}

但随着前端框架（如 Vue、React、Angular）的发展，前端和后端逐渐分离，后端只需提供数据接口（JSON 格式），不再负责页面渲染。在没有 @ResponseBody 之前，开发者需要手动将对象转为 JSON 字符串并写入 HttpServletResponse：

@GetMapping("/users")
public void getAllUsers(HttpServletResponse response) throws IOException {List<User> users = userService.findAll();String json = new ObjectMapper().writeValueAsString(users);response.getWriter().write(json);
}

这种方式繁琐且容易出错，所以引入了 @ResponseBody。
@ResponseBody 告诉 Spring：“这个方法返回的数据不是视图名，而是直接写入 HTTP 响应体的内容。”
Spring 会根据客户端请求头中的 Accept 内容选择合适的 HttpMessageConverter（如 Jackson 来处理数据格式，比如：
application/json → Jackson
application/xml → JAXB 或 Jackson XML 扩展

全局处理与异常

[Q&A] @InitBinder 引入背景
@InitBinder 是为了解决：Spring 自动绑定参数时，有些数据你希望它“按你的规则”来处理，而不是 Spring 默认的方式。比如：
1、把 “2024-03-15” 转成 Date 类型
2、不允许绑定 isAdmin 字段
3、给这个对象加一个验证器（比如检查 name 是否为空）

[Q&A] @ExceptionHandler 引入背景
在没有 @ExceptionHandler 之前，开发者通常会在每个控制器方法中使用 try-catch 来处理异常：

@GetMapping("/user/{id}")
public String getUser(@PathVariable Long id, Model model) {try {User user = userService.findById(id);model.addAttribute("user", user);return "user-detail";} catch (UserNotFoundException ex) {model.addAttribute("error", "用户不存在");return "error-page";}
}

典型用法

spring-webmvc @RequestParam 典型用法
spring-webmvc @PathVariable 典型用法
spring-webmvc @RequestBody 典型用法
spring-webmvc @CookieValue 典型用法
spring-webmvc @RequestHeader 典型用法
spring-webmvc @MatrixVariable 典型用法
spring-webmvc @RequestMapping @GetMapping @PostMapping @PutMapping @DeleteMapping @PatchMapping 典型用法
spring-webmvc @ResponseStatus 典型用法
spring-webmvc @ResponseBody 典型用法
spring-webmvc @InitBinder 典型用法