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

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

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

1. 映射位置：

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

2. 映射内容（属性）：
   @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 (同一个路径不同返回类型)
     

3. 组合注解 (更简洁的替代)：
   为了简化常见 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 应用中，推荐优先使用这些组合注解，代码更清晰。

4. 工作原理：
   当一个 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 控制器的基础。

理解 @RequestMapping 是掌握 Spring Web 开发的关键第一步。