cn-rdms/rdms-framework/rdms-spring-boot-starter-redis/README.md

# rdms-spring-boot-starter-redis

## 模块定位
`rdms-spring-boot-starter-redis` 不是单纯把 Redis 依赖引进来，而是把项目里常用的 Redis 使用约定统一收口。

当前模块主要承担三类职责：

1. 统一 `RedisTemplate` 的序列化策略
2. 统一 Spring Cache 基于 Redis 的实现方式
3. 引入 Redisson，为分布式锁、限流等上层模块提供基础能力

它的重点不是封装大量 Redis 工具类，而是先把“Redis 怎么接入、怎么序列化、缓存怎么配置”这些基础设施统一好。

## 设计思路

## 1. 先统一 RedisTemplate，再让上层模块复用
模块通过 `RdmsRedisAutoConfiguration` 注册了统一的 `RedisTemplate<String, Object>`，核心约定是：

1. Key 使用字符串序列化
2. Hash Key 使用字符串序列化
3. Value 使用 JSON 序列化
4. Hash Value 使用 JSON 序列化

这样可以避免各模块各自定义一套 `RedisTemplate`，导致同一个 Redis 里出现不同的序列化格式。

## 2. 优先解决“可读性和兼容性”问题
这个模块没有采用 JDK 默认序列化，而是直接使用 JSON 序列化。这样做的直接收益是：

1. Redis 中的数据结构更容易观察和排查
2. 避免 JDK 序列化带来的可读性差和兼容性问题
3. 方便不同模块围绕同一种序列化格式工作

同时，它还额外处理了 `LocalDateTime` 的序列化问题，避免 Java 时间类型在 Redis 中读写异常。

## 3. 把 Cache 也纳入统一约定
模块不只提供 `RedisTemplate`，还把 Spring Cache 一起接入 Redis：

1. 开启 `@EnableCaching`
2. 统一 `RedisCacheConfiguration`
3. 统一 `RedisCacheManager`
4. 扩展支持按缓存名声明过期时间

这说明模块的目标不是“给你 Redis 客户端自己玩”，而是先把项目里高频使用的缓存场景标准化。

## 4. 通过小扩展解决 Spring Cache 默认能力不够用的问题
模块里的 `TimeoutRedisCacheManager` 做了一个很实用的扩展：

1. 如果缓存名是普通格式，例如 `user`
2. 则按全局默认 TTL 工作
3. 如果缓存名写成 `user#10m`
4. 则这个缓存自动按 10 分钟过期

这相当于把“单个缓存项的过期时间”从配置文件和自定义代码里，收口到了缓存名约定里。

## 5. 给上层能力模块提供 Redis 和 Redisson 基座
这个模块本身不直接实现分布式锁、限流、幂等，但它提供了这些上层能力所依赖的基础能力：

1. `StringRedisTemplate`
2. `RedisTemplate<String, Object>`
3. `RedissonClient`
4. 基于 Redis 的 Spring Cache

因此像 `rdms-spring-boot-starter-protection`、`rdms-spring-boot-starter-mq` 这样的模块，都可以把 Redis 能力建立在这个 starter 之上。

## 自动装配链路

## 1. Spring Boot 自动配置入口
`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`

1. `com.njcn.rdms.framework.redis.config.RdmsRedisAutoConfiguration`
2. `com.njcn.rdms.framework.redis.config.RdmsCacheAutoConfiguration`

## 2. 各配置类负责的事情

| 配置类 | 作用 |
| --- | --- |
| `RdmsRedisAutoConfiguration` | 注册统一序列化规则的 `RedisTemplate<String, Object>` |
| `RdmsCacheAutoConfiguration` | 开启 Spring Cache，注册 `RedisCacheConfiguration` 和自定义 `RedisCacheManager` |

## 核心组件

| 组件 | 作用 |
| --- | --- |
| `RdmsRedisAutoConfiguration` | 提供统一 JSON 序列化的 RedisTemplate，并处理 `LocalDateTime` 序列化 |
| `RdmsCacheAutoConfiguration` | 统一 Redis Cache 前缀、TTL、空值缓存策略和 CacheManager |
| `RdmsCacheProperties` | 提供 `rdms.cache.*` 配置项，目前包含 `redis-scan-batch-size` |
| `TimeoutRedisCacheManager` | 支持通过 `cacheName#ttl` 的形式为单个缓存声明过期时间 |

## 功能说明

## 1. 统一 RedisTemplate 序列化
核心类：

1. `RdmsRedisAutoConfiguration`

实现方式：

1. `RedisTemplate<String, Object>` 统一由框架注册
2. Key/Hash Key 使用字符串序列化
3. Value/Hash Value 使用 JSON 序列化
4. 通过 `JavaTimeModule` 兼容 `LocalDateTime`

适合场景：

1. 业务模块直接注入 `RedisTemplate<String, Object>` 使用
2. 需要缓存对象、列表、Map 等结构
3. 希望 Redis 中的数据具有一定可读性

示例：

```java
@Resource
private RedisTemplate<String, Object> redisTemplate;

public void saveUser(Long userId, UserRespVO user) {
    redisTemplate.opsForValue().set("user:" + userId, user);
}
```

## 2. 统一 Spring Cache 基于 Redis 的实现
核心类：

1. `RdmsCacheAutoConfiguration`
2. `RdmsCacheProperties`

实现方式：

1. 开启 `@EnableCaching`
2. 创建统一的 `RedisCacheConfiguration`
3. 按 `spring.cache.redis.*` 读取默认 TTL、前缀、空值缓存等配置
4. 使用 JSON 序列化缓存值
5. 使用自定义 `RedisCacheManager`

这个模块还额外做了一个约定：

1. Cache Key 前缀使用单个 `:`，而不是默认的 `::`
2. 这样 Redis 中的 Key 更紧凑，也更方便在可视化工具中查看

Spring Cache 在这个模块里的作用，可以理解为：

1. 让“方法查询结果缓存”变成注解式能力，而不是每次都手写 `RedisTemplate`
2. 让缓存的写入、读取、失效围绕业务方法本身声明
3. 让“查库 -> 放缓存 -> 下次命中缓存”这类标准流程交给框架处理

它更适合下面这类场景：

1. 根据主键查询角色、菜单、模板、配置
2. 根据某个唯一业务字段查询对象，例如 `clientId`、`code`
3. 根据某个参数查询相对稳定的数据，例如部门子节点列表、权限对应菜单列表

这类场景通常有几个共同点：

1. 输入参数比较明确
2. 返回结果可以直接缓存
3. 数据更新时可以找到明确的缓存失效点

典型流程是：

1. 在查询方法上加 `@Cacheable`
2. 第一次执行时，方法正常查数据库或远程接口
3. 返回结果自动写入 Redis
4. 后续相同参数调用时，直接命中缓存，不再进入方法体
5. 在更新、删除方法上通过 `@CacheEvict` 清理对应缓存

和直接使用 `RedisTemplate` 相比，Spring Cache 的优势主要是：

1. 不需要手写 `get -> 判空 -> set -> expire` 这类模板代码
2. 缓存逻辑和业务方法绑定更紧，读代码时更容易看出哪里有缓存
3. 适合“查询结果缓存”这种标准模式

当前项目里，权限、角色、菜单、模板这类数据就大量采用这种方式；而像 Token、验证码这类更像“直接把业务对象存到 Redis”的场景，则更适合单独写 RedisDAO。

示例：

```java
@Cacheable(cacheNames = "user", key = "#id")
public UserRespVO getUser(Long id) {
    return userApi.getUser(id);
}
```

如果某个写操作会影响缓存，需要配套清理缓存：

```java
@CacheEvict(cacheNames = "user", key = "#id")
public void deleteUser(Long id) {
    userMapper.deleteById(id);
}
```

在当前项目语境下，更贴近实际的使用案例包括：

1. 根据角色 ID 查询角色信息，并在角色更新或删除时清理缓存
2. 根据权限标识查询菜单 ID 列表，并在菜单新增、修改、删除时清理缓存
3. 根据模板编码查询通知模板、邮件模板，并在模板变更时清理缓存

## 3. 支持按缓存名自定义过期时间
核心类：

1. `TimeoutRedisCacheManager`

实现方式：

1. 解析 `@Cacheable(cacheNames = "...")` 中的缓存名
2. 如果命中 `cacheName#ttl` 格式，则为该缓存单独设置 TTL
3. 支持的单位有：
   - `d` 天
   - `h` 小时
   - `m` 分钟
   - `s` 秒
4. 如果不带单位，默认按秒处理

示例：

```java
@Cacheable(cacheNames = "user#10m", key = "#id")
public UserRespVO getUser(Long id) {
    return userApi.getUser(id);
}
```

说明：

1. `#10m` 只用于声明这个缓存的过期时间是 10 分钟
2. 它不会作为最终 Redis key 的一部分长期保留
3. 如果 `id = 1`
4. 且 `spring.cache.redis.key-prefix = rdms`
5. 那么实际 Redis key 一般形如 `rdms:user:1`
6. 其中 `user` 是缓存名，`1` 是 `key = "#id"` 计算出的缓存 Key

```java
@Cacheable(cacheNames = "config#30s", key = "#key")
public ConfigRespVO getConfig(String key) {
    return configService.getConfig(key);
}
```

说明：

1. 如果 `key = "sms"`
2. 且 `spring.cache.redis.key-prefix = rdms`
3. 那么实际 Redis key 一般形如 `rdms:config:sms`
4. `#30s` 同样只影响 TTL，不直接体现在最终 key 名上

这种方式适合“绝大多数缓存共用默认 TTL，少数缓存按场景单独缩短或延长过期时间”的场景。

补充说明：

1. `cacheNames = "user#10m"` 中的 `user` 是缓存名，`10m` 是 TTL 描述
2. `key = "#id"` 或 `key = "#key"` 才决定具体缓存项的业务 Key
3. 如果配置了 `spring.cache.redis.key-prefix = rdms`，最终 Redis key 通常是 `rdms:user:1`、`rdms:config:sms` 这种形式
4. `#10m`、`#30s` 这类 TTL 后缀用于创建缓存时解析过期时间，不应理解成最终 key 名的一部分

## 4. 提供 Redisson 基础能力
从依赖上看，模块直接引入了 `redisson-spring-boot-starter`，因此除了 Spring Data Redis 以外，也会把 `RedissonClient` 这类能力带入项目。

这部分的直接收益是：

1. 分布式锁能力可被上层模块直接复用
2. 限流等基于 Redisson 的能力可直接建立在此模块之上
3. 项目不需要在多个模块里重复引入 Redisson

## 如何使用

## 1. 引入依赖
业务模块通常直接依赖：

```xml
<dependency>
    <groupId>com.njcn</groupId>
    <artifactId>rdms-spring-boot-starter-redis</artifactId>
</dependency>
```

## 2. 基础配置
最常见的配置重点包括：

1. `spring.data.redis.*`
2. `spring.cache.redis.*`
3. `rdms.cache.redis-scan-batch-size`

示例：

```yaml
spring:
  data:
    redis:
      host: 127.0.0.1 # Redis 地址
      port: 6379 # Redis 端口
      database: 0 # 使用的 Redis 库编号

  cache:
    type: REDIS # Spring Cache 底层使用 Redis
    redis:
      time-to-live: 1h # 全局默认缓存过期时间
      cache-null-values: false # 是否缓存空值，通常建议关闭
      use-key-prefix: true # 是否启用缓存 Key 前缀
      key-prefix: rdms # 缓存 Key 的统一前缀

rdms:
  cache:
    redis-scan-batch-size: 100 # Redis CacheWriter 使用 SCAN 批量处理时的单次扫描数量
```

说明：

1. `spring.cache.redis.time-to-live` 是全局默认缓存过期时间
2. `cacheName#ttl` 可以覆盖单个缓存的 TTL
3. `rdms.cache.redis-scan-batch-size` 用于控制 Redis CacheWriter 使用 `SCAN` 批量处理时的单次返回数量

## 3. 直接使用 RedisTemplate
如果场景不适合 Spring Cache，例如：

1. 需要操作复杂数据结构
2. 需要精细控制过期时间
3. 需要手动删除、递增、集合操作

可以直接注入 `RedisTemplate<String, Object>` 或 `StringRedisTemplate` 使用。

## 4. 优先使用 Spring Cache 的场景
如果场景是：

1. 查询结果缓存
2. 参数到结果的简单映射
3. 希望通过注解快速声明缓存

则优先使用 `@Cacheable`、`@CacheEvict`、`@CachePut`，并利用统一的 Redis Cache 约定。

这三个注解的典型使用场景可以这样区分：

1. `@Cacheable`
   用于“先查缓存，缓存没有再执行方法，并把结果写入缓存”。
   适合读操作，例如“根据 ID 查询角色”“根据编码查询模板”。

```java
@Cacheable(cacheNames = "role", key = "#id", unless = "#result == null")
public RoleDO getRoleFromCache(Long id) {
    return roleMapper.selectById(id);
}
```

2. `@CacheEvict`
   用于“执行方法后删除缓存”，避免更新或删除数据后缓存还是旧值。
   适合写操作，例如“更新角色后清理角色缓存”“删除模板后清理模板缓存”。

```java
@CacheEvict(cacheNames = "role", key = "#updateReqVO.id")
public void updateRole(RoleSaveReqVO updateReqVO) {
    roleMapper.updateById(BeanUtils.toBean(updateReqVO, RoleDO.class));
}
```

3. `@CachePut`
   用于“执行方法后，把方法返回值直接写回缓存”。
   适合更新后希望立即刷新缓存，而不是简单删除缓存的场景。

```java
@CachePut(cacheNames = "role", key = "#result.id")
public RoleDO updateRoleAndReturn(RoleSaveReqVO updateReqVO) {
    RoleDO role = BeanUtils.toBean(updateReqVO, RoleDO.class);
    roleMapper.updateById(role);
    return role;
}
```

可以把它们简单记成：

1. `@Cacheable`：查的时候用，没有缓存才执行方法
2. `@CacheEvict`：改或删的时候用，执行后清缓存
3. `@CachePut`：改的时候用，执行后直接刷新缓存

## 注意事项

1. `RedisTemplate<String, Object>` 使用 JSON 序列化，适合对象缓存，但跨版本变更字段时仍应关注兼容性。
2. `LocalDateTime` 已做序列化兼容处理，但复杂对象结构仍应关注 Jackson 序列化结果。
3. `cacheName#ttl` 是这个模块扩展出来的约定，不是 Spring Cache 默认语法。
4. 通过 `cacheName#ttl` 设置过期时间时，TTL 是针对这个缓存名生效的，不是针对单条 Key 动态计算。
5. `RdmsCacheAutoConfiguration` 将 Cache Key 前缀改成了单冒号 `:` 风格，如果已有依赖默认 `::` 的脚本或习惯，需要注意。
6. 这个模块本身主要解决“接入和约定”问题，不提供大量 Redis 业务工具方法；复杂 Redis 场景通常还是由业务模块或上层 starter 自己封装。

## 总结
这个模块的核心价值，不是简单引入 Redis 依赖，而是统一项目里的 Redis 使用方式：

1. 统一 `RedisTemplate` 的序列化规则
2. 统一 Spring Cache 的 Redis 落地方式
3. 提供按缓存名声明 TTL 的扩展能力
4. 为 Redisson 相关的上层能力提供基础环境

如果把它理解成一个“Redis 接入基座 + Cache 约定基座”的 starter，这个模块的设计会比较清晰。