|
此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Framework 6.2.0！ |
映射请求
本节讨论带 Comments 的 Controller 的请求映射。
@RequestMapping
这@RequestMappingannotation 用于将请求映射到 controllers 方法。它有
按 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 模式
您可以使用 glob 模式和通配符映射请求：
| 模式 | 描述 | 例 |
|---|---|---|
|
匹配一个字符 |
|
|
匹配路径段中的零个或多个字符 |
|
|
匹配零个或多个路径段，直到路径的结尾 |
|
|
匹配路径段并将其捕获为名为 “name” 的变量 |
|
|
匹配 regexp |
|
|
匹配零个或多个路径段，直到路径的末尾，并将其捕获为名为 “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) {
// ...
}
}| 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")），但您可以
如果名称相同，并且您使用-parameterscompiler 标志。
语法{*varName}声明与零个或多个剩余路径匹配的 URI 变量
段。例如/resources/{*path}匹配/resources/和"path"variable 捕获/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针对本地、系统、环境和
其他属性来源。例如，您可以使用它来根据
一些外部配置。
Spring WebFlux 使用PathPattern和PathPatternParser，了解 URI 路径匹配支持。
这两个类都位于spring-web并专为与 HTTP URL 一起使用而设计
paths 的 Web 应用程序中的 paths，其中在运行时匹配了大量 URI 路径模式。 |
Spring WebFlux 不支持后缀模式匹配——与 Spring MVC 不同，其中
映射（如/person也匹配到/person.*.对于基于 URL 的内容
negotiation，如果需要，我们建议使用 query 参数，它更简单、更
显式的，并且不易受到基于 URL 路径的漏洞利用。
形态比较
当多个模式与一个 URL 匹配时，必须比较它们以找到最佳匹配。此作已完成
跟PathPattern.SPECIFICITY_COMPARATOR，它查找更具体的模式。
对于每个模式，都会根据 URI 变量和通配符的数量计算分数。 其中 URI 变量的得分低于通配符。总分较低的模式 赢了。如果两个模式具有相同的分数，则选择较长的模式。
Catch-all 模式（例如 ，**{*varName}） 被排除在评分之外，并且始终
排序为 last。如果两个模式都是 catch-all，则选择较长的模式。
易耗品介质类型
您可以根据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属性。与大多数其他请求不同
mapping 属性，但是，当在类级别使用时，方法级别的consumes属性
覆盖而不是扩展类级声明。
MediaType为常用的媒体类型提供常量 — 例如APPLICATION_JSON_VALUE和APPLICATION_XML_VALUE. |
可生产的培养基类型
您可以根据Acceptrequest 标头和
控制器方法生成的内容类型，如下例所示：
-
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属性。与大多数其他请求不同
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. |
您还可以将 SAME 与请求标头条件一起使用，如下例所示：
-
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 头， 选项
@GetMapping和@RequestMapping(method=HttpMethod.GET)支持 HTTP HEAD
透明地用于请求映射目的。控制器方法不需要更改。
响应包装器，应用于HttpHandlerserver 适配器，确保Content-Lengthheader 设置为写入的字节数，但未实际写入响应。
默认情况下，HTTP OPTIONS 是通过设置Allow响应标头的 HTTP 列表
所有@RequestMapping方法。
对于@RequestMapping如果没有 HTTP 方法声明，则Allowheader 设置为GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS.控制器方法应始终声明
支持的 HTTP 方法（例如，通过使用特定于 HTTP 方法的变体 —@GetMapping,@PostMapping等）。
您可以显式映射@RequestMapping方法更改为 HTTP HEAD 和 HTTP OPTIONS，但
在常见情况下不是必需的。
自定义注释
Spring WebFlux 支持使用组合注释进行请求映射。这些注释本身是元注释的@RequestMapping并组合以重新声明@RequestMapping具有更狭窄、更具体目的的属性。
@GetMapping,@PostMapping,@PutMapping,@DeleteMapping和@PatchMapping是
组合注释的示例。之所以提供它们，是因为可以说，大多数
控制器方法应该映射到特定的 HTTP 方法，而不是使用@RequestMapping,
默认情况下，它与所有 HTTP 方法匹配。如果您需要有关如何实现的示例
一个组合的注释，看看这些是如何声明的。
@RequestMapping不能与其他@RequestMapping在同一元素（类、接口或方法）上声明的注释。如果
倍数@RequestMapping在同一元素上检测到注释，则会显示警告
记录，并且仅使用第一个映射。这也适用于组合@RequestMapping注解，例如@GetMapping,@PostMapping等。 |
Spring WebFlux 还支持具有自定义请求匹配的自定义请求映射属性
逻辑。这是一个更高级的选项，需要子类化RequestMappingHandlerMapping并覆盖getCustomMethodCondition方法，其中
您可以检查 custom 属性并返回您自己的RequestCondition.
显式注册
您可以通过编程方式注册 Handler 方法，这些方法可用于动态 registrations 或高级情况，例如同一处理程序的不同实例 在不同的 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 | 注入 target handlers 和控制器的处理程序 Map。 |
| 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 | 注入 target handlers 和控制器的处理程序 Map。 |
| 2 | 准备请求映射元数据。 |
| 3 | 获取处理程序方法。 |
| 4 | 添加注册。 |
@HttpExchange
虽然@HttpExchange是使用
generated proxy 的 HTTP 接口，该 HTTP 接口
放置此类注释是 Client 端 vs Server 使用的中立合约。
除了简化客户端代码之外，在某些情况下，HTTP 接口
可能是服务器公开其 API 以供客户端访问的便捷方式。这导致
增加客户端和服务器之间的耦合，这通常不是一个好的选择，
特别是对于公共 API，但可能正是内部 API 的目标。
这是 Spring Cloud 中常用的一种方法，这就是为什么@HttpExchange是
支持作为@RequestMapping用于服务器端处理
controller 类。
例如：
-
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支持。