Sa-Token 集成 Redis

Sa-Token 默认将数据保存在内存中，此模式读写速度最快，且避免了序列化与反序列化带来的性能消耗，但是此模式也有一些缺点，比如：

重启后数据会丢失。
无法在分布式环境中共享数据。

为此，Sa-Token 提供了扩展接口，你可以轻松将会话数据存储在一些专业的缓存中间件上（比如 Redis），做到重启数据不丢失，而且保证分布式环境下多节点的会话一致性。

1、Sa-Token 整合 RedisTemplate

RedisTemplate 是 SpringBoot 官方推荐的 Redis 客户端，Sa-Token 提供基于 RedisTemplate 的 Redis 整合方案：

xml

<!-- Sa-Token 整合 RedisTemplate -->
<dependency>
	<groupId>cn.dev33</groupId>
	<artifactId>sa-token-redis-template</artifactId>
	<version>${sa.top.version}</version>
</dependency>

<!-- 提供 Redis 连接池 -->
<dependency>
	<groupId>org.apache.commons</groupId>
	<artifactId>commons-pool2</artifactId>
</dependency>

gradle

// Sa-Token 整合 RedisTemplate
implementation 'cn.dev33:sa-token-redis-template:${sa.top.version}'

// 提供 Redis 连接池
implementation 'org.apache.commons:commons-pool2'

Redis 的集成有多种方式，缓存的方案也不止 Redis 一种，Sa-Token 为缓存方案提供多种扩展实现。

如果你对 Sa-Token 还不太熟悉，或者只想“省心省事”，我们推荐你直接使用上述的 RedisTemplate 集成方案，而不必进行过多研究。到此为止，你可以跳转到下一章节了。

如果你想对缓存方案再进行一下深入探究，那么你可以参考：缓存层扩展

[!WARNING| ] 若往 Session 存自定义实体类后，从 Redis 读回报错 无法反序列化的类型：xxx，请先将其注册到 JSON 全局类型白名单，请参考：JSON 全局类型白名单机制

[!WARNING| ] 自 v1.46.0 起，sa-token-redis-template / sa-token-redisson 使用了 Redis 6.0+ 的 SET KEEPTTL 特性。若 Redis 服务低于 6.0，会报 ERR syntax error。解决方案见：Q：Redis 6.0 以下版本集成报错

2、自定义序列化方案

如果你按照上述 RedisTemplate 方案进行集成测试，会发现框架在 Redis 中是以 json 格式存储数据的。可以自定义数据序列化格式吗？当然是可以的。

框架的默认序列化层调用为 String 序列化 -> JSON 序列化。要自定义数据序列化方式你可以从这两方面入手：

2.1、自定义 JSON 序列化方案：

先说较为底层的 JSON 序列化，如果你引入的是 sa-token-spring-boot-starter 集成包 (含SpringBoot3) ，那么框架将会自动引入 Jackson 框架作为 JSON 序列化方案。

如果你想更换为其它 JSON 解析框架，可以引入相关依赖：

xml

<!-- Sa-Token 整合 Fastjson -->
<dependency>
	<groupId>cn.dev33</groupId>
	<artifactId>sa-token-fastjson</artifactId>
	<version>${sa.top.version}</version>
</dependency>

Gradle 参考：implementation 'cn.dev33:sa-token-fastjson:${sa.top.version}'

xml

<!-- Sa-Token 整合 Fastjson2 -->
<dependency>
	<groupId>cn.dev33</groupId>
	<artifactId>sa-token-fastjson2</artifactId>
	<version>${sa.top.version}</version>
</dependency>

Gradle 参考：implementation 'cn.dev33:sa-token-fastjson2:${sa.top.version}'

xml

<!-- Sa-Token 整合 Snack3 -->
<dependency>
	<groupId>cn.dev33</groupId>
	<artifactId>sa-token-snack3</artifactId>
	<version>${sa.top.version}</version>
</dependency>

Gradle 参考：implementation 'cn.dev33:sa-token-snack3:${sa.top.version}'

完整插件列表请参考：JSON 序列化扩展

2.2、自定义 String 序列化方案：

或者你想更直接点，不使用 json 序列化方案，也是可以的。你可以直接自定义数据的 String 序列化方案：

java

// 设置序列化方案: jdk序列化 (base64编码)
@PostConstruct
public void rewriteComponent() {
	SaManager.setSaSerializerTemplate(new SaSerializerTemplateForJdkUseBase64());
}

java

// 设置序列化方案: jdk序列化 (16进制编码)
@PostConstruct
public void rewriteComponent() {
	SaManager.setSaSerializerTemplate(new SaSerializerTemplateForJdkUseHex());
}

java

// 设置序列化方案: jdk序列化 (ISO-8859-1编码)
@PostConstruct
public void rewriteComponent() {
	SaManager.setSaSerializerTemplate(new SaSerializerTemplateForJdkUseISO_8859_1());
}

除了以上的几种序列化方案，我们还提供了序列化扩展包，详细可参考：序列化插件扩展包

3、集成 Redis 请注意：

1. 引入了依赖，我还需要为 Redis 配置连接信息吗？

需要！只有项目初始化了正确的 Redis 实例，Sa-Token才可以使用 Redis 进行数据持久化，参考以下yml配置：

yaml

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: 0

properties

# Redis数据库索引（默认为0）
spring.redis.database=1
# Redis服务器地址
spring.redis.host=127.0.0.1
# Redis服务器连接端口
spring.redis.port=6379
# Redis服务器连接密码（默认为空）
# spring.redis.password=
# 连接超时时间
spring.redis.timeout=10s
# 连接池最大连接数
spring.redis.lettuce.pool.max-active=200
# 连接池最大阻塞等待时间（使用负值表示没有限制）
spring.redis.lettuce.pool.max-wait=-1ms
# 连接池中的最大空闲连接
spring.redis.lettuce.pool.max-idle=10
# 连接池中的最小空闲连接
spring.redis.lettuce.pool.min-idle=0

[!WARNING| label:小提示 ] 如果你使用的是 SpringBoot3.x 版本，则需要将前缀 spring.redis 改为 spring.data.redis。

2. 集成 Redis 后，是我额外手动保存数据，还是框架自动保存？

框架自动保存。集成 Redis 只需要引入对应的 pom依赖 即可，框架所有上层 API 保持不变。

3. 集成包版本问题

Sa-Token-Redis 集成包的版本尽量与 Sa-Token-Starter 集成包的版本一致，否则可能出现兼容性问题。

4、多个项目共用同一个 Redis，怎么防止冲突？

如无特殊需求，建议多个项目不要共用同一个 Redis。如果非要共用，可用以下方式隔离数据：

方式 1：使用不同的 db 索引

Redis 默认提供 16 个 database，每个项目配置不同的 spring.redis.database（SpringBoot3 为 spring.data.redis.database）即可。

方式 2：配置不同的 sa-token.token-name

此配置项默认为 satoken，会作为框架在 Redis 中存储数据时的统一前缀，例如：

yaml

sa-token: 
    token-name: my-app-a

[!NOTE| label:注意 ] token-name 同时也会作为前端提交 Token 时的参数名 / Header 名。若只想隔离 Redis 键、又不想改前端传参方式，请看方式 4。

方式 3：使用 Alone 独立 Redis / Redisson 插件

让权限缓存与业务缓存分离，或让不同项目连接不同的 Redis 实例：

RedisTemplate：Alone 独立 Redis 插件
Redisson：Alone 独立 Redisson 插件

方式 4：重写 wrapKey 自定义键前缀（保底方案）

sa-token-redis-template（及 sa-token-redis-template-jdk-serializer）提供了 wrapKey 钩子，默认原样返回 key。需要给所有 Redis 键加项目前缀时，可注册自定义 Dao 并重写该方法：

java

@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。

5、集成 Redisson

如果你的项目用的是 Redisson，而不是上文的 RedisTemplate，可以改用本节方案。这是与第 1 节 并列的可选项，不是必须步骤。已经按 RedisTemplate 集成的，不必再引入 Redisson；也不要两套 Dao 同时引入。

集成 Redisson 有两种方式，二选一即可。

5.1、方式一：引入 `sa-token-redisson`

通用插件，Spring Boot、Solon、JFinal 等都可用。需要项目里已有 RedissonClient，并自己注册 SaTokenDao。

xml

<!-- Sa-Token 整合 Redisson -->
<dependency>
	<groupId>cn.dev33</groupId>
	<artifactId>sa-token-redisson</artifactId>
	<version>${sa.top.version}</version>
</dependency>

gradle

implementation 'cn.dev33:sa-token-redisson:${sa.top.version}'

然后注册 Dao（RedissonClient 由你现有的 Redisson 配置提供）：

java

@Configuration
public class SaTokenDaoConfig {
	@Bean
	public SaTokenDao saTokenDao(RedissonClient redissonClient) {
		return new SaTokenDaoForRedisson(redissonClient);
	}
}

5.2、方式二：引入 `sa-token-redisson-spring-boot-starter`

Spring Boot 专用自动配置包，内部已包含 sa-token-redisson 和官方 redisson-spring-boot-starter。引入后会自动注册 SaTokenDao，不用手写 Java。

xml

<!-- Sa-Token 整合 Redisson（Spring Boot 自动配置） -->
<dependency>
	<groupId>cn.dev33</groupId>
	<artifactId>sa-token-redisson-spring-boot-starter</artifactId>
	<version>${sa.top.version}</version>
</dependency>

gradle

implementation 'cn.dev33:sa-token-redisson-spring-boot-starter:${sa.top.version}'

配置 Redis 连接即可（与官方 Redisson starter 相同）。Spring Boot 3.x 请将前缀 spring.redis 改为 spring.data.redis：

yaml

spring:
    redis:
        host: 127.0.0.1
        port: 6379
        database: 1
        # password:

properties

spring.redis.host=127.0.0.1
spring.redis.port=6379
spring.redis.database=1
# spring.redis.password=

示例：sa-token-demo-springboot-redisson

若需要权限缓存与业务缓存分离，请改用 Alone 独立 Redisson 插件。

5.3、升级注意

SaTokenDaoForRedisson 按 String 读写，默认使用 StringCodec，与业务 RedissonClient 的全局 codec（未配置时为 Kryo5Codec）隔离。

Sa-Token 旧版本下（version<=v1.45.0） getBucket(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()。例如：

java

@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+。若 Redis 服务低于 6.0，会报 ERR syntax error，请参考：Q：Redis 6.0 以下版本集成报错

Sa-Token 集成 Redis

Sa-Token 集成 Redis

1、Sa-Token 整合 RedisTemplate

2、自定义序列化方案

2.1、自定义 JSON 序列化方案：

2.2、自定义 String 序列化方案：

3、集成 Redis 请注意：

4、多个项目共用同一个 Redis，怎么防止冲突？

5、集成 Redisson

5.1、方式一：引入 sa-token-redisson

5.2、方式二：引入 sa-token-redisson-spring-boot-starter

5.3、升级注意

6、扩展：集成 MongoDB

5.1、方式一：引入 `sa-token-redisson`

5.2、方式二：引入 `sa-token-redisson-spring-boot-starter`