|
对于最新稳定版本，请使用 Spring Framework 7.0.6！ |
请求映射
@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 模式
你可以使用通配符模式（glob patterns）和通配符来映射请求：
| 模式 | <description> </description> | 例举 |
|---|---|---|
|
匹配一个字符 |
|
|
匹配路径段中的零个或多个字符 |
|
|
匹配零个或多个路径段，直到路径结束 |
|
|
匹配一个路径段，并将其捕获为名为“name”的变量 |
|
|
将正则表达式 |
|
|
匹配零个或多个路径段，直到路径结束，并将其捕获为名为“path”的变量 |
|
可以使用 @PathVariable 访问捕获的 URI 变量，如下例所示：
-
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}") (1)
public class OwnerController {
@GetMapping("/pets/{petId}") (2)
public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) {
// ...
}
}| 1 | 类级别的 URI 映射。 |
| 2 | 方法级别的 URI 映射。 |
@Controller
@RequestMapping("/owners/{ownerId}") (1)
class OwnerController {
@GetMapping("/pets/{petId}") (2)
fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet {
// ...
}
}| 1 | 类级别的 URI 映射。 |
| 2 | 方法级别的 URI 映射。 |
URI 变量会自动转换为适当的类型，否则将抛出 TypeMismatchException。默认支持简单类型（int、long、Date 等），您也可以注册对其他任何数据类型的支持。
请参阅 类型转换 和 DataBinder。
URI 变量可以显式命名（例如，@PathVariable("customId")），但如果变量名称相同，并且你使用 -parameters 编译器标志编译代码，则可以省略该细节。
语法 {*varName} 声明一个 URI 变量，用于匹配零个或多个剩余的路径段。例如，/resources/{*path} 会匹配 /resources/ 下的所有文件，且 "path" 变量会捕获 /resources 下的完整路径。
语法 {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 version, @PathVariable String ext) {
// ...
}@GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}")
fun handle(@PathVariable version: String, @PathVariable ext: String) {
// ...
}URI 路径模式还可以包含嵌入的 ${…} 占位符，这些占位符在启动时通过 PropertySourcesPlaceholderConfigurer 从本地、系统、环境及其他属性源中进行解析。例如，你可以利用此功能根据某些外部配置对基础 URL 进行参数化。
Spring WebFlux 使用 PathPattern 和 PathPatternParser 来提供 URI 路径匹配支持。
这两个类都位于 spring-web 模块中，专为在 Web 应用程序中处理 HTTP URL 路径而设计，适用于运行时需要匹配大量 URI 路径模式的场景。 |
Spring WebFlux 不支持后缀模式匹配 —— 与 Spring MVC 不同，在 Spring MVC 中，像 /person 这样的映射也会匹配 /person.*。如果需要基于 URL 的内容协商，我们建议使用查询参数，这种方式更简单、更明确，并且不易受到基于 URL 路径的攻击。
模式对比
当多个模式匹配同一个 URL 时，必须对它们进行比较以找出最佳匹配。这是通过 PathPattern.SPECIFICITY_COMPARATOR 实现的，它会寻找更加具体的模式。
对于每个模式，都会根据 URI 变量和通配符的数量计算一个得分，其中 URI 变量的得分低于通配符。总得分较低的模式胜出。如果两个模式得分相同，则选择较长的那个。
通配模式（例如，**、{*varName}）不参与评分，并始终排在最后。如果两个模式都是通配模式，则选择较长的那个。
可消费的媒体类型
您可以根据请求的 Content-Type 来缩小请求映射的范围，如下例所示：
-
Java
-
Kotlin
@PostMapping(path = "/pets", consumes = "application/json")
public void addPet(@RequestBody Pet pet) {
// ...
}@PostMapping("/pets", consumes = ["application/json"])
fun addPet(@RequestBody pet: Pet) {
// ...
}!text/plain 属性也支持否定表达式——例如，text/plain 表示除 2 之外的任何内容类型。
你可以在类级别声明一个共享的 consumes 属性。然而，与大多数其他请求映射属性不同的是，当在类级别使用时，方法级别的 consumes 属性会覆盖而非扩展类级别的声明。
MediaType 提供了常用媒体类型的常量——例如，
APPLICATION_JSON_VALUE 和 APPLICATION_XML_VALUE。 |
可生成的媒体类型
您可以根据 Accept 请求头以及控制器方法所生成的内容类型列表来缩小请求映射的范围，如下例所示：
-
Java
-
Kotlin
@GetMapping(path = "/pets/{petId}", produces = "application/json")
@ResponseBody
public Pet getPet(@PathVariable String petId) {
// ...
}@GetMapping("/pets/{petId}", produces = ["application/json"])
@ResponseBody
fun getPet(@PathVariable petId: String): Pet {
// ...
}媒体类型可以指定字符集。支持否定表达式——例如，!text/plain 表示除 text/plain 之外的任何内容类型。
你可以在类级别声明一个共享的 produces 属性。然而，与大多数其他请求映射属性不同的是，当在类级别使用时，方法级别的 produces 属性会覆盖而不是扩展类级别的声明。
MediaType 提供了常用媒体类型的常量——例如
APPLICATION_JSON_VALUE、APPLICATION_XML_VALUE。 |
参数和请求头
您可以根据查询参数条件来缩小请求映射的范围。您可以测试某个查询参数是否存在（myParam）、是否不存在（!myParam），或者是否具有特定值（myParam=myValue）。以下示例测试的是一个带有特定值的参数：
-
Java
-
Kotlin
@GetMapping(path = "/pets/{petId}", params = "myParam=myValue") (1)
public void findPet(@PathVariable String petId) {
// ...
}| 1 | 检查 myParam 是否等于 myValue。 |
@GetMapping("/pets/{petId}", params = ["myParam=myValue"]) (1)
fun findPet(@PathVariable petId: String) {
// ...
}| 1 | 检查 myParam 是否等于 myValue。 |
你也可以将其与请求头条件一起使用，如下例所示：
-
Java
-
Kotlin
@GetMapping(path = "/pets/{petId}", headers = "myHeader=myValue") (1)
public void findPet(@PathVariable String petId) {
// ...
}| 1 | 检查 myHeader 是否等于 myValue。 |
@GetMapping("/pets/{petId}", headers = ["myHeader=myValue"]) (1)
fun findPet(@PathVariable petId: String) {
// ...
}| 1 | 检查 myHeader 是否等于 myValue。 |
HTTP HEAD, OPTIONS
@GetMapping 和 @RequestMapping(method=HttpMethod.GET) 在请求映射方面对 HTTP HEAD 方法提供透明支持。控制器方法无需做任何更改。
在 HttpHandler 服务器适配器中应用的一个响应包装器，可确保设置 Content-Length 头部为实际写入的字节数，而无需真正向响应中写入内容。
默认情况下，HTTP OPTIONS 请求的处理方式是将 Allow 响应头设置为所有具有匹配 URL 模式的 @RequestMapping 方法中列出的 HTTP 方法列表。
对于未声明 HTTP 方法的 @RequestMapping，Allow 响应头将被设置为
GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS。控制器方法应始终明确声明所支持的 HTTP 方法（例如，通过使用特定于 HTTP 方法的注解变体——@GetMapping、@PostMapping 等）。
你可以显式地将 @RequestMapping 方法映射到 HTTP HEAD 和 HTTP OPTIONS，但在一般情况下并不需要这样做。
自定义注解
Spring WebFlux 支持使用组合注解进行请求映射。这些注解本身使用 @RequestMapping 进行元注解，并通过组合方式重新声明 @RequestMapping 的部分（或全部）属性，以实现更窄、更具体的目的。
@GetMapping、@PostMapping、@PutMapping、@DeleteMapping 和 @PatchMapping 是组合注解的示例。提供这些注解是因为，可以说，大多数控制器方法应当映射到特定的 HTTP 方法，而不是使用默认匹配所有 HTTP 方法的 @RequestMapping。如果你需要组合注解的示例，可以查看这些注解的声明方式。
Spring WebFlux 还支持使用自定义请求匹配逻辑的自定义请求映射属性。这是一种更高级的选项，需要继承 RequestMappingHandlerMapping 类并重写 getCustomMethodCondition 方法，在该方法中你可以检查自定义属性并返回你自己的 RequestCondition。
显式注册
您可以以编程方式注册处理方法（Handler methods），这可用于动态注册或高级场景，例如在不同 URL 下注册同一处理程序的不同实例。以下示例展示了如何实现这一点：
-
Java
-
Kotlin
@Configuration
public class MyConfig {
@Autowired
public void setHandlerMapping(RequestMappingHandlerMapping mapping, UserHandler handler) (1)
throws NoSuchMethodException {
RequestMappingInfo info = RequestMappingInfo
.paths("/user/{id}").methods(RequestMethod.GET).build(); (2)
Method method = UserHandler.class.getMethod("getUser", Long.class); (3)
mapping.registerMapping(info, handler, method); (4)
}
}| 1 | 注入目标处理器和控制器的处理器映射。 |
| 2 | 准备请求映射元数据。 |
| 3 | 获取处理方法。 |
| 4 | 添加注册信息。 |
@Configuration
class MyConfig {
@Autowired
fun setHandlerMapping(mapping: RequestMappingHandlerMapping, handler: UserHandler) { (1)
val info = RequestMappingInfo.paths("/user/{id}").methods(RequestMethod.GET).build() (2)
val method = UserHandler::class.java.getMethod("getUser", Long::class.java) (3)
mapping.registerMapping(info, handler, method) (4)
}
}| 1 | 注入目标处理器和控制器的处理器映射。 |
| 2 | 准备请求映射元数据。 |
| 3 | 获取处理方法。 |
| 4 | 添加注册信息。 |