映射请求

DeepSeek V3 中英对照 Mapping Requests

查看 Reactive 栈中的等效内容

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

@RequestMapping

查看 Reactive 栈中的等效内容

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

@RequestMapping 也有针对特定 HTTP 方法的快捷方式变体：

• @GetMapping

• @PostMapping

• @PutMapping

• @DeleteMapping

• @PatchMapping

快捷方式是自定义注解，之所以提供这些注解，是因为大多数控制器方法应该映射到特定的 HTTP 方法，而不是使用默认匹配所有 HTTP 方法的 @RequestMapping。在类级别上仍然需要 @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 模式

查看 Reactive 堆栈中的等效内容

@RequestMapping 方法可以使用 URL 模式进行映射。有两种选择：

• PathPattern — 一个预解析的模式，与同样预解析为 PathContainer 的 URL 路径进行匹配。专为 Web 使用设计，该解决方案能有效处理编码和路径参数，并高效匹配。

• AntPathMatcher — 将字符串模式与字符串路径进行匹配。这是原始解决方案，也用于 Spring 配置中以选择类路径、文件系统和其他位置上的资源。它的效率较低，且字符串路径输入在处理编码和 URL 的其他问题时存在挑战。

PathPattern 是 Web 应用程序的推荐解决方案，并且在 Spring WebFlux 中是唯一的选择。从 Spring MVC 5.3 版本开始，它被启用为可用选项，并从 6.0 版本开始默认启用。有关路径匹配选项的自定义，请参阅 MVC 配置。

PathPattern 支持与 AntPathMatcher 相同的模式语法。此外，它还支持捕获模式，例如 {*spring}，用于匹配路径末尾的 0 个或多个路径段。PathPattern 还限制了 ** 的使用，以便仅在模式末尾允许匹配多个路径段。这消除了在为给定请求选择最佳匹配模式时的许多歧义情况。有关完整模式语法，请参阅 PathPattern 和 AntPathMatcher。

一些示例模式：

• "/resources/ima?e.png" - 匹配路径段中的一个字符

• "/resources/*.png" - 匹配路径段中的零个或多个字符

• "/resources/**" - 匹配多个路径段

• "/projects/{project}/versions" - 匹配一个路径段并将其捕获为变量

• "/projects/{project:[a-z]+}/versions" - 使用正则表达式匹配并捕获变量

可以通过 @PathVariable 访问捕获的 URI 变量。例如：

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}")
public class OwnerController {

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

java

Kotlin

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

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

kotlin

URI 变量会自动转换为适当的类型，否则会抛出 TypeMismatchException 异常。默认情况下支持简单类型（如 int、long、Date 等），你也可以注册对其他数据类型的支持。请参阅 类型转换 和 DataBinder。

你可以显式地命名 URI 变量（例如 @PathVariable("customId")），但如果名称相同并且你的代码是使用 -parameters 编译器标志编译的，则可以省略该细节。

语法 {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 name, @PathVariable String version, @PathVariable String ext) {
    // ...
}

java

Kotlin

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

kotlin

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

模式比较

查看 Reactive 栈中的等效内容

当多个模式匹配一个 URL 时，必须选择最佳匹配。根据是否启用了已解析的 PathPattern 使用，可以通过以下方式之一完成：

• PathPattern.SPECIFICITY_COMPARATOR

• AntPathMatcher.getPatternComparator(String path)

两者都有助于将更具体的模式排序到顶部。如果一个模式的 URI 变量（计为 1）、单通配符（计为 1）和双通配符（计为 2）的数量较少，则认为它更具体。在得分相同的情况下，选择较长的模式。在得分和长度都相同的情况下，选择 URI 变量比通配符更多的模式。

默认的映射模式 (/**) 被排除在评分之外，并且总是排在最后。此外，前缀模式（如 /public/**）被认为比其他没有双通配符的模式更不具体。

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

后缀匹配

从 5.3 版本开始，默认情况下，Spring MVC 不再执行 .* 后缀模式匹配，这意味着映射到 /person 的控制器不再隐式映射到 /person.*。因此，路径扩展不再用于解释响应的请求内容类型——例如，/person.pdf、/person.xml 等。

以这种方式使用文件扩展名在过去是必要的，因为浏览器发送的 Accept 标头难以一致地解析。如今，这已不再必要，使用 Accept 标头应是首选方式。

随着时间的推移，文件扩展名的使用已经证明在多种方式上存在问题。当与 URI 变量、路径参数和 URI 编码的使用叠加时，可能会导致歧义。基于 URL 的授权和安全性的推理（详见下一节）也变得更加困难。

在 5.3 之前的版本中，要完全禁用路径扩展的使用，请设置以下内容：

• useSuffixPatternMatching(false)，参见 PathMatchConfigurer

• favorPathExtension(false)，参见 ContentNegotiationConfigurer

除了通过 "Accept" 头请求内容类型之外，还有其他方式也可以派上用场，例如在浏览器中直接输入 URL 时。路径扩展的一个安全替代方案是使用查询参数策略。如果必须使用文件扩展名，可以考虑通过 ContentNegotiationConfigurer 的 mediaTypes 属性将其限制在明确注册的扩展名列表中。

后缀匹配与 RFD

反射文件下载（Reflected File Download，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 头。请参阅内容类型。

请参阅 CVE-2015-5211 获取与 RFD 相关的其他建议。

可消费的媒体类型

查看 Reactive 堆栈中的等效内容

你可以根据请求的 Content-Type 来缩小请求映射的范围，如下例所示：

Java

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

java

• 使用 consumes 属性通过内容类型缩小映射范围。

Kotlin

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

kotlin

• 使用 consumes 属性通过内容类型缩小映射范围。

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

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

提示

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

可生成的媒体类型

查看 Reactive 堆栈中的等效内容

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

Java

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

java

• 使用 produces 属性通过内容类型缩小映射范围。

Kotlin

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

kotlin

• 使用 produces 属性通过内容类型缩小映射范围。

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

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

提示

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

参数与请求头

查看响应式堆栈中的等效内容

你可以根据请求参数条件来缩小请求映射的范围。你可以测试请求参数是否存在（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。

提示

你可以使用 headers 条件来匹配 Content-Type 和 Accept，但最好使用 consumes 和 produces 来代替。

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 方法，而不是使用默认匹配所有 HTTP 方法的 @RequestMapping。如果你需要一个如何实现组合注解的示例，可以看看这些注解是如何声明的。

备注

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

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

显式注册

查看 Reactive 栈中的等效内容

你可以以编程方式注册处理程序方法，这可以用于动态注册或高级用例，例如在不同 URL 下使用相同处理程序的不同实例。以下示例展示如何注册一个处理程序方法：

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

查看 Reactive 堆栈中的等效内容

@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 的列表。

@HttpExchange 还支持一个 headers() 参数，该参数接受类似于 @RequestMapping(headers={}) 中的 "name=value" 键值对。在服务器端，这扩展到了 @RequestMapping 所支持的完整语法。