服务框架升级前，先做哪些确认

服务框架升级前先做哪些确认从 Spring Boot 2 升到 3风险多半来自 Jakarta 命名空间、依赖版本和运行时行为。升级前先列出兼容性范围、验证路径和回滚方案能减少把问题带到发布窗口的概率。java.lang.NoClassDefFoundError: javax/servlet/Filter at java.base/java.lang.ClassLoader.defineClass1(Native Method) at org.springframework.boot.context.embedded.EmbeddedWebApplicationContext...与之伴随的还有自己编写的自定义 Starter 在启动时静默失效——所有标注了Configuration的 AutoConfiguration 类就像凭空消失了一样连日志都没打出一行。很多团队觉得 Spring Boot 大版本升级无非就是改改pom.xml里的version再把 JDK 从 8 改成 17 或 21。实际踩过坑才知道从 Spring Boot 2.x 迈向 3.x底层涉及了 SPI 加载机制的彻底替换、Jakarta EE 命名空间断层以及条件装配 Matcher 的解析顺序重构。如果不做前置确认就盲目上线灰度发布阶段等待你的只能是频繁的回滚。# 检查依赖树中是否依然混入了旧版的 javax.servlet 依赖包 mvn dependency:tree -Dverbose -Dincludesjavax.servlet:* # 扫描工程中所有的 META-INF/spring.factories 文件排查未迁移的 AutoConfiguration find . -type f -path */META-INF/spring.factories | xargs grep EnableAutoConfigurationSpring Boot 底层 SPI 机制演进物理对比在 Spring Boot 2.7 之前框架的自动装配核心依赖SpringFactoriesLoader去读取META-INF/spring.factories。而到了 Spring Boot 3.0这一机制被彻底废弃取而代之的是AutoConfiguration.imports。如果团队内部维护了公共的底层 Starter且没有在META-INF/spring/下补全AutoConfiguration.imports文件升级到 Spring Boot 3.x 后这些 Starter 里的配置类将完全不会被 Spring 容器扫描到。双版本兼容的生产级 AutoConfiguration 编写规范如果你的组件库需要同时支持公司内部尚未升级的 Spring Boot 2.x 应用和新拉起的 Spring Boot 3.x 应用可以通过以下代码结构实现渐进式兼容。1. 物理配置文件双写在src/main/resources/目录下同时保留两个 SPI 声明文件META-INF/spring.factories供 Boot 2.x 使用org.springframework.boot.autoconfigure.EnableAutoConfiguration\ com.company.boot.starter.CoreAutoConfigurationMETA-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports供 Boot 3.x 使用com.company.boot.starter.CoreAutoConfiguration2. 兼容 Java 命名空间与 Class 条件装配代码在 Java 代码层面为了同时兼容javax.servlet与jakarta.servlet可以使用 Spring 框架的条件注解与反射机制进行隔离包装。package com.company.boot.starter; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.boot.autoconfigure.AutoConfiguration; import org.springframework.boot.autoconfigure.condition.ConditionalOnClass; import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; import org.springframework.context.annotation.Bean; AutoConfiguration // Spring Boot 2.7 与 3.x 通用的新注解 public class CoreAutoConfiguration { private static final Logger log LoggerFactory.getLogger(CoreAutoConfiguration.class); public CoreAutoConfiguration() { log.info(CoreAutoConfiguration 自动装配成功已兼容 Boot 2.x 与 3.x 机制); } Bean ConditionalOnMissingBean public ServiceBridge serviceBridge() { // 动态检查当前 JVM 中是 javax 环境还是 jakarta 环境 boolean hasJakarta isClassPresent(jakarta.servlet.Filter); boolean hasJavax isClassPresent(javax.servlet.Filter); log.info(检测环境依赖: jakarta.servlet{}, javax.servlet{}, hasJakarta, hasJavax); return new ServiceBridge(hasJakarta, hasJavax); } private static boolean isClassPresent(String className) { try { Class.forName(className, false, CoreAutoConfiguration.class.getClassLoader()); return true; } catch (ClassNotFoundException e) { return false; } } public record ServiceBridge(boolean isJakarta, boolean isJavax) {} }升级前必做的 5 项工程确认清单为了保障灰度升级过程中可以快速回滚且不破坏数据兼容性升级前必须在 CI 阶段和预发环境挨个核对这 5 项清单。# 确认清单 1: 扫描 Jar 包中是否有残留的 javax 依赖冲突 mvn dependency:analyze | grep -E javax.servlet|javax.persistence # 确认清单 2: 编译阶段检查 JDK 17 / 21 的 byte-code 版本标记 (55.0 Java 11, 61.0 Java 17) javap -v target/classes/com/company/boot/starter/CoreAutoConfiguration.class | grep major version确认 1三方 Jar 包的 Jakarta 转移程度除了自己的业务代码必须检查Spring Security、Hibernate、Druid、MyBatis-Plus的版本。如果 Druid 使用了旧版druid-spring-boot-starter版本 1.2.20它会在启动时因为找不到javax.sql.DataSource报错。必须将其升级为druid-spring-boot-3-starter。确认 2spring.factories到.imports的全面梳理使用脚本对工程依赖的自研二方库进行递归扫描确保所有包含EnableAutoConfiguration的二方库都已经提供了AutoConfiguration.imports。3. RestTemplate 与 WebClient 默认 HTTP Client 的变更确认Spring Boot 3.0 把RestTemplate底层的默认 Client 改变了且去除了对旧版 Apache HttpClient 4.x 的默认适配转而支持Apache HttpClient 5.x。如果不显式配置 Client Factory在高并发场景下会导致 连接连接池复用失效退化为短连接模式。4. 属性绑定规则 (ConfigurationProperties) 的严格校验在 2.x 中宽松绑定Relaxed Binding允许my_config_item自动映射到myConfigItem。但在 3.x 升级后环境变量与 YAML 属性映射更加严格特别是带有短横线与下划线混合的配置必须全部规范化为 kebab-case (如my-config-item)。5. 灰度双跑与可回滚部署策略灰度上线时将旧 Boot 2.x Pod 与新 Boot 3.x Pod 混合部署在同一个 Nacos / Eureka 注册中心里。此时必须验证RPC 序列化兼容性。例如 Hessian2 或 JDK Native 序列化在跨 Java 17/8 传输java.time.LocalDateTime时非常容易报序列化 Error。建议 RPC 序列化统一使用 Protobuf 或 Jackson JSON。把这几项在上线前确认清楚Spring Boot 大版本升级就不再是一场碰运气的冒险。