对于最新稳定版本，请使用 Spring Framework 7.0.6！spring-doc.cadn.net.cn

请求映射

参见响应式栈中的等效内容spring-doc.cadn.net.cn

你可以使用 @RequestMapping 注解将请求映射到控制器方法。它提供了多种属性，可用于根据 URL、HTTP 方法、请求参数、请求头和媒体类型进行匹配。你可以在类级别上使用该注解以表达共享的映射，也可以在方法级别上使用以精确指定某个端点的映射。spring-doc.cadn.net.cn

此外，还有针对特定 HTTP 方法的 @RequestMapping 快捷变体：spring-doc.cadn.net.cn

这些快捷方式是自定义注解，之所以提供它们，是因为可以说大多数控制器方法都应该映射到特定的 HTTP 方法，而不是使用默认情况下匹配所有 HTTP 方法的 @RequestMapping。 在类级别上仍然需要使用 @RequestMapping 来表达共享的映射。spring-doc.cadn.net.cn

以下示例包含类型级别和方法级别的映射：spring-doc.cadn.net.cn

@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 模式

参见响应式栈中的等效内容spring-doc.cadn.net.cn

@RequestMapping 方法可以使用 URL 模式进行映射。有两种替代方案：spring-doc.cadn.net.cn

  • PathPattern — 一种预先解析的模式，用于匹配同样以 PathContainer 形式预先解析的 URL 路径。该方案专为 Web 使用而设计，能有效处理编码和路径参数，并高效地进行匹配。spring-doc.cadn.net.cn

  • AntPathMatcher — 将字符串路径与字符串模式进行匹配。这是最初的解决方案，Spring 配置中也使用它来选择类路径、文件系统及其他位置上的资源。该方案效率较低，且字符串形式的路径输入在有效处理 URL 编码及其他相关问题方面存在挑战。spring-doc.cadn.net.cn

PathPattern 是 Web 应用程序的推荐解决方案，并且是 Spring WebFlux 中唯一的选择。从 Spring MVC 5.3 版本开始，它已被启用使用，并从 6.0 版本起默认启用。有关路径匹配选项的自定义配置，请参阅MVC 配置。spring-doc.cadn.net.cn

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

一些示例模式：spring-doc.cadn.net.cn

可以使用 @PathVariable 访问捕获的 URI 变量。例如：spring-doc.cadn.net.cn

@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 变量，如下例所示：spring-doc.cadn.net.cn

@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。spring-doc.cadn.net.cn

你可以显式地命名 URI 变量（例如，@PathVariable("customId")），但如果变量名称相同，并且你的代码是使用 -parameters 编译器标志编译的，那么可以省略这一细节。spring-doc.cadn.net.cn

语法 {varName:regex} 声明了一个带有正则表达式的 URI 变量，其语法为 {varName:regex}。例如，对于 URL "/spring-web-3.0.5.jar"，以下方法可提取出名称、版本号和文件扩展名：spring-doc.cadn.net.cn

@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 进行参数化。spring-doc.cadn.net.cn

模式对比

参见响应式栈中的等效内容spring-doc.cadn.net.cn

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

两者都有助于对模式进行排序，将更具体的模式排在前面。如果一个模式的 URI 变量数量（计为 1）、单通配符数量（计为 1）和双通配符数量（计为 2）的总分更低，则认为该模式更具体。在得分相同的情况下，选择更长的模式。如果得分和长度都相同，则优先选择 URI 变量数量多于通配符数量的模式。spring-doc.cadn.net.cn

默认的映射模式（/**）在评分时会被排除，并始终排在最后。此外，前缀模式（例如 /public/**）被认为比那些不包含双通配符的其他模式更不具体。spring-doc.cadn.net.cn

有关完整详情，请点击上方链接查看模式比较器（Pattern Comparators）。spring-doc.cadn.net.cn

后缀匹配

从 5.3 版本开始，默认情况下 Spring MVC 不再执行 .* 后缀模式匹配，即映射到 /person 的控制器不再隐式地同时映射到 /person.*。因此，路径扩展名不再用于解析响应所请求的内容类型——例如 /person.pdf、/person.xml 等。spring-doc.cadn.net.cn

以这种方式使用文件扩展名在以前是必要的，因为浏览器发送的 Accept 请求头难以一致地解析。如今，这种做法已不再必要，应当优先选择使用 Accept 请求头。spring-doc.cadn.net.cn

随着时间的推移，使用文件扩展名在多个方面被证明存在问题。 当与URI变量、路径参数以及URI编码结合使用时，可能会引起歧义。 基于URL的授权和安全性（更多详细信息请参见下一节）也变得更加复杂。spring-doc.cadn.net.cn

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

除了通过 "Accept" 请求头之外，拥有其他方式来请求内容类型仍然很有用，例如在浏览器中直接输入 URL 时。一种安全的替代路径扩展名的方法是使用查询参数策略。如果您必须使用文件扩展名，请考虑通过 ContentNegotiationConfigurer 的 ../mvc-config/content-negotiation.html 属性，将扩展名限制为一组显式注册的扩展名列表。spring-doc.cadn.net.cn

后缀匹配和 RFD

反射型文件下载（RFD）攻击与 XSS 类似，都是依赖于请求输入（例如查询参数和 URI 变量）在响应中被反射。然而，与将 JavaScript 插入 HTML 不同的是，RFD 攻击利用浏览器切换为下载模式，并在用户后续双击该文件时将其作为可执行脚本处理。spring-doc.cadn.net.cn

在 Spring MVC 中，@ResponseBody 和 ResponseEntity 方法存在风险，因为它们可以渲染不同的内容类型，而客户端可以通过 URL 路径扩展名来请求这些内容类型。 禁用后缀模式匹配并将路径扩展名用于内容协商可以降低风险，但不足以完全防止 RFD 攻击。spring-doc.cadn.net.cn

为了防止RFD攻击，Spring MVC在渲染响应体之前，会添加一个Content-Disposition:inline;filename=f.txt头部，以建议使用一个固定且安全的下载文件名。此操作仅在URL路径包含的文件扩展名既未被列为安全扩展名，也未在内容协商中显式注册时才会执行。然而，当用户直接在浏览器中输入URL时，该机制可能会产生潜在的副作用。spring-doc.cadn.net.cn

默认情况下，许多常见的路径扩展名被视为安全而被允许。使用自定义 HttpMessageConverter 实现的应用程序可以显式注册用于内容协商的文件扩展名，以避免为这些扩展名添加 Content-Disposition 响应头。 参见 内容类型。spring-doc.cadn.net.cn

有关RFD的更多建议，请参见CVE-2015-5211。spring-doc.cadn.net.cn

可消费的媒体类型

参见响应式栈中的等效内容spring-doc.cadn.net.cn

您可以根据请求的 Content-Type 来缩小请求映射的范围，如下例所示：spring-doc.cadn.net.cn

@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 之外的任何内容类型。spring-doc.cadn.net.cn

你可以在类级别声明一个共享的 consumes 属性。然而，与其他大多数请求映射属性不同的是，当在类级别使用时，方法级别的 consumes 属性会覆盖而不是扩展类级别的声明。spring-doc.cadn.net.cn

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

可生成的媒体类型

参见响应式栈中的等效内容spring-doc.cadn.net.cn

您可以根据 Accept 请求头以及控制器方法所生成的内容类型列表来缩小请求映射的范围，如下例所示：spring-doc.cadn.net.cn

@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" 之外的任何内容类型。spring-doc.cadn.net.cn

你可以在类级别声明一个共享的 produces 属性。然而，与其他大多数请求映射属性不同的是，当在类级别使用时，方法级别的 produces 属性会覆盖而不是扩展类级别的声明。spring-doc.cadn.net.cn

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

参数，请求头

参见响应式栈中的等效内容spring-doc.cadn.net.cn

您可以根据请求参数条件来缩小请求映射的范围。您可以测试某个请求参数是否存在（myParam）、是否不存在（!myParam），或者是否具有特定值（myParam=myValue）。以下示例展示了如何测试参数是否具有特定值：spring-doc.cadn.net.cn

@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。

你也可以将其与请求头条件一起使用，如下例所示：spring-doc.cadn.net.cn

@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。
你可以使用 headers 条件来匹配 Content-Type 和 Accept，但更好的做法是使用 consumes 和 <produces。

HTTP HEAD, OPTIONS

参见响应式栈中的等效内容spring-doc.cadn.net.cn

@GetMapping（以及 @RequestMapping(method=HttpMethod.GET)）在请求映射中透明地支持 HTTP HEAD 方法。控制器方法无需做任何改动。 一个应用于 jakarta.servlet.http.HttpServlet 的响应包装器会确保设置 Content-Length 头部，其值为写入的字节数（而实际上并不向响应中写入内容）。spring-doc.cadn.net.cn

@GetMapping（以及 @RequestMapping(method=HttpMethod.GET)）会隐式映射并支持 HTTP HEAD 请求。HTTP HEAD 请求的处理方式与 HTTP GET 相同，区别在于不会写入响应体，而是计算字节数并设置 Content-Length 响应头。spring-doc.cadn.net.cn

默认情况下，HTTP OPTIONS 请求的处理方式是将 Allow 响应头设置为所有具有匹配 URL 模式的 @RequestMapping 方法中列出的 HTTP 方法列表。spring-doc.cadn.net.cn

对于未声明 HTTP 方法的 @RequestMapping，Allow 响应头将被设置为 GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS。控制器方法应始终明确声明所支持的 HTTP 方法（例如，通过使用特定于 HTTP 方法的注解变体： @GetMapping、@PostMapping 等）。spring-doc.cadn.net.cn

你可以显式地将 @RequestMapping 方法映射到 HTTP HEAD 和 HTTP OPTIONS，但在一般情况下并不需要这样做。spring-doc.cadn.net.cn

自定义注解

参见响应式栈中的等效内容spring-doc.cadn.net.cn

Spring MVC 支持使用组合注解进行请求映射。这些注解本身使用 @RequestMapping 进行元注解，并通过组合方式重新声明 @RequestMapping 注解的部分（或全部）属性，以实现更窄、更具体的目的。spring-doc.cadn.net.cn

@GetMapping、@PostMapping、@PutMapping、@DeleteMapping 和 @PatchMapping 是组合注解（composed annotations）的示例。之所以提供这些注解，是因为可以认为大多数控制器方法应当映射到特定的 HTTP 方法，而不是使用默认情况下匹配所有 HTTP 方法的 @RequestMapping。如果你需要组合注解的示例，请查看这些注解的声明方式。spring-doc.cadn.net.cn

Spring MVC 还支持使用自定义请求匹配逻辑的自定义请求映射属性。这是一种更高级的选项，需要继承 RequestMappingHandlerMapping 类并重写 getCustomMethodCondition 方法，在该方法中你可以检查自定义属性并返回你自己的 RequestCondition。spring-doc.cadn.net.cn

显式注册

参见响应式栈中的等效内容spring-doc.cadn.net.cn

您可以以编程方式注册处理方法，这可用于动态注册或高级场景，例如在不同 URL 下注册同一处理程序的不同实例。以下示例注册了一个处理方法：spring-doc.cadn.net.cn

@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 添加注册信息。