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

请求映射

请参阅响应式栈中的等效项spring-doc.cadn.net.cn

您可以使用@注解将请求映射到控制器方法。它有多种属性可以匹配URL、HTTP方法、请求参数、头信息和媒体类型。您可以在类级别使用它来表达共享映射，也可以在方法级别使用它来缩小到特定的端点映射。spring-doc.cadn.net.cn

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

快捷方式是 自定义注解，之所以提供它们， 可以说，大多数控制器方法应该映射到特定的HTTP方法，而不是 使用 @RequestMapping，默认情况下，它会匹配所有HTTP方法。 仍然需要一个 @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 — 一个预先解析的模式，用于匹配URL路径，也预先解析为 PathContainer。专为网络使用设计，该解决方案能有效处理编码和路径参数，并且匹配效率高。spring-doc.cadn.net.cn

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

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

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

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

捕获的URI变量可以通过 @PathVariable 访问。例如：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

有关详细信息，请按照上述链接前往模式比较器部分。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的mediaTypes属性限制它们为显式注册的扩展名列表。spring-doc.cadn.net.cn

后缀匹配和RFD

反射文件下载（RFD）攻击与跨站脚本（XSS）攻击类似，因为它依赖于请求输入（例如，查询参数和URI变量）在响应中被反射。然而，与在HTML中插入JavaScript不同，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

请参阅 CVE-2015-5211 了解有关RFD的其他建议。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 属性来根据内容类型缩小映射范围。

The 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

对于一个@RequestMapping没有HTTP方法声明，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 是组合注解的例子。它们被提供是因为，可以说，大多数控制器方法应该映射到特定的HTTP方法，而不是使用 @RequestMapping，后者默认匹配所有HTTP方法。如果你需要组合注解的例子，看看这些是如何声明的。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 添加注册。