映射请求
本节讨论带注解的控制器的请求映射。
@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 模式
@RequestMapping 个方法可以通过URL模式映射。
Spring MVC 正在使用 PathPattern 个预解析的模式，该模式与作为 PathContainer 的URL路径进行匹配。
专为Web使用设计，此解决方案有效处理编码和路径参数，并高效匹配。
有关路径匹配选项的自定义，请参见 MVC配置。
AntPathMatcher 版本现已弃用，因为它效率较低，且字符串路径输入在有效处理URL的编码和其他问题上存在挑战。 |
您可以使用通配符模式和通配符来映射请求：
| 模式 | 描述 | 示例 |
|---|---|---|
|
字面模式 |
|
|
匹配一个字符 |
|
|
匹配路径段中的零个或多个字符 |
|
|
匹配零个或多个路径段 |
|
|
与 |
|
|
匹配正则表达式 |
|
|
与 |
|
捕获的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表达式
#{…}.
模式比较
当多个模式匹配一个URL时，必须选择最佳匹配。这取决于是否启用了解析后的PathPattern的使用情况，通过以下一种方式来完成：
两者都有助于将更具体的模式排在前面。如果某个模式的URI变量数量（计为1分）、单通配符数量（计为1分）和双通配符数量（计为2分）的总分较低，则其更具具体性。若得分相同，则选择较长的模式。如果得分和长度均相同，则优先选择URI变量数量多于通配符数量的模式。
默认的映射模式 (/**) 不参与评分，并且始终排序在最后。此外，前缀模式（如 /public/**）被认为比没有双通配符的其他模式更不具体。
有关详细信息，请按照上述链接前往模式比较器部分。
后缀匹配和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头。请参见内容类型。
请参阅 CVE-2015-5211 了解有关RFD的其他建议。
可消耗的媒体类型
您可以根据请求的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 属性来根据内容类型缩小映射范围。 |
The consumes 属性还支持否定表达式——例如，!text/plain 表示除了 text/plain 之外的任何内容类型。
您可以在类级别声明一个共享的consumes属性。然而，与其他大多数请求映射属性不同的是，当在类级别使用时，方法级别的consumes属性会覆盖而不是扩展类级别的声明。
MediaType 提供了常用媒体类型的常量，例如 APPLICATION_JSON_VALUE 和 APPLICATION_XML_VALUE。 |
可生成的媒体类型
您可以根据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。 |
参数、头部
你可以根据请求参数条件缩小请求映射。你可以测试请求参数是否存在（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。 |
API 版本
在指定API版本时没有统一的标准，因此当您在MVC配置中启用API版本控制时，需要指定如何解析版本。MVC配置会创建一个ApiVersionStrategy，进而用于映射请求。
一旦API版本控制启用，您就可以开始映射带有版本的请求。
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.3必须存在于映射中，或被 配置为受支持。 |
对于带有版本号 "1.5" 的请求：
-
(1) 匹配任何版本
-
(2) 不匹配
-
(3) 符合条件，因为它匹配1.2及以上版本
-
(4) 个匹配项，并被选为最高匹配项
版本为"1.6"的请求没有匹配项。尽管(1)和(3)匹配，但被(4)覆盖，而(4)只允许严格匹配，因此并未匹配。
在这种情况下，使用NotAcceptableApiVersionException会导致返回400响应。
未带有版本号的控制器方法旨在支持在引入版本化替代方法之前创建的客户端。因此，尽管未版本化的控制器方法被认为与任何版本匹配，但实际上其优先级最低，且实际上会被任何带有版本的替代控制器方法所取代。
参见API版本控制以了解更多关于基础架构和对API版本控制的支持的详细信息。
HTTP HEAD, OPTIONS
@GetMapping (和 @RequestMapping(method=HttpMethod.GET)) 支持 HTTP HEAD
透明地用于请求映射。控制器方法不需要更改。
一个响应包装器，在 jakarta.servlet.http.HttpServlet 中应用，确保 Content-Length
头设置为已写入的字节数（实际上不写入响应）。
默认情况下，HTTP OPTIONS 通过将 Allow 响应头设置为所有具有匹配 URL 模式的 @RequestMapping 方法中列出的 HTTP 方法列表来处理。
对于一个@RequestMapping没有HTTP方法声明，Allow标头将被设置为GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS。控制器方法应该始终声明支持的HTTP方法（例如，通过使用特定的HTTP方法变体：@GetMapping、@PostMapping等）。
您可以显式地将@RequestMapping方法映射到HTTP HEAD和HTTP OPTIONS，但在常见情况下这并不是必须的。
自定义注解
Spring MVC 支持使用 组合注解
进行请求映射。这些注解本身带有
@RequestMapping 的元注解，并组合起来重新声明 @RequestMapping
属性的子集（或全部），具有更窄、更特定的目的。
@GetMapping、@PostMapping、@PutMapping、@DeleteMapping 和 @PatchMapping 是组合注解的示例。提供它们的原因是，大多数控制器方法应该映射到特定的 HTTP 方法，而不是使用默认匹配所有 HTTP 方法的 @RequestMapping。如果您需要实现组合注解的示例，可以查看这些注解是如何声明的。
@RequestMapping 不能与在同一元素（类、接口或方法）上声明的其他 @RequestMapping 注解一起使用。如果在同一个元素上检测到多个 @RequestMapping 注解，将记录一条警告，并且仅第一个映射会被使用。这也适用于组合的 @RequestMapping 注解，例如 @GetMapping、@PostMapping 等。 |
Spring MVC 也支持带有自定义请求匹配逻辑的自定义请求映射属性。这是一个更高级的选项，需要子类化 RequestMappingHandlerMapping 并重写 getCustomMethodCondition 方法，在这里你可以检查自定义属性并返回你自己的 RequestCondition。
显式注册
您可以编程式地注册处理器方法，这些方法可用于动态注册或用于高级情况，例如在不同的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
虽然@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 支持的完整语法。