从javax到jakarta：JeecgBoot升级Spring Boot 3.1.5的Shiro与Knife4j深度适配指南

最近在技术社区看到不少团队开始将JeecgBoot项目迁移到Spring Boot 3.1.5，但普遍反映Shiro权限框架和Knife4j接口文档的适配过程相当棘手。作为经历过完整升级流程的实践者，我想分享一些官方文档没详细说明的实战经验。这次升级不仅仅是版本号的变更，更涉及到从javax到jakarta的命名空间迁移、依赖生态的全面调整，稍有不慎就会陷入各种兼容性陷阱。

1. 升级前的环境评估与准备

在动手之前，建议先用dependency:tree命令生成当前项目的完整依赖树并保存为基准。我遇到过团队直接开始修改pom.xml，结果陷入依赖地狱无法回退的情况。Spring Boot 3.1.5对运行环境有明确要求：

• JDK版本 ：必须≥17（推荐17 LTS版本）
• 构建工具 ：Maven 3.6.3+ 或 Gradle 7.x
• IDE支持 ：需要确保IDE支持Jakarta EE 9+的命名空间（如IntelliJ IDEA 2022.3+）

特别提醒：检查项目中是否有直接依赖javax.servlet-api的地方。使用以下命令快速定位：

mvn dependency:tree | grep 'javax.servlet'

2. Shiro适配的三大核心问题解决方案

2.1 Jakarta命名空间适配

Shiro官方提供了jakarta分类器的适配版本，但需要注意依赖排除策略。以下是经过生产验证的配置方案：

<dependency>
    <groupId>org.apache.shiro</groupId>
    <artifactId>shiro-spring-boot-starter</artifactId>
    <version>1.11.0</version>
    <exclusions>
        <exclusion>
            <groupId>org.apache.shiro</groupId>
            <artifactId>shiro-spring</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<!-- 关键：使用jakarta分类器版本 -->
<dependency>
    <groupId>org.apache.shiro</groupId>
    <artifactId>shiro-spring</artifactId>
    <classifier>jakarta</classifier>
    <version>1.11.0</version>
</dependency>

2.2 Jedis版本冲突的优雅解决

Spring Boot 3.1.5默认带的Jedis 4.x与shiro-redis存在兼容问题。推荐方案不是简单降级，而是采用隔离加载：

1. 在 <dependencyManagement> 中锁定Jedis版本
2. 为shiro-redis创建单独的Bean定义

@Bean
@ConfigurationProperties(prefix = "spring.redis")
public RedisConnectionFactory shiroRedisConnectionFactory() {
    JedisConnectionFactory factory = new JedisConnectionFactory();
    factory.setUsePool(true);
    return factory;
}

2.3 自定义Filter的改造要点

原有继承自javax.servlet的Filter需要重写为jakarta版本。常见问题包括：

• @WebFilter 注解的包路径变更
• FilterChainDefinitionMap的配置方式调整
• SessionDAO实现类的接口变化

提示：使用IDE的全局替换功能时，注意不要替换测试代码中的mock javax.servlet对象

3. Knife4j的全套注解迁移策略

3.1 注解对照表与常见陷阱

从springfox到springdoc的注解变化不仅仅是简单的重命名，还包括参数结构的调整。以下是容易出错的映射关系：

原注解	新注解	特别注意事项
@Api	@Tag	name属性改为title
@ApiModelProperty	@Schema	枚举值的表示方式变化
@ApiImplicitParam	@Parameter	必须显式声明in参数

// 改造前
@ApiOperation(value="用户登录", notes="返回JWT令牌")
public Result<String> login(...)

// 改造后
@Operation(summary="用户登录", description="返回JWT令牌")
public Result<String> login(...)

3.2 配置类的重写要点

Knife4j 4.x版本的OpenAPI配置需要特别注意两点：

1. GroupedOpenApi的路径匹配规则更严格
2. SecurityScheme的配置方式变化

推荐采用工厂模式创建配置：

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .components(new Components()
            .addSecuritySchemes("bearerAuth", 
                new SecurityScheme()
                    .type(SecurityScheme.Type.HTTP)
                    .scheme("bearer")
                    .bearerFormat("JWT")))
        .info(new Info()
            .title("API文档")
            .version("3.0"));
}

4. 升级后的验证与调试技巧

4.1 分层验证策略

建议按以下顺序验证系统功能：

1. 基础验证 ：项目能否正常启动
2. Shiro验证 ：
   • 权限注解是否生效
   • Session共享是否正常
   • Redis缓存是否工作
3. Knife4j验证 ：
   • 文档能否正常访问
   • 参数示例是否正确显示
   • 认证头是否可传递

4.2 常见问题排查表

现象	可能原因	解决方案
启动时报ClassNotFound	未正确排除javax包	检查所有shiro依赖的exclusions
权限注解失效	代理模式变化	添加@EnableAspectJAutoProxy
文档页面空白	静态资源冲突	调整springdoc.swagger-ui.path

4.3 性能监控建议

升级后建议重点关注：

• Shiro的授权响应时间
• Knife4j的文档生成耗时
• Redis连接池的使用情况

可以使用Spring Boot Actuator添加自定义监控端点：

@Endpoint(id="shiro-metrics")
@Component
public class ShiroMetricsEndpoint {
    @ReadOperation
    public Map<String, Object> metrics() {
        // 返回Shiro性能指标
    }
}

整个升级过程最耗时的往往不是技术实现，而是全面测试各个业务场景下的权限控制和接口文档展示。建议建立完整的回归测试用例集，特别要关注原有自定义Filter链和Swagger扩展功能的表现。