上个月把项目从 Spring Boot 2.6 直接升级到 3.2对应的 Spring Framework 版本从 5.3 一下拉到了 6.1。本来以为只是改改版本号、换换依赖的事结果从启动到联调整整折腾了两天其中一大半时间都耗在 SpringMVC 新版本的“隐藏变化”上。这次升级遇到的最典型的问题有三个javax 到 jakarta 的包名迁移导致项目直接起不来springmvc拦截器注册得好好的结果就是不生效登录态直接裸奔以及各种 404、静态资源放行不对的诡异现象。好在每个问题最后都查到了根因并且解决标题里敢写“[已解决]”是真的解决了。下面按问题逐个复盘顺便把 SpringMVC 工作流程里容易混淆的 Filter、HandlerInterceptor、HandlerMapping 之间的关系理一遍。如果你的项目还在 Spring Boot 2.7 或更低版本、近期准备升级这篇文章可以当一份避坑清单如果你已经在 3.x 上遇到了类似问题可以直接跳到对应小节看结论。1. 升级前的版本盘点与风险预判1.1 新版本到底“新”在哪先说一个容易忽略的事实Spring Boot 3.x 对应的 Spring Framework 6.x并不是在 Spring 5 基础上小修小补而是跨了两代很多底层假设直接变了。Spring Framework 6 的基线要求是 Java 17对所有基于 Servlet 的代码做了 Jakarta EE 9 迁移默认的路径匹配器也从 AntPathMatcher 换成了 PathPatternParser。也就是说哪怕你的业务代码一行没改光是把 spring-boot-starter-web 的版本号从 2.6 改成 3.2运行时的行为都可能不一样。这一点特别影响那些“看起来没问题”的配置尤其是 springmvc拦截器。拦截器的注册 API 本身没变但拦截器内部的路径匹配规则、过滤链的组装方式都换了底层实现。项目里积累多年的通配符路径表达式很可能在新版本里含义完全变了。升级前如果没意识到这一点后面排查拦截器失效问题的时候很容易被带到沟里去。1.2 踩坑前先把家底盘清我的建议是升级前先做一次“家底盘点”。不是说上来就改 pom.xml而是先确认下面几件事当前项目是用 spring-boot-starter-web 打包成 jar 运行还是打成 war 放到外部 Tomcat外部容器部署的话容器版本必须至少是 Tomcat 10因为 Servlet 规范已经换包名了。项目里直接使用了哪些 javax 开头的 API比如 javax.servlet、javax.validation、javax.annotation。这些在 Spring Boot 3 里全部要换成 jakarta 开头。是否用到第三方库比如老版本的 Dubbo、Shiro、某个内部封装的 starter。这些库如果还是基于旧的 javax.servlet 编译的光替换业务代码没用传递依赖会把旧类重新带进来。是否在代码里大量使用 Ant 风格的通配路径比如/api/*.do、/path/**/detail、带正则的路径变量。这类写法在新版本路径匹配器下最容易翻车。把这些信息列出来后面升级的时候就能有的放矢。我这次就是因为只关注了版本号没有提前梳理外部容器和第三方库的兼容性才在第一步就踩了个大坑。2. 第一个大坑javax 变成 jakarta启动直接失败2.1 报错现场还原升级之后第一次启动还没来得及看到日志里的 Spring Boot Logo直接抛了一串异常。核心报错是java.lang.NoClassDefFoundError: javax/servlet/ServletContext这个错很典型一看就是运行时找不到 servlet 相关类。因为项目是打成 war 部署到外部 Tomcat 的而 Tomcat 9 及其之前的版本Servlet 规范还叫 javax.servletSpring Boot 3 和 Spring Framework 6 已经基于 Jakarta EE 9Servlet API 的包名变成了 jakarta.servlet。两边对不上容器启动阶段就崩了。2.2 包名迁移背后的逻辑这不是 Spring 心血来潮而是整个 Java EE 生态的变更。Java EE 从 8 升级到 9 时改名为 Jakarta EE并把所有 API 的包名前缀从 javax 换成了 jakarta。Servlet、Validation、Annotation 这些规范全部受影响。Spring Framework 6 选择了全面跟随 Jakarta EE 9所以不只是 Spring MVC 的代码要改所有依赖 Servlet API 的库也得跟着升级。很多人以为升级 Spring Boot 3 就是换依赖实际上如果你的工程里遍布import javax.servlet.http.HttpServletRequest那等于所有涉及 Web 层的代码都要动。这个工作量说大不大说小也不小但必须一次做干净。2.3 替换代码时容易漏掉的地方我在替换包名时用的是 IDE 的全局替换直接搜javax.servlet换成jakarta.servlet。这一步很顺利但紧接着又踩了两个隐蔽的地方。第一个是 javax.validation。项目里大量使用了Valid、NotNull这类校验注解它们来自 validation-api包名同样要换// 旧写法 import javax.validation.Valid; import javax.validation.constraints.NotNull; // 新写法 import jakarta.validation.Valid; import jakarta.validation.constraints.NotNull;第二个是 javax.annotation。项目里用到了Resource、PostConstruct、PreDestroy这些注解也迁移到了 jakarta.annotation 下。如果漏掉同样会在运行期报找不到类。漏掉这些包名的直接后果是编译能过但启动时报NoClassDefFoundError或者ClassNotFoundException而且往往报错位置在某个深层依赖里排查起来非常费劲。所以我强烈建议替换完成后跑一遍依赖树检查是否还有传递依赖带入了 javax 系列包mvn dependency:tree -Dincludesjavax.servlet:javax.servlet-api如果结果里还有 javax 开头的 servlet 相关依赖说明某个第三方库还没升级兼容版本需要手动排除或者升级库本身。这一步很多人容易忽略但它决定了你的应用在外部容器里能不能正常启动。3. 第二个大坑springmvc拦截器“注册了却不生效”3.1 现象描述包名迁移解决之后应用能正常启动了但紧接着发现一个更隐蔽的问题登录拦截器完全没生效。我访问一个需要登录才能看的接口后端直接返回了数据登录校验逻辑压根没走。这个问题的隐蔽之处在于配置类和拦截器类代码一行没改IDEA 里看依赖也都在断点打上去preHandle方法就是进不去。我甚至怀疑过是不是拦截器类没有被 Spring 扫描到反复检查了Component注解和包扫描路径都没问题。3.2 先回顾 SpringMVC 工作流程再排查排查这种问题不能靠猜最好先回到 SpringMVC 工作流程本身。一个标准的请求处理链路大概是这样的请求先到达 DispatcherServlet它根据请求路径去找 HandlerMapping拿到一个 HandlerExecutionChain也就是“拦截器链 Controller 方法”的组合。然后再由 HandlerAdapter 执行这个链路。执行的时候会先调用拦截器链里的preHandle如果返回 true 才继续进入 Controller 方法处理完之后再由postHandle和afterCompletion做收尾。所以拦截器不生效无非下面几个环节出了问题HandlerMapping 没有把请求匹配到 Controller匹配到了 Controller 但拦截器没有挂上去拦截器挂上去了但路径规则把它排除掉了或者拦截器链根本没有被 HandlerAdapter 执行。对照这个流程我先看 HandlerMapping。新版本的 SpringMVC 默认使用 PathPatternParser 来做路径匹配而我的老项目里Controller 上写的是这样的映射GetMapping(/api/v1/user/detail) public Result userDetail(RequestParam Long id) { ... }拦截器注册写的是registry.addInterceptor(loginInterceptor) .addPathPatterns(/api/*) .excludePathPatterns(/api/login);问题一下浮出水面了。/api/*在旧版 AntPathMatcher 里也匹配不了/api/v1/user/detail这种多级路径按理说升级前拦截器也不该生效。但事实是升级前的项目用的表达式是/api/**某次维护时被改成了/api/*在旧版本里误打误撞也能拦住。升级之后 PathPatternParser 对路径段的划分更严格*只匹配单段路径多级路径直接不匹配等于拦截器被静默架空了。3.3 真正原因默认路径匹配器换了这个坑的本质原因是 Spring Framework 6 把默认的路径匹配器从 AntPathMatcher 换成了 PathPatternParser。两者表面上看都是处理通配符但语法和语义有差异。简单说PathPatternParser 更规范也更严格它对路径段的划分是明确的*匹配一个路径段内的任意字符但不匹配斜杠也不能跨段。**匹配 0 到多个路径段。{name}匹配一个路径段并作为路径变量绑定。{*name}匹配 0 到多个路径段常用于 catch-all 的场景。老项目里常见的/api/*想表达“下面所有接口”这种模糊写法在新版里是行不通的必须改成/api/**。类似的问题还有在拦截器 excludePathPatterns 里写/assets/*.js这种后缀匹配在 PathPatternParser 下也容易出问题。另一个要注意的点是这个变化不只影响拦截器还会影响RequestMapping的路径映射和静态资源的路径匹配。如果你在项目里大量使用/**、/static/**这种标准写法问题不大如果你用的是各种自创的、在 AntPathMatcher 默认实现下碰巧能跑的通配符表达式升级后就要逐条检查。3.4 解决方案对比解决这个问题有两条路我建议优先改表达式而不是换回老策略。第一把所有拦截器的路径表达式统一改成新语法。因为 SpringMVC 后续只会加强对 PathPatternParser 的支持投奔新语法是长期成本最低的选择。我的登录拦截器最后改成了这样Configuration public class WebMvcConfig implements WebMvcConfigurer { Resource private LoginInterceptor loginInterceptor; Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(loginInterceptor) .addPathPatterns(/api/**) .excludePathPatterns(/api/login, /api/register, /error, /static/**, /favicon.ico); } }关键就是把/api/*改成/api/**并且把静态资源路径、错误页路径都显式排除掉避免拦截器把静态资源也拦住。第二如果老项目里历史表达式太多短时间改不完可以暂时把路径匹配策略切回 AntPathMatcherspring: mvc: pathmatch: matching-strategy: ant_path_matcher这个配置在 Spring Boot 3 里依然有效设置之后 HandlerMapping 和拦截器的匹配规则会退回旧行为。但我个人建议只把它当临时方案因为后续版本对 PathPatternParser 的依赖会越来越深老策略迟早会被彻底移除。这里还要多说一句排查拦截器问题时记得把日志级别调低能看到 SpringMVC 的匹配过程logging: level: org.springframework.web: DEBUG org.springframework.web.servlet: TRACE我实际排查时就是靠 TRACE 日志确认了拦截器链里根本没有我注册的 LoginInterceptor才把目光聚焦到路径匹配规则上。没有这一步我可能还在扫描配置类上瞎折腾。4. 第三个大坑404、静态资源与欢迎页4.1 首页 404 排查实录拦截器问题解决之后系统能登录了但新的问题又来了访问应用根路径直接 404连个欢迎页都没有。项目里的 index.html 明明放在src/main/resources/static/下面Spring Boot 的默认静态资源位置也没改过。排查思路还是回到 SpringMVC 工作流程。静态资源请求会被 SimpleUrlHandlerMapping 交给 ResourceHttpRequestHandler 处理而 index.html 的欢迎页功能是由 WelcomePageHandlerMapping 处理的。这个映射在 Spring Boot 3 里依然存在但它的优先级比 RequestMappingHandlerMapping 低。我的项目里恰好写了一个GetMapping(/)的 Controller直接把根路径给占了。旧版本里欢迎页还能跟 Controller 共存新版本对欢迎页和手写映射的冲突处理更严格了手写映射直接压过了欢迎页Controller 又没返回正确视图于是 404。解决办法很简单要么删掉那个抢根路径的 Controller要么在 Controller 里显式转发到静态页面GetMapping(/) public String index() { return forward:/index.html; }我选择了保留 Controller因为它在接口统一返回格式上还有作用只是在里面加了个转发。4.2 静态资源被拦截器“误伤”欢迎页 404 刚解决又发现页面上的 CSS 和 JS 全部加载不出来。一看请求日志静态资源请求全被 LoginInterceptor 给拦下来了。原因是拦截器里我写的是addPathPatterns(/**)把所有路径都纳入了拦截范围但 excludePathPatterns 里只排除了接口路径没有排除静态资源路径。这个问题在升级前其实不存在因为那时候静态资源路径由容器默认放行拦截器对/static/**的匹配也相对宽松。升级后 PathPatternParser 对路径段匹配更严格拦截器的/**确实把所有资源路径都覆盖到了静态资源走到了拦截器链里。如果不排除就会出现“页面能打开但寸步难行”的诡异情况。正确的做法是把静态资源路径全部排除掉.excludePathPatterns(/static/**, /css/**, /js/**, /images/**, /favicon.ico);如果你的项目把静态资源放在 classpath:/static/ 下并且访问路径不带 /static 前缀比如直接访问/css/app.css那排除路径就要写成/css/**而不是/static/**。这个细节我踩过值得留意。4.3 顺带踩了的 CORS 坑静态资源问题解决之后前端同事又来反馈跨域问题。项目里用的是全局 CORS 配置在 WebMvcConfigurer 里重写了addCorsMappingsOverride public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/api/**) .allowedOrigins(https://example.com) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS); }老版本里这段配置很好用但新版本里如果请求是 OPTIONS 预检请求并且被拦截器拦住了就会直接返回 401 或 403根本没机会走到 CORS 处理的环节。解决方式有两个一是在拦截器的 excludePathPatterns 里把 OPTIONS 请求放行二是在拦截器 preHandle 里加一个判断请求方法是 OPTIONS 就直接放行。我最后在拦截器里加了这个小逻辑保证所有预检请求都能绕过登录校验因为浏览器预检请求本来就不携带业务凭证拦在那里除了制造麻烦没有任何意义。if (OPTIONS.equalsIgnoreCase(request.getMethod())) { return true; }5. 排查工具、高频问题速查与版本兼容参考5.1 一套行之有效的排查套路经历这几个坑之后我总结了一套排查 SpringMVC 新版本问题的固定套路分享出来应该能帮大家少走弯路。第一步先确认请求有没有被 DispatcherServlet 接住。看日志里有没有 DispatcherServlet 的进入记录如果没有问题在容器层面比如 servlet 路径映射不对如果有问题就在 SpringMVC 内部。第二步看 HandlerMapping 选择了哪个处理器。把org.springframework.web.servlet的日志级别调到 TRACE 后SpringMVC 会打印出当前请求命中了哪个 HandlerMapping、哪个 Handler。这一步能快速定位是想匹配的路径规则根本没生效还是被另一个 Handler 抢先截走了。第三步看 HandlerExecutionChain 里有哪些拦截器。日志会列出拦截器链的组成如果里面没有你注册的拦截器基本就是路径匹配规则的问题如果有再看是哪个拦截器返回了 false把链断掉了。第四步如果前三点都正常但响应还是不对重点检查 CORS、消息转换器、参数绑定和异常处理器。很多时候问题不在匹配而在后续的执行链。5.2 高频问题速查表现象根因解决方案启动报 javax.servlet 找不到Servlet API 包名迁移容器版本过旧升级外部容器到 Tomcat 10代码包名换 jakarta编译通过但运行期 java.lang.NoClassDefFoundError第三方库内仍传递引用旧 javax API升级第三方库到 Jakarta 兼容版本或排除旧依赖拦截器 preHandle 不执行拦截器路径表达式不匹配 PathPatternParser 规则检查 addPathPatterns把单段/*改成/**或用 ant_path_matcher 兜底静态资源被拦截器拦截excludePathPatterns 没包含静态资源路径显式排除/css/**、/js/**、/images/**等路径访问根路径 404Controller 抢占了/欢迎页失效删除根路径映射或在 Controller 内 forward 到 index.html浏览器预检请求失败OPTIONS 请求被拦截器拦下在 preHandle 中直接放行 OPTIONS 请求日期参数传字符串失败新版本对 LocalDateTime 的格式化配置调整检查 spring.mvc.format.date或 DateTimeFormat 显式指定格式跨域配置不生效CORS 请求在到达 CORS 处理器前被拦截器拦截拦截器放行预检请求并确认 CorsRegistry 的路径规则5.3 版本兼容参考如果你正准备升级下面这个参考表可以帮你快速决策。Spring Boot 2.7 对应 Spring Framework 5.3Spring Boot 3.0 对应 Spring Framework 6.0Spring Boot 3.2 对应 Spring Framework 6.1。越往后对 Jakarta EE 和 PathPatternParser 的依赖越彻底所以不要指望还有“保持老写法也能跑”的过渡期。组件Spring Boot 2.7Spring Boot 3.2Java 版本要求Java 8Java 17Servlet APIjavax.servletjakarta.servletValidation APIjavax.validationjakarta.validation默认路径匹配器AntPathMatcherPathPatternParser内置 Tomcat9.x10.1如果你因为团队规范原因暂时无法升到 Java 17那就老老实实留在 Spring Boot 2.7不要强上 3.x。Java 版本不达标Spring Boot 3 连启动都做不到这一点没有商量余地。结尾这一趟升级下来最大的体会是SpringMVC 新版本的坑绝大多数不是“新功能不会用”而是“旧写法在新规则下悄悄失效”。特别是 springmvc拦截器这块API 看起来一模一样但底层的路径匹配规则换了代码不报错行为就是不对这种问题最耗时间。最后分享一个排查细节遇到这类问题优先看日志不要急着改代码。把org.springframework.web.servlet调到 TRACESpringMVC 会把 HandlerMapping 的匹配过程、拦截器链的组装过程原原本本打出来。我这次能在一小时内定位到拦截器失效靠的就是这条日志而不是靠猜。升级这种事一次踩坑是教训两次踩坑就是不长记性了。希望这份复盘能让你少熬两个夜。