映射请求

参见 Reactive 栈中的对应内容

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

@RequestMapping

参见 Reactive 栈中的对应内容

你可以使用 @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 模式

参见 Reactive 栈中的对应内容

@RequestMapping 方法可以使用 URL 模式进行映射。Spring MVC 使用 PathPattern——一个预解析的模式，与同样预解析为 PathContainer 的 URL 路径进行匹配。该解决方案专为 Web 使用而设计，有效处理编码和路径参数，并高效匹配。有关路径匹配选项的自定义，请参阅 MVC 配置。

AntPathMatcher 变体现在已弃用，因为它效率较低，并且字符串路径输入对于有效处理编码和 URL 的其他问题来说是一个挑战。

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

模式 描述 示例

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}")
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 变量（计为 1）、单个通配符（计为 1）和双通配符（计为 2）的数量较少，则该模式更具体。如果分数相同，则选择较长的模式。如果分数和长度相同，则选择 URI 变量多于通配符的模式。

默认映射模式 (/**) 不参与评分，并且始终排在最后。此外，前缀模式（例如 /public/**）被认为不如其他没有双通配符的模式具体。

有关完整详细信息，请点击以上链接到模式比较器。

后缀匹配和 RFD

反射文件下载 (RFD) 攻击类似于 XSS，因为它依赖于请求输入（例如，查询参数和 URI 变量）在响应中被反射。但是，RFD 攻击不是将 JavaScript 插入 HTML，而是依赖于浏览器切换到执行下载并将响应视为可执行脚本（在稍后双击时）。

在 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) {
	// ...
}
1 使用 consumes 属性根据内容类型缩小映射范围。 
@PostMapping("/pets", consumes = ["application/json"]) (1)
fun addPet(@RequestBody pet: Pet) {
	// ...
}
1 使用 consumes 属性根据内容类型缩小映射范围。

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

你可以在类级别声明一个共享的 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) {
	// ...
}
1 使用 produces 属性根据内容类型缩小映射范围。 
@GetMapping("/pets/{petId}", produces = ["application/json"]) (1)
@ResponseBody
fun getPet(@PathVariable petId: String): Pet {
	// ...
}
1 使用 produces 属性根据内容类型缩小映射范围。

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

你可以在类级别声明一个共享的 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) {
	// ...
}
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。
你可以使用 headers 条件匹配 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(version = "1.5") (4)
	public Account getAccount1_5() {
	}
}
1 匹配任何版本
2 匹配版本 1.1
3 匹配版本 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 是组合注解的示例。之所以提供它们，是因为，可以说，大多数控制器方法应该映射到特定的 HTTP 方法，而不是使用 @RequestMapping，后者默认匹配所有 HTTP 方法。如果你需要一个如何实现组合注解的示例，请查看这些注解是如何声明的。

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

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

显式注册

参见 Reactive 栈中的对应内容

你可以通过编程方式注册处理程序方法，这可用于动态注册或高级情况，例如在不同的 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 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 添加注册。

@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 支持的完整语法。

© . This site is unofficial and not affiliated with VMware.