映射请求

查看在响应式堆栈中的等效内容

本节讨论注解控制器的请求映射。

@RequestMapping

查看在响应式堆栈中的等效内容

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

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

  • @GetMapping

  • @PostMapping

  • @PutMapping

  • @DeleteMapping

  • @PatchMapping

这些快捷方式是提供的自定义注解，因为可以说，大多数控制器方法应该映射到特定的HTTP方法，而不是使用@RequestMapping，后者默认匹配所有HTTP方法。在类级别仍然需要一个@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模式进行映射。有两种选择：

  • PathPattern — 一个预解析的模式，与URL路径进行匹配，也预解析为PathContainer。设计用于Web使用，这个解决方案有效地处理编码和路径参数，并且匹配效率高。

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

PathPattern 是Web应用程序的推荐解决方案，也是Spring WebFlux中的唯一选择。从版本5.3开始，它已被启用用于Spring MVC，并且从版本6.0开始默认启用。查看MVC配置以自定义路径匹配选项。

PathPattern 支持与AntPathMatcher相同的模式语法。此外，它还支持捕获模式，例如{*spring}，用于匹配路径末尾的0个或多个路径段。 PathPattern 还限制了使用**来匹配多个路径段，只允许在模式的末尾使用。这消除了在选择给定请求的最佳匹配模式时许多歧义的情况。有关完整的模式语法，请参阅PathPattern和AntPathMatcher。

一些示例模式：

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

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

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

  • "/projects/{project}/versions" - 匹配一个路径段并将其捕获为变量

  • "/projects/{project:[a-z]+}/versions" - 匹配并捕获带有正则表达式的变量

捕获的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。

模式比较

查看在响应式堆栈中的等效内容

当多个模式匹配一个URL时，必须选择最佳匹配。这取决于是否启用了解析的PathPattern，可以使用以下之一：

两者都有助于对具有更具体模式的模式进行排序。如果模式具有较低数量的URI变量（计为1）、单个通配符（计为1）和双通配符（计为2），则该模式更具体。在得分相等的情况下，选择更长的模式。在得分和长度相同的情况下，选择具有比通配符更多的URI变量的模式。

默认映射模式（/**）不计入评分，始终排在最后。此外，前缀模式（例如/public/**）被认为比没有双通配符的其他模式不够具体。

有关完整详情，请查看上述链接到模式比较器。

后缀匹配

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

在浏览器发送难以一致解释的Accept标头时，以这种方式使用文件扩展名是必要的。目前，这不再是必要的，使用Accept标头应该是首选选择。

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

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

在某些情况下，通过"Accept"标头以外的方式请求内容类型仍然很有用，例如在浏览器中键入URL。路径扩展名的一个安全替代方案是使用查询参数策略。如果必须使用文件扩展名，请考虑通过ContentNegotiationConfigurer的mediaTypes属性将其限制为一组明确注册的扩展名。

后缀匹配和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

  • 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。
您可以使用头部条件匹配Content-Type和Accept，但最好使用consumes和produces代替。

HTTP HEAD, OPTIONS

查看在响应式堆栈中的等效内容

@GetMapping（和@RequestMapping(method=HttpMethod.GET)）支持HTTP HEAD透明地进行请求映射。控制器方法无需更改。应用在jakarta.servlet.http.HttpServlet中的响应包装器确保将Content-Length头设置为写入的字节数（实际上不写入响应）。

默认情况下，通过将Allow响应头设置为所有具有匹配URL模式的@RequestMapping方法中列出的HTTP方法列表来处理HTTP OPTIONS。

对于没有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方法，而不是使用@RequestMapping，后者默认匹配所有HTTP方法。如果您需要一个组合注解的实现示例，请查看如何声明这些注解。

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

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

显式注册

查看在响应式堆栈中的等效内容

您可以以编程方式注册处理程序方法，用于动态注册或高级情况，例如在不同的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 添加注册。

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