Spring MVC 如何映射 HTTP 请求到 Controller 方法？

我们来详细分析一下如何在 Spring MVC 中将 HTTP 请求映射到 Controller 的处理方法（Handler Methods）上，以及 @RequestMapping 注解的使用方法。

请求映射的核心：@RequestMapping 注解

@RequestMapping 是 Spring MVC 中最核心、最通用的映射注解。它可以用于类级别（Class-level）和方法级别（Method-level）。

1. 类级别映射 (Class-level Mapping):

   • 当 @RequestMapping 应用在类上时，它定义了Controller 处理所有请求的基类URL 路径。
   • 这样可以避免在每个方法上添加重复相同的路径前缀。

2. 方法级别映射 (Method-level Mapping):

   • 当 @RequestMapping 应用在方法上时，它指定了该方法具体处理哪个（或哪些）URL 路径的请求。
   • 这个路径是相对于类级别路径的（如果存在的话）。

@RequestMapping 的主要属性：

• value 或 path:

  • 指定映射的 URL 路径。可以是一个字符串数组，表示映射多个路径到同一个方法。
  • 支持 Ant 风格的路径模式（如 *, **, ?）和 URI 模板变量（路径变量，如 {userId}）。
  • value 和 path 是同义词，可以互换使用。

• method:

  • 指定该方法处理的 HTTP 请求方法（GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD, TRACE）。
  • 可以是一个 RequestMethod 枚举值的数组，表示处理多种 HTTP 方法。
  • 如果不指定，默认会匹配 所有 HTTP 方法。

• params:

  • 根据请求参数（Query Parameters 或 Form Data）进行映射。只有当请求中包含（或不包含，或具有特定值）指定的参数时，才会匹配成功。
  • 表达式语法：
    • "myParam": 参数 myParam 必须存在。
    • "!myParam": 参数 myParam 必须不存在。
    • "myParam=myValue": 参数 myParam 必须存在且值为 myValue。
    • "myParam!=myValue": 参数 myParam 必须存在且值不为 myValue。
    • 可以组合多个条件，如 {"myParam=val", "otherParam"}（AND 关系）。

• headers:

  • 根据请求头（Request Headers）进行映射。只有当请求包含（或不包含，或具有特定值）指定的头信息时，才会匹配成功。
  • 语法与 params 类似，如 "Accept=application/json", "!User-Agent", "X-Custom-Header=value"。

• consumes:

  • 指定该方法能够处理的请求的 Content-Type（即客户端发送的数据类型）。只有当请求的 Content-Type Header 与指定的值匹配时，才会映射成功。
  • 例如：consumes = "application/json" 或 consumes = MediaType.APPLICATION_JSON_VALUE。可以指定多个，如 {"application/json", "application/xml"}。

• produces:

  • 指定该方法能够生成的响应的 Content-Type（即服务器返回的数据类型）。Spring 会根据请求的 Accept Header 和此属性进行内容协商（Content Negotiation），选择最合适的 HttpMessageConverter 来序列化返回值。
  • 例如：produces = "application/json" 或 produces = MediaType.APPLICATION_JSON_VALUE。可以指定多个。

示例：使用 @RequestMapping

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;
import org.springframework.http.MediaType;

@Controller
@RequestMapping("/users") // 类级别映射，所有方法都在 /users 路径下
public class UserController {

    // 映射 GET /users/{id}
    @RequestMapping(value = "/{id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseBody // 如果用 @Controller 需要加这个来返回数据
    public User getUser(@PathVariable Long id) {
        // ... 获取用户逻辑 ...
        return new User(id, "Example User");
    }

    // 映射 POST /users
    @RequestMapping(method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE)
    @ResponseBody
    public String createUser(@RequestBody User newUser) {
        // ... 创建用户逻辑 ...
        return "User created";
    }

    // 映射 GET /users?admin=true (需要 admin 参数)
    @RequestMapping(method = RequestMethod.GET, params = "admin=true")
    @ResponseBody
    public String getAdminUsers() {
        // ... 获取管理员用户列表 ...
        return "List of Admin Users";
    }

    // 映射 GET /users (只接受 JSON 请求)
    @RequestMapping(method = RequestMethod.GET, headers = "Accept=application/json")
    @ResponseBody
    public String getUsersAcceptingJson() {
        // ... 获取用户列表 ...
        return "List of Users (JSON requested)";
    }
}

@RequestMapping 的变体 (快捷方式注解)

为了提高代码的可读性和简洁性，Spring 提供了针对特定 HTTP 方法的快捷方式注解。它们本质上是 @RequestMapping 预设了 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)。

这些快捷注解也支持 @RequestMapping 的 value/path, params, headers, consumes, produces 属性。

使用快捷方式注解的优点：

1. 更简洁: 代码更短。
2. 更清晰: 一眼就能看出方法处理的是哪种 HTTP 请求。

示例：使用快捷方式注解 (@RestController 简化)

import org.springframework.web.bind.annotation.*;
import org.springframework.http.MediaType;

@RestController // 使用 @RestController，无需在每个方法上加 @ResponseBody
@RequestMapping("/api/items") // 类级别映射
public class ItemController {

    // 映射 GET /api/items/{itemId}
    // produces 也可直接写字符串
    @GetMapping(value = "/{itemId}", produces = MediaType.APPLICATION_JSON_VALUE)
    public Item getItem(@PathVariable String itemId) {
        // ... 获取物品逻辑 ...
        return new Item(itemId, "Sample Item");
    }

    // 映射 POST /api/items
    // consumes 可以指定多个
    @PostMapping(consumes = {MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_XML_VALUE})
    public String createItem(@RequestBody Item newItem) {
        // ... 创建物品逻辑 ...
        return "Item created: " + newItem.getName();
    }

    // 映射 PUT /api/items/{itemId}
    @PutMapping("/{itemId}")
    public Item updateItem(@PathVariable String itemId, @RequestBody Item updatedItem) {
        // ... 更新物品逻辑 ...
        updatedItem.setId(itemId); // 假设更新成功
        return updatedItem;
    }

    // 映射 DELETE /api/items/{itemId}
    @DeleteMapping("/{itemId}")
    public String deleteItem(@PathVariable String itemId) {
        // ... 删除物品逻辑 ...
        return "Item deleted: " + itemId;
    }

    // 映射 GET /api/items?type=gadget
    @GetMapping(params = "type=gadget")
    public String getGadgets() {
        return "List of Gadgets";
    }

    // 映射 GET /api/items (需要特定 Header)
    @GetMapping(headers = "X-API-Version=2")
    public String getItemsV2() {
        return "List of Items (API V2)";
    }
}

// 示例 Pojo
class Item {
    private String id;
    private String name;
    // constructors, getters, setters...
    public Item(String id, String name) { this.id = id; this.name = name; }
    public String getId() { return id; }
    public void setId(String id) { this.id = id; }
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
}

class User {
    private Long id;
    private String username;
    // constructors, getters, setters...
    public User(Long id, String username) { this.id = id; this.username = username; }
    public Long getId() { return id; }
    public String getUsername() { return username; }
}

总结

• @RequestMapping 是基础，可以映射任何 HTTP 方法，并提供最全面的配置选项（path, method, params, headers, consumes, produces）。
• @GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @PatchMapping 是针对特定 HTTP 方法的快捷方式，使代码更简洁明了，是目前 Spring MVC/WebFlux 开发中的推荐用法。
• 可以在类级别和方法级别同时使用映射注解，类级别定义基础路径，方法级别定义相对路径。
• URL 路径通过 value 或 path 属性匹配，支持模式和路径变量 ({var})。
• HTTP 方法通过 method 属性（在 @RequestMapping 中）或选择特定的快捷注解（如 @GetMapping）来匹配。
• 请求参数通过 params 属性进行匹配。
• 请求头通过 headers 属性进行匹配。
• 请求体类型 (Content-Type) 通过 consumes 属性进行匹配。
• 可接受的响应类型 (Accept) 通过 produces 属性参与内容协商。