Apache Shiro与Jakarta EE兼容性配置指南

背景介绍

Apache Shiro作为Java安全框架，在2.0.0版本开始提供了对Jakarta EE的支持。随着Java EE向Jakarta EE的过渡，许多开发者在使用Shiro时遇到了与Servlet API相关的兼容性问题。

问题现象

当开发者使用Shiro的Spring Boot Starter时，可能会遇到ShiroFilterFactoryBean的setFilters方法期望接收javax.servlet.Filter类型参数的问题，而实际环境中使用的是Jakarta EE的jakarta.servlet.Filter接口。

解决方案

1. 正确声明依赖

确保所有Shiro相关依赖都使用Jakarta分类器：

<dependency>
    <groupId>org.apache.shiro</groupId>
    <artifactId>shiro-core</artifactId>
    <classifier>jakarta</classifier>
    <version>2.0.0</version>
</dependency>
<dependency>
    <groupId>org.apache.shiro</groupId>
    <artifactId>shiro-web</artifactId>
    <classifier>jakarta</classifier>
    <version>2.0.0</version>
</dependency>
<dependency>
    <groupId>org.apache.shiro</groupId>
    <artifactId>shiro-spring-boot-web-starter</artifactId>
    <classifier>jakarta</classifier>
    <version>2.0.0</version>
</dependency>

2. 引入Shiro BOM管理

关键步骤是引入Shiro的BOM(Bill of Materials)来管理依赖版本：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.apache.shiro</groupId>
            <artifactId>shiro-bom</artifactId>
            <version>2.0.0</version>
            <scope>import</scope>
            <type>pom</type>
        </dependency>
    </dependencies>
</dependencyManagement>

技术原理

Shiro 2.0.0通过提供Jakarta分类器的版本，实现了对Jakarta EE API的兼容。BOM的使用确保了所有Shiro组件使用一致的Jakarta版本，避免了因依赖冲突导致的类加载问题。

最佳实践

1. 统一版本管理：始终通过BOM管理Shiro相关依赖版本
2. 完整转换：确保项目中所有Shiro组件都使用Jakarta分类器版本
3. 环境检查：确认项目整体使用Jakarta EE而非Java EE

常见误区

1. 混合使用：同时引入javax和jakarta版本的依赖会导致类冲突
2. 遗漏BOM：仅添加分类器而不使用BOM可能导致某些间接依赖仍指向javax版本
3. 版本不一致：不同Shiro组件使用不同版本会导致兼容性问题

通过遵循上述配置指南，开发者可以顺利地在Jakarta EE环境中使用Apache Shiro的安全功能，避免因API变更导致的兼容性问题。