Skip to content

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 + JavaTimeModuleredis/config/PmforgeRedisAutoConfiguration.java
PmforgeCacheAutoConfiguration@EnableCaching,@Primary RedisCacheConfiguration + RedisCacheManagerredis/config/PmforgeCacheAutoConfiguration.java
PmforgeCachePropertiespmforge.cache.redis-scan-batch-sizeredis/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.cachetypeREDIS(示例配置)选用 Redis 缓存实现
spring.cache.redistime-to-live1h(示例配置)默认缓存过期时间,#ttl 会覆盖它
spring.cache.rediskey-prefix空缓存 key 前缀;框架保证以单冒号结尾
spring.cache.rediscache-null-values框架取 Spring 默认(false)是否缓存 null
spring.cache.redisuse-key-prefix框架取 Spring 默认(true)是否启用前缀
pmforge.cacheredis-scan-batch-size30SCAN 批量大小,影响按前缀清理缓存的耗时
spring.data.redisrepositories.enabledfalse(示例配置)项目未用 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. 常见坑 ​

  1. #ttl 是本模块私有语法,不是 Spring 原生:换成默认 RedisCacheManager(或自己新建一个)后,缓存名会原样带上 #10m,等于每个名字都是一套新 key。
  2. 事务感知缓存有可见性延迟:setTransactionAware(true) 下,事务内先 @CachePut 再读缓存读不到新值;需要「写完立刻可见」时改用显式 RedisTemplate 操作。
  3. TTL 单位靠最后一个字母猜:#30 等于 30 秒、#30m 才是 30 分钟,写错不会报错,只会悄悄用错过期时间。
  4. RedisSerializer.json() 的模块是在反射拿到的 mapper 上追加的:如果业务把 JSON 值换成自定义对象(无默认构造、无 @JsonCreator),反序列化会抛 InvalidDefinitionException,而错误发生在读缓存时,很难定位到写缓存的地方。
  5. spring.data.redis.repositories.enabled=false 是刻意的(注释:未使用 Repository,禁用保证启动速度),业务若开始用 Spring Data Repository 必须自己打开。

7. 关联页面 ​