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

请求映射

在 Reactive 堆栈中查看 equivalentspring-doc.cadn.net.cn

您可以使用@RequestMapping注解将请求映射到控制器方法。它有 按 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 模式

在 Reactive 堆栈中查看 equivalentspring-doc.cadn.net.cn

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

  • PathPattern— 与 URL 路径匹配的预解析模式，也预先解析为PathContainer.该解决方案专为 Web 使用而设计，可有效地处理编码和 path 参数进行匹配，并有效地进行匹配。spring-doc.cadn.net.cn

  • AntPathMatcher— 将 String 模式与 String 路径匹配。这是原始的 解决方案也用于选择 Classpath 上的资源，在 filesystem 和其他位置。它的效率较低，并且 String path input 是一个 有效处理 URL 的编码和其他问题的挑战。spring-doc.cadn.net.cn

PathPattern是 Web 应用程序的推荐解决方案，也是 Spring WebFlux 的 Web Flux 中。从 5.3 版开始，它被允许在 Spring MVC 中使用，并通过 从 6.0 版本开始的默认值。请参阅 MVC 配置 路径匹配选项的自定义。spring-doc.cadn.net.cn

PathPattern支持与AntPathMatcher.此外，它还 支持捕获模式，例如{*spring}，用于匹配 0 个或多个路径段 在路径的末尾。PathPattern还限制了 for matching multiple 的使用 path segments 的 URL，以便只允许在 pattern 的末尾使用。这消除了许多 为给定请求选择最佳匹配模式时出现歧义的情况。 有关完整的模式语法，请参阅 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")），但您可以 如果名称相同，并且您的代码是使用-parameterscompiler 标志。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针对本地、系统、环境和 其他属性来源。例如，您可以使用它来根据 一些外部配置。spring-doc.cadn.net.cn

形态比较

在 Reactive 堆栈中查看 equivalentspring-doc.cadn.net.cn

当多个模式与一个 URL 匹配时，必须选择最佳匹配项。这是通过 以下之一，具体取决于是否使用 parsedPathPattern是否启用使用：spring-doc.cadn.net.cn

两者都有助于对模式进行排序，其中更具体的模式位于顶部。如果 它具有较少的 URI 变量（计为 1）、单个通配符（计为 1）、 和双通配符（计为 2）。如果得分相等，则选择较长的模式。 在给定相同的分数和长度的情况下，URI 变量多于通配符的模式为 选择。spring-doc.cadn.net.cn

默认映射模式 （） 从评分中排除，并且始终 最后排序。此外，前缀模式（例如/**/public/**） 被视为较小 specific than 其他没有双通配符的模式。spring-doc.cadn.net.cn

有关完整详细信息，请点击上述链接进入 Comparators 模式。spring-doc.cadn.net.cn

后缀匹配

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

当浏览器过去发送Accept头 这很难始终如一地解释。目前，这不再是必需的，并且 使用Acceptheader 应该是首选。spring-doc.cadn.net.cn

随着时间的推移，文件扩展名的使用已被证明以各种方式存在问题。 当与 URI 变量、路径参数和 URI 编码。基于 URL 的授权的推理 安全性（有关更多详细信息，请参阅下一节）也变得更加困难。spring-doc.cadn.net.cn

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

有一种方法可以请求内容类型，而不是通过"Accept"header 仍然可以 很有用，例如，在浏览器中键入 URL 时。路径扩展的安全替代方案是 以使用 Query Parameter 策略。如果必须使用文件扩展名，请考虑限制 它们通过mediaTypesContentNegotiationConfigurer 的属性。spring-doc.cadn.net.cn

后缀匹配和 RFD

反射文件下载 （RFD） 攻击与 XSS 类似，因为它依赖于请求输入 （例如，查询参数和 URI 变量）反映在响应中。但是，而不是 将 JavaScript 插入 HTML 中，RFD 攻击依赖于浏览器切换来执行 download 并在稍后双击时将响应视为可执行脚本。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 路径包含的文件扩展名既不是 允许作为 SAFE 或明确注册内容协商。但是，它可以 当 URL 直接输入到浏览器中时，可能会产生副作用。spring-doc.cadn.net.cn

默认情况下，许多常见的路径扩展名都是安全的。具有自定义HttpMessageConverter实现可以显式地为内容注册文件扩展名 negotiation 以避免出现Content-Disposition标头。 请参阅内容类型。spring-doc.cadn.net.cn

有关其他信息，请参阅 CVE-2015-5211 与 RFD 相关的建议。spring-doc.cadn.net.cn

易耗品介质类型

在 Reactive 堆栈中查看 equivalentspring-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属性按内容类型缩小映射范围。

这consumesattribute 还支持否定表达式 — 例如!text/plain指任何 内容类型不是text/plain.spring-doc.cadn.net.cn

您可以声明一个共享的consumes属性。与大多数其他 request-mapping 属性，但是，当在类级别使用时，方法级别的consumes属性 覆盖而不是扩展类级声明。spring-doc.cadn.net.cn

MediaType为常用媒体类型提供常量，例如APPLICATION_JSON_VALUE和APPLICATION_XML_VALUE.

可生产的培养基类型

在 Reactive 堆栈中查看 equivalentspring-doc.cadn.net.cn

您可以根据Acceptrequest 标头和 控制器方法生成的内容类型，如下例所示：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属性。与大多数其他 request-mapping 属性，但是，当在类级别使用时，方法级别的produces属性 覆盖而不是扩展类级声明。spring-doc.cadn.net.cn

MediaType为常用媒体类型提供常量，例如APPLICATION_JSON_VALUE和APPLICATION_XML_VALUE.

参数、标头

在 Reactive 堆栈中查看 equivalentspring-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.

您还可以将 SAME 与请求标头条件一起使用，如下例所示：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.
您可以匹配Content-Type和Accept使用 headers 条件，但最好改用 consumes 和 produces。

HTTP 头， 选项

在 Reactive 堆栈中查看 equivalentspring-doc.cadn.net.cn

@GetMapping（以及@RequestMapping(method=HttpMethod.GET)） 支持 HTTP HEAD transparently 进行请求映射。控制器方法不需要更改。 响应包装器，应用于jakarta.servlet.http.HttpServlet，请确保Content-Lengthheader 设置为写入的字节数（不实际写入响应）。spring-doc.cadn.net.cn

@GetMapping（以及@RequestMapping(method=HttpMethod.GET)） 隐式映射到 并支持 HTTP HEAD。HTTP HEAD 请求的处理方式与它是 HTTP GET 一样，但 而不是写入正文，而是计算字节数，并且Content-Lengthheader 的spring-doc.cadn.net.cn

默认情况下，HTTP OPTIONS 是通过设置Allow响应标头的 HTTP 列表 所有@RequestMapping方法。spring-doc.cadn.net.cn

对于@RequestMapping如果没有 HTTP 方法声明，则Allowheader 设置为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

自定义注释

在 Reactive 堆栈中查看 equivalentspring-doc.cadn.net.cn

Spring MVC 支持使用组合注释进行请求映射。这些注释本身是元注释的@RequestMapping并组合以重新声明@RequestMapping具有更狭窄、更具体目的的属性。spring-doc.cadn.net.cn

@GetMapping,@PostMapping,@PutMapping,@DeleteMapping和@PatchMapping是 组合注释的示例。提供这些 API 是因为可以说，大多数 控制器方法应该映射到特定的 HTTP 方法，而不是使用@RequestMapping, 默认情况下，它与所有 HTTP 方法匹配。如果你需要一个组合的示例 annotations 中，看看这些是怎么声明的。spring-doc.cadn.net.cn

Spring MVC 还支持具有自定义请求匹配的自定义请求映射属性 逻辑。这是一个更高级的选项，需要子类化RequestMappingHandlerMapping并覆盖getCustomMethodCondition方法，其中 您可以检查 custom 属性并返回您自己的RequestCondition.spring-doc.cadn.net.cn

显式注册

在 Reactive 堆栈中查看 equivalentspring-doc.cadn.net.cn

您可以通过编程方式注册处理程序方法，这些方法可用于动态 registrations 或高级情况，例如同一处理程序的不同实例 在不同的 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 注入 target handler 和 controller 的处理程序 Map。
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 注入 target handler 和 controller 的处理程序 Map。
2 准备请求映射元数据。
3 获取处理程序方法。
4 添加注册。