Spring 默认会从请求 URI 中移除分号及其后内容（如 476%3B 被截断为 476），导致路径变量解析异常；本文详解其机制、风险及通过 UrlPathHelper 禁用该行为的正确配置方式。
spring 默认会从请求 uri 中移除分号及其后内容（如 `476%3b` 被截断为 `476`），导致路径变量解析异常；本文详解其机制、风险及通过 `urlpathhelper` 禁用该行为的正确配置方式。
在 Spring Web 应用中，当 RESTful API 的路径变量（path variable）包含 URL 编码的分号 %3B（例如 /api/items/476%3B），你可能会遇到一个隐蔽但关键的问题：服务端实际接收到的路径变量值是 476，而非预期的 476%3B。这直接导致后续 Integer.parseInt("476%3B") 抛出 NumberFormatException，本应返回 400 Bad Request，却因 ID 被错误截断为纯数字 476 后查无此资源，最终返回 404 Not Found —— 掩盖了真正的输入校验失败。
该行为的根源在于 Spring 框架内置的 UrlPathHelper 组件。自 Spring 3.0 起，默认启用 removeSemicolonContent = true，其设计初衷是遵循早期 Servlet 规范中对“分号路径参数”（path parameters，如 /user;jsessionid=xxx）的兼容性处理。根据 RFC 3986，分号在 URI 路径中属于保留字符，常用于分隔路径段与参数（类似 ;version=2）。因此，Spring 会主动剥离分号及其后所有内容，仅保留前面部分作为路径标识符。
⚠️ 注意：这一逻辑发生在请求进入 DispatcherServlet 的最早期解析阶段（早于 Controller 映射和路径变量绑定），因此即使你在 @PathVariable 注解中声明了 String id，拿到的也已是被截断后的值 —— Integer.parseInt("476%3B") 根本不会执行，因为 %3B 已在网关或 Spring MVC 层被静默丢弃。
要彻底解决该问题，需显式禁用分号清理行为。推荐在配置类中自定义 UrlPathHelper：
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void configurePathMatch(PathMatchConfigurer configurer) {
UrlPathHelper urlPathHelper = new UrlPathHelper();
urlPathHelper.setRemoveSemicolonContent(false); // 关键：关闭分号截断
configurer.setUrlPathHelper(urlPathHelper);
}
}
✅ 此配置生效后，/api/items/476%3B 将完整传递至控制器，@PathVariable String id 将准确接收 "476%3B" 字符串，开发者可据此进行显式校验（如正则匹配、Integer.parseInt() 异常捕获），并统一返回 400。
? 补充说明：
- 若使用 Spring Boot 2.6+，还需确认 spring.mvc.pathmatch.matching-strategy 未设为 ant_path_matcher（已废弃），推荐保持默认 path_pattern_parser（更安全且不依赖 UrlPathHelper）；但路径变量中含 %3B 时，仍需确保底层 PathPatternParser 或兼容层未引入类似截断逻辑，故上述配置在多数场景下仍是必要保障。
- 生产环境中，强烈建议避免在 ID 类路径变量中使用分号等保留字符；若业务确需支持特殊编码 ID，请同步加强入参校验与日志追踪，防止因框架默认行为引发的诊断盲区。
总结：Spring 的分号清理是历史兼容特性，非 bug，但需开发者主动认知并按需关闭。通过 UrlPathHelper.setRemoveSemicolonContent(false) 可精准控制 URI 解析行为，确保路径语义完整性与错误响应准确性。
