|
此版本仍在开发中，尚不被认为是稳定的。对于最新的稳定版本，请使用 Spring Framework 6.2.10！ |
映射请求
本节讨论带注释的控制器的请求映射。
@RequestMapping
您可以使用@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— 与 URL 路径匹配的预解析模式也预解析为PathContainer.
该解决方案专为 Web 使用而设计，可有效处理编码和路径参数，并有效匹配。
有关路径匹配选项的自定义，请参阅 MVC 配置。
这AntPathMatchervariant 现在已被弃用，因为它效率较低，并且 String 路径输入是
有效处理 URL 的编码和其他问题的挑战。 |
您可以使用 glob 模式和通配符来映射请求：
| 模式 | 描述 | 示例 |
|---|---|---|
|
文字模式 |
|
|
匹配一个字符 |
|
|
匹配路径段中的零个或多个字符 |
|
|
匹配零个或多个路径段 |
|
|
匹配路径段并将其捕获为名为“name”的变量 |
|
|
匹配正则表达式 |
|
|
匹配零个或多个路径段并将其捕获为名为“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针对本地、系统、环境和 其他属性来源。例如，这很有用，可以根据 外部配置。 -
SpEL表达
#{…}.
模式比较
当多个模式与一个 URL 匹配时，必须选择最佳匹配项。这是通过
以下之一取决于是否使用 parsedPathPattern是否启用使用：
两者都有助于对模式进行排序，并在顶部添加更具体的模式。如果 它具有较低的 URI 变量（计为 1）、单个通配符（计为 1）、 和双通配符（计为 2）。给定相等的分数，则选择较长的模式。 在相同的分数和长度下，URI 变量多于通配符的模式为 选择。
默认映射模式 （） 从评分中排除，并且始终
最后排序。此外，前缀模式（例如/**/public/**）被认为较少
比没有双通配符的其他模式更具体。
有关完整详细信息，请点击上面链接到模式比较器。
后缀匹配和 RFD
反射文件下载 （RFD） 攻击与 XSS 类似，因为它依赖于请求输入 （例如，查询参数和 URI 变量）反映在响应中。但是，而不是 将 JavaScript 插入 HTML 中，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属性，按内容类型缩小映射范围。 |
这consumes属性还支持否定表达式——例如，!text/plain表示任何
内容类型以外的text/plain.
您可以声明共享的consumes属性。与大多数其他
request-mapping 属性，但是，当在类级别使用时，方法级别consumes属性
覆盖而不是扩展类级声明。
MediaType为常用媒体类型提供常量，例如APPLICATION_JSON_VALUE和APPLICATION_XML_VALUE. |
可生产的培养基类型
您可以根据Acceptrequest 标头和
控制器方法生成的内容类型，如以下示例所示：
-
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指除“文本/纯色”以外的任何内容类型。
您可以声明共享的produces属性。与大多数其他
request-mapping 属性，但是，当在类级别使用时，方法级别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 版本的标准方法，因此当您启用 API 版本控制时 在 MVC 配置中，您需要 以指定如何解析版本。MVC 配置创建一个 ApiVersionStrategy，而该 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） 取代，它只允许严格匹配，因此不匹配。
在这种情况下，NotAcceptableApiVersionException结果是 400 的响应。
| 上述假设请求版本是“受支持”版本，否则 会失败。 |
有关底层的更多详细信息，请参阅 API 版本控制 基础设施和对 API 版本控制的支持。
HTTP 头， 选项
@GetMapping（和@RequestMapping(method=HttpMethod.GET)） 支持 HTTP HEAD
透明地用于请求映射。控制器方法不需要更改。
响应包装器，应用于jakarta.servlet.http.HttpServlet，确保Content-Lengthheader 设置为写入的字节数（而不实际写入响应）。
默认情况下，HTTP OPTIONS 是通过设置Allowresponse 标头添加到 HTTP 列表中
所有@RequestMapping具有匹配 URL 模式的方法。
对于一个@RequestMapping如果没有 HTTP 方法声明，则Allowheader 设置为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 方法，而不是使用@RequestMapping,
默认情况下，它与所有 HTTP 方法匹配。如果您需要如何实现的示例
一个组合的注释，看看这些是如何声明的。
@RequestMapping不能与其他@RequestMapping在同一元素（类、接口或方法）上声明的注释。如果
倍数@RequestMapping在同一元素上检测到注释，则会发出警告
，并且仅使用第一个映射。这也适用于组合@RequestMapping注释，例如@GetMapping,@PostMapping等。 |
Spring MVC 还支持具有自定义请求匹配的自定义请求映射属性
逻辑。这是一个更高级的选项，需要子类化RequestMappingHandlerMapping并覆盖getCustomMethodCondition方法，其中
您可以检查自定义属性并返回您自己的RequestCondition.
显式注册
您可以以编程方式注册处理程序方法，这些方法可用于动态 注册或高级情况，例如同一处理程序的不同实例 在不同的 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
虽然主要目的@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 方法声明单个端点，
path 和内容类型。
对于方法参数和返回值，通常，@HttpExchange支持
方法参数的子集@RequestMapping确实。值得注意的是，它排除了任何
服务器端特定参数类型。有关详细信息，请参阅@HttpExchange和@RequestMapping列表。
@HttpExchange还支持headers()参数，该参数接受"name=value"-喜欢
像 in@RequestMapping(headers={})在客户端。在服务器端，
这扩展到完整的语法@RequestMapping支持。