Spring Boot 3.0 + Java 17 整合 Shiro 踩坑记：从 javax.servlet 到 jakarta.servlet 的完整迁移指南-程序员充电站

Spring Boot 3.0 + Java 17 整合 Shiro 的完整迁移实战：从 javax.servlet 到 jakarta.servlet 的深度解析

最近在将一个老项目升级到 Spring Boot 3.0 和 Java 17 时，遇到了一个典型的"踩坑"场景：整合 Shiro 时抛出了ClassNotFoundException: javax.servlet.Filter错误。这个看似简单的错误背后，实际上隐藏着 Java EE 到 Jakarta EE 的演进历史。本文将带你深入理解这个问题，并提供一套完整的解决方案。

1. 问题背景与根源分析

当你在 Spring Boot 3.0 项目中尝试集成 Shiro 时，可能会遇到以下错误堆栈：

java.lang.ClassNotFoundException: javax.servlet.Filter at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:641) at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(ClassLoaders.java:188) at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:520)

这个错误的根源在于Servlet API 的包名变更。从 Java EE 到 Jakarta EE 的转变过程中，最显著的变化之一就是包名的迁移：

Java EE 时代：javax.servlet.*
Jakarta EE 时代：jakarta.servlet.*

Spring Boot 3.0 基于 Servlet 5.0 规范，已经完全迁移到了 Jakarta EE 9+ 的命名空间。而许多老版本的库（包括 Shiro 的某些模块）仍然使用旧的javax.servlet包名，这就导致了类加载失败。

提示：这个迁移不仅仅是简单的包名替换，还涉及到一些 API 的细微变化，因此需要特别注意兼容性问题。

2. 解决方案全景图

解决这个问题的完整方案包含以下几个关键步骤：

使用 Shiro 的 Jakarta 兼容版本：Shiro 1.11.0+ 提供了专门适配 Jakarta 的版本
排除冲突的依赖：确保项目中不会混用 javax 和 jakarta 版本的 Servlet API
验证依赖树：使用 Maven 或 Gradle 工具检查依赖关系

2.1 关键 Maven 配置

以下是经过验证的完整 pom.xml 配置片段：

<dependency> <groupId>org.apache.shiro</groupId> <artifactId>shiro-spring</artifactId> <classifier>jakarta</classifier> <version>1.11.0</version> <!-- 排除仍使用了javax.servlet的依赖 --> <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> <classifier>jakarta</classifier> <version>1.11.0</version> </dependency> <dependency> <groupId>org.apache.shiro</groupId> <artifactId>shiro-web</artifactId> <classifier>jakarta</classifier> <version>1.11.0</version> <exclusions> <exclusion> <groupId>org.apache.shiro</groupId> <artifactId>shiro-core</artifactId> </exclusion> </exclusions> </dependency>

2.2 配置解析

这个配置有几个关键点：

<classifier>jakarta</classifier>：指定使用 Jakarta 兼容版本
<exclusions>：排除仍然依赖 javax.servlet 的子模块
版本一致性：确保所有 Shiro 组件使用相同版本

3. 深入理解依赖冲突

为了彻底解决问题，我们需要深入理解 Maven 依赖树。可以使用以下命令查看依赖关系：

mvn dependency:tree -Dincludes=org.apache.shiro

典型的依赖冲突场景可能如下表所示：

问题依赖	冲突表现	解决方案
shiro-core	依赖 javax.servlet	使用 jakarta 分类器版本
shiro-web	传递依赖旧版 shiro-core	显式排除并引入正确版本
shiro-spring	内部依赖未迁移的组件	排除后单独配置

注意：在实际项目中，可能还需要检查其他间接依赖是否引入了 javax.servlet API，确保完全清除所有冲突源。

4. 完整集成步骤

4.1 环境准备

确保你的开发环境满足以下要求：

JDK 17+
Spring Boot 3.0+
Maven 3.6+ 或 Gradle 7+

4.2 分步集成指南

添加基础依赖：

首先添加 Spring Boot 和 Shiro 的基础依赖：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>

配置 Shiro Jakarta 版本：
使用前面提供的完整配置添加 Shiro 依赖。

创建 Shiro 配置类：

@Configuration public class ShiroConfig { @Bean public SecurityManager securityManager() { DefaultWebSecurityManager securityManager = new DefaultWebSecurityManager(); // 配置 Realm 等组件 return securityManager; } @Bean public ShiroFilterFactoryBean shiroFilter(SecurityManager securityManager) { ShiroFilterFactoryBean filterFactoryBean = new ShiroFilterFactoryBean(); filterFactoryBean.setSecurityManager(securityManager); // 配置过滤规则 return filterFactoryBean; } }