去年年底团队决定把一个运行了四年的Spring Boot 2.7项目升级到4.0。立项时的理由是充分的2.7早已停止维护安全补丁断了团队也想用上虚拟线程和新的HTTP客户端。我主动揽下了这个任务心想无非是改改版本号、跑跑测试。结果接下来三周的经历让我彻底理解了什么叫“跨代迁移”。第一课根本不存在“从2.x直接升4.x”我最初的计划很简单把pom.xml里的父版本改成4.0然后逐个修编译错误。这个计划在第一小时就破产了。官方迁移指南的态度非常明确如果你的项目还在2.x必须先升级到3.x并验证通过才能继续往4.x走。Moderne的文档甚至用了“staged”这个词——升级是分阶段的中间不能跳步。我被迫把计划拆成了两段2.7 → 3.53.5 → 4.0。仅第一阶段就消耗了一周半。其中最大的障碍是javax到jakarta的全量替换。任何一个使用Servlet、Validation、JPA注解的文件都受影响而老项目往往有几百个文件。OpenRewrite的recipe能自动处理大部分重命名但仍有漏网之鱼需要全局搜索残留的javax导入逐一确认。第二课Jackson 3的“同名不同性”2.7升级到3.5的过程虽然繁琐但至少是可预期的。真正让我栽跟头的是3.5到4.0这一步。Spring Boot 4的默认JSON库从Jackson 2换成了Jackson 3包名从com.fasterxml.jackson变成了tools.jackson。我按惯例检查了依赖发现Jackson 3已经在classpath里了以为配置改改就行。但上线后一个富文本提交接口开始报错JSON解析失败错误提示指向一个/字符被误认为注释标记。排查过程令人抓狂。我先后试了降级Jackson版本、切换fastjson都无济于事。后来才意识到Jackson 3对某些转义字符的处理策略与Jackson 2不同前端提交的富文本内容中包含HTML标签的转义序列在Jackson 2下能正常解析在Jackson 3下触发了更严格的解析规则。最终的修复不在后端而在前端提交前对富文本属性做一次字符替换避开Jackson 3的敏感字符。这个问题让我付出了将近两天的联调时间而它的根因只是“Jackson 3变得更严格了”。第三课安全配置和测试注解的“消失”3.x到4.0的迁移中Spring Security 7的API变更比预期更彻底。WebSecurityConfigurerAdapter在3.0就被移除4.0进一步收紧了配置方式。我们项目里有一段从2.x时代遗留下来的AuthenticationManager配置在3.5下还能靠兼容层勉强运行到4.0直接编译失败。重写花了大半天。另一个意外是测试注解。MockBean和SpyBean在4.0中被移除了官方建议替换为Spring Test的MockitoBean和MockitoSpyBean。这个替换本身不难但项目里有三十多个测试类分散使用批量替换后还需要逐个验证Mock行为是否一致。回头看如果重来一次三周下来项目最终跑在了4.0上启动速度确实快了虚拟线程的接入也比预想顺利。但如果重新规划我会做三件事。第一预留两倍于预估的时间。我最初估了一周实际用了三周。跨代迁移的隐性成本——第三方库的版本兼容、自动化工具覆盖不到的角落、测试行为的微妙变化——远比你想象的多。第二把Jackson 3的适配提前到升级清单的第一项。序列化问题是4.0迁移中最容易在生产环境暴露的坑而且往往以“接口突然报错”的形式出现排查方向容易被误导。在测试环境就应该用真实流量回放来验证所有涉及JSON出入的接口。第三不要跳过3.5的稳定期。我在3.5上只停留了三天就急着往4.0推。现在想来如果在3.5上多跑一两周让javax替换的隐患充分暴露4.0的迁移会从容得多。官方推荐先升到3.5.x最新版验证通过再继续这条建议值得严格遵守。升级完成的那天我在提交记录里写了一句大版本迁移没有捷径分阶段走就是最快的路。
去年年底团队决定把一个运行了四年的Spring Boot 2.7项目升级到4.0。立项时的理由是充分的2.7早已停止维护安全补丁断了团队也想用上虚拟线程和新的HTTP客户端。我主动揽下了这个任务心想无非是改改版本号、跑跑测试。结果接下来三周的经历让我彻底理解了什么叫“跨代迁移”。第一课根本不存在“从2.x直接升4.x”我最初的计划很简单把pom.xml里的父版本改成4.0然后逐个修编译错误。这个计划在第一小时就破产了。官方迁移指南的态度非常明确如果你的项目还在2.x必须先升级到3.x并验证通过才能继续往4.x走。Moderne的文档甚至用了“staged”这个词——升级是分阶段的中间不能跳步。我被迫把计划拆成了两段2.7 → 3.53.5 → 4.0。仅第一阶段就消耗了一周半。其中最大的障碍是javax到jakarta的全量替换。任何一个使用Servlet、Validation、JPA注解的文件都受影响而老项目往往有几百个文件。OpenRewrite的recipe能自动处理大部分重命名但仍有漏网之鱼需要全局搜索残留的javax导入逐一确认。第二课Jackson 3的“同名不同性”2.7升级到3.5的过程虽然繁琐但至少是可预期的。真正让我栽跟头的是3.5到4.0这一步。Spring Boot 4的默认JSON库从Jackson 2换成了Jackson 3包名从com.fasterxml.jackson变成了tools.jackson。我按惯例检查了依赖发现Jackson 3已经在classpath里了以为配置改改就行。但上线后一个富文本提交接口开始报错JSON解析失败错误提示指向一个/字符被误认为注释标记。排查过程令人抓狂。我先后试了降级Jackson版本、切换fastjson都无济于事。后来才意识到Jackson 3对某些转义字符的处理策略与Jackson 2不同前端提交的富文本内容中包含HTML标签的转义序列在Jackson 2下能正常解析在Jackson 3下触发了更严格的解析规则。最终的修复不在后端而在前端提交前对富文本属性做一次字符替换避开Jackson 3的敏感字符。这个问题让我付出了将近两天的联调时间而它的根因只是“Jackson 3变得更严格了”。第三课安全配置和测试注解的“消失”3.x到4.0的迁移中Spring Security 7的API变更比预期更彻底。WebSecurityConfigurerAdapter在3.0就被移除4.0进一步收紧了配置方式。我们项目里有一段从2.x时代遗留下来的AuthenticationManager配置在3.5下还能靠兼容层勉强运行到4.0直接编译失败。重写花了大半天。另一个意外是测试注解。MockBean和SpyBean在4.0中被移除了官方建议替换为Spring Test的MockitoBean和MockitoSpyBean。这个替换本身不难但项目里有三十多个测试类分散使用批量替换后还需要逐个验证Mock行为是否一致。回头看如果重来一次三周下来项目最终跑在了4.0上启动速度确实快了虚拟线程的接入也比预想顺利。但如果重新规划我会做三件事。第一预留两倍于预估的时间。我最初估了一周实际用了三周。跨代迁移的隐性成本——第三方库的版本兼容、自动化工具覆盖不到的角落、测试行为的微妙变化——远比你想象的多。第二把Jackson 3的适配提前到升级清单的第一项。序列化问题是4.0迁移中最容易在生产环境暴露的坑而且往往以“接口突然报错”的形式出现排查方向容易被误导。在测试环境就应该用真实流量回放来验证所有涉及JSON出入的接口。第三不要跳过3.5的稳定期。我在3.5上只停留了三天就急着往4.0推。现在想来如果在3.5上多跑一两周让javax替换的隐患充分暴露4.0的迁移会从容得多。官方推荐先升到3.5.x最新版验证通过再继续这条建议值得严格遵守。升级完成的那天我在提交记录里写了一句大版本迁移没有捷径分阶段走就是最快的路。
