版本：7.0.3

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

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

映射请求

Hunyuan 7b 中英对照 Mapping Requests

参见Servlet堆栈中的等效内容

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

`@RequestMapping`

请参阅Servlet栈中的等效内容

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

请参阅Servlet堆栈中的等效内容

您可以使用通配符和wildcard（通常写作“*”）来匹配请求：

模式	描述	示例
`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}` 的组合。

捕获的 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}") 1
public class OwnerController {

	@GetMapping("/pets/{petId}") 2
	public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) {
		// ...
	}
}

类级 URI 映射。
方法级 URI 映射。

@Controller
@RequestMapping("/owners/{ownerId}") 1
class OwnerController {

	@GetMapping("/pets/{petId}") 2
_fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet {
		// ...
	}
}

类级 URI 映射。
方法级 URI 映射。

URI变量会自动转换为相应的类型，否则将抛出TypeMismatchException异常。默认支持简单类型（如int、long、Date等），你也可以注册对其他任何数据类型的支持。请参阅类型转换和DataBinder。

URI变量可以明确指定名称（例如，@PathVariable("customId")），但如果名称相同，你也可以省略这一细节，并使用-parameters编译器标志来编译代码。

语法 {*varName} 声明了一个 URI 变量，该变量可以匹配零个或多个剩余的路径段。例如 /resources/{*path} 可以匹配 /resources/ 下的所有文件，而 „path“ 变量则会捕获 /resources/ 下的完整路径。

语法 {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 version, @PathVariable String ext) {
	// ...
}

@GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}")
fun handle(@PathVariable version: String, @PathVariable ext: String) {
	// ...
}

URI路径模式还可以包含：

嵌入的 ${…} 占位符在启动时会通过 PropertySources PlaceholderConfigurer 从本地、系统、环境以及其他属性源中获取对应的值。例如，这可以用来根据外部配置来参数化基础URL。
SpEL 表达式 #{…}。

备注

Spring WebFlux使用PathPattern和PathPatternParser来支持URI路径匹配。这两个类都位于spring-web包中，专门为在Web应用程序中处理大量运行时需要匹配的URI路径而设计。

Spring WebFlux不支持后缀模式匹配——与Spring MVC不同，在Spring MVC中，像 /person 这样的映射也会匹配到 /person.*。如果需要进行基于URL的内容协商，我们建议使用查询参数，这种方式更简单、更明确，而且不易受到基于URL路径的攻击的影响。

模式比较

请参阅Servlet栈中的等效内容

当多个模式与一个URL匹配时，必须进行比较以找到最佳匹配项。这是通过PathPattern.SPECIFICITY_COMPARATOR来完成的，它用于查找更为具体的模式。

对于每个模式，都会根据URI变量和通配符的数量来计算一个得分，其中URI变量的得分低于通配符的得分。总得分较低的模式获胜。如果两个模式的得分相同，则会选择长度较长的那个模式。

通配模式（例如 **、{*varName}）不参与评分，且总是被排在最后。如果两个模式都是通配模式，则会选择较长的那个。

可消费媒体类型

请参阅Servlet堆栈中的等效内容

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

Java
Kotlin

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

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

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

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

提示

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

可生产的媒体类型

请参阅Servlet堆栈中的等效内容

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

Java
Kotlin

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

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

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

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

提示

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

参数和头部

请参阅Servlet堆栈中的等效内容

您可以根据查询参数条件来缩小请求映射的范围。您可以测试查询参数的存在（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。

API版本

请参阅Servlet堆栈中的等效内容

没有标准的方法来指定API版本，因此当你在WebFlux Config中启用API版本控制时，你需要指定如何解析版本。WebFlux Config会创建一个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(version = "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

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

@GetMapping 和 @RequestMapping(method=HttpMethod.GET) 在请求映射时支持透明的 HTTP HEAD 请求。控制器方法无需进行任何修改。在 HttpHandler 服务器适配器中应用的响应包装器会确保设置 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请求上，但在常见情况下这是没有必要的。

自定义注解

请参阅Servlet堆栈中的等效内容

Spring WebFlux支持使用组合注解进行请求映射。这些注解自身被@RequestMapping元注解标记，通过组合这些注解可以重新声明一部分（或全部）@RequestMapping属性，从而实现更具体、更精细的请求处理功能。

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

备注

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

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

明确注册

参见Servlet堆栈中的等效内容

你可以通过编程方式注册处理器（Handler）方法，这些方法可以用于动态注册，或者在高级情况下使用，例如在不同的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 = UserHandler.class.getMethod("getUser", Long.class); 3

		mapping.registerMapping(info, handler, method); 4
	}

}

注入目标处理器和控制器的方法映射。
准备请求映射元数据。
获取处理方法。
进行注册。

@Configuration
class MyConfig {

	@Autowired
	fun setHandlerMapping(mapping: RequestMappingHandlerMapping, handler: UserHandler) { 1

		val info = RequestMappingInfopaths("/user/{id}").methods(RequestMethod.GET).build() 2

		val method = UserHandler::class.java.getMethod("getUser", Long::class.java) 3

		mapping.registerMapping(info, handler, method) 4
	}
}

注入目标处理器和控制器的方法映射。
准备请求映射元数据。
获取处理方法。
进行注册。

`@HttpExchange`

请参阅Servlet堆栈中的等效内容

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

@RequestMapping​

URI模式​

模式比较​

可消费媒体类型​

可生产的媒体类型​

参数和头部​

API版本​

HTTP HEAD, OPTIONS​

自定义注解​

明确注册​

@HttpExchange​

`@RequestMapping`

URI模式

模式比较

可消费媒体类型

可生产的媒体类型

参数和头部

API版本

HTTP HEAD, OPTIONS

自定义注解

明确注册

`@HttpExchange`