Mapping Requests

本部分讨论了带注解控制器的请求映射。

@RequestMapping

你可以使用 @RequestMapping 注解将请求映射到控制器方法。它具有各种属性，可根据 URL、HTTP 方法、请求参数、标头和媒体类型进行匹配。你可以在类级别使用它来表达共享映射，也可以在方法级别使用它来缩小到特定端点映射。

@RequestMapping 还存在 HTTP 方法特定的快捷方式变体：

  • @GetMapping

  • @PostMapping

  • @PutMapping

  • @DeleteMapping

  • @PatchMapping

快捷方式是 Custom Annotations，之所以提供此快捷方式是因为可以说大多数控制器方法应当映射到一个特定 HTTP 方法，而不是使用 @RequestMapping，它默认匹配所有 HTTP 方法。仍然需要在类级别使用 @RequestMapping 来表示共享映射。

@RequestMapping 不能与在同一元素（类、接口或方法）上声明的其他 @RequestMapping 注释结合使用。如果在同一元素上检测到多个 @RequestMapping 注释，将记录一条警告，并且只会使用第一个映射。这也适用于 @GetMapping、@PostMapping 等复合 @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 patterns

可以使用 URL 模式映射 @RequestMapping 方法。有两种选择：

  • PathPattern-一个预解析模式与 URL 路径进行匹配，同时 URL 路径也作为`PathContainer`预先解析。此解决方案专为 Web 使用而设计，可以有效地处理编码和路径参数，并进行高效匹配。

  • AntPathMatcher- 将字符串模式与字符串路径进行匹配。这是初始解决方案，还用于 Spring 配置，以选择类路径、文件系统和其他位置上的资源。它效率较低，并且在字符串路径输入中，对编码以及 URL 中的其他问题进行有效处理是一个挑战。

PathPattern 是适用于 Web 应用程序的推荐解决方案，并且是 Spring WebFlux 中唯一的选择。自版本 5.3 起，它已在 Spring MVC 中启用，且自版本 6.0 起默认启用。请参见 MVC config 了解路径匹配选项的自定义。

PathPattern 支持与 AntPathMatcher 相同的模式语法。此外，它还支持捕获模式，例如 {spring}, for matching 0 or more path segments at the end of a path. PathPattern also restricts the use of *，用于匹配多个路径段，因此它只允许在模式的末尾。当为给定的请求选择最佳匹配模式时，这消除了许多模棱两可的情况。有关完整的模式语法，请参考 PathPattern 和 AntPathMatcher。

一些示例模式：

  • "/resources/ima?e.png"- 匹配路径段中的一个字符

  • "/resources/*.png"- 匹配路径段中的零个或多个字符

  • "/resources/**"- 匹配多个路径段

  • "/projects/{project}/versions"——匹配路径片段并作为变量捕获它

  • "/projects/{project:[a-z]}/versions"+——用正则表达式匹配和捕获变量

可以通过 @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 等），您可以注册对任何其他数据类型提供支持。请参见 Type Conversion 和 DataBinder。

你可以显式命名 URI 变量（例如，@PathVariable("customId")），但是如果名称相同且你的代码是用 -parameters 编译器标志编译的，那么你可以省略该详细信息。

语法 {varName:regex} 用具有 {varName:regex} 语法的正则表达式声明一个 URI 变量。例如，给定 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。

Pattern Comparison

当多个模式匹配 URL 时，必须选择最佳匹配。这会通过以下方式之一完成，具体取决于是否启用使用已解析的 PathPattern：

两种方法都有助于排序模式，将更具体的模式排在顶部。如果 URI 变量数（算作 1 个）、单个通配符（算作 1 个）和双重通配符（算作 2 个）较少，则模式越具体。给定相同分数，选择较长的模式。在分数和长度相同的情况下，选择具有比通配符更多的 URI 变量的模式。

默认映射模式 (/) 被排除在评分之外，并且始终排在最后。此外，前缀模式（如 /public/）被认为不如没有双重通配符的其他模式具体。

有关完整详细信息，请按照上述链接访问模式比较器。

Suffix Match

从 5.3 开始，默认情况下，Spring MVC 不再执行 . 后缀模式匹配，其中映射到 /person 的控制器也隐式映射到 /person.。因此，路径扩展不再用于解释响应的请求内容类型，例如 /person.pdf、/person.xml 等。

当浏览器用于发送难以一致解释的 Accept 头时，需要以这种方式使用文件扩展名。目前，这不再是必需的，并且首选使用 Accept 头。

随着时间的推移，文件扩展名的使用已被证明在各种方式上存在问题。当与 URI 变量、路径参数和 URI 编码一起使用时，可能会导致歧义。基于 URL 的授权和安全性（有关更多详细信息，请参阅下一部分）的推理也变得更加困难。

要在 5.3 之前的版本中完全禁用路径扩展名的使用，请设置以下内容：

除了通过 "Accept" 头部以外，还有一种方法可以请求内容类型，例如在浏览器中键入 URL 时仍然有用。路径扩展的安全替代方法是使用查询参数策略。如果您必须使用文件扩展名，请考虑通过 mediaTypes 的 ContentNegotiationConfigurer 属性将它们限制为显式注册扩展名的列表。

Suffix Match and RFD

反射文件下载 (RFD) 攻击类似于 XSS，因为它依赖于请求输入（例如，查询参数和 URI 变量）反映在响应中。但是，RFD 攻击不是将 JavaScript 插入到 HTML 中，而是依赖于浏览器切换以执行下载，并在以后双击时将响应视为可执行脚本。

在 Spring MVC 中，@ResponseBody 和 ResponseEntity 方法存在风险，因为它们可以呈现不同的内容类型，客户端可以通过 URL 路径扩展名请求这些内容类型。禁用后缀模式匹配和使用路径扩展名进行内容协商可以降低风险，但不足以防止 RFD 攻击。

为了防止 RFD 攻击，Spring MVC 在呈现响应主体之前会添加一个 Content-Disposition:inline;filename=f.txt 头以建议一个固定且安全的下载文件。仅当 URL 路径包含既不被允许作为安全，也未明确为内容协商而注册的文件扩展名时，才会执行此操作。但是，当 URL 直接键入浏览器时，它可能会产生副作用。

许多常见的路径扩展被默认允许为安全。具有 custom`HttpMessageConverter` 实现的应用程序可显式注册文件扩展，以进行内容协商，以避免为这些扩展添加 Content-Disposition 标头。请参见 Content Types。

请参见 CVE-2015-5211 了解与 RFD 相关的其他建议。

Consumable Media Types

您可以根据请求的 Content-Type 缩小请求映射的范围，如下例所示：

Java
@PostMapping(path = "/pets", consumes = "application/json") (1)
public void addPet(@RequestBody Pet pet) {
	// ...
}
1 使用 `consumes`属性按内容类型缩小映射范围。
Kotlin
@PostMapping("/pets", consumes = ["application/json"]) (1)
fun addPet(@RequestBody pet: Pet) {
	// ...
}
2 使用 `consumes`属性按内容类型缩小映射范围。

consumes 属性还支持否定表达式，例如，!text/plain 表示除 text/plain 之外的任何内容类型。

您可以在类级别声明共享的 consumes 属性。但是，与大多数其他请求映射属性不同，当在类级别使用时，方法级 consumes 属性会覆盖类级声明，而不是对其进行扩展。

MediaType 提供常量，用于常用的媒体类型，例如 APPLICATION_JSON_VALUE 和 APPLICATION_XML_VALUE。

Producible Media Types

你可以根据 Accept 请求头和控制器方法生成的长度类型列表来缩小请求映射范围，如下例所示：

Java
@GetMapping(path = "/pets/{petId}", produces = "application/json") (1)
@ResponseBody
public Pet getPet(@PathVariable String petId) {
	// ...
}
1 使用 `produces`属性按内容类型缩小映射范围。
Kotlin
@GetMapping("/pets/{petId}", produces = ["application/json"]) (1)
@ResponseBody
fun getPet(@PathVariable petId: String): Pet {
	// ...
}
2 使用 `produces`属性按内容类型缩小映射范围。

媒体类型可以指定一个字符集。支持否定表达式 - 例如 !text/plain 表示除 "text/plain" 之外的任何内容类型。

你可以在类级别声明共享的 produces 属性。但是，与大多数其他请求映射属性不同，在类级别使用时，方法级别的 produces 属性覆盖而不是扩展类级别的声明。

MediaType 提供常量，用于常用的媒体类型，例如 APPLICATION_JSON_VALUE 和 APPLICATION_XML_VALUE。

Parameters, headers

你可以根据请求参数条件缩小请求映射范围。你可以测试请求参数（myParam）的存在、不存在（!myParam）或特定值（myParam=myValue）。以下示例展示了如何测试特定值：

Java
@GetMapping(path = "/pets/{petId}", params = "myParam=myValue") (1)
public void findPet(@PathVariable String petId) {
	// ...
}
1 测试 myParam`是否等于 `myValue。
Kotlin
@GetMapping("/pets/{petId}", params = ["myParam=myValue"]) (1)
fun findPet(@PathVariable petId: String) {
	// ...
}
2 测试 myParam`是否等于 `myValue。

你还可以使用与请求头的条件相同的条件，如下例所示：

Java
@GetMapping(path = "/pets/{petId}", headers = "myHeader=myValue") (1)
public void findPet(@PathVariable String petId) {
	// ...
}
1 测试 myHeader`是否等于 `myValue。
Kotlin
@GetMapping("/pets/{petId}", headers = ["myHeader=myValue"]) (1)
fun findPet(@PathVariable petId: String) {
	// ...
}
2 测试 myHeader`是否等于 `myValue。

您可以使用标头条件匹配 Content-Type 和 Accept，但最好使用 consumes 和 produces。

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。Controller 方法应始终声明受支持的 HTTP 方法（例如，通过使用特定于 HTTP 方法的变体：@GetMapping、@PostMapping 等）。

你可以将 @RequestMapping 方法明确映射到 HTTP HEAD 和 HTTP OPTIONS，但在一般情况下，这不是必需的。

Custom Annotations

Spring MVC 支持将 composed annotations 用于请求映射。这些是本身已通过 @RequestMapping 进行元注释并由更窄、更具体目的的 @RequestMapping 属性的子集（或全部）重新声明的注释。

@GetMapping、@PostMapping、@PutMapping、@DeleteMapping 和 @PatchMapping 是复合注释的示例。之所以提供这些注释，是因为可以说，大多数控制器方法都应映射到特定 HTTP 方法，而不是使用默认情况下与所有 HTTP 方法相匹配的 @RequestMapping。如果你需要一个如何实现复合注释的示例，请查看这些注释是如何声明的。

@RequestMapping 不能与在同一元素（类、接口或方法）上声明的其他 @RequestMapping 注释结合使用。如果在同一元素上检测到多个 @RequestMapping 注释，将记录一条警告，并且只会使用第一个映射。这也适用于 @GetMapping、@PostMapping 等复合 @RequestMapping 注释。

Spring MVC 还支持带有自定义请求匹配逻辑的自定义请求映射属性。这是一个更高级的选项，需要对 RequestMappingHandlerMapping 进行子类化并覆盖 getCustomMethodCondition 方法，在该方法中你可以检查自定义属性并返回你自己的 RequestCondition。

Explicit Registrations

你可以以编程方式注册处理程序方法，这些方法可用于动态注册或高级场景，例如不同 URL 下相同处理程序的不同实例。以下示例注册了一个处理程序方法：

Java
@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 Get the handler method.
4 Add the registration.
Kotlin
@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)
	}
}
5 为控制器注入目标处理程序和处理程序映射。
6 准备请求映射元数据。
7 Get the handler method.
8 Add the registration.

@HttpExchange

虽然 @HttpExchange 的主要目的是使用生成的代理抽象 HTTP 客户端代码，但是放置此类注释的 HTTP Interface 是一个对于客户端和服务器使用而言呈中立态度的合约。除了简化客户端代码之外，还有部分情况下，一个 HTTP 接口可能是一种便利的方法，让服务器为客户端访问公开其 API。这会导致客户端与服务器耦合度升高，对于公共 API，这往往不是一个好选择，但对于内部 API 来说，它可能正是目标。这在 Spring Cloud 中是一种常用的方法，这也是 @HttpExchange 作为服务器端处理的替代方案在控制器类中受支持的原因。

例如：

  • 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 的列表。