版本：7.0.3

本站内所有文档均为中英对照文档，点击中文可以显示英文。此提醒连续关闭5次后，将不再显示。

文档内容来源于 spring.io，由 springdoc.tech 翻译，版权归属于 SPRING.IO (Broadcom. Inc)。可供个人学习、研究，未经许可，不得进行转载或用于商业行为。

映射请求

Hunyuan 7b 中英对照 Mapping Requests

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

`@RequestMapping`

你可以使用@RequestMapping注解来将请求映射到控制器的方法上。该注解具有多种属性，可以根据URL、HTTP方法、请求参数、请求头和媒体类型来进行匹配。你可以在类级别使用它来定义通用的映射规则，也可以在方法级别使用它来指定特定的端点映射。

@RequestMapping 还有以下针对特定 HTTP 方法的快捷变体：

@GetMapping
@PostMapping
@PutMapping
@DeleteMapping
@PatchMapping

这些快捷方式是自定义注释，之所以提供这些快捷方式，是因为大多数控制器方法应该被映射到特定的HTTP方法上，而不是使用@RequestMapping（默认情况下，@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模式

参见Reactive堆栈中的等效内容

@RequestMapping 方法可以通过 URL 模式来映射。Spring MVC 使用的是 PathPattern——这是一种预先解析的模式，会与也作为 PathContainer 预先解析的 URL 路径进行匹配。这种专为 Web 使用而设计的解决方案能够有效处理编码和路径参数，并且匹配效率很高。有关路径匹配选项的定制，请参阅 MVC 配置。

备注

AntPathMatcher 变体现已过时，因为它的效率较低，而且使用字符串路径输入在处理编码和其他与 URL 相关的问题时会遇到困难。

你可以通过使用通配符模式（glob patterns）和通配字符（wildcards）来匹配请求：

| 模式 | 描述 | 示例 |
| :----------------:|-------------------------------------------------------------------: |
| spring | 字面量模式 | "/spring" 与 "/spring" 匹配 |
| ? | 匹配一个字符 | "/pages/t?st.html" 与 "/pages/test.html" 以及 "/pages/t3st.html" 匹配 |
| * | 匹配路径段中的零个或多个字符 | "/resources/*.png" 与 "/resources/file.png" 匹配

"/projects/*/versions" 与 "/projects/spring/versions" 匹配，但不与 "/projects/spring/boot/versions" 匹配。

"/projects/*" 与 "/projects/spring" 匹配，但由于路径段不存在，所以不与 "/projects" 匹配 |
| ** | 匹配零个或多个路径段 | "/resources/**" 与 "/resources", "/resources/file.png" 以及 "/resources/images/file.png" 匹配

"/**/info" 与 "/info", "/spring/info" 以及 "/spring/framework/info" 匹配

"/resources/**/file.png" 是无效的，因为路径中间不允许使用 **。

"/**/spring/**" 是不允许的，因为每个模式中只允许出现一个 **/{*path} 的组合 |
| {name} | 与 * 类似，但还会将路径段捕获为名为 "name" 的变量 | "/projects/{project}/versions" 与 "/projects/spring/versions" 匹配，并捕获 project=spring

"/projects/{project}/versions" 不与 "/projects/spring/framework/versions" 匹配，因为它只捕获了一个路径段 |
| {name:[a-z]+} | 匹配正则表达式 [a-z]+，并将其作为名为 "name" 的路径变量捕获 | "/projects/{project:[a-z]+}/versions" 与 "/projects/spring/versions" 匹配，但不与 "/projects/spring1/versions" 匹配 |
| {*path} | 与 ** 类似，但也会将路径段捕获为名为 "path" 的变量 | "/resources/{*file}" 与 "/resources/images/file.png" 匹配，并捕获 file=/images/file.png

"{*path}/resources" 与 "/spring/framework/resources" 匹配，并捕获 path=/spring/framework

"/resources/{*path}/file.png" 是无效的，因为路径中间不允许使用 {*path}。

"/{*path}/spring/**" 是不允许的，因为每个模式中只允许出现一个 **/{*path} 的组合 |

可以使用@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等），你也可以注册对其他数据类型的支持。请参阅类型转换和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。
SpEL 表达式 #{…}。

模式比较

参见Reactive栈中的等效内容

当多个模式与一个URL匹配时，必须选择最佳匹配项。根据是否启用了解析后的PathPattern的使用，可以通过以下方法之一来完成这一操作：

两者都有助于对模式进行排序，其中更具体的模式会排在更前面。一个模式越具体，其URI变量的数量就越少（每个URI变量计为1分），单个通配符的数量也越少（每个通配符计为1分），而双通配符的数量则更多（每个双通配符计为2分）。在得分相同的情况下，会选择更长的模式；在得分和长度都相同的情况下，则会选择URI变量数量多于通配符数量的模式。

默认的匹配模式（/**）不计入评分范围，且总是被排在最后。此外，前缀模式（如 /public/**）被认为不如那些没有双通配符的模式具体（即匹配范围更宽）。

如需完整详情，请点击上述链接查看模式比较器（Pattern Comparators）。

后缀匹配和RFD

反射文件下载（RFD）攻击与XSS攻击类似，因为它依赖于请求输入（例如查询参数和URI变量）在响应中被反射出来。然而，与在HTML中插入JavaScript不同，RFD攻击利用浏览器在双击时切换到执行下载操作，并将响应视为可执行脚本来实施攻击。

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

为了防止RFD攻击，Spring MVC在渲染响应体之前会添加一个Content-Disposition:inline;filename=f.txt头部信息，以建议用户下载一个固定且安全的文件。这一操作仅在URL路径中包含的文件扩展名既不被视为安全的，也没有被明确注册用于内容协商时才会执行。然而，当用户直接在浏览器中输入URL时，这可能会产生副作用。

默认情况下，许多常见的路径扩展名都被视为安全的。具有自定义 HttpMessageConverter 实现的应用程序可以显式注册文件扩展名以进行内容协商，从而避免为这些扩展名添加 Content-Disposition 头部信息。请参阅内容类型。

有关RFD的更多建议，请参阅CVE-2015-5211。

可消耗媒体类型

参见Reactive堆栈中的等效内容

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

Java
Kotlin

@PostMapping(path = "/pets", consumes = "application/json") 1
public void addPet(@RequestBody Pet pet) {
	// ...
}

使用 consumes 属性根据内容类型来限定映射。

@PostMapping("/pets", consumes = ["application/json"]) 1
fun addPet(@RequestBody pet: Pet) {
	// ...
}

使用 consumes 属性根据内容类型来限定映射。

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

你可以在类级别声明一个共享的 consumes 属性。然而，与大多数其他请求映射属性不同，当在类级别使用 consumes 属性时，方法级别的 consumes 属性会覆盖而不是继承类级别的声明。

提示

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

可生产的媒体类型

参见Reactive堆栈中的等效内容

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

Java
Kotlin

@GetMapping(path = "/pets/{petId}", produces = "application/json") 1
@ResponseBody
public Pet getPet(@PathVariable String petId) {
	// ...
}

使用 produces 属性根据内容类型来限定映射。

@GetMapping("/pets/{petId}", produces = ["application/json"]) 1
@ResponseBody
fun getPet(@PathVariable petId: String): Pet {
	// ...
}

使用 produces 属性根据内容类型来限定映射。

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

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

提示

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

参数、头部信息

参见Reactive栈中的等效内容

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

Java
Kotlin

@GetMapping(path = "/pets/{petId}", params = "myParam=myValue") 1
public void findPet(@PathVariable String petId) {
	// ...
}

测试 myParam 是否等于 myValue。

@GetMapping("/pets/{petId}", params = ["myParam=myValue"]) 1
fun findPet(@PathVariable petId: String) {
	// ...
}

测试 myParam 是否等于 myValue。

您也可以将相同的方法用于请求头条件，如下例所示：

Java
Kotlin

@GetMapping(path = "/pets/{petId}", headers = "myHeader=myValue") 1
public void findPet(@PathVariable String petId) {
	// ...
}

测试 myHeader 是否等于 myValue。

@GetMapping("/pets/{petId}", headers = ["myHeader=myValue"]) 1
fun findPet(@PathVariable petId: String) {
	// ...
}

测试 myHeader 是否等于 myValue。

提示

你可以使用头部条件来匹配 Content-Type 和 Accept，但更好的是使用 consumes 和 produces。

API版本

参见Reactive堆栈中的等效内容

没有标准的方法来指定API版本，因此当你在MVC配置中启用API版本控制时，你需要指定如何解析版本。MVC配置会创建一个ApiVersionStrategy，该策略随后被用来映射请求。

一旦启用了API版本控制，你就可以开始将请求与版本关联起来。@RequestMapping的version属性支持以下几种配置：

固定版本（“1.2”）——仅匹配给定版本
基线版本（“1.2+”）——匹配给定版本及以上版本
无值（“”）——匹配任何版本，但会被更具体的版本匹配规则所替代

如果多个控制器方法的版本小于或等于请求的版本，并且其中有一个版本的数值最高且最接近请求的版本，那么这个方法将被视为有效的方法，实际上会取代其他方法。

为了说明这一点，考虑以下映射：

Java

@RestController
@RequestMapping("/account/{id}")
public class AccountController {

	@GetMapping 1
	public Account getAccount() {
	}

	@GetMapping(version = "1.1") 2
	public Account getAccount1_1() {
	}

	@GetMapping.version = "1.2+") 3
	public Account getAccount1_2() {
	}

	@GetMapping versión = "1.5") 4
	public Account getAccount1_5() {
	}
}

匹配任意版本
匹配版本 1.1
匹配版本 1.2 及以上
\ [#4] 匹配版本 1.5

对于版本为“1.3”的请求：

(1) 匹配，因为它与任何版本都匹配。
(2) 不匹配。
(3) 匹配，因为它与1.2及以上版本匹配，并且被选中为最高匹配项。
(4) 更高版本，但不匹配。

对于版本为“1.5”的请求：

(1) 匹配，因为它能匹配任何版本
(2) 不匹配
(3) 匹配，因为它能匹配1.2及以上版本
(4) 匹配，并且被选择为最佳匹配项

版本为“1.6”的请求没有匹配项。（1）和（3）有匹配项，但被（4）所取代，（4）只允许严格匹配，因此也没有匹配到。在这种情况下，NotAcceptableApiVersionException会导致400响应。

没有版本的控制器方法旨在支持在引入带版本控制的替代方法之前创建的客户端。因此，尽管一个没有版本的控制器方法被认为可以与任何版本匹配，但实际上它会被赋予最低的优先级，并且实际上会被任何带有版本的替代控制器方法所取代。

备注

上述内容假设请求的版本是 "支持的" 版本，否则将会失败。

有关底层基础设施和API版本控制的支持的更多详细信息，请参阅API版本控制。

HTTP HEAD, OPTIONS

参见Reactive栈中的等效内容

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

你可以明确地将@RequestMapping方法映射到HTTP HEAD和HTTP OPTIONS请求上，但在常见情况下这并不是必需的。

自定义注解

请参见Reactive堆栈中的等效内容

Spring MVC支持使用组合注解来进行请求映射。这些注解本身又被元注解@RequestMapping所标注，通过组合这些注解可以重新声明一部分（或全部）@RequestMapping属性，使其具有更具体、更狭窄的用途。

@GetMapping, @PostMapping, @PutMapping, @DeleteMapping, 和 @PatchMapping 是组合注解（composed annotations）的例子。提供这些注解的原因是，大多数控制器方法应该被映射到特定的 HTTP 方法上，而不是使用默认会匹配所有 HTTP 方法的 @RequestMapping。如果你需要了解如何实现组合注解的示例，可以看看这些注解是如何声明的。

备注

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

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

显式注册

请参阅Reactive栈中的对应内容

你可以通过编程方式注册处理方法，这些方法可以用于动态注册，或者用于更复杂的情况，例如在不同的URL下使用同一个处理方法的不同实例。以下示例展示了一个处理方法的注册过程：

Java
Kotlin

@Configuration
public class MyConfiguration {

	// Inject the target handler and the handler mapping for controllers
	@Autowired
	public void setHandlerMapping(RequestMappingHandlerMapping mapping, UserHandler handler)
			throws NoSuchMethodException {

		// Prepare the request mapping meta data
		RequestMappingInfo info = RequestMappingInfo
				.paths("/user/{id}").methods(RequestMethod.GET).build();

		// Get the handler method
		Method method = UserHandler.class.getMethod("getUser", Long.class);

		// Add the registration
		mapping.registerMapping(info, handler, method);
	}
}

@Configuration
class MyConfiguration {

	// Inject the target handler and the handler mapping for controllers
	@Autowired
	fun setHandlerMapping(mapping: RequestMappingHandlerMapping, handler: UserHandler) {

		// Get the handler method
		val info = RequestMappingInfo.paths("/user/{id}").methods(RequestMethod.GET).build()

		// Get the handler method
		val method = UserHandler::class.java.getMethod("getUser", Long::class.java)

		// Add the registration
		mapping.registerMapping(info, handler, method)
	}
}

`@HttpExchange`

请参见Reactive栈中的等效内容

虽然@HttpExchange的主要目的是通过生成的代理来抽象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中的列表。

@HttpExchange 还支持一个 headers() 参数，该参数可以接受类似 "name=value" 的键值对，类似于客户端上的 @RequestMapping(headers={})。在服务器端，这一功能扩展到了 @RequestMapping 支持的完整语法。

@RequestMapping​

URI模式​

模式比较​

后缀匹配和RFD​

可消耗媒体类型​

可生产的媒体类型​

参数、头部信息​

API版本​

HTTP HEAD, OPTIONS​

自定义注解​

显式注册​

@HttpExchange​

`@RequestMapping`

URI模式

模式比较

后缀匹配和RFD

可消耗媒体类型

可生产的媒体类型

参数、头部信息

API版本

HTTP HEAD, OPTIONS

自定义注解

显式注册

`@HttpExchange`