Spring Boot 2.7 已经停止开源维护，升级到 3.x 不只是为了跟进版本，更是获得虚拟线程、原生镜像与新版可观测性体系的前提。本文记录我们团队将 20+ 模块的核心服务从 2.7.18 升级到 3.2.5 的完整过程。

升级前的准备工作

大型项目直接改版本号是灾难的开始。我们花了两天时间做前置工作，事后证明这是整个升级过程中最划算的投资。

依赖与版本对齐

  • 确认 JDK 版本：3.x 最低要求 Java 17，我们选择直接跳到 21（LTS）。
  • 梳理所有第三方 starter：逐一确认其 Spring Boot 3 兼容版本，列出升级对照表。
  • 处理内部框架：自研的 common 包先于业务模块完成 3.x 适配并发布 SNAPSHOT。

利用 OpenRewrite 批量迁移

javax 到 jakarta 的命名空间迁移涉及上千个 import，手工改不现实。OpenRewrite 的一条命令完成了 90% 的机械修改，剩下的 10% 是它覆盖不到的反射与 XML 配置场景。

bash
1# 使用 OpenRewrite 批量完成命名空间与配置迁移2mvn -U org.openrewrite.maven:rewrite-maven-plugin:run \3  -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-spring:RELEASE \4  -Drewrite.activeRecipes=org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_2

核心踩坑记录

Spring Security 6 配置体系重构

Security 6 移除了 WebSecurityConfigurerAdapter，所有配置必须改为声明式的 SecurityFilterChain Bean。我们原有 200 多行的适配器子类，重构成链式配置后反而更清晰了。

java
1@Configuration2@EnableWebSecurity3public class SecurityConfig {45    @Bean6    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {7        http8            .csrf(AbstractHttpConfigurer::disable)9            .authorizeHttpRequests(auth -> auth10                .requestMatchers("/api/public/**").permitAll()11                .requestMatchers("/api/admin/**").hasRole("ADMIN")12                .anyRequest().authenticated())13            .sessionManagement(session ->14                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))15            .addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class);16        return http.build();17    }18}

隐蔽的反射与资源加载问题

有一类问题编译期完全发现不了：通过 Class.forName 动态加载的类、硬编码 javax.servlet 路径的过滤器、还有读取 META-INF/spring.factories 的老式自动装配——后者必须迁移到新的 AutoConfiguration.imports 文件，否则 Starter 静默失效。

升级最大的风险从来不是编译错误，而是「看起来正常运行的静默失效」。回归测试必须覆盖所有自动装配行为。

回归验证与上线策略

我们采用了「双跑对比」策略：新旧版本同时接收从测试流量镜像来的请求，比对响应差异。三天双跑捕获了两个静默问题——一个序列化字段默认值变化，一个 Feign 超时配置未生效。

  1. 单元测试 + 集成测试全绿，覆盖率不低于升级前水平。
  2. 测试环境双跑对比至少 72 小时。
  3. 灰度一台实例观察核心指标（错误率、P99、GC）再全量发布。

整个升级历时两周，其中真正写代码只用了四天，其余时间都在验证。慢就是快，这句话在框架升级这件事上体现得淋漓尽致。