矩阵变量 (Matrix Variables)

RFC 3986 讨论了路径段中的键值对。在 Spring MVC 中，我们称之为“矩阵变量”（Matrix Variables），也可以称为 URI 路径参数。

语法规则

• 变量之间用分号 ; 分隔。
• 同一变量的多个值用逗号 , 分隔，或者重复变量名。
• 示例：/cars;color=red,green;year=2012 或 /cars;color=red;color=green;year=2012。

使用示例

矩阵变量可以出现在任何路径段中。你需要在映射中使用 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
}

Kotlin

// 请求：GET /pets/42;q=11;r=22

@GetMapping("/pets/{petId}")
fun findPet(@PathVariable petId: String, @MatrixVariable q: Int) {
	// 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
}

启用矩阵变量

默认情况下，Spring MVC 禁用了矩阵变量（出于安全和 URL 解析规范的考虑）。你需要在配置中手动开启：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        UrlPathHelper urlPathHelper = new UrlPathHelper();
        urlPathHelper.setRemoveSemicolonContent(false); // 不移除分号后的内容
        configurer.setUrlPathHelper(urlPathHelper);
    }
}

---

补充教学

1. 为什么叫“矩阵”变量？

这个名字源于 Web 之父 Tim Berners-Lee 的一篇老帖子。他认为层级路径（用 / 分隔）像一棵树，而段内的参数（用 ; 分隔）则能提供更丰富的非层级描述，结构上更像矩阵。

2. 它和查询参数（Query Params）有什么区别？

• 查询参数（?a=1&b=2）：作用于整个请求 URL。
• 矩阵变量（;a=1）：精确关联到某一个路径段。
• 应用场景：当你需要对路径中的某个资源进行极其细致的描述时（例如：/地图/经纬度;缩放=10/导出;格式=pdf），矩阵变量比查询参数更具语义化。

3. SEO 影响

虽然功能强大，但矩阵变量会使 URL 变得非常复杂。大多数搜索引擎优化（SEO）建议路径尽量简洁，因此矩阵变量更多用于内部后台系统或复杂的 REST API，而较少用于面向普通用户的门户网站。