Spring Boot升级后依赖冲突导致启动失败

Question

升级Spring Boot至2.7或3.x版本后，常因内嵌Tomcat版本变更与第三方库（如 springfox-swagger）不兼容导致启动失败，典型表现为`java.lang.NoClassDefFoundError: javax/servlet/Filter`或`Unsupported class file major version`。此问题源于Spring Boot 3移除了javax.servlet支持（转为jakarta.servlet），而旧版依赖未适配Jakarta EE，引发类加载失败。需排查并替换不兼容依赖，如使用springdoc-openapi替代swagger。

Answer 1

1. 问题背景与现象分析

在将Spring Boot项目从2.x版本升级至2.7或3.x版本过程中，开发者普遍遇到应用启动失败的问题。典型异常包括：

• java.lang.NoClassDefFoundError: javax/servlet/Filter
• Unsupported class file major version 61
• java.lang.ClassNotFoundException: javax.servlet.ServletContextListener

这些错误的根本原因在于Spring Boot 3.x开始全面采用Jakarta EE 9+规范，将原有的javax.*命名空间迁移至jakarta.*。例如，javax.servlet.Filter变为jakarta.servlet.Filter，而大量第三方库如springfox-swagger仍基于旧的Java EE（即Javax）API构建，导致类加载器无法找到对应类。

2. 技术演进路径：从Java EE到Jakarta EE

自Eclipse基金会接管Java EE并更名为Jakarta EE后，包命名空间发生根本性变化。Spring Boot 3.x顺应这一变革，内嵌Tomcat版本升级至10.x系列，其原生支持Jakarta Servlet 6.0 API，不再兼容javax.servlet。

Spring Boot 版本	内嵌 Tomcat 版本	Servlet API	命名空间
2.6.x 及以下	9.0.x	Servlet 4.0	javax.servlet.*
2.7.x	9.0.x	Servlet 4.0 / 实验性 Jakarta 支持	javax / jakarta 共存
3.0+	10.1.x	Servlet 6.0	jakarta.servlet.*

3. 常见不兼容依赖及其影响

以下为典型的与Spring Boot 3.x不兼容的第三方库：

1. springfox-swagger 2.x / 3.0.0：严重依赖javax.servlet和Springfox内部反射机制，在Jakarta环境下无法初始化Swagger资源。
2. spring-security-oauth2-client（旧版本）：部分过滤器链引用javax.servlet.Filter。
3. jersey-core / jersey-server：若用于REST服务暴露，可能引入javax.ws.rs冲突。
4. log4j-web：某些版本中存在对javax.servlet的硬编码依赖。
5. metrics-servlet：Dropwizard Metrics组件未及时适配Jakarta。

4. 排查与诊断流程

使用以下步骤定位具体冲突源：

        
# 查看依赖树中是否存在 javax.servlet 引用
./mvnw dependency:tree | grep -i servlet

# 搜索具体类的来源jar包
./mvnw dependency:tree -Dverbose -Dincludes=javax.servlet

# 在IDE中全局搜索 "javax.servlet" 使用位置
        
    

通过上述命令可识别出哪些传递依赖仍在引用javax命名空间，进而锁定需替换或排除的模块。

5. 解决方案与替代技术栈

针对关键组件提出现代化替代方案：

旧依赖	问题点	推荐替代方案	优势
springfox-swagger	不支持Jakarta EE，维护停滞	springdoc-openapi-ui	原生支持Spring Boot 3 + OpenAPI 3，自动配置
spring-security-oauth2-client (老)	javax.servlet.Filter 遗留	Spring Security 6.x + OAuth2 Login	标准化、轻量级、集成良好
jersey	JAX-RS javax.* 包	Spring Web MVC + @RestController	减少技术栈复杂度

6. 迁移示例：从 springfox 到 springdoc-openapi

迁移步骤如下：

        

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>


<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.2</version>
</dependency>
        
    

配置完成后，访问http://localhost:8080/swagger-ui.html即可查看API文档界面（路径可能因版本略有不同）。

7. 架构级建议与长期维护策略

为避免未来类似问题，建议实施以下架构原则：

• 建立依赖审查机制，定期扫描javax.*调用。
• 优先选择官方维护活跃、明确支持Spring Boot 3的库。
• 使用@ConditionalOnClass等条件注解隔离老旧组件。
• 引入SBOM（Software Bill of Materials）工具如Syft+CycloneDX进行依赖合规检查。
• 制定版本升级路线图，分阶段完成微服务模块迁移。

8. 自动化检测流程图（Mermaid）

以下为自动化检测与修复建议流程：

graph TD
            A[开始升级Spring Boot至3.x] --> B{是否出现NoClassDefFoundError?}
            B -- 是 --> C[执行dependency:tree分析]
            C --> D[定位包含javax.servlet的jar包]
            D --> E{是否为核心业务组件?}
            E -- 是 --> F[寻找Jakarta兼容替代品]
            E -- 否 --> G[尝试排除冲突依赖]
            F --> H[替换为springdoc-openapi等现代库]
            G --> H
            H --> I[重新编译并测试]
            I --> J{启动成功?}
            J -- 是 --> K[完成迁移]
            J -- 否 --> C