|
此版本仍在开发中，尚未被视为稳定版。如需最新稳定版本，请使用 Spring Framework 7.0.6！ |
映射请求
本节讨论带注解控制器的请求映射。
@RequestMapping
你可以使用 @RequestMapping 注解将请求映射到控制器方法。它提供了多种属性，可用于根据 URL、HTTP 方法、请求参数、请求头和媒体类型进行匹配。你可以在类级别上使用该注解以表达共享的映射，也可以在方法级别上使用以精确指定某个端点的映射。
此外，还有针对特定 HTTP 方法的 @RequestMapping 快捷变体：
-
@GetMapping -
@PostMapping -
@PutMapping -
@DeleteMapping -
@PatchMapping
这些快捷方式是自定义注解，
之所以提供它们，是因为可以说大多数控制器方法都应该映射到特定的
HTTP 方法，而不是使用默认情况下匹配所有 HTTP 方法的 @RequestMapping。
在类级别上仍然需要使用 @RequestMapping 来表达共享的映射。
@RequestMapping 不能与在同一元素（类、接口或方法）上声明的其他 @RequestMapping 注解一起使用。如果在同一个元素上检测到多个 @RequestMapping 注解，系统将记录一条警告，并且仅使用第一个映射。此规则也适用于组合型的 @RequestMapping 注解，例如 @GetMapping、@PostMapping 等。 |
以下示例包含类型级别和方法级别的映射：
-
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 配置。
AntPathMatcher 变体现在已被弃用，因为它效率较低，而且字符串路径输入在有效处理 URL 编码及其他相关问题方面存在困难。 |
你可以使用通配符模式（glob patterns）和通配符来映射请求：
| 模式 | 描述 | 例举 |
|---|---|---|
|
字面量模式 |
|
|
匹配一个字符 |
|
|
匹配路径段中的零个或多个字符 |
|
|
匹配零个或多个路径段 |
|
|
类似于 |
|
|
将正则表达式 |
|
|
类似于 |
|
可以使用 @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}")
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/**）被认为比那些不包含双通配符的其他模式更不具体。
有关完整详情，请点击上方链接查看模式比较器（Pattern Comparators）。
后缀匹配和 RFD
反射型文件下载（RFD）攻击与 XSS 类似，都是依赖于请求输入（例如查询参数和 URI 变量）在响应中被反射。然而，与将 JavaScript 插入 HTML 不同的是，RFD 攻击利用浏览器切换为下载模式，并在用户后续双击该文件时将其作为可执行脚本处理。
在 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
-
Kotlin
@PostMapping(path = "/pets", consumes = "application/json") (1)
public void addPet(@RequestBody Pet pet) {
// ...
}| 1 | 使用 consumes 属性根据内容类型来缩小映射范围。 |
@PostMapping("/pets", consumes = ["application/json"]) (1)
fun addPet(@RequestBody pet: Pet) {
// ...
}| 1 | 使用 consumes 属性根据内容类型来缩小映射范围。 |
consumes 属性也支持否定表达式 —— 例如，!text/plain 表示除 text/plain 之外的任何内容类型。
你可以在类级别声明一个共享的 consumes 属性。然而，与其他大多数请求映射属性不同的是，当在类级别使用时，方法级别的 consumes 属性会覆盖而不是扩展类级别的声明。
MediaType 提供了常用媒体类型的常量，例如
APPLICATION_JSON_VALUE 和 APPLICATION_XML_VALUE。 |
可生成的媒体类型
您可以根据 Accept 请求头以及控制器方法所生成的内容类型列表来缩小请求映射的范围，如下例所示：
-
Java
-
Kotlin
@GetMapping(path = "/pets/{petId}", produces = "application/json") (1)
@ResponseBody
public Pet getPet(@PathVariable String petId) {
// ...
}| 1 | 使用 produces 属性根据内容类型来缩小映射范围。 |
@GetMapping("/pets/{petId}", produces = ["application/json"]) (1)
@ResponseBody
fun getPet(@PathVariable petId: String): Pet {
// ...
}| 1 | 使用 produces 属性根据内容类型来缩小映射范围。 |
媒体类型可以指定字符集。支持否定表达式——例如，!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。 |
API 版本
没有指定 API 版本的标准方式，因此当你在MVC 配置中启用 API 版本控制时， 需要指定如何解析版本。MVC 配置会创建一个 ApiVersionStrategy，该策略随后用于映射请求。
一旦启用了 API 版本控制，你就可以开始将请求映射到特定版本。
@RequestMapping 注解的 version 属性支持以下内容：
-
固定版本（“1.2”）——仅匹配指定的版本
-
基准版本（“1.2+”）——匹配上述给定的和受支持的版本
-
无值 — 匹配任意版本，但会被更具体的版本匹配所取代
如果多个控制器方法的版本号小于或等于请求的版本号，则会选择其中版本号最高、且最接近请求版本号的方法，实际上会取代其余方法。
为说明这一点，请考虑以下映射：
-
Java
@RestController
@RequestMapping("/account/{id}")
public class AccountController {
@GetMapping (1)
public Account getAccount() {
}
@GetMapping(version = "1.1") (2)
public Account getAccount1_1() {
}
@GetMapping(version = "1.2+") (3)
public Account getAccount1_2() {
}
@GetMapping(version = "1.5") (4)
public Account getAccount1_5() {
}
}| 1 | 匹配任意版本 |
| 2 | 匹配版本 1.1 |
| 3 | 匹配版本 1.2 及以上支持的版本 |
| 4 | 匹配版本 1.5 |
对于版本为 "1.3" 的请求：
-
(1) 匹配，因为它匹配任意版本
-
(2) 不匹配
-
(3) 符合条件，因为它匹配 1.2 及以上版本，并且作为最高匹配版本被选中
-
(4) 更高，且不匹配
| 版本 1.3 必须出现在映射中，或者被配置为受支持的版本。 |
对于版本为 "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 响应头设置为所有具有匹配 URL 模式的 @RequestMapping 方法中列出的 HTTP 方法列表。
对于未声明 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。如果你需要一个实现组合注解的示例，可以查看这些注解的声明方式。
@RequestMapping 不能与在同一元素（类、接口或方法）上声明的其他 @RequestMapping 注解一起使用。如果在同一个元素上检测到多个 @RequestMapping 注解，系统将记录一条警告，并且仅使用第一个映射。此规则也适用于组合型的 @RequestMapping 注解，例如 @GetMapping、@PostMapping 等。 |
Spring MVC 还支持使用自定义请求匹配逻辑的自定义请求映射属性。这是一种更高级的选项，需要继承 RequestMappingHandlerMapping 类并重写 getCustomMethodCondition 方法，在该方法中你可以检查自定义属性并返回你自己的 RequestCondition。
显式注册
您可以以编程方式注册处理方法，这可用于动态注册或高级场景，例如在不同 URL 下注册同一处理程序的不同实例。以下示例注册了一个处理方法：
-
Java
-
Kotlin
@Configuration
public class MyConfiguration {
// Inject the target handler and the handler mapping for controllers
@Autowired
public void setHandlerMapping(RequestMappingHandlerMapping mapping, UserHandler handler)
throws NoSuchMethodException {
// Prepare the request mapping meta data
RequestMappingInfo info = RequestMappingInfo
.paths("/user/{id}").methods(RequestMethod.GET).build();
// Get the handler method
Method method = UserHandler.class.getMethod("getUser", Long.class);
// Add the registration
mapping.registerMapping(info, handler, method);
}
}@Configuration
class MyConfiguration {
// Inject the target handler and the handler mapping for controllers
@Autowired
fun setHandlerMapping(mapping: RequestMappingHandlerMapping, handler: UserHandler) {
// Get the handler method
val info = RequestMappingInfo.paths("/user/{id}").methods(RequestMethod.GET).build()
// Get the handler method
val method = UserHandler::class.java.getMethod("getUser", Long::class.java)
// Add the registration
mapping.registerMapping(info, handler, method)
}
}@HttpExchange
虽然 @HttpExchange 的主要目的是通过生成的代理来抽象 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 所支持的完整语法。