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。这不仅仅是名称的变更，更带来了深层次的技术调整：

这种命名空间的变更影响深远，特别是对于那些深度依赖 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> <groupId>org.apache.shiro</groupId> <artifactId>shiro-spring</artifactId> <version>2.0.1</version> <classifier>jakarta</classifier> <exclusions> <exclusion> <groupId>org.apache.shiro</groupId> <artifactId>shiro-core</artifactId> </exclusion> <exclusion> <groupId>org.apache.shiro</groupId> <artifactId>shiro-web</artifactId> </exclusion> </exclusions> </dependency> <!-- 显式引入 Jakarta 兼容版本 --> <dependency> <groupId>org.apache.shiro</groupId> <artifactId>shiro-core</artifactId> <version>2.0.1</version> <classifier>jakarta</classifier> </dependency> <dependency> <groupId>org.apache.shiro</groupId> <artifactId>shiro-web</artifactId> <version>2.0.1</version> <classifier>jakarta</classifier> </dependency>

注意：必须确保所有 Shiro 相关依赖都使用 jakarta 分类器，并排除可能引入 javax 版本的传递依赖。

3.2 代码层面的调整

除了依赖配置，我们还需要检查代码中是否有直接引用javax.servlet的地方。常见的需要修改的类包括：

1. 自定义 Realm 实现
2. 自定义 Filter 实现
3. 任何直接使用 HttpServletRequest/Response 的工具类

修改示例：

// 修改前 import javax.servlet.http.HttpServletRequest; // 修改后 import jakarta.servlet.http.HttpServletRequest;

4. 完整迁移检查清单

为了确保迁移彻底完成，我总结了一份检查清单：

1. 依赖检查：

   • 运行mvn dependency:tree确认没有 javax.servlet 的残留
   • 检查所有第三方库是否兼容 Jakarta EE

2. 代码检查：

   • 全局搜索import javax.servlet
   • 检查测试用例中的 Mock 对象

3. 运行时验证：

   • 确认 Shiro 过滤器链正常工作
   • 测试各种权限场景

4. 构建环境：

   • 确保 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 的新特性。