1. 概述
本文将深入解析 Spring Web 模块中常用的注解，主要来自 org.springframework.web.bind.annotation 包。这些注解是构建 RESTful 接口和处理 HTTP 请求响应的核心工具，掌握它们能让你的开发更高效、代码更清晰。
对于有经验的开发者来说，这些注解早已是家常便饭，但其中一些细节和组合用法仍值得深挖，避免踩坑。
2. @RequestMapping
@RequestMapping 是 Spring Web 中最基础的注解之一，用于标记控制器中的请求处理方法。它可以配置以下属性：
value/path：指定该方法映射的 URL 路径method：限定支持的 HTTP 方法（如 GET、POST）params：根据请求参数的存在与否或值进行过滤headers：根据请求头进行匹配consumes：指定请求体可接受的媒体类型（如application/json）produces：指定响应体返回的媒体类型
✅ 示例代码：
@Controller
class VehicleController {
@RequestMapping(value = "/vehicles/home", method = RequestMethod.GET)
String home() {
return "home";
}
}
⚠️ 注意：@RequestMapping 也可以用在类级别，作为该 Controller 下所有方法的公共前缀。此时方法级别的路径会与类级别的路径拼接，而不是覆盖。
例如，下面的写法与上面等价：
@Controller
@RequestMapping(value = "/vehicles", method = RequestMethod.GET)
class VehicleController {
@RequestMapping("/home")
String home() {
return "home";
}
}
✅ 小贴士：从 Spring 4.3 开始，引入了更语义化的衍生注解：
@GetMapping→ 等价于@RequestMapping(method = GET)@PostMapping@PutMapping@DeleteMapping@PatchMapping
这些注解让代码意图更明确，推荐优先使用。
3. @RequestBody
@RequestBody 用于将 HTTP 请求体自动反序列化为 Java 对象，常用于接收 JSON 或 XML 数据。
Spring 会根据 Content-Type 头自动选择合适的 HttpMessageConverter 进行转换。
✅ 示例代码：
@PostMapping("/save")
void saveVehicle(@RequestBody Vehicle vehicle) {
// vehicle 已经由 JSON 自动映射为对象
}
⚠️ 踩坑提醒：如果前端传的 JSON 字段与 Java 对象字段不匹配（比如大小写、命名风格），记得检查是否开启了 Jackson 的 @JsonProperty 或配置了全局命名策略。
4. @PathVariable
@PathVariable 用于绑定 URI 模板变量到方法参数。通常与 @RequestMapping 的路径占位符配合使用。
✅ 示例代码：
@RequestMapping("/{id}")
Vehicle getVehicle(@PathVariable("id") long id) {
// /123 → id = 123
}
如果参数名与模板变量名一致，可以直接省略括号内的名称：
@RequestMapping("/{id}")
Vehicle getVehicle(@PathVariable long id) {
// Spring 自动匹配
}
✅ 可选参数：通过设置 required = false 可将路径变量设为可选：
@RequestMapping("/{id}")
Vehicle getVehicle(@PathVariable(required = false) Long id) {
// id 可为 null
}
⚠️ 注意：此时参数类型应为包装类（如 Long），否则基本类型无法接收 null。
5. @RequestParam
@RequestParam 用于获取 HTTP 请求参数（query string 或 form data）。
✅ 示例代码：
@RequestMapping
Vehicle getVehicleByParam(@RequestParam("id") long id) {
// GET /?id=123 → id = 123
}
它也支持 required、defaultValue 等配置。设置 defaultValue 后，required 会自动设为 false：
@RequestMapping("/buy")
Car buyCar(@RequestParam(defaultValue = "5") int seatCount) {
// 若未传 seatCount，默认值为 5
}
其他请求部分
除了参数，还可以通过以下注解获取：
@CookieValue：获取 Cookie 值@RequestHeader：获取请求头信息
用法与 @RequestParam 类似，支持 defaultValue、required 等属性。
6. 响应处理注解
这部分注解用于控制 HTTP 响应的行为。
6.1. @ResponseBody
@ResponseBody 表示方法返回值应直接作为响应体内容，而不是视图名。
✅ 示例代码：
@ResponseBody
@RequestMapping("/hello")
String hello() {
return "Hello World!";
// 直接输出字符串，不走视图解析
}
如果加在 @Controller 类上，则该类所有方法都默认使用此行为。
6.2. @ExceptionHandler
用于定义自定义异常处理器。当控制器中抛出指定异常时，Spring 会调用该方法进行处理。
✅ 示例代码：
@ExceptionHandler(IllegalArgumentException.class)
void onIllegalArgumentException(IllegalArgumentException exception) {
// 统一处理非法参数异常
}
可以结合 @ResponseStatus 返回特定状态码。
6.3. @ResponseStatus
用于指定响应的 HTTP 状态码。
code/value：设置状态码（如HttpStatus.OK）reason：设置原因短语（可选）
✅ 常见用法：
@ExceptionHandler(IllegalArgumentException.class)
@ResponseStatus(HttpStatus.BAD_REQUEST)
void onIllegalArgumentException(IllegalArgumentException exception) {
// 返回 400 Bad Request
}
⚠️ 注意：@ResponseStatus 也可用于自定义异常类上，实现声明式状态码。
7. 其他常用 Web 注解
这些注解不直接处理请求/响应，但在实际开发中非常关键。
7.1. @Controller
标记一个类为 Spring MVC 的控制器组件。它是 @Component 的衍生注解，会被组件扫描自动注册为 Bean。
更多信息可参考 Spring Bean 相关注解。
7.2. @RestController
@RestController 是 @Controller 和 @ResponseBody 的组合注解，专用于构建 RESTful 接口。
✅ 以下两种写法等价：
@Controller
@ResponseBody
class VehicleRestController {
// 所有方法返回值直接作为响应体
}
@RestController
class VehicleRestController {
// 更简洁
}
✅ 推荐：现代 Spring Boot 项目中，REST 接口一律使用 @RestController。
7.3. @ModelAttribute
有两个主要用途：
- 从模型中获取已有对象：
@PostMapping("/assemble")
void assembleVehicle(@ModelAttribute("vehicle") Vehicle vehicleInModel) {
// 获取 Model 中 key 为 "vehicle" 的对象
}
若参数名与 model key 一致，可省略：
@PostMapping("/assemble")
void assembleVehicle(@ModelAttribute Vehicle vehicle) {
// 自动绑定
}
- 将方法返回值自动加入 Model：
@ModelAttribute("vehicle")
Vehicle getVehicle() {
return new Vehicle();
// 每次请求前都会执行，加入 model
}
可省略 key，Spring 默认使用方法名：
@ModelAttribute
Vehicle vehicle() {
return new Vehicle();
}
⚠️ 执行时机：在请求处理方法执行前，所有 @ModelAttribute 方法都会被调用。
7.4. @CrossOrigin
用于开启跨域（CORS）支持，解决前端常见的 No 'Access-Control-Allow-Origin' 问题。
✅ 示例代码：
@CrossOrigin
@RequestMapping("/hello")
String hello() {
return "Hello World!";
}
加在类上则对所有接口生效。
支持细粒度配置，如 origins、methods、allowedHeaders 等。
8. 总结
本文系统梳理了 Spring Web 开发中核心的注解体系，涵盖请求映射、参数绑定、响应处理及跨域等关键场景。
这些注解是构建现代 Web 应用的基石，熟练掌握不仅能提升开发效率，还能避免许多隐蔽的坑。建议结合实际项目多加练习，真正内化为自己的“肌肉记忆”。
文中所有示例代码均可在 GitHub 获取：https://github.com/tech-tutorial/spring-boot-annotations