Spring Boot 3.2 集成 Shiro 2.0.1 踩坑实录：从 javax.servlet 到 jakarta.servlet 的完整迁移指南

Spring Boot 3.2 与 Shiro 2.0.1 深度整合实战跨越 Jakarta EE 的兼容性鸿沟当我们将项目从 Spring Boot 2.x 升级到 3.2 版本时许多开发者都会遇到一个令人头疼的问题——原本运行良好的 Shiro 安全框架突然失效了。这背后隐藏着一个更深层次的变革Java EE 向 Jakarta EE 的演进。本文将带你深入剖析这一兼容性问题的本质并提供一套完整的解决方案。1. 问题背景与现象分析上周五晚上十点当我将本地开发环境的 Spring Boot 版本从 2.7.5 升级到 3.2.0 后启动日志一切正常但所有需要权限校验的接口突然都可以被随意访问了。Shiro 的过滤器链似乎完全失去了作用。经过初步排查我发现问题出在 Servlet API 的包名变更上。Spring Boot 3.x 基于 Java 17 和 Jakarta EE 9其中最大的变化之一就是将javax.servlet迁移到了jakarta.servlet。而 Shiro 1.x 版本仍然使用旧的javax.servlet包结构这就导致了类加载时的兼容性问题。关键现象总结应用启动无报错但 Shiro 权限控制完全失效日志中无任何权限校验相关的记录调试发现 ShiroFilter 未被正确初始化2. 技术原理从 Java EE 到 Jakarta EE要彻底解决这个问题我们需要理解背后的技术演进。2017 年Oracle 将 Java EE 移交给了 Eclipse 基金会由于商标授权问题Java EE 被重命名为 Jakarta EE。这不仅仅是名称的变更更带来了深层次的技术调整特性Java EE 8 及之前Jakarta EE 9 及之后基础包名javax.*jakarta.*规范维护OracleEclipse 基金会兼容性向后兼容需要显式迁移这种命名空间的变更影响深远特别是对于那些深度依赖 Servlet API 的框架比如 Shiro。当 Spring Boot 3.x 强制使用jakarta.servlet时任何仍然引用javax.servlet的库都会面临兼容性问题。3. 解决方案Shiro 2.0.1 的 Jakarta 适配经过深入调研我发现 Apache Shiro 团队已经意识到了这个问题并在 2.0.0 版本后提供了 Jakarta 兼容版本。不过这个解决方案并不像简单的版本升级那么简单。3.1 Maven 依赖配置正确的依赖配置是解决问题的第一步。我们需要使用带有jakarta分类器(classifier)的 Shiro 组件!-- 核心配置 -- dependency groupIdorg.apache.shiro/groupId artifactIdshiro-spring/artifactId version2.0.1/version classifierjakarta/classifier exclusions exclusion groupIdorg.apache.shiro/groupId artifactIdshiro-core/artifactId /exclusion exclusion groupIdorg.apache.shiro/groupId artifactIdshiro-web/artifactId /exclusion /exclusions /dependency !-- 显式引入 Jakarta 兼容版本 -- dependency groupIdorg.apache.shiro/groupId artifactIdshiro-core/artifactId version2.0.1/version classifierjakarta/classifier /dependency dependency groupIdorg.apache.shiro/groupId artifactIdshiro-web/artifactId version2.0.1/version classifierjakarta/classifier /dependency注意必须确保所有 Shiro 相关依赖都使用 jakarta 分类器并排除可能引入 javax 版本的传递依赖。3.2 代码层面的调整除了依赖配置我们还需要检查代码中是否有直接引用javax.servlet的地方。常见的需要修改的类包括自定义 Realm 实现自定义 Filter 实现任何直接使用 HttpServletRequest/Response 的工具类修改示例// 修改前 import javax.servlet.http.HttpServletRequest; // 修改后 import jakarta.servlet.http.HttpServletRequest;4. 完整迁移检查清单为了确保迁移彻底完成我总结了一份检查清单依赖检查运行mvn dependency:tree确认没有 javax.servlet 的残留检查所有第三方库是否兼容 Jakarta EE代码检查全局搜索import javax.servlet检查测试用例中的 Mock 对象运行时验证确认 Shiro 过滤器链正常工作测试各种权限场景构建环境确保 CI/CD 流水线使用正确的 JDK 版本(17)更新 Docker 基础镜像5. 常见问题与解决方案在实际迁移过程中我遇到了几个典型问题问题1应用启动时报NoClassDefFoundError或ClassNotFoundException与 Servlet API 相关解决方案确认所有 Shiro 依赖都使用了 jakarta 分类器检查是否有其他库引入了 javax.servlet 的传递依赖问题2权限校验逻辑异常但无报错解决方案检查 ShiroFilter 的配置顺序确认 RequiresPermissions 等注解所在的包是 jakarta问题3单元测试失败解决方案更新 Mock 相关的导入语句检查测试框架的兼容性迁移到 Jakarta EE 是一个不可逆的趋势虽然短期内会带来一些适配工作但从长远来看这确保了框架能够持续获得维护和更新。在完成 Shiro 的迁移后我发现系统启动速度有所提升而且能够更顺畅地使用 Spring Boot 3.2 的新特性。