Sa-Token 1.34.0适配Spring Boot 3.0全攻略

1. Sa-Token 框架概述与版本迭代背景

Sa-Token作为Java生态中广受欢迎的轻量级权限认证框架，自2018年发布以来已迭代至1.34.0版本。这个由国内开发者社区主导的开源项目，以其简洁的API设计和全面的权限管理功能，在Gitee平台获得超过5000星标，并入选GVP（Gitee最有价值开源项目）。框架核心解决了Web应用中的身份认证（Authentication）、授权（Authorization）和会话管理（Session Management）三大基础安全问题。

随着Spring Boot 3.0的正式发布，Java生态迎来重大变革。新版本基于Java 17+基线，引入Jakarta EE 9+命名空间，并对GraalVM原生镜像提供实验性支持。这些变化导致大量依赖Spring Boot 2.x的组件需要适配升级。Sa-Token 1.34.0正是为响应这一技术演进而发布的关键版本，其核心价值在于：

  • 保持原有API设计哲学：延续"一行代码实现登录"的极简风格
  • 无缝对接Spring Boot 3新特性：包括对Reactive编程模型的深度支持
  • 解决兼容性痛点：特别是Jakarta包名变更引发的类加载问题

2. Spring Boot 3适配的核心技术点

2.1 Jakarta EE 9+命名空间迁移

Spring Boot 3最大的破坏性变更来自javax.*到jakarta.*的包名切换。Sa-Token 1.34.0对所有涉及Servlet API的模块进行了重构：

// 旧版本(Spring Boot 2.x) import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; // 新版本(Spring Boot 3.x) import jakarta.servlet.http.HttpServletRequest; import jakarta.servlet.http.HttpServletResponse;

这种变更影响到了：

  • 核心过滤器SaTokenFilter的请求/响应处理
  • Cookie操作工具类SaTokenCookie
  • 会话存储模块的Servlet依赖

实际升级时常见的ClassNotFoundException往往源于依赖传递未统一。建议使用Maven的dependency:tree检查所有间接依赖是否都已升级到Jakarta兼容版本。

2.2 自动配置机制升级

Spring Boot 3重构了自动配置加载机制，Sa-Token对此进行了针对性适配：

  1. 配置属性前缀变更：
# 旧版配置 sa-token.token-name=satoken # 新版推荐写法（保持兼容） spring.sa-token.token-name=satoken

  1. 条件装配逻辑优化： 新版本采用更严格的Bean加载条件判断，特别是对WebFlux等非阻塞场景的支持。Sa-Token现在会根据spring.webflux.enabled自动切换响应式编程模型。

  2. 健康检查端点扩展： 新增/actuator/satoken端点，暴露会话统计信息和权限策略配置。

2.3 Redis集成方案升级

针对Spring Boot 3的Redis客户端变更：

  1. Lettuce连接池配置：
spring: data: redis: client-type: lettuce lettuce: pool: max-active: 16 max-wait: 200ms
  1. 序列化策略调整： 默认采用Jackson2JsonRedisSerializer替代JDK序列化，解决Java 17模块化带来的反射限制：
@Bean public RedisTemplate<String, Object> saTokenRedisTemplate(RedisConnectionFactory factory) { RedisTemplate<String, Object> template = new RedisTemplate<>(); template.setConnectionFactory(factory); template.setKeySerializer(new StringRedisSerializer()); template.setValueSerializer(new Jackson2JsonRedisSerializer<>(Object.class)); return template; }

3. 从Spring Boot 2.x迁移的完整指南

3.1 依赖管理调整

在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>

注意区分两个starter：

  • sa-token-spring-boot-starter：用于Spring Boot 2.x
  • sa-token-spring-boot3-starter：专为Spring Boot 3设计

3.2 配置文件迁移

典型配置对比示例：

配置项Spring Boot 2.x格式Spring Boot 3.x推荐格式
Token名称sa-token.token-namespring.sa-token.token-name
超时时间sa-token.timeout=3600spring.sa-token.timeout=3600
Redis地址sa-token.redis.host=127.0.0.1spring.data.redis.host=127.0.0.1

3.3 代码级适配要点

  1. 注解鉴权调整： 原先的@SaCheckLogin等注解需要更新导入路径：
import cn.dev33.satoken.annotation.SaCheckLogin; // 路径不变 // 但需要确保aop依赖兼容
  1. 拦截器注册变化： WebMvcConfigurer的实现方式有所调整：
@Configuration public class SaTokenConfig implements WebMvcConfigurer { @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(new SaInterceptor()) .addPathPatterns("/**") .excludePathPatterns("/auth/login"); } }

4. 实战中的典型问题与解决方案

4.1 混合依赖导致的类冲突

常见错误日志示例：

java.lang.NoClassDefFoundError: javax/servlet/Filter

解决方案步骤：

  1. 执行mvn dependency:tree检查依赖树
  2. 排除传递性javax依赖：
<dependency> <groupId>com.example</groupId> <artifactId>some-library</artifactId> <exclusions> <exclusion> <groupId>javax.servlet</groupId> <artifactId>javax.servlet-api</artifactId> </exclusion> </exclusions> </dependency>

4.2 Redis序列化异常

错误表现：

org.springframework.data.redis.serializer.SerializationException: Could not read JSON...

处理方案：

  1. 确保实体类实现Serializable
  2. 添加无参构造函数
  3. 检查Jackson注解配置

4.3 响应式编程支持

在WebFlux环境中需要特别配置：

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

5. 升级后的验证 Checklist

为确保迁移成功，建议按以下步骤验证：

  1. 基础功能验证：

    • [ ] 登录接口返回Token正确
    • [ ] 权限注解生效
    • [ ] 会话超时配置有效

  2. Redis集成验证：

    • [ ] 重启服务后会话保持
    • [ ] 集群环境下会话同步

  3. 性能基准测试：

    # 使用wrk进行压力测试 wrk -t4 -c100 -d30s http://localhost:8080/api/protected

  4. 监控指标检查：

    • [ ] /actuator/satoken端点可访问
    • [ ] Prometheus指标采集正常

我在实际项目升级过程中发现，合理规划迁移窗口期非常重要。建议先在预发布环境进行完整回归测试，特别注意微服务之间的鉴权交互。对于大型分布式系统，可以采用金丝雀发布策略逐步替换节点。