Sa-Token v1.34.0全面适配SpringBoot3的技术解析

weixin_30421809

340人浏览 · 2026-07-16 16:48:49

weixin_30421809 · 2026-07-16 16:48:49 发布

1. Sa-Token v1.34.0 更新概览

Sa-Token v1.34.0 版本的核心目标是实现对 SpringBoot3 的全面适配。作为 Java 生态中广受欢迎的权限认证框架，这次更新解决了 SpringBoot 大版本升级带来的兼容性问题。从技术实现来看，主要涉及以下几个方面的适配工作：

包路径调整：SpringBoot3 将 javax 包迁移到了 jakarta 包下
自动配置机制变更：SpringBoot3 对自动配置加载机制进行了优化
依赖管理调整：SpringBoot3 对 starter 的依赖管理方式有所改变

提示：升级前建议先检查项目中是否有直接依赖 javax 包的代码，这些都需要手动调整为 jakarta 包路径。

2. SpringBoot3 适配细节解析

2.1 包路径迁移方案

SpringBoot3 最大的变化就是从 javax.* 迁移到了 jakarta.* 命名空间。这对 Sa-Token 的影响主要体现在：

Servlet API 相关接口：如 HttpServletRequest/Response
JSR 标准注解：如 @PostConstruct、@PreDestroy
其他第三方依赖：如 validation-api

我们在适配过程中采用了条件编译的方式，通过 Maven 的 profiles 配置实现不同版本的兼容：

<profiles>
    <profile>
        <id>springboot2</id>
        <dependencies>
            <dependency>
                <groupId>javax.servlet</groupId>
                <artifactId>javax.servlet-api</artifactId>
            </dependency>
        </dependencies>
    </profile>
    <profile>
        <id>springboot3</id>
        <dependencies>
            <dependency>
                <groupId>jakarta.servlet</groupId>
                <artifactId>jakarta.servlet-api</artifactId>
            </dependency>
        </dependencies>
    </profile>
</profiles>

2.2 自动配置机制调整

SpringBoot3 对自动配置机制做了以下优化：

移除了 spring.factories 自动发现机制
改用 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
配置项前缀统一规范

Sa-Token 的自动配置类需要相应调整：

# 旧版配置方式
META-INF/spring.factories
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
cn.dev33.satoken.spring.SaTokenAutoConfiguration

# 新版配置方式
META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
cn.dev33.satoken.spring.SaTokenAutoConfiguration

3. 升级实操指南

3.1 环境准备

升级前需要确认以下环境条件：

JDK 版本 ≥ 17（SpringBoot3 最低要求）
Maven/Gradle 构建工具最新稳定版
IDE 支持 Jakarta EE 9+ 规范

推荐使用以下版本组合：

SpringBoot 3.1.5
Sa-Token 1.34.0
JDK 17/21

3.2 具体升级步骤

修改 pom.xml 依赖：

<!-- 移除旧版依赖 -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-boot-starter</artifactId>
    <version>1.33.0</version>
</dependency>

<!-- 添加新版依赖 -->  
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-boot3-starter</artifactId>
    <version>1.34.0</version>
</dependency>

全局替换 javax 为 jakarta：
- 在 IDE 中使用全局替换功能
- 重点检查过滤器、拦截器相关代码
配置项检查：
- 原有的 sa-token.* 配置前缀保持不变
- 检查 redis 连接配置（如果使用redis集成）
测试验证：
- 基础登录功能
- 权限校验功能
- Session操作
- 踢人下线等高级功能

4. 常见问题解决方案

4.1 类找不到问题

报错示例：

java.lang.ClassNotFoundException: javax.servlet.Filter

解决方案：

确保使用了正确的 starter（sa-token-spring-boot3-starter）
检查依赖冲突，排除传递依赖中的 javax 包

4.2 自动配置不生效

可能原因：

配置文件位置不正确
包扫描路径未包含 Sa-Token 组件

排查步骤：

检查 META-INF/spring 目录结构
在启动类添加显式注解：

@Import({SaTokenAutoConfiguration.class})

4.3 Redis 集成异常

SpringBoot3 中 Lettuce 客户端有较大变化，建议：

使用最新版本的 spring-boot-starter-data-redis
检查连接池配置：

spring:
  redis:
    lettuce:
      pool:
        max-active: 8
        max-idle: 8
        min-idle: 0

5. 升级后的性能优化

适配 SpringBoot3 后，可以结合新特性进行优化：

虚拟线程支持（JDK21+）：

@Bean
public SaTokenConfig saTokenConfig() {
    SaTokenConfig config = new SaTokenConfig();
    config.setIsVirtualThread(true);
    return config;
}

响应式编程支持：

@Bean 
public SaReactorFilter saReactorFilter() {
    return new SaReactorFilter()
        .addInclude("/**")
        .setAuth(obj -> SaRouter.match("/**").check());
}

AOT 编译优化：

提前生成 native image
减少运行时反射开销

6. 最佳实践建议

渐进式升级策略：
- 先在新模块中使用 SpringBoot3
- 逐步迁移老模块
- 使用兼容层处理跨版本调用
监控指标集成：

@Bean
public MeterRegistryCustomizer<MeterRegistry> saTokenMetrics() {
    return registry -> {
        registry.gauge("sa_token.session.count", 
            SaManager.getSaTokenDao()::getSessionCount);
    };
}