当前位置：首页 > news >正文

Spring核心注解@RequestMapping详解

news 2025/7/17 8:13:26

@RequestMapping 是 Spring Framework 中一个核心注解，用于在 Spring MVC（或 Spring WebFlux）中将 HTTP 请求映射到特定的处理器（Controller 中的方法）或处理器类。它告诉 Spring 框架：当一个匹配特定条件的 HTTP 请求到达时，应该调用哪个方法来处理该请求。

简单来说，它是定义 Web 请求端点（API 接口）的基础。

以下是 @RequestMapping 的关键功能和用法：

映射位置：
- 类级别： 标注在 Controller 类上，为该类中所有处理器方法提供一个公共的 URL 路径前缀。
- 方法级别： 标注在 Controller 类内部的方法上，定义该方法的具体映射路径（相对于类级别的路径）和处理逻辑。通常一个方法处理一个具体的请求。

映射内容（属性）：
@RequestMapping 接受多个属性来精确指定它要匹配的请求特征：

value 或 path (最常用)： 指定请求的 URL 路径模式。支持 Ant 风格通配符 (*, **, ?) 和路径变量 ({variable})。

@RequestMapping("/users") // 类级别前缀
@RestController
public class UserController {@RequestMapping("/profile") // 实际映射到 /users/profilepublic String userProfile() { ... }@RequestMapping("/orders/{orderId}") // 路径变量public String getOrder(@PathVariable String orderId) { ... }
}

method： 指定请求的 HTTP 方法 (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS 等)。这是定义 RESTful 风格 API 的关键。

@RequestMapping(value = "/users", method = RequestMethod.POST) // 只处理 POST /users
public User createUser(@RequestBody User user) { ... }@RequestMapping(value = "/users/{id}", method = RequestMethod.GET) // 只处理 GET /users/{id}
public User getUser(@PathVariable Long id) { ... }

params： 要求请求必须包含特定的请求参数，或者参数具有特定值。支持表达式 (=, !=, ! 存在)。

@RequestMapping(value = "/search", params = "q") // 必须有 q 参数
public List<User> searchUsers(@RequestParam String q) { ... }@RequestMapping(value = "/activate", params = "token=valid") // 必须有 token 参数且值为 'valid'
public void activateAccount() { ... }

headers： 要求请求必须包含特定的 HTTP 头信息，或者头信息具有特定值。

@RequestMapping(value = "/data", headers = "X-Custom-Header=MyValue") // 需要特定自定义头
public String getData() { ... }@RequestMapping(value = "/pdf", headers = "Accept=application/pdf") // 要求 Accept 头包含 pdf
public ResponseEntity<byte[]> getPdf() { ... }

consumes： 指定处理器方法能够接收（消费）的请求内容类型 (Content-Type)。例如 application/json, application/xml。

@RequestMapping(value = "/users", method = RequestMethod.POST, consumes = "application/json")
public User createUserJson(@RequestBody User user) { ... } // 只处理 Content-Type 为 JSON 的 POST

produces： 指定处理器方法返回的响应内容类型 (Content-Type)。客户端可以通过 Accept 头来匹配。

@RequestMapping(value = "/users/{id}", method = RequestMethod.GET, produces = "application/json")
public User getUserJson(@PathVariable Long id) { ... } // 返回 JSON@RequestMapping(value = "/users/{id}", method = RequestMethod.GET, produces = "application/xml")
public User getUserXml(@PathVariable Long id) { ... } // 返回 XML (同一个路径不同返回类型)

组合注解 (更简洁的替代)：
为了简化常见 HTTP 方法的映射，Spring 提供了基于 @RequestMapping 的组合注解（元注解）。它们内部已经设置了 method 属性，语法更简洁：
- @GetMapping = @RequestMapping(method = RequestMethod.GET)
- @PostMapping = @RequestMapping(method = RequestMethod.POST)
- @PutMapping = @RequestMapping(method = RequestMethod.PUT)
- @DeleteMapping = @RequestMapping(method = RequestMethod.DELETE)
- @PatchMapping = @RequestMapping(method = RequestMethod.PATCH)
  现代 Spring Boot 应用中，推荐优先使用这些组合注解，代码更清晰。
工作原理：
当一个 HTTP 请求到达 DispatcherServlet（Spring MVC 前端控制器）时：
- DispatcherServlet 会查询一个或多个 HandlerMapping 组件。
- HandlerMapping 组件（如 RequestMappingHandlerMapping）负责检查所有带有 @Controller 或 @RestController 注解的类及其方法上的 @RequestMapping（或组合注解）定义。
- 它会根据请求的 URL 路径、HTTP 方法、请求头、参数、内容类型等，找到最匹配的处理器方法（HandlerMethod）。
- 找到匹配的方法后，DispatcherServlet 就会调用该方法来处理请求并生成响应。

总结：

@RequestMapping 是 Spring MVC 中定义请求处理入口的核心注解。
它通过 path/value, method, params, headers, consumes, produces 等属性精确匹配传入的 HTTP 请求。
可以放在类上（定义公共前缀）和方法上（定义具体端点）。
组合注解 (@GetMapping, @PostMapping 等) 是更简洁、更现代的写法，推荐优先使用。
它是构建 RESTful API 和传统 Web 控制器的基础。