映射请求

ChatGPT-4o-mini 中英对照 Mapping Requests

查看 Servlet 栈中的等效项

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

@RequestMapping

查看 Servlet 栈中的等效项

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

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

• @GetMapping

• @PostMapping

• @PutMapping

• @DeleteMapping

• @PatchMapping

前面的注解是 自定义注解，因为可以说，大多数控制器方法应该映射到特定的 HTTP 方法，而不是使用 @RequestMapping，后者默认匹配所有 HTTP 方法。与此同时，在类级别仍然需要 @RequestMapping 来表达共享的映射。

备注

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

以下示例使用类型和方法级映射：

Java

@RestController
@RequestMapping("/persons")
class PersonController {

    @GetMapping("/{id}")
    public Person getPerson(@PathVariable Long id) {
        // ...
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public void add(@RequestBody Person person) {
        // ...
    }
}

java

Kotlin

@RestController
@RequestMapping("/persons")
class PersonController {

    @GetMapping("/{id}")
    fun getPerson(@PathVariable id: Long): Person {
        // ...
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    fun add(@RequestBody person: Person) {
        // ...
    }
}

kotlin

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

@GetMapping("/owners/{ownerId}/pets/{petId}")
public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) {
    // ...
}

java

Kotlin

@GetMapping("/owners/{ownerId}/pets/{petId}")
fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet {
    // ...
}

kotlin

您可以在类和方法级别声明 URI 变量，如下例所示：

Java

@Controller
@RequestMapping("/owners/{ownerId}") 1
public class OwnerController {

    @GetMapping("/pets/{petId}") 2
    public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) {
        // ...
    }
}

java

• 类级 URI 映射。

• 方法级 URI 映射。

Kotlin

@Controller
@RequestMapping("/owners/{ownerId}") 1
class OwnerController {

    @GetMapping("/pets/{petId}") 2
    fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet {
        // ...
    }
}

kotlin

• 类级 URI 映射。

• 方法级 URI 映射。

URI 变量会自动转换为适当的类型，或者抛出 TypeMismatchException。简单类型（int、long、Date 等）默认是支持的，您可以注册对任何其他数据类型的支持。请参见 Type Conversion 和 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

@GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}")
public void handle(@PathVariable String version, @PathVariable String ext) {
    // ...
}

java

Kotlin

@GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}")
fun handle(@PathVariable version: String, @PathVariable ext: String) {
    // ...
}

kotlin

URI 路径模式还可以包含嵌入的 ${…​} 占位符，这些占位符在启动时通过 PropertySourcesPlaceholderConfigurer 解析，针对本地、系统、环境和其他属性源。您可以使用这项功能，例如，根据某些外部配置对基础 URL 进行参数化。

备注

Spring WebFlux 使用 PathPattern 和 PathPatternParser 来支持 URI 路径匹配。这两个类位于 spring-web 中，专门设计用于在 Web 应用程序中处理 HTTP URL 路径，在运行时匹配大量 URI 路径模式。

Spring WebFlux 不支持后缀模式匹配 — 与 Spring MVC 不同，在 Spring MVC 中，像 /person 这样的映射也会匹配到 /person.*。对于基于 URL 的内容协商，如果需要，我们建议使用查询参数，这样更简单、更明确，并且不易受到基于 URL 路径的攻击。

模式比较

查看 Servlet 栈中的等效项

当多个模式匹配一个 URL 时，必须进行比较以找到最佳匹配。这是通过 PathPattern.SPECIFICITY_COMPARATOR 完成的，它会寻找更具体的模式。

对于每个模式，计算一个分数，基于 URI 变量和通配符的数量，其中 URI 变量的分数低于通配符。总分较低的模式获胜。如果两个模式的分数相同，则选择较长的模式。

通配符模式（例如，**，{*varName}）被排除在评分之外，并且总是被排在最后。如果两个模式都是通配符，则选择较长的那个。

可消耗媒体类型

查看 Servlet 栈中的等效项

您可以根据请求的 Content-Type 来缩小请求映射，以下示例展示了这一点：

Java

@PostMapping(path = "/pets", consumes = "application/json")
public void addPet(@RequestBody Pet pet) {
    // ...
}

java

Kotlin

@PostMapping("/pets", consumes = ["application/json"])
fun addPet(@RequestBody pet: Pet) {
    // ...
}

kotlin

consumes 属性也支持否定表达式 — 例如，!text/plain 意味着任何内容类型都不是 text/plain。

您可以在类级别声明一个共享的 consumes 属性。然而，与大多数其他请求映射属性不同的是，当在类级别使用时，方法级别的 consumes 属性会覆盖而不是扩展类级别的声明。

提示

MediaType 提供了常用媒体类型的常量 — 例如，APPLICATION_JSON_VALUE 和 APPLICATION_XML_VALUE。

可生成的媒体类型

查看 Servlet 栈中的等效项

您可以根据 Accept 请求头和控制器方法生成的内容类型列表来缩小请求映射，如以下示例所示：

Java

@GetMapping(path = "/pets/{petId}", produces = "application/json")
@ResponseBody
public Pet getPet(@PathVariable String petId) {
    // ...
}

java

Kotlin

@GetMapping("/pets/{petId}", produces = ["application/json"])
@ResponseBody
fun getPet(@PathVariable petId: String): Pet {
    // ...
}

kotlin

媒体类型可以指定字符集。支持否定表达式 — 例如，!text/plain 意味着任何内容类型，除了 text/plain。

您可以在类级别声明一个共享的 produces 属性。然而，与大多数其他请求映射属性不同的是，当在类级别使用时，方法级别的 produces 属性会覆盖而不是扩展类级别的声明。

提示

MediaType 提供了常用媒体类型的常量 — 例如，APPLICATION_JSON_VALUE，APPLICATION_XML_VALUE。

参数和头部

查看 Servlet 栈中的等效项

您可以根据查询参数条件缩小请求映射。您可以测试查询参数的存在性（myParam）、缺失性（!myParam）或特定值（myParam=myValue）。以下示例测试具有特定值的参数：

Java

@GetMapping(path = "/pets/{petId}", params = "myParam=myValue") 1
public void findPet(@PathVariable String petId) {
    // ...
}

java

• 检查 myParam 是否等于 myValue。

Kotlin

@GetMapping("/pets/{petId}", params = ["myParam=myValue"]) 1
fun findPet(@PathVariable petId: String) {
    // ...
}

kotlin

• 检查 myParam 是否等于 myValue。

您也可以在请求头条件中使用相同的内容，如以下示例所示：

Java

@GetMapping(path = "/pets/{petId}", headers = "myHeader=myValue") 1
public void findPet(@PathVariable String petId) {
    // ...
}

java

• 检查 myHeader 是否等于 myValue。

Kotlin

@GetMapping("/pets/{petId}", headers = ["myHeader=myValue"]) 1
fun findPet(@PathVariable petId: String) {
    // ...
}

kotlin

• 检查 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

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

}

java

• 注入目标处理程序和控制器的处理程序映射。

• 准备请求映射元数据。

• 获取处理程序方法。

• 添加注册。

Kotlin

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

kotlin

• 注入目标处理程序和控制器的处理程序映射。

• 准备请求映射元数据。

• 获取处理程序方法。

• 添加注册。

@HttpExchange

查看 Servlet 栈中的等效项

虽然 @HttpExchange 的主要目的是通过生成的代理来抽象 HTTP 客户端代码，但放置此类注解的 HTTP 接口 是一个对客户端与服务器使用中立的契约。除了简化客户端代码外，HTTP 接口在某些情况下也可能是服务器为客户端访问暴露其 API 的便捷方式。这导致客户端与服务器之间的耦合性增加，通常不是一个好的选择，特别是对于公共 API，但对于内部 API 可能正是目标。这是一种在 Spring Cloud 中常用的方法，这也是为什么 @HttpExchange 被支持作为 @RequestMapping 在控制器类中进行服务器端处理的替代方案。

例如：

Java

@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) {
        // ...
    }
}

java

Kotlin

@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) {
        // ...
    }
}

kotlin

@HttpExchange 和 @RequestMapping 有所不同。 @RequestMapping 可以通过路径模式、HTTP 方法等映射到任意数量的请求，而 @HttpExchange 声明了一个具有具体 HTTP 方法、路径和内容类型的单一端点。

对于方法参数和返回值，通常情况下，@HttpExchange 支持 @RequestMapping 的一部分方法参数。特别是，它排除了任何服务器端特定的参数类型。有关详细信息，请参见 @HttpExchange 和 @RequestMapping 的列表。