请求映射

参见 Servlet 栈中的等效项

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

@RequestMapping

参见 Servlet 栈中的等效项

@RequestMapping 注解用于将请求映射到控制器方法。它具有各种属性，可以通过 URL、HTTP 方法、请求参数、标头和媒体类型进行匹配。您可以将其用于类级别以表达共享映射，或用于方法级别以缩小到特定端点映射。

还有一些特定于 HTTP 方法的@RequestMapping快捷变体

  • @GetMapping

  • @PostMapping

  • @PutMapping

  • @DeleteMapping

  • @PatchMapping

上述注解是自定义注解，之所以提供它们是因为，可以说，大多数控制器方法应该映射到特定的 HTTP 方法，而不是使用@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 栈中的等效项

您可以使用 glob 模式和通配符来映射请求

模式 描述 示例

?

匹配一个字符

"/pages/t?st.html" 匹配 "/pages/test.html" 和 "/pages/t3st.html"

*

匹配路径段中零个或多个字符

"/resources/*.png" 匹配 "/resources/file.png"

"/projects/*/versions" 匹配 "/projects/spring/versions" 但不匹配 "/projects/spring/boot/versions"

**

匹配零个或多个路径段，直到路径的结尾

"/resources/**" 匹配 "/resources/file.png" 和 "/resources/images/file.png"

"/resources/**/file.png" 无效，因为** 只能位于路径的末尾。

{name}

匹配路径段并将其捕获为名为“name”的变量

"/projects/{project}/versions" 匹配 "/projects/spring/versions" 并捕获 project=spring

{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

捕获的 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) {
		// ...
	}
}
1 类级 URI 映射。
2 方法级 URI 映射。 
@Controller
@RequestMapping("/owners/{ownerId}") (1)
class OwnerController {

	@GetMapping("/pets/{petId}") (2)
	fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet {
		// ...
	}
}
1 类级 URI 映射。
2 方法级 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 路径模式也可以包含嵌入的${…​}占位符，这些占位符在启动时通过PropertySourcesPlaceholderConfigurer针对本地、系统、环境和其他属性源进行解析。例如，您可以使用它根据某些外部配置参数化基本 URL。

Spring WebFlux 使用PathPattern和PathPatternParser进行 URI 路径匹配支持。这两个类都位于spring-web中，并专门设计用于在 Web 应用程序中使用 HTTP URL 路径，在 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属性会覆盖而不是扩展类级别的声明。

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）或特定值（myParam=myValue）。以下示例测试具有值的参数

  • Java

  • Kotlin

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

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

  • Java

  • Kotlin

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

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是组合注解的示例。它们之所以提供，是因为可以说，大多数控制器方法应该映射到特定的HTTP方法，而不是使用@RequestMapping，后者默认情况下匹配所有HTTP方法。如果需要有关如何实现组合注解的示例，请查看这些注解的声明方式。

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

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

显式注册

参见 Servlet 栈中的等效项

可以以编程方式注册Handler方法，这可以用于动态注册或高级用例，例如在不同URL下使用同一Handler的不同实例。以下示例演示了如何执行此操作

  • 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 method = UserHandler.class.getMethod("getUser", Long.class); (3)

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

}
1 注入目标Handler和控制器的Handler映射。
2 准备请求映射元数据。
3 获取Handler方法。
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 注入目标Handler和控制器的Handler映射。
2 准备请求映射元数据。
3 获取Handler方法。
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的列表。

@HttpExchange还支持headers()参数，该参数接受类似于"name=value"的对，就像客户端的@RequestMapping(headers={})一样。在服务器端，这扩展到@RequestMapping支持的完整语法。