Spring MVC默认禁用矩阵变量，需通过WebMvcConfigurer配置UrlPathHelper.setRemoveSemicolonContent(false)显式开启；它适用于RESTful中与路径段强绑定的参数（如分页、状态），通过@MatrixVariable注解配合@PathVariable接收，支持pathVar区分多段参数。
Spring MVC 支持矩阵变量（Matrix Variables），但默认是禁用的，需要显式开启才能使用。它适合在 URL 路径段中嵌入键值对参数，尤其适用于 RESTful 风格中与某个资源 ID 关联的过滤、分页或状态参数，比查询参数更语义化、更贴近资源层级。
启用矩阵变量支持
矩阵变量依赖于 UrlPathHelper 的解析能力，默认不启用。需在配置类中手动开启：
- Spring Boot 2.6+（基于 WebMvcConfigurer）：
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void configurePathMatch(PathMatchConfigurer configurer) {
UrlPathHelper urlPathHelper = new UrlPathHelper();
urlPathHelper.setRemoveSemicolonContent(false); // 关键：保留分号内容
configurer.setUrlPathHelper(urlPathHelper);
}
}
- 若使用 XML 配置（较少见），需在
<mvc:annotation-driven>中设置removeSemicolonContent="false"； - 注意：Spring Boot 2.6 起默认禁用路径中的分号解析（出于安全考虑），所以
setRemoveSemicolonContent(false)是必须步骤。
在 Controller 中接收矩阵变量
使用 @MatrixVariable 注解提取路径段中的矩阵参数。它必须配合路径变量（@PathVariable）使用，因为矩阵变量属于某个路径段的附属信息。
例如请求 URL：/api/users;age=25;role=admin/123;status=active
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
立即学习“Java免费学习笔记（深入）”；
-
;age=25;role=admin属于/users段的矩阵变量； -
;status=active属于/123段的矩阵变量。
对应 Controller 写法：
@GetMapping("/api/users;{userFilters}/{"id";{idFilters}}")
public ResponseEntity<User> getUser(
@MatrixVariable(pathVar = "userFilters") Map<String, String> userFilters,
@MatrixVariable(pathVar = "idFilters") Map<String, String> idFilters,
@PathVariable Long id) {
// userFilters = {age="25", role="admin"}
// idFilters = {status="active"}
...
}
-
pathVar属性指定该矩阵变量绑定到哪个@PathVariable名称； - 可直接注入单个值：
@MatrixVariable(name = "age", pathVar = "userFilters") String age； - 若某段无矩阵变量，对应
@MatrixVariable需加required = false，否则会抛异常。
常见问题与注意事项
矩阵变量易用错，主要陷阱有：
- URL 中分号
;后不能有空格（如; age=25会被截断）； - 矩阵变量名不能含点（
.）、斜杠（/）等特殊字符，否则解析失败； - Tomcat 默认会剥离分号及之后内容（安全策略），需在启动时添加 JVM 参数：
-Dorg.apache.catalina.connector.REJECT_EMPTY_PATH_INFO=true不推荐；更稳妥方式是改用 Undertow 或 Jetty，或确保 Tomcat 版本 ≥ 9.0.31 并配置relaxedPathChars=";"和relaxedQueryChars=";"； - 前端发请求时，需对分号和等号做编码（实际很少这么做），通常建议后端统一处理，前端保持原始写法（现代浏览器对路径中分号支持较稳定）。
替代方案对比
矩阵变量并非万能，适用场景有限：
- ✅ 适合：资源层级明确、参数与某段路径强绑定（如
/orders;status=paid/123）； - ❌ 不适合：通用筛选（如搜索字段、排序）、跨多个资源段的公共参数——此时用查询参数（
?sort=name&page=2）更清晰、兼容性更好； - ⚠️ 注意：OpenAPI/Swagger 对矩阵变量支持较弱，文档生成可能不完整，需手工补充说明。
