映射请求
本节讨论注解控制器的请求映射。
@RequestMapping
您可以使用 @RequestMapping 注解将请求映射到控制器方法。它具有各种属性，
可以根据 URL、HTTP 方法、请求参数、请求头和媒体类型进行匹配。您可以在类级别
使用它来表达共享映射，或者在方法级别使用它来缩小到特定的端点映射。
还有 HTTP 方法特定的 @RequestMapping 快捷变体：
-
@GetMapping -
@PostMapping -
@PutMapping -
@DeleteMapping -
@PatchMapping
这些快捷方式是
组合注解，
之所以提供它们，是因为可以说，大多数控制器方法应该映射到特定的 HTTP 方法，
而不是使用默认匹配所有 HTTP 方法的 @RequestMapping。
类级别仍然需要 @RequestMapping 来表达共享映射。
|
|
以下示例包含类型级别和方法级别映射：
-
Java
-
Kotlin
@RestController
@RequestMapping("/persons")
class PersonController {
@GetMapping("/{id}")
public Person getPerson(@PathVariable Long id) {
// ...
}
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
public void add(@RequestBody Person person) {
// ...
}
}@RestController
@RequestMapping("/persons")
class PersonController {
@GetMapping("/{id}")
fun getPerson(@PathVariable id: Long): Person {
// ...
}
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
fun add(@RequestBody person: Person) {
// ...
}
}URI 模式
@RequestMapping 方法可以使用 URL 模式进行映射。
Spring MVC 使用 PathPattern —— 一个预解析的模式，与预解析为 PathContainer 的 URL 路径进行匹配。
该解决方案专为 Web 使用而设计，能有效处理编码和路径参数，并高效匹配。
有关路径匹配选项的自定义，请参阅 MVC 配置。
|
|
您可以使用 glob 模式和通配符来映射请求：
| 模式 | 描述 | 示例 |
|---|---|---|
|
字面模式 |
|
|
匹配一个字符 |
|
|
匹配路径段内的零个或多个字符 |
|
|
匹配零个或多个路径段 |
|
|
匹配一个路径段并将其捕获为名为 "name" 的变量 |
|
|
匹配正则表达式 |
|
|
匹配零个或多个路径段并将其捕获为名为 "path" 的变量 |
|
捕获的 URI 变量可以通过 @PathVariable 访问。例如：
-
Java
-
Kotlin
@GetMapping("/owners/{ownerId}/pets/{petId}")
public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) {
// ...
}@GetMapping("/owners/{ownerId}/pets/{petId}")
fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet {
// ...
}您可以在类级别和方法级别声明 URI 变量，如以下示例所示：
-
Java
-
Kotlin
@Controller
@RequestMapping("/owners/{ownerId}")
public class OwnerController {
@GetMapping("/pets/{petId}")
public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) {
// ...
}
}@Controller
@RequestMapping("/owners/{ownerId}")
class OwnerController {
@GetMapping("/pets/{petId}")
fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet {
// ...
}
}URI 变量会自动转换为适当的类型，否则会引发 TypeMismatchException。
默认支持简单类型（int、long、Date 等），您可以注册对任何其他数据类型的支持。
请参阅 类型转换 和 DataBinder。
您可以显式命名 URI 变量（例如，@PathVariable("customId")），但如果名称相同并且您的代码使用 -parameters 编译器标志编译，则可以省略该细节。
语法 {varName:regex} 声明了一个带有正则表达式的 URI 变量，其语法为 {varName:regex}。
例如，给定 URL "/spring-web-3.0.5.jar"，以下方法提取名称、版本和文件扩展名：
-
Java
-
Kotlin
@GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}")
public void handle(@PathVariable String name, @PathVariable String version, @PathVariable String ext) {
// ...
}@GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}")
fun handle(@PathVariable name: String, @PathVariable version: String, @PathVariable ext: String) {
// ...
}URI 路径模式还可以包含：
-
嵌入的
${…}占位符，这些占位符在启动时通过PropertySourcesPlaceholderConfigurer根据本地、系统、环境和其他属性源进行解析。这对于例如根据外部配置参数化基本 URL 非常有用。 -
SpEL 表达式
#{…}。
模式比较
当多个模式匹配一个 URL 时，必须选择最佳匹配。这通过以下方式之一完成，具体取决于是否启用了解析后的 PathPattern：
两者都有助于对模式进行排序，更具体的模式排在前面。如果一个模式的 URI 变量（计为 1）、单通配符（计为 1）和双通配符（计为 2）的数量较低，则该模式更具体。 在得分相同的情况下，选择较长的模式。在得分和长度相同的情况下，选择 URI 变量多于通配符的模式。
默认映射模式 (/) 不参与评分，并且始终排在最后。此外，前缀模式（例如 /public/）被认为比没有双通配符的其他模式不那么具体。
有关完整详细信息，请点击上述链接查看模式比较器。
后缀匹配和 RFD
反射文件下载 (RFD) 攻击类似于 XSS，因为它依赖于请求输入（例如，查询参数和 URI 变量）在响应中被反射。 然而，RFD 攻击不是将 JavaScript 插入 HTML，而是依赖于浏览器切换到执行下载并将响应视为可执行脚本（稍后双击时）。
在 Spring MVC 中，@ResponseBody 和 ResponseEntity 方法存在风险，因为它们可以呈现不同的内容类型，客户端可以通过 URL 路径扩展请求这些内容类型。
禁用后缀模式匹配并使用路径扩展进行内容协商可以降低风险，但不足以防止 RFD 攻击。
为了防止 RFD 攻击，在渲染响应正文之前，Spring MVC 会添加 Content-Disposition:inline;filename=f.txt 头，以建议一个固定且安全的下载文件。
这仅在 URL 路径包含的文件扩展名既不允许安全使用也未明确注册用于内容协商时才执行。
然而，当 URL 直接输入浏览器时，这可能会产生副作用。
许多常见的路径扩展名默认允许安全使用。具有自定义 HttpMessageConverter 实现的应用程序可以明确注册用于内容协商的文件扩展名，以避免为这些扩展名添加 Content-Disposition 头。
请参阅 内容类型。
有关 RFD 的其他建议，请参阅 CVE-2015-5211。
可消费的媒体类型
您可以根据请求的 Content-Type 缩小请求映射，如以下示例所示：
- Java
-
@PostMapping(path = "/pets", consumes = "application/json") [id="CO1-1"][id="CO1-1"][id="CO1-1"](1) public void addPet(@RequestBody Pet pet) { // ... }
<1> 使用 `consumes` 属性通过内容类型缩小映射范围。
- Kotlin
-
@PostMapping("/pets", consumes = ["application/json"]) [id="CO2-1"][id="CO1-2"][id="CO2-1"](1) fun addPet(@RequestBody pet: Pet) { // ... }
<1> 使用 `consumes` 属性通过内容类型缩小映射范围。
consumes 属性还支持否定表达式——例如，!text/plain 表示除了 text/plain 之外的任何内容类型。
您可以在类级别声明一个共享的 consumes 属性。然而，与大多数其他请求映射属性不同，当在类级别使用时，方法级别的 consumes 属性会覆盖而不是扩展类级别的声明。
|
|
可生产的媒体类型
您可以根据 Accept 请求头和控制器方法生成的内容类型列表缩小请求映射，如以下示例所示：
- Java
-
@GetMapping(path = "/pets/{petId}", produces = "application/json") [id="CO3-1"][id="CO1-3"][id="CO3-1"](1) @ResponseBody public Pet getPet(@PathVariable String petId) { // ... }
<1> 使用 `produces` 属性通过内容类型缩小映射范围。
- Kotlin
-
@GetMapping("/pets/{petId}", produces = ["application/json"]) [id="CO4-1"][id="CO1-4"][id="CO4-1"](1) @ResponseBody fun getPet(@PathVariable petId: String): Pet { // ... }
<1> 使用 `produces` 属性通过内容类型缩小映射范围。
媒体类型可以指定字符集。支持否定表达式——例如，!text/plain 表示除了 "text/plain" 之外的任何内容类型。
您可以在类级别声明一个共享的 produces 属性。然而，与大多数其他请求映射属性不同，当在类级别使用时，方法级别的 produces 属性会覆盖而不是扩展类级别的声明。
|
|
参数，请求头
您可以根据请求参数条件缩小请求映射。您可以测试请求参数是否存在 (myParam)、不存在 (!myParam) 或具有特定值 (myParam=myValue)。以下示例展示了如何测试特定值：
- Java
-
@GetMapping(path = "/pets/{petId}", params = "myParam=myValue") [id="CO5-1"][id="CO1-5"][id="CO5-1"](1) public void findPet(@PathVariable String petId) { // ... }
<1> 测试 `myParam` 是否等于 `myValue`。
- Kotlin
-
@GetMapping("/pets/{petId}", params = ["myParam=myValue"]) [id="CO6-1"][id="CO1-6"][id="CO6-1"](1) fun findPet(@PathVariable petId: String) { // ... }
<1> 测试 `myParam` 是否等于 `myValue`。
您也可以对请求头条件使用相同的方法，如以下示例所示：
- Java
-
@GetMapping(path = "/pets/{petId}", headers = "myHeader=myValue") [id="CO7-1"][id="CO1-7"][id="CO7-1"](1) public void findPet(@PathVariable String petId) { // ... }
<1> 测试 `myHeader` 是否等于 `myValue`。
- Kotlin
-
@GetMapping("/pets/{petId}", headers = ["myHeader=myValue"]) [id="CO8-1"][id="CO1-8"][id="CO8-1"](1) fun findPet(@PathVariable petId: String) { // ... }
<1> 测试 `myHeader` 是否等于 `myValue`。
API 版本
没有标准的方法来指定 API 版本，因此当您在 MVC 配置 中启用 API 版本控制时， 您需要指定如何解析版本。MVC 配置会创建一个 ApiVersionStrategy， 该策略反过来用于映射请求。
一旦启用了 API 版本控制，您就可以开始使用版本映射请求。
@RequestMapping 的 version 属性支持以下内容：
-
无值 — 匹配任何版本
-
固定版本 ("1.2") — 仅匹配给定版本
-
基线版本 ("1.2+") — 匹配给定版本及以上
如果多个控制器方法的版本小于或等于请求版本，则选择其中最高且最接近请求版本的那个， 从而取代其余的。
为了说明这一点，请考虑以下映射：
- Java
-
@RestController @RequestMapping("/account/{id}") public class AccountController { @GetMapping [id="CO9-1"][id="CO1-9"][id="CO9-1"](1) public Account getAccount() { } @GetMapping(version = "1.1") [id="CO9-2"][id="CO1-10"][id="CO9-2"](2) public Account getAccount1_1() { } @GetMapping(version = "1.2+") [id="CO9-3"][id="CO1-11"][id="CO9-3"](3) public Account getAccount1_2() { } @GetMapping(version = "1.5") [id="CO9-4"][id="CO1-12"][id="CO9-4"](4) public Account getAccount1_5() { } }
<1> 匹配任何版本 <1> 匹配版本 1.1 <1> 匹配版本 1.2 及以上 <1> 匹配版本 1.5
对于版本为 "1.3" 的请求：
-
(1) 匹配，因为它匹配任何版本
-
(2) 不匹配
-
(3) 匹配，因为它匹配 1.2 及以上，并被 选中 为最高匹配
-
(4) 更高且不匹配
对于版本为 "1.5" 的请求：
-
(1) 匹配，因为它匹配任何版本
-
(2) 不匹配
-
(3) 匹配，因为它匹配 1.2 及以上
-
(4) 匹配并被 选中 为最高匹配
版本为 "1.6" 的请求没有匹配项。(1) 和 (3) 确实匹配，但被 (4) 取代，(4) 只允许严格匹配，因此不匹配。
在这种情况下，NotAcceptableApiVersionException 会导致 400 响应。
|
以上假设请求版本是 "支持的" 版本，否则会失败。 |
有关底层基础结构和 API 版本控制支持的更多详细信息，请参阅 API 版本控制。
HTTP HEAD, OPTIONS
@GetMapping (和 @RequestMapping(method=HttpMethod.GET)) 透明地支持 HTTP HEAD 用于请求映射。
控制器方法不需要更改。在 jakarta.servlet.http.HttpServlet 中应用的响应包装器确保 Content-Length
头设置为写入的字节数（实际上不写入响应）。
默认情况下，HTTP OPTIONS 通过将 Allow 响应头设置为所有 @RequestMapping 方法中列出的 HTTP 方法列表来处理，这些方法具有匹配的 URL 模式。
对于没有 HTTP 方法声明的 @RequestMapping，Allow 头设置为 GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS。
控制器方法应始终声明支持的 HTTP 方法（例如，通过使用 HTTP 方法特定的变体：@GetMapping、@PostMapping 等）。
您可以显式将 @RequestMapping 方法映射到 HTTP HEAD 和 HTTP OPTIONS，但在常见情况下没有必要。
自定义注解
Spring MVC 支持使用 组合注解 进行请求映射。
这些注解本身被 @RequestMapping 元注解注释，并组合以重新声明 @RequestMapping 属性的子集（或全部），
具有更窄、更具体的目的。
@GetMapping、@PostMapping、@PutMapping、@DeleteMapping 和 @PatchMapping 是组合注解的示例。
提供它们的原因是，可以说，大多数控制器方法应该映射到特定的 HTTP 方法，而不是使用默认匹配所有 HTTP 方法的 @RequestMapping。
如果您需要一个如何实现组合注解的示例，请查看它们是如何声明的。
|
|
Spring MVC 还支持带有自定义请求匹配逻辑的自定义请求映射属性。
这是一个更高级的选项，需要子类化 RequestMappingHandlerMapping 并覆盖 getCustomMethodCondition 方法，
您可以在其中检查自定义属性并返回自己的 RequestCondition。
显式注册
您可以以编程方式注册处理程序方法，这可用于动态注册或高级用例， 例如在不同 URL 下使用相同处理程序的不同实例。以下示例注册了一个处理程序方法：
- Java
-
@Configuration public class MyConfig { @Autowired public void setHandlerMapping(RequestMappingHandlerMapping mapping, UserHandler handler) [id="CO10-1"][id="CO1-13"][id="CO10-1"](1) throws NoSuchMethodException { RequestMappingInfo info = RequestMappingInfo .paths("/user/{id}").methods(RequestMethod.GET).build(); [id="CO10-2"][id="CO1-14"][id="CO10-2"](2) Method method = UserHandler.class.getMethod("getUser", Long.class); [id="CO10-3"][id="CO1-15"][id="CO10-3"](3) mapping.registerMapping(info, handler, method); [id="CO10-4"][id="CO1-16"][id="CO10-4"](4) } }
<1> 注入目标处理程序和控制器的处理程序映射。 <1> 准备请求映射元数据。 <1> 获取处理程序方法。 <1> 添加注册。
- Kotlin
-
@Configuration class MyConfig { @Autowired fun setHandlerMapping(mapping: RequestMappingHandlerMapping, handler: UserHandler) { [id="CO11-1"][id="CO1-17"][id="CO11-1"](1) val info = RequestMappingInfo.paths("/user/{id}").methods(RequestMethod.GET).build() [id="CO11-2"][id="CO1-18"][id="CO11-2"](2) val method = UserHandler::class.java.getMethod("getUser", Long::class.java) [id="CO11-3"][id="CO1-19"][id="CO11-3"](3) mapping.registerMapping(info, handler, method) [id="CO11-4"][id="CO1-20"][id="CO11-4"](4) } }
<1> 注入目标处理程序和控制器的处理程序映射。 <1> 准备请求映射元数据。 <1> 获取处理程序方法。 <1> 添加注册。
@HttpExchange
虽然 @HttpExchange 的主要目的是通过生成的代理抽象 HTTP 客户端代码，但
HTTP 接口（放置此类注解的位置）是
一种与客户端与服务器使用无关的契约。除了简化客户端代码外，在某些情况下，HTTP 接口
也可能是服务器公开其 API 以供客户端访问的便捷方式。这会导致客户端和服务器之间耦合增加，
通常不是一个好的选择，特别是对于公共 API，但对于内部 API 来说可能正是目标。
这是 Spring Cloud 中常用的一种方法，这也是为什么 @HttpExchange 作为
@RequestMapping 的替代方案在控制器类中支持服务器端处理的原因。
例如：
-
Java
-
Kotlin
@HttpExchange("/persons")
interface PersonService {
@GetExchange("/{id}")
Person getPerson(@PathVariable Long id);
@PostExchange
void add(@RequestBody Person person);
}
@RestController
class PersonController implements PersonService {
public Person getPerson(@PathVariable Long id) {
// ...
}
@ResponseStatus(HttpStatus.CREATED)
public void add(@RequestBody Person person) {
// ...
}
}@HttpExchange("/persons")
interface PersonService {
@GetExchange("/{id}")
fun getPerson(@PathVariable id: Long): Person
@PostExchange
fun add(@RequestBody person: Person)
}
@RestController
class PersonController : PersonService {
override fun getPerson(@PathVariable id: Long): Person {
// ...
}
@ResponseStatus(HttpStatus.CREATED)
override fun add(@RequestBody person: Person) {
// ...
}
}@HttpExchange 和 @RequestMapping 存在差异。
@RequestMapping 可以通过路径模式、HTTP 方法等映射到任意数量的请求，而 @HttpExchange 声明一个具有具体 HTTP 方法、路径和内容类型的单个端点。
对于方法参数和返回值，通常，@HttpExchange 支持 @RequestMapping 的方法参数子集。
值得注意的是，它排除了任何服务器端特定的参数类型。有关详细信息，请参阅
@HttpExchange 和
@RequestMapping 的列表。
@HttpExchange 还支持 headers() 参数，该参数接受 "name=value" 形式的键值对，
类似于客户端的 @RequestMapping(headers={})。在服务器端，这扩展到
<<`@RequestMapping`,mvc-ann-requestmapping-params-and-headers>> 支持的完整语法。