<!-- Source: https://mvnrepository.com/artifact/org.springframework/spring-web -->
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-web</artifactId>
<version>6.2.18</version>
<scope>compile</scope>
</dependency>
spring-web 依赖包中提供的注解主要集中在 org.springframework.web.bind.annotation 包下，是构建 Spring MVC 或 WebFlux 应用程序的核心工具。
为了方便查阅，我将这些常用注解按功能分为了以下几类：
一、请求处理与参数绑定
这一组注解用于将 HTTP 请求映射到控制器方法，并将请求中的各种数据（如路径变量、查询参数、请求体等）绑定到方法参数上。
| 注解 | 说明 | 核心作用 |
|---|---|---|
@RequestMapping |
基础映射注解，用于将特定URL路径的HTTP请求映射到控制器类或方法上。 | 通过 method 属性指定请求方法类型 。 |
@GetMapping |
组合注解，处理 HTTP GET 请求的快捷方式。 | 等价于 @RequestMapping(method = RequestMethod.GET) 。 |
@PostMapping |
组合注解，处理 HTTP POST 请求的快捷方式。 | 等价于 @RequestMapping(method = RequestMethod.POST) 。 |
@PutMapping |
组合注解，处理 HTTP PUT 请求的快捷方式。 | 等价于 @RequestMapping(method = RequestMethod.PUT) 。 |
@DeleteMapping |
组合注解，处理 HTTP DELETE 请求的快捷方式。 | 等价于 @RequestMapping(method = RequestMethod.DELETE) 。 |
@PatchMapping |
组合注解，处理 HTTP PATCH 请求的快捷方式。 | 等价于 @RequestMapping(method = RequestMethod.PATCH) 。 |
@PathVariable |
将 URI 模板变量（如 /users/{id} 中的 {id}）绑定到方法参数上。 |
常用于 RESTful API 中获取资源标识符 。 |
@RequestParam |
将 HTTP 请求参数（URL 中的 query string 或表单数据）绑定到方法参数上。 | 常用于处理分页、筛选等参数 。 |
@RequestBody |
将 HTTP 请求的 Body 内容（通常是 JSON 或 XML）反序列化为一个 Java 对象。 | 常用于处理 POST/PUT 请求中提交的复杂数据 。 |
@RequestAttribute |
将 HTTP 请求域（request scope）中的属性值绑定到控制器的方法参数上。 | 常用于在同一个请求内的过滤器、拦截器和控制器之间传递数据 。 |
@RequestHeader |
将 HTTP 请求头中的特定值绑定到方法参数上。 | 常用于获取身份认证 Token、语言偏好等信息 。 |
@CookieValue |
将 HTTP Cookie 的值绑定到方法参数上。 | 用于获取客户端存储的 Cookie 信息 。 |
@RequestPart |
将 multipart/form-data 请求中的一个部分绑定到方法参数上。 |
常用于文件上传或接收复杂的表单数据 。 |
@MatrixVariable |
将 URI 路径段中的键值对（矩阵变量）绑定到方法参数上。 | 是一种较少见的 URL 传参方式 。 |
@SessionAttribute |
将 HTTP Session 中的属性值绑定到控制器的方法参数上。 | 用于获取存储在用户会话中的对象 。 |
@ModelAttribute |
将方法参数或返回值绑定到 Model 中，暴露给视图页面使用。 | 既可以绑定请求参数到对象，也可以在方法执行前准备模型数据 。 |
二、响应处理
这一组注解用于控制如何将处理结果返回给客户端。
| 注解 | 说明 | 核心作用 |
|---|---|---|
@ResponseBody |
将控制器方法的返回值直接作为 HTTP 响应体写入，而不是解析为视图名。 | 常用于 REST API 中返回 JSON/XML 数据 。 |
@ResponseStatus |
为 HTTP 响应的状态码指定一个特定的状态码。 | 可以让接口返回如 201 Created 或 204 No Content 等具体的、非默认的状态码 。 |
三、控制器声明与全局配置
用于声明一个类为控制器，或提供全局的控制机制。
| 注解 | 说明 | 核心作用 |
|---|---|---|
@Controller |
声明一个类是 Spring MVC 的控制器，会被组件扫描自动注册。 | 传统的 Spring MVC 控制器，通常需要配合 @ResponseBody 或视图解析器使用 。 |
@RestController |
组合注解，标记在一个类上，相当于 @Controller + @ResponseBody。 |
它是构建纯 RESTful API 最常用的注解，该控制器中所有方法的返回值都会自动作为响应体 。 |
@ControllerAdvice |
全局控制器增强，用于统一处理跨控制器的逻辑。 | 通常与 @ExceptionHandler、@InitBinder 或 @ModelAttribute 配合使用，实现全局异常处理、数据绑定等 。 |
@RestControllerAdvice |
组合注解，相当于 @ControllerAdvice + @ResponseBody。 |
用于全局异常处理，并将处理结果直接返回为 JSON 等格式的响应体 。 |
@InitBinder |
用于自定义请求参数到 JavaBean 的绑定逻辑。 | 常用于对日期、数字等格式进行全局或局部的统一处理和转换 。 |
四、其他辅助功能
提供一些实用的特性支持。
| 注解 | 说明 | 核心作用 |
|---|---|---|
@CrossOrigin |
在类或方法级别启用跨域请求。 | 用于解决前后端分离项目中常见的跨域请求问题 。 |
@ExceptionHandler |
用于定义一个方法，专门处理特定类型的异常。 | 通常在 @ControllerAdvice 类中使用，进行全局异常处理，也可以用在单个控制器内 。 |
@SessionAttributes |
用于将 Model 中的特定属性存储到 HTTP Session 中。 | 用于在多个请求之间共享数据 。 |
对于大多数使用 Spring Boot 进行 Web 开发的朋友来说，最常打交道的就是 @RestController、@RequestMapping 及其衍生注解、以及 @PathVariable、@RequestParam 和 @RequestBody 这几个核心成员。