矩阵变量

ChatGPT-4o-mini 中英对照 Matrix Variables

查看 Reactive 栈中的等效内容

RFC 3986 讨论了路径段中的名称-值对。在 Spring MVC 中，我们称这些为“矩阵变量”，这是基于 Tim Berners-Lee 的一篇 “旧帖子”，但它们也可以被称为 URI 路径参数。

矩阵变量可以出现在任何路径段中，每个变量用分号分隔，多个值用逗号分隔（例如，/cars;color=red,green;year=2012）。多个值也可以通过重复变量名来指定（例如，color=red;color=green;color=blue）。

如果一个 URL 预计包含矩阵变量，则控制器方法的请求映射必须使用 URI 变量来掩盖该变量内容，并确保请求可以成功匹配，而不受矩阵变量的顺序和存在的影响。以下示例使用了一个矩阵变量：

Java

// GET /pets/42;q=11;r=22

@GetMapping("/pets/{petId}")
public void findPet(@PathVariable String petId, @MatrixVariable int q) {

    // petId == 42
    // q == 11
}

java

Kotlin

// GET /pets/42;q=11;r=22

@GetMapping("/pets/{petId}")
fun findPet(@PathVariable petId: String, @MatrixVariable q: Int) {

    // petId == 42
    // q == 11
}

kotlin

鉴于所有路径段可能包含矩阵变量，有时您可能需要消除歧义，以确定矩阵变量预期在哪个路径变量中。以下示例展示了如何做到这一点：

Java

// GET /owners/42;q=11/pets/21;q=22

@GetMapping("/owners/{ownerId}/pets/{petId}")
public void findPet(
        @MatrixVariable(name="q", pathVar="ownerId") int q1,
        @MatrixVariable(name="q", pathVar="petId") int q2) {

    // q1 == 11
    // q2 == 22
}

java

Kotlin

// GET /owners/42;q=11/pets/21;q=22

@GetMapping("/owners/{ownerId}/pets/{petId}")
fun findPet(
        @MatrixVariable(name = "q", pathVar = "ownerId") q1: Int,
        @MatrixVariable(name = "q", pathVar = "petId") q2: Int) {

    // q1 == 11
    // q2 == 22
}

kotlin

一个矩阵变量可以被定义为可选，并指定一个默认值，如下例所示：

Java

// GET /pets/42

@GetMapping("/pets/{petId}")
public void findPet(@MatrixVariable(required=false, defaultValue="1") int q) {

    // q == 1
}

java

Kotlin

// GET /pets/42

@GetMapping("/pets/{petId}")
fun findPet(@MatrixVariable(required = false, defaultValue = "1") q: Int) {

    // q == 1
}

kotlin

要获取所有矩阵变量，可以使用 MultiValueMap，如下例所示：

Java

// GET /owners/42;q=11;r=12/pets/21;q=22;s=23

@GetMapping("/owners/{ownerId}/pets/{petId}")
public void findPet(
        @MatrixVariable MultiValueMap<String, String> matrixVars,
        @MatrixVariable(pathVar="petId") MultiValueMap<String, String> petMatrixVars) {

    // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23]
    // petMatrixVars: ["q" : 22, "s" : 23]
}

java

Kotlin

// GET /owners/42;q=11;r=12/pets/21;q=22;s=23

@GetMapping("/owners/{ownerId}/pets/{petId}")
fun findPet(
        @MatrixVariable matrixVars: MultiValueMap<String, String>,
        @MatrixVariable(pathVar="petId") petMatrixVars: MultiValueMap<String, String>) {

    // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23]
    // petMatrixVars: ["q" : 22, "s" : 23]
}

kotlin

注意，您需要启用矩阵变量的使用。在 MVC Java 配置中，您需要通过 路径匹配 设置一个 UrlPathHelper，并将 removeSemicolonContent=false。在 MVC XML 命名空间中，您可以设置 <mvc:annotation-driven enable-matrix-variables="true"/>。