主题
starter-redis
1. 职责
把 Redis 的两套用法固定下来:一是统一序列化的 RedisTemplate<String, Object>(key 用字符串、value 用 JSON 且注册了 JavaTimeModule),二是基于 Spring Cache 的注解式缓存(@Cacheable/@CacheEvict),并额外支持 cacheName#ttl 这种「按缓存名单独设置过期时间」的写法。
它只做「连接之上的约定」:连接池、集群、哨兵、Redisson 客户端配置全部由 Spring Boot / Redisson starter 负责,本模块不建连接。
它不解决:分布式锁(用 Lock4j / Redisson)、消息队列(starter-mq)、限流(starter-protection 的 RateLimiterRedisDAO)。
本节路径均省略公共前缀
framework/pmforge-spring-boot-starter-redis/src/main/java/com/pmforge/framework/。
2. 关键类
| 类 | 作用 | 路径 |
|---|---|---|
PmforgeRedisAutoConfiguration | 定义 RedisTemplate<String,Object>:key/hashKey 用 RedisSerializer.string(),value/hashValue 用 JSON + JavaTimeModule | redis/config/PmforgeRedisAutoConfiguration.java |
PmforgeCacheAutoConfiguration | @EnableCaching,@Primary RedisCacheConfiguration + RedisCacheManager | redis/config/PmforgeCacheAutoConfiguration.java |
PmforgeCacheProperties | pmforge.cache.redis-scan-batch-size | redis/config/PmforgeCacheProperties.java |
TimeoutRedisCacheManager | 解析 cacheName#ttl(# 后为过期时间,单位取最后一个字母 d/h/m/s,默认 s) | redis/core/TimeoutRedisCacheManager.java |
3. 自动配置
| 配置类 | 生效条件 | 注册了什么 |
|---|---|---|
PmforgeRedisAutoConfiguration | @AutoConfiguration(before = RedissonAutoConfigurationV2.class),保证自定义模板先生效 | RedisTemplate<String,Object>(key 字符串、value JSON) |
PmforgeCacheAutoConfiguration | 始终装配(依赖容器里已有 RedisConnectionFactory) | @EnableCaching;@Primary RedisCacheConfiguration(前缀 keyPrefix + 缓存名 + :,TTL、cacheNullValues、useKeyPrefix 取自 spring.cache.redis.*);RedisCacheManager = TimeoutRedisCacheManager,扫描策略 BatchStrategies.scan(redisScanBatchSize),并 setTransactionAware(true) |
RedisCacheManager 的 setTransactionAware(true) 含义:在 @Transactional 方法内,@CachePut/@CacheEvict 会推迟到事务 提交后 执行;不在事务里时行为不变。
4. 配置项
| 前缀 | 键 | 默认值 | 说明 |
|---|---|---|---|
spring.cache | type | REDIS(示例配置) | 选用 Redis 缓存实现 |
spring.cache.redis | time-to-live | 1h(示例配置) | 默认缓存过期时间,#ttl 会覆盖它 |
spring.cache.redis | key-prefix | 空 | 缓存 key 前缀;框架保证以单冒号结尾 |
spring.cache.redis | cache-null-values | 框架取 Spring 默认(false) | 是否缓存 null |
spring.cache.redis | use-key-prefix | 框架取 Spring 默认(true) | 是否启用前缀 |
pmforge.cache | redis-scan-batch-size | 30 | SCAN 批量大小,影响按前缀清理缓存的耗时 |
spring.data.redis | repositories.enabled | false(示例配置) | 项目未用 Spring Data Repository,关掉可加快启动 |
5. 扩展点
- 给单个缓存设 TTL:
@Cacheable(cacheNames = "user_role_ids#10m"),#前是真实缓存名,框架会剥掉 TTL 段再建缓存。 - 改序列化:参考
PmforgeRedisAutoConfiguration覆盖RedisTemplate;业务里不要自己new一个模板,否则 key 会退回 JDK 序列化(带二进制前缀,无法在 redis-cli 里看)。 - 加缓存管理器:容器里已有
@Primary的RedisCacheManager,业务需要多套(例如本地 Caffeine + Redis 两级)时应声明为@Primary或按名称注入。 - 用 Redisson 原生能力(锁、限流器、布隆过滤器):直接注入
RedissonClient,starter-protection就是这么做的。 - 租户隔离:
biz-tenant用TenantRedisCacheManager覆写了@Primary缓存管理器,给缓存名追加:租户ID。
6. 常见坑
#ttl是本模块私有语法,不是 Spring 原生:换成默认RedisCacheManager(或自己新建一个)后,缓存名会原样带上#10m,等于每个名字都是一套新 key。- 事务感知缓存有可见性延迟:
setTransactionAware(true)下,事务内先@CachePut再读缓存读不到新值;需要「写完立刻可见」时改用显式RedisTemplate操作。 - TTL 单位靠最后一个字母猜:
#30等于 30 秒、#30m才是 30 分钟,写错不会报错,只会悄悄用错过期时间。 RedisSerializer.json()的模块是在反射拿到的 mapper 上追加的:如果业务把 JSON 值换成自定义对象(无默认构造、无@JsonCreator),反序列化会抛InvalidDefinitionException,而错误发生在读缓存时,很难定位到写缓存的地方。spring.data.redis.repositories.enabled=false是刻意的(注释:未使用 Repository,禁用保证启动速度),业务若开始用 Spring Data Repository 必须自己打开。
7. 关联页面
- starter-biz-tenant:
TenantRedisCacheManager与pmforge.tenant.ignore-caches - starter-mq:基于 Redis Stream 的消费依赖本模块的
RedisTemplate - starter-protection:
idempotent:、rate_limiter:、api_signature_*等 key 都在 Redis 里 - 横切机制、Redis 使用