Redis缓存架构

引用文件

本文档引用的文件

• YudaoRedisAutoConfiguration.java
• YudaoCacheAutoConfiguration.java
• YudaoCacheProperties.java
• TimeoutRedisCacheManager.java
• RedisDistributionLockUtils.java
• RedisCacheUtils.java
• RedisClient.java
• org.springframework.boot.autoconfigure.AutoConfiguration.imports
• RedisController.java
• RedisMonitorRespVO.java
• RedisConvert.java

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖关系分析
7. 性能考虑
8. 故障排查指南
9. 结论
10. 附录

简介

本文件系统性梳理 yudao-cloud 中的 Redis 缓存架构，重点覆盖：

• 多层次缓存设计：应用层缓存、分布式锁、缓存管理器
• 自动配置机制：连接池、序列化策略、缓存管理器选择
• 工具类能力：RedisClient 提供的字符串/哈希/集合/有序集合等常用操作
• 分布式锁：RedisDistributionLockUtils 的加锁/解锁机制与死锁避免策略
• 缓存治理：失效策略、穿透防护、雪崩预防
• 性能优化、监控指标与故障处理

项目结构

yudao-cloud 的 Redis 相关能力主要集中在 yudao-spring-boot-starter-redis 模块，配合基础设施模块提供监控能力。

Mermaid Diagram Code:

graph TB
subgraph "Redis启动器"
A["YudaoRedisAutoConfiguration<br/>RedisTemplate/Redisson配置"]
B["YudaoCacheAutoConfiguration<br/>Cache配置/管理器"]
C["YudaoCacheProperties<br/>缓存配置项"]
D["TimeoutRedisCacheManager<br/>自定义过期时间"]
E["RedisClient<br/>通用操作工具"]
F["RedisDistributionLockUtils<br/>分布式锁工具"]
G["RedisCacheUtils<br/>缓存清理工具"]
end
subgraph "基础设施监控"
H["RedisController<br/>监控接口"]
I["RedisMonitorRespVO<br/>监控响应"]
J["RedisConvert<br/>监控转换"]
end
A --> E
A --> F
B --> D
B --> C
H --> I
H --> J

图表来源

• YudaoRedisAutoConfiguration.java
• YudaoCacheAutoConfiguration.java
• YudaoCacheProperties.java
• TimeoutRedisCacheManager.java
• RedisClient.java
• RedisDistributionLockUtils.java
• RedisCacheUtils.java
• RedisController.java

章节来源

• org.springframework.boot.autoconfigure.AutoConfiguration.imports

核心组件

• 自动配置类
  • YudaoRedisAutoConfiguration：负责 RedisTemplate、RedissonClient 的创建与 JSON 序列化配置
  • YudaoCacheAutoConfiguration：负责 RedisCacheConfiguration、CacheManager 选择与本地缓存配置
• 缓存管理器扩展
  • TimeoutRedisCacheManager：支持在缓存名中通过“#ttl”语法自定义过期时间
• 工具类
  • RedisClient：提供丰富的 Redis 操作封装（字符串、哈希、集合、有序集合、管道等）
  • RedisDistributionLockUtils：基于 SETNX 的分布式锁工具
  • RedisCacheUtils：基于 CacheManager 的缓存清理工具
• 配置项
  • YudaoCacheProperties：缓存扫描批次、随机过期时间范围等

章节来源

• YudaoRedisAutoConfiguration.java
• YudaoCacheAutoConfiguration.java
• YudaoCacheProperties.java
• TimeoutRedisCacheManager.java
• RedisClient.java
• RedisDistributionLockUtils.java
• RedisCacheUtils.java

架构总览

yudao-cloud 的 Redis 缓存采用“自动配置 + 多级缓存 + 工具类”的架构模式：

• 自动配置层：统一创建 RedisTemplate、RedissonClient、CacheConfiguration
• 缓存管理层：支持主 CacheManager（Redis）与本地 Caffeine 缓存，以及按缓存名自定义过期时间
• 应用层：通过 RedisClient 提供的丰富 API 实现业务缓存，通过 RedisDistributionLockUtils 实现分布式锁
• 监控层：基础设施模块提供 Redis 监控接口，输出命令统计与数据库大小

Mermaid Diagram Code:

sequenceDiagram
participant App as "应用服务"
participant AC as "YudaoCacheAutoConfiguration"
participant RC as "RedisCacheManager"
participant TRCM as "TimeoutRedisCacheManager"
participant RT as "RedisTemplate"
participant RCli as "RedisClient"
App->>AC : 加载自动配置
AC->>RC : 创建主缓存管理器
AC->>TRCM : 包装自定义过期时间
App->>RC : 获取缓存实例
App->>RCli : 读写缓存数据
RCli->>RT : 执行Redis命令
RC-->>App : 返回缓存结果

图表来源

• YudaoCacheAutoConfiguration.java
• TimeoutRedisCacheManager.java
• RedisClient.java

详细组件分析

自动配置机制（YudaoRedisAutoConfiguration）

• RedisTemplate 配置
  • Key 使用 String 序列化
  • Value 使用 JSON 序列化（支持 Java 8 时间类型）
• RedissonClient 配置
  • 单机模式，支持密码认证
  • 使用 JsonJacksonCodec，注册 JavaTimeModule
• 作用
  • 为上层 Cache 与工具类提供统一的 Redis 访问入口

Mermaid Diagram Code:

classDiagram
class YudaoRedisAutoConfiguration {
+redisTemplate(factory)
+buildRedisSerializer()
+redissonClient(redisProperties)
}
class RedisTemplate
class RedissonClient
YudaoRedisAutoConfiguration --> RedisTemplate : "创建"
YudaoRedisAutoConfiguration --> RedissonClient : "创建"

图表来源

• YudaoRedisAutoConfiguration.java

章节来源

• YudaoRedisAutoConfiguration.java

缓存配置与管理（YudaoCacheAutoConfiguration）

• RedisCacheConfiguration
  • 自定义 key 前缀规则，兼容单冒号命名
  • 使用 JSON 序列化缓存值
  • 支持全局 TTL、禁用空值缓存、禁用 key 前缀
• CacheManager 选择
  • 未启用多租户时，优先使用 TimeoutRedisCacheManager
  • 启用多租户时，由多租户配置覆盖
• 本地缓存（Caffeine）
  • 提供独立的本地缓存管理器，可配置过期时间与容量

Mermaid Diagram Code:

flowchart TD
Start(["加载缓存配置"]) --> Prefix["计算key前缀"]
Prefix --> Serialize["设置JSON序列化"]
Serialize --> GlobalTTL{"是否设置全局TTL?"}
GlobalTTL --> |是| ApplyTTL["应用entryTtl"]
GlobalTTL --> |否| SkipTTL["跳过"]
ApplyTTL --> NullCache{"是否禁用空值缓存?"}
SkipTTL --> NullCache
NullCache --> |是| DisableNull["disableCachingNullValues"]
NullCache --> |否| KeepNull["保留空值"]
DisableNull --> KeyPrefix{"是否禁用key前缀?"}
KeepNull --> KeyPrefix
KeyPrefix --> |是| DisablePrefix["disableKeyPrefix"]
KeyPrefix --> |否| KeepPrefix["保留前缀"]
DisablePrefix --> Done(["完成"])
KeepPrefix --> Done

图表来源

• YudaoCacheAutoConfiguration.java

章节来源

• YudaoCacheAutoConfiguration.java

自定义过期时间（TimeoutRedisCacheManager）

• 语法：cacheNames = "{name}#{ttl}{unit}"
  • 支持单位：d（天）、h（小时）、m（分钟）、s（秒）
  • 默认单位为 s
• 实现要点
  • 解析“#ttl”后的持续时间字符串
  • 动态设置 RedisCacheConfiguration 的 entryTtl
  • 忽略“#ttl”部分创建缓存实例

Mermaid Diagram Code:

flowchart TD
A["收到缓存名"] --> B{"包含'#'分隔符?"}
B --> |否| C["使用默认配置创建缓存"]
B --> |是| D["拆分得到name与ttl部分"]
D --> E["解析时间单位与数值"]
E --> F["设置entryTtl"]
F --> G["创建带自定义TTL的缓存"]

图表来源

• TimeoutRedisCacheManager.java

章节来源

• TimeoutRedisCacheManager.java

RedisClient 工具类（常用操作）

• 键值操作
  • get/mGet/setEx/incr/incrBy/del/batchGetWithPrefix
  • 支持随机过期时间，避免集中过期
• 哈希操作
  • hGet/hGetAll/hSet/hMSet/hDel/hExists/hIncr
  • 支持随机过期时间
• 列表操作
  • lRange/lLen/lIndex/rPush/lSet/lRem/lTrim/lPop
• 集合操作
  • sMembers/sIsMember/sAdd/sRem/sPop/sRandMember/sEditLua
  • 支持批量 Lua 批处理与随机过期时间
• 有序集合操作
  • zAdd/zCount/zIncrBy/zScore/zRank/zRevRangeWithScores/zRem
  • 支持随机过期时间
• 管道与扫描
  • pipelineAction 管道封装
  • sScan 增量扫描，避免阻塞

Mermaid Diagram Code:

classDiagram
class RedisClient {
+get(key, clz)
+setEx(key, value, expire)
+hGet/hSet/hMSet/hDel
+lRange/rPush/lPop
+sMembers/sAdd/sRem/sRandMember
+zAdd/zRevRangeWithScores/zRem
+pipelineAction()
+sScan(key, count, pattern, clz, consumer)
}

图表来源

• RedisClient.java

章节来源

• RedisClient.java

分布式锁（RedisDistributionLockUtils）

• 加锁
  • 基于 SET key value NX EX ttl
  • 成功返回 true，失败记录调试日志
• 解锁
  • 仅当当前值等于持有者值时删除 key
• 获取锁（重试）
  • 在等待时间内循环尝试加锁，间隔固定等待
• 死锁避免策略
  • 使用带过期时间的加锁，避免异常释放导致的永久占用
  • 值中包含唯一标识，确保仅释放自己的锁

Mermaid Diagram Code:

sequenceDiagram
participant Caller as "调用方"
participant Utils as "RedisDistributionLockUtils"
participant Redis as "Redis"
Caller->>Utils : tryLock(key, value, waitTime, leaseTime)
loop 等待期内
Utils->>Redis : SET key value NX EX leaseTime
alt 成功
Utils-->>Caller : true
else 失败
Utils->>Utils : 等待固定时间
end
end
Utils-->>Caller : false超时未获锁
Caller->>Utils : unlock(key, value)
Utils->>Redis : GET key
alt 值匹配
Utils->>Redis : DEL key
else 不匹配
Utils-->>Caller : 忽略非持有者
end

图表来源

• RedisDistributionLockUtils.java

章节来源

• RedisDistributionLockUtils.java

缓存治理策略

• 失效策略
  • 全局 TTL：通过 CacheProperties.Redis 配置
  • 自定义 TTL：通过 TimeoutRedisCacheManager 的“#ttl”语法
  • 随机过期：RedisClient 提供随机过期时间，缓解缓存击穿
• 缓存穿透
  • RedisClient.sort 等方法在空结果时写入“占位空值”，防止重复查询数据库
• 缓存雪崩
  • 随机过期时间分散过期时间点
  • 本地缓存（Caffeine）作为第二层保护

章节来源

• YudaoCacheAutoConfiguration.java
• TimeoutRedisCacheManager.java
• RedisClient.java

缓存清理工具（RedisCacheUtils）

• 清理单个或多个缓存键
• 基于 Spring CacheManager 的 evict 操作

章节来源

• RedisCacheUtils.java

依赖关系分析

• 自动配置导入
  • spring.factories 导入 YudaoRedisAutoConfiguration 与 YudaoCacheAutoConfiguration
• 组件耦合
  • RedisClient 依赖 RedisTemplate 与 RedissonClient
  • TimeoutRedisCacheManager 依赖 RedisCacheWriter 与 RedisCacheConfiguration
  • RedisDistributionLockUtils 依赖 StringRedisTemplate
• 外部集成
  • RedissonClient 用于分布式锁与位图等高级特性
  • 基础设施模块提供 Redis 监控接口

Mermaid Diagram Code:

graph LR
AutoImports["AutoConfiguration.imports"] --> RAC["YudaoRedisAutoConfiguration"]
AutoImports --> CAC["YudaoCacheAutoConfiguration"]
RAC --> RT["RedisTemplate"]
RAC --> RS["RedissonClient"]
CAC --> TRCM["TimeoutRedisCacheManager"]
TRCM --> RCW["RedisCacheWriter"]
RCli["RedisClient"] --> RT
RCli --> RS
DL["RedisDistributionLockUtils"] --> SRT["StringRedisTemplate"]

图表来源

• org.springframework.boot.autoconfigure.AutoConfiguration.imports
• YudaoRedisAutoConfiguration.java
• YudaoCacheAutoConfiguration.java

章节来源

• org.springframework.boot.autoconfigure.AutoConfiguration.imports

性能考虑

• 序列化与网络
  • 使用 JSON 序列化，支持 Java 8 时间类型，减少反序列化开销
• 批处理与管道
  • RedisClient 提供批量删除、批量更新过期、管道执行等能力
  • 集合批量操作支持 Lua 分批执行，降低网络往返
• 过期策略
  • 随机过期时间避免缓存集中过期
  • 自定义 TTL 使热点数据与冷数据差异化管理
• 本地缓存
  • Caffeine 本地缓存减少热点键的远程访问压力

[本节为通用指导，无需列出具体文件来源]

故障排查指南

• 监控接口
  • RedisController 提供 getRedisMonitorInfo，返回 info、dbSize、commandStats
  • RedisConvert 将命令统计转换为可读结构
• 常见问题定位
  • 缓存未命中：检查 key 前缀与序列化配置
  • 分布式锁无法释放：确认解锁时使用的值与加锁一致
  • 性能瓶颈：关注命令统计与管道使用情况

章节来源

• RedisController.java
• RedisMonitorRespVO.java
• RedisConvert.java

结论

yudao-cloud 的 Redis 缓存架构通过自动配置、多级缓存与丰富的工具类，实现了高性能、易用且可治理的缓存体系。结合随机过期、自定义 TTL、穿透与雪崩防护策略，能够在高并发场景下稳定运行。基础设施监控接口进一步提升了运维可观测性。

[本节为总结性内容，无需列出具体文件来源]

附录

• 配置项参考
  • yudao.cache.redisScanBatchSize：Redis SCAN 批次大小
  • yudao.cache.randomKeyExpireMinSecond/randomKeyExpireMaxSecond：随机过期时间范围
• 使用建议
  • 热点键使用自定义 TTL 与本地缓存
  • 批量操作优先使用 RedisClient 的批量与 Lua 能力
  • 分布式锁务必设置合理过期时间并确保解锁值匹配

章节来源

• YudaoCacheProperties.java