Sa-Token 集成 Redis 全指南RedisTemplate / Redisson 双方案实战与序列化深度解析【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token导读Sa-Token 默认将 Token、Session 等数据保存在内存中读写速度最快且免去序列化开销但存在重启数据丢失和无法在分布式环境中共享会话两大痛点。本指南以sa-token-doc/up/integ-redis.md为骨架完整讲解RedisTemplate 与 Redisson 两种集成方案的依赖引入、连接配置、自定义序列化、多项目键隔离与升级注意事项并结合作者开源仓库中的 Dao 实现源码sa-token-plugin/sa-token-redis-template、sa-token-plugin/sa-token-redisson剖析底层原理。读完本文你将能独立完成 Sa-Token 的 Redis 持久化改造、按需切换 JSON 序列化框架并在多项目共用 Redis 时正确规避键冲突。一、为什么需要集成 RedisSa-Token 默认的内存存储模式虽然性能最优但存在两个硬伤重启后数据丢失内存数据随进程退出全部消失所有已登录用户的会话失效无法在分布式环境中共享数据多节点部署时节点 A 颁发的 Token 在节点 B 无法校验通过。为此Sa-Token 将数据持久化操作抽象到了SaTokenDao接口定义于sa-token-core并提供了多种缓存中间件实现。你只需要引入对应的pom依赖就能将会话数据迁移到 Redis 等专业缓存中间件上做到重启数据不丢失、分布式环境多节点会话一致而框架所有上层 API 保持不变。从源码结构看框架已提供的持久层集成包包括详见 缓存层扩展文档sa-token-redis-template基于 Spring Data Redis 官方RedisTemplate的集成包sa-token-redis-template-jdk-serializerRedis 集成包Object 读写改用 JDK 默认序列化sa-token-redisson与sa-token-redisson-spring-boot-starter基于 Redisson 客户端sa-token-alone-redis/sa-token-alone-redisson独立连接权限缓存与业务缓存分离sa-token-caffeine、sa-token-hutool-timed-cache、sa-token-redisx等其它方案。下文重点讲解最常用的 RedisTemplate 与 Redisson 两条主线。二、方案一整合 Spring 官方 RedisTemplate推荐2.1 引入依赖RedisTemplate是 SpringBoot 官方推荐的 Redis 客户端sa-token-redis-template基于它实现持久化。在项目pom.xml中引入!-- Sa-Token 整合 RedisTemplate -- dependency groupIdcn.dev33/groupId artifactIdsa-token-redis-template/artifactId version${sa.top.version}/version /dependency !-- 提供 Redis 连接池 -- dependency groupIdorg.apache.commons/groupId artifactIdcommons-pool2/artifactId /dependencyGradle 方式// Sa-Token 整合 RedisTemplate implementation cn.dev33:sa-token-redis-template:${sa.top.version} // 提供 Redis 连接池 implementation org.apache.commons:commons-pool2其中${sa.top.version}替换为你实际使用的 Sa-Token 版本。commons-pool2为 Lettuce 连接池提供底层支持属于标准搭配。如果你对 Sa-Token 还不太熟悉、只想省心省事直接使用上述 RedisTemplate 方案即可不必过度研究配置好连接信息后即可跳转到下文集成注意事项继续阅读。2.2 底层实现它是如何工作的sa-token-redis-template的核心类只有一个——SaTokenDaoForRedisTemplate它实现了SaTokenDao接口通过Autowired注入 Spring 容器中的RedisConnectionFactory在init()中自行构建一个StringRedisTemplate并完成初始化isInit标记保证只初始化一次get / set / delete / getTimeout / updateTimeout / searchData等方法逐一映射到stringRedisTemplate的opsForValue()等操作set()对timeout做了约定处理timeout 0或小于SaTokenDao.NOT_VALUE_EXPIRE时直接不写入timeout SaTokenDao.NEVER_EXPIRE时写入永不过期的键否则写入带 TTL秒的键。也就是说集成 Redis 后数据的读写完全由框架自动完成——引入依赖并配置好连接即实现了从内存 Dao到Redis Dao的透明切换。2.3 测试验证仓库为 RedisTemplate 实现提供了完整的单元测试可作为集成正确性的参考验证需要本地可用的 Redis 连接SaTokenDaoForRedisTemplateTest覆盖set / get / update / delete、TTL 读写等核心 CRUD 行为SaTokenDaoForRedisTemplateSearchDataTest验证searchData的 SCAN 模糊匹配与分页排序逻辑底层使用ScanOptions.match()connection.scan()实现避免阻塞生产实例。三、自定义序列化方案按上文方式集成并测试后你会发现框架在 Redis 中是以JSON 格式存储数据的。Sa-Token 的默认序列化调用链为String 序列化→JSON 序列化其中String 序列化负责把框架的 String 类型数据写入 RedisJSON 序列化负责把SaSession等对象序列化为 JSON 字符串。要自定义数据格式可以从这两层分别入手。3.1 自定义 JSON 序列化方案如果你引入的是sa-token-spring-boot-starter集成包含 SpringBoot3框架会自动引入Jackson作为 JSON 序列化方案。若想更换为其它 JSON 解析框架引入对应依赖即可SPI 机制自动注入无需改代码Fastjson!-- Sa-Token 整合 Fastjson -- dependency groupIdcn.dev33/groupId artifactIdsa-token-fastjson/artifactId version${sa.top.version}/version /dependencyGradle 参考implementation cn.dev33:sa-token-fastjson:${sa.top.version}Fastjson2dependency groupIdcn.dev33/groupId artifactIdsa-token-fastjson2/artifactId version${sa.top.version}/version /dependencyGradle 参考implementation cn.dev33:sa-token-fastjson2:${sa.top.version}Snack3dependency groupIdcn.dev33/groupId artifactIdsa-token-snack3/artifactId version${sa.top.version}/version /dependencyGradle 参考implementation cn.dev33:sa-token-snack3:${sa.top.version}说明sa-token-spring-boot4-starter默认引入的是sa-token-jackson3。完整插件列表含 Jackson / Jackson3 / Fory JSON / Snack4 等请参考 JSON 序列化扩展。关于JSON 全局类型白名单的重要提示[!WARNING] 若往 Session 存自定义实体类后从 Redis 读回报错无法反序列化的类型xxx请先将其注册到 JSON 全局类型白名单请参考 JSON 全局类型白名单机制。该机制是 Sa-Token 为防止多态反序列化 RCE攻击者篡改 Redis 中的类型标记、实例化任意类而引入的安全防线只有白名单内的类型才能参与多态反序列化你的业务实体类默认不在白名单中。三种注册方式实体类实现SaJsonType标记接口推荐、启动前调用SaJsonStrategy.instance.registerAllowType(...)、或通过 SPI 文件META-INF/satoken/sa-json-type.list按行声明。3.2 自定义 String 序列化方案如果你希望更直接——不使用 JSON 序列化方案也可以自定义数据的 String 序列化。框架提供了基于 JDK 序列化的三种编码实现类定义于sa-token-core/src/main/java/cn/dev33/satoken/serializer/impl/下通过SaManager.setSaSerializerTemplate(...)全局替换jdk 序列化base64 编码// 设置序列化方案: jdk序列化 (base64编码) PostConstruct public void rewriteComponent() { SaManager.setSaSerializerTemplate(new SaSerializerTemplateForJdkUseBase64()); }jdk 序列化16 进制编码// 设置序列化方案: jdk序列化 (16进制编码) PostConstruct public void rewriteComponent() { SaManager.setSaSerializerTemplate(new SaSerializerTemplateForJdkUseHex()); }jdk 序列化ISO-8859-1 编码// 设置序列化方案: jdk序列化 (ISO-8859-1编码) PostConstruct public void rewriteComponent() { SaManager.setSaSerializerTemplate(new SaSerializerTemplateForJdkUseISO_8859_1()); }以上三类实现类分别位于SaSerializerTemplateForJdkUseBase64SaSerializerTemplateForJdkUseHexSaSerializerTemplateForJdkUseISO_8859_1除上述内置方案外框架还提供了序列化扩展包支持自定义 String / Object 的序列化模板详细参考 序列化插件扩展包。补充如果你希望Object 数据也采用 JDK 序列化而不是 JSON 字符串可以直接改用sa-token-redis-template-jdk-serializer集成包。其实现类 SaTokenDaoForRedisTemplateUseJdkSerializer 在initMore()中额外构建了一个RedisTemplateString, ObjectKey 用StringRedisSerializer、Value 用JdkSerializationRedisSerializer专门负责getObject / setObject / updateObject等对象级操作。四、集成 Redis 请注意4.1 还需要配置 Redis 连接信息吗需要只有项目初始化了正确的 Redis 实例Sa-Token 才能使用 Redis 进行数据持久化。参考以下yml配置spring: # redis配置 redis: # Redis数据库索引默认为0 database: 1 # Redis服务器地址 host: 127.0.0.1 # Redis服务器连接端口 port: 6379 # Redis服务器连接密码默认为空 # password: # 连接超时时间 timeout: 10s lettuce: pool: # 连接池最大连接数 max-active: 200 # 连接池最大阻塞等待时间使用负值表示没有限制 max-wait: -1ms # 连接池中的最大空闲连接 max-idle: 10 # 连接池中的最小空闲连接 min-idle: 0properties风格等价写法# Redis数据库索引默认为0 spring.redis.database1 # Redis服务器地址 spring.redis.host127.0.0.1 # Redis服务器连接端口 spring.redis.port6379 # Redis服务器连接密码默认为空 # spring.redis.password # 连接超时时间 spring.redis.timeout10s # 连接池最大连接数 spring.redis.lettuce.pool.max-active200 # 连接池最大阻塞等待时间使用负值表示没有限制 spring.redis.lettuce.pool.max-wait-1ms # 连接池中的最大空闲连接 spring.redis.lettuce.pool.max-idle10 # 连接池中的最小空闲连接 spring.redis.lettuce.pool.min-idle0[!WARNING| label:小提示] 如果你使用的是SpringBoot3.x版本需要将前缀spring.redis改为spring.data.redisSpringBoot4 同理。4.2 集成后需要手动保存数据吗框架自动保存。集成 Redis 只需引入对应的pom依赖即可框架所有上层 API 保持不变——你之前调用的StpUtil.login()、StpUtil.getSession()等接口无需任何改动数据落盘由SaTokenDao自动完成。4.3 版本问题sa-token-redis-template等集成包的版本尽量与sa-token-spring-boot-starter集成包的版本保持一致否则可能出现兼容性问题。可参考仓库示例 sa-token-demo-springboot-redisson 中sa-token.version属性的统一管理方式。4.4 Redis 6.0 版本要求[!WARNING] 自 v1.46.0 起sa-token-redis-template/sa-token-redisson使用了 Redis 6.0 的SET KEEPTTL特性。若 Redis 服务低于 6.0会报ERR syntax error。解决方案见 QRedis 6.0 以下版本集成报错。从源码可以印证这一特性SaTokenDaoForRedisTemplate.update()通过Expiration.keepTtl()RedisStringCommands.SetOption.ifPresent()实现仅键存在时覆写 value 并保留原 TTL见 源码实现SaTokenDaoForRedisson.update()则调用RBucket.setAndKeepTTL(value)见 源码实现。两个类的文件底部注释都给出了 Redis 6.0 时的毫秒级兼容写法可手工替换。五、多个项目共用同一个 Redis怎么防止冲突如无特殊需求建议多个项目不要共用同一个 Redis。如果非要共用可用以下 4 种方式隔离数据方式 1使用不同的 db 索引Redis 默认提供 16 个 database每个项目配置不同的spring.redis.databaseSpringBoot3 为spring.data.redis.database即可实现物理隔离。方式 2配置不同的sa-token.token-name此配置项默认为satoken会作为框架在 Redis 中存储数据时的统一键前缀。例如sa-token: token-name: my-app-a[!NOTE| label:注意]token-name同时也会作为前端提交 Token 时的参数名 / Header 名。若只想隔离 Redis 键、又不想改前端传参方式请看方式 4。方式 3使用 Alone 独立 Redis / Redisson 插件让权限缓存与业务缓存分离或让不同项目连接不同的 Redis 实例RedisTemplateAlone 独立 Redis 插件RedissonAlone 独立 Redisson 插件方式 4重写wrapKey自定义键前缀保底方案sa-token-redis-template及sa-token-redis-template-jdk-serializer提供了wrapKey钩子默认原样返回 key源码见 SaTokenDaoForRedisTemplate.wrapKey()。需要给所有 Redis 键加项目前缀时可注册自定义 Dao 并重写该方法Configuration public class SaTokenDaoConfig { Bean Primary public SaTokenDao saTokenDao() { return new SaTokenDaoForRedisTemplate() { Override public String wrapKey(String key) { return my-app: key; } }; } }重写后框架读写的键会变成类似my-app:satoken:login:token:xxxx。从源码看get / set / delete / getTimeout / searchData等方法都会先经wrapKey包装再访问 Redis因此该钩子对全部键操作生效searchData甚至会对完整匹配串做 wrap避免用户只 wrap 前缀时拼错 SCAN 模式。六、方案二集成 Redisson如果你的项目用的是Redisson而不是 RedisTemplate可以改用本节方案。这是与上文第 2 节并列的可选项不是必须步骤——已经按 RedisTemplate 集成的不必再引入 Redisson也不要两套 Dao 同时引入。集成 Redisson 有两种方式二选一即可。6.1 方式一引入sa-token-redisson通用插件sa-token-redisson是通用插件Spring Boot、Solon、JFinal 等环境都可用。前提是项目里已有RedissonClient并需要自己注册SaTokenDao。Maven!-- Sa-Token 整合 Redisson -- dependency groupIdcn.dev33/groupId artifactIdsa-token-redisson/artifactId version${sa.top.version}/version /dependencyGradleimplementation cn.dev33:sa-token-redisson:${sa.top.version}然后注册 DaoRedissonClient由你现有的 Redisson 配置提供Configuration public class SaTokenDaoConfig { Bean public SaTokenDao saTokenDao(RedissonClient redissonClient) { return new SaTokenDaoForRedisson(redissonClient); } }6.2 方式二引入sa-token-redisson-spring-boot-starterSpring Boot 自动配置这是Spring Boot 专用自动配置包内部已包含sa-token-redisson和官方redisson-spring-boot-starter。引入后会自动注册SaTokenDao不用手写 Java。Maven!-- Sa-Token 整合 RedissonSpring Boot 自动配置 -- dependency groupIdcn.dev33/groupId artifactIdsa-token-redisson-spring-boot-starter/artifactId version${sa.top.version}/version /dependencyGradleimplementation cn.dev33:sa-token-redisson-spring-boot-starter:${sa.top.version}自动注册逻辑在 SaTokenDaoForRedissonBeanRegister 中通过Bean方法注入RedissonClient并new SaTokenDaoForRedisson(redissonClient)。配置 Redis 连接即可与官方 Redisson starter 相同。Spring Boot 3.x 请将前缀spring.redis改为spring.data.redisspring: redis: host: 127.0.0.1 port: 6379 database: 1 # password:properties风格spring.redis.host127.0.0.1 spring.redis.port6379 spring.redis.database1 # spring.redis.password可运行示例参考仓库中的 sa-token-demo-springboot-redisson。若需要权限缓存与业务缓存分离请改用 Alone 独立 Redisson 插件。6.3 升级注意v1.46.0 起 codec 行为变更SaTokenDaoForRedisson按 String 读写默认使用StringCodec与业务RedissonClient的全局 codec未配置时为Kryo5Codec隔离。这一点在 SaTokenDaoForRedisson 源码 中体现为双构造器设计无参 codec 构造器默认StringCodec.INSTANCE另有显式传入Codec的构造器。升级影响Sa-Token 旧版本下version v1.45.0getBucket(key)跟随RedissonClient全局codec一般默认是Kryo5Codec。升级sa-token-redisson或sa-token-redisson-spring-boot-starter后改为默认StringCodec旧缓存将无法反序列化登录态会失效。处理方式二选一清空旧缓存推荐删除 Redis 中 Sa-Token 相关 key默认前缀为配置项sa-token.token-name一般为satoken:让用户重新登录。保持旧 codec重写SaTokenDao的注册方式在构造时显式传入升级前的codec。未自定义过 Redisson codec 时传入new Kryo5Codec()。例如Configuration public class SaTokenDaoConfig { Bean Primary public SaTokenDao saTokenDao(RedissonClient redissonClient) { return new SaTokenDaoForRedisson(redissonClient, new Kryo5Codec()); } }若你曾在 Redisson 配置里指定过其它 codec如JsonJacksonCodec请传入当时使用的那个而不是Kryo5Codec。另外setAndKeepTTL要求 Redis 6.0低于 6.0 会报ERR syntax error处理方式同本文 4.4 节参考 QRedis 6.0 以下版本集成报错。七、扩展集成 MongoDB除 Redis 外Sa-Token 还提供了基于 MongoDB 的持久层参考实现可作为缓存中间件的备选方案集成 MongoDB 参考一集成 MongoDB 参考二总结集成 Redis 是 Sa-Token 从单机内存会话走向分布式共享会话的关键一步最省心的路线引入sa-token-redis-templateSpring Boot 官方 Redis 客户端或使用 Spring Boot 专用sa-token-redisson-spring-boot-starter自动配置包配置好连接即可无需改动任何业务 API存储格式定制默认String → JSON序列化链可通过更换 JSON 插件Fastjson / Fastjson2 / Snack3 等或替换 String 序列化模板JDK 三种编码灵活调整业务实体类参与反序列化需先注册 JSON 全局类型白名单多项目隔离db 索引、token-name前缀、Alone 独立插件、wrapKey重写四条路径按需选用升级留意v1.46.0 起SET KEEPTTL要求 Redis 6.0Redisson 方案默认 codec 变更为StringCodec升级前请清理旧缓存或显式传入旧 codec。所有底层行为均可在仓库源码与测试中验证例如 SaTokenDaoForRedisTemplate、SaTokenDaoForRedisson 及其对应测试类供你在深度排查时对照阅读。【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考