跳到主要内容

矩阵变量

DeepSeek V3 中英对照 Matrix Variables

RFC 3986 讨论了路径段中的键值对。在 Spring WebFlux 中，我们根据 Tim Berners-Lee 的一篇“旧文章”将这些称为“矩阵变量”，但它们也可以被称为 URI 路径参数。

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

与 Spring MVC 不同，在 WebFlux 中，URL 中是否存在矩阵变量不会影响请求映射。换句话说，您不需要使用 URI 变量来隐藏变量内容。也就是说，如果您想从控制器方法访问矩阵变量，您需要在预期包含矩阵变量的路径段中添加一个 URI 变量。以下示例展示了如何做到这一点：

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

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

    // petId == 42
    // q == 11
}
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

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

// GET /pets/42

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

    // q == 1
}
java

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

// 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