Matrix Variables / 矩阵变量

RFC 3986 讨论了路径段中的 name-value 。在 Spring MVC 中，根据 Tim Berners-Lee 的一篇 《old post》，我们将这些变量称为 「矩阵变量」，但它们也可以被称为 URI 路径参数。

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

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

// GET /pets/42;q=11;r=22
@GetMapping("/pets/{petId}")
public void findPet(@PathVariable String petId, @MatrixVariable int q) {
    // petId == 42
    // q == 11
}

鉴于所有的路径段都可能包含矩阵变量，有时你可能需要区分矩阵变量应该在哪个路径变量中。下面的例子说明了如何做到这一点：

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

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

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

为了获得所有的矩阵变量，你可以使用 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]
}

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