Redis缓存架构

引用文件

本文引用的文件

简介

本文件面向 yudao-cloud 的 Redis 缓存架构，系统性阐述多级缓存策略（本地缓存 + 分布式缓存 + 布隆过滤器）、缓存键命名规范、过期策略与随机抖动、缓存一致性与预热、穿透/击穿/雪崩防护、监控与运维要点。文档以仓库现有实现为依据，结合配置与工具类进行说明，并提供可视化图示帮助理解。

项目结构

围绕 Redis 的核心实现集中在 yudao-spring-boot-starter-redis 模块，配套的本地缓存工具位于 yudao-common，缓存一致性事件通过 yudao-module-rule 的 LocalCacheClearEvent 与 RuleUtil/RulesApiUtil 广播。

Mermaid Diagram Code:

graph TB
subgraph "Redis封装模块"
A["YudaoRedisAutoConfiguration<br/>RedisTemplate/RedissonClient"]
B["YudaoCacheAutoConfiguration<br/>RedisCacheConfiguration/Manager"]
C["TimeoutRedisCacheManager<br/>动态过期"]
D["YudaoCacheProperties<br/>扫描批大小/随机抖动"]
E["BloomFilterUtils<br/>布隆过滤器工具"]
end
subgraph "本地缓存"
F["CacheUtils<br/>LoadingCache/异步刷新"]
end
subgraph "缓存一致性"
G["LocalCacheClearEvent<br/>本地缓存清理事件"]
H["RuleUtil/RuleApiUtil<br/>事件广播"]
end
A --> B
B --> C
B --> D
E --> A
F --> B
H --> G
G --> B

图表来源

章节来源

核心组件

RedisTemplate/RedissonClient：统一的 JSON 序列化、连接工厂与 Redisson 客户端配置。
RedisCacheConfiguration/Manager：集中式缓存配置与前缀策略，支持自定义过期时间。
TimeoutRedisCacheManager：在缓存名中通过“#ttl”语法动态覆盖过期时间。
YudaoCacheProperties：扫描批大小、随机过期抖动参数。
BloomFilterUtils：基于 Redisson 的布隆过滤器工具，支持分区与批量操作。
CacheUtils：本地缓存 LoadingCache 构建与异步刷新。
LocalCacheClearEvent + RuleUtil/RuleApiUtil：通过 Spring Cloud Bus 广播本地缓存清理事件，实现多实例一致性。

章节来源

架构总览

yudao-cloud 的缓存采用“本地缓存 + 分布式缓存 + 布隆过滤器”的多级策略：

本地缓存：Guava/Caffeine，降低热点数据的远程访问压力。
分布式缓存：Spring Cache + Redis，统一序列化与 TTL 策略。
布隆过滤器：在高并发读场景前置过滤，避免无效的后端查询。
一致性：通过 Spring Cloud Bus 广播本地缓存清理事件，确保多实例一致。

Mermaid Diagram Code:

graph TB
Client["客户端/服务调用方"]
LC["本地缓存<br/>LoadingCache"]
RC["Redis 缓存<br/>RedisCacheManager"]
BF["布隆过滤器<br/>BloomFilterUtils"]
RS["RedissonClient"]
BK["Redis 集群/单机"]
Client --> BF
BF --> |命中| Client
BF --> |未命中| LC
LC --> |缺失| RC
RC --> RS
RS --> BK

图表来源

组件详解

Redis 配置与序列化

RedisTemplate 使用 String 序列化键值，VALUE 使用 JSON（Jackson + JavaTimeModule），保证 LocalDateTime 等时间类型的正确序列化。
RedissonClient 通过 JsonJacksonCodec 配置，支持 Java 8 日期时间类型。
RedissonClient 默认单机模式，地址来自 spring.redis.* 配置。

章节来源

YudaoRedisAutoConfiguration.java

缓存配置与前缀策略

RedisCacheConfiguration 默认配置，支持：
- 自定义 key 前缀（computePrefixWith），避免 Redis Desktop Manager 显示空格问题。
- JSON 序列化 VALUE。
- 从 CacheProperties.Redis 读取 TTL、禁用空值缓存、禁用 key 前缀等。
默认 TTL 可在各模块 application.yaml 中配置（如黑名单模块配置了 1h）。

章节来源

动态过期策略（TimeoutRedisCacheManager）

在缓存名中使用“cacheName#ttl”，其中 ttl 支持 d/h/m/s 单位，默认秒。
解析后通过 entryTtl 动态覆盖默认 TTL，实现不同业务的差异化过期。

Mermaid Diagram Code:

flowchart TD
Start(["进入 createRedisCache"]) --> CheckName["判断缓存名是否为空"]
CheckName --> |空| ReturnDefault["返回默认缓存"]
CheckName --> |非空| Split["按 '#' 分割"]
Split --> LenCheck{"长度==2?"}
LenCheck --> |否| ReturnDefault
LenCheck --> |是| Parse["解析 ttl 字符串为 Duration"]
Parse --> Apply["设置 entryTtl"]
Apply --> Create["创建 RedisCache忽略 ttl 片段"]
Create --> End(["返回"])

图表来源

TimeoutRedisCacheManager.java

章节来源

TimeoutRedisCacheManager.java

缓存键命名规范

前缀策略：由 computePrefixWith 生成，最终格式为“prefix:cacheName:”。
建议规范（基于现有实现）：
- 使用“模块:领域:业务标识”层级命名，如“user:profile:userId”。
- 对于带过期的缓存，使用“cacheName#ttl”语法，如“menu:list#2h”。

章节来源

YudaoCacheAutoConfiguration.java

过期策略与随机抖动

默认 TTL：可通过 CacheProperties.Redis 或模块配置设置。
随机抖动：YudaoCacheProperties 提供随机过期范围（默认 20~24 小时），用于缓解缓存雪崩。
动态过期：TimeoutRedisCacheManager 支持按业务粒度设置过期时间。

章节来源

布隆过滤器（BloomFilterUtils）

初始化：支持 expectedInsertions 与 falseProbability，可按分区初始化。
添加：支持单个/批量添加，批量时按元素哈希分区落盘。
查询：mightContain 支持分区与非分区两种方式。
重置/删除：reset/resetAllElement/delete 等方法，便于离线重建。

Mermaid Diagram Code:

sequenceDiagram
participant Caller as "调用方"
participant BFU as "BloomFilterUtils"
participant RC as "RedissonClient"
participant BK as "Redis"
Caller->>BFU : addElement(name, elements, partitionCount)
BFU->>BFU : 分区映射/聚合
BFU->>RC : getBloomFilter(partitionName)
RC-->>BFU : BloomFilter 实例
BFU->>RC : add(elements)
RC-->>BFU : 结果
BFU-->>Caller : 成功条数

图表来源

BloomFilterUtils.java

章节来源

BloomFilterUtils.java

本地缓存（LoadingCache）

CacheUtils 提供两类缓存：
- buildAsyncReloadingCache：异步刷新，避免阻塞主请求线程。
- buildCache：同步刷新，适用于全局/系统级缓存。
与 Redis 的配合：热点数据优先命中本地缓存，减少 Redis 压力。

章节来源

CacheUtils.java

缓存一致性与预热

一致性：通过 LocalCacheClearEvent 广播本地缓存清理事件，RuleUtil/RuleApiUtil 负责发布，确保多实例本地缓存及时失效。
预热：建议在启动阶段或定时任务中，对热点键执行读取操作，触发本地与分布式缓存填充。

Mermaid Diagram Code:

sequenceDiagram
participant Producer as "业务变更方"
participant Bus as "Spring Cloud Bus"
participant Consumer as "各服务实例"
participant LC as "本地缓存"
Producer->>Bus : 发布 LocalCacheClearEvent(cacheName, cacheKey?)
Bus-->>Consumer : 广播事件
Consumer->>LC : 清理指定 cacheName 或 key
LC-->>Consumer : 完成清理

图表来源

章节来源

缓存穿透/击穿/雪崩防护

缓存穿透：利用布隆过滤器在读前拦截不存在的 key，避免无效查询。
缓存击穿：热点 key 过期时，通过本地缓存异步刷新（LoadingCache）与互斥锁（Redisson 提供）保护后端。
缓存雪崩：启用随机抖动（YudaoCacheProperties），并结合动态过期（TimeoutRedisCacheManager）分散过期高峰。

章节来源

监控与运维

Redis 连接与序列化：YudaoRedisAutoConfiguration 统一配置，便于集中治理。
缓存扫描批大小：YudaoCacheProperties.redisScanBatchSize 控制 SCAN 批量大小，平衡 CPU 与网络。
模块级 TTL：可在 application.yaml 中为不同模块设置合理的 TTL，避免全局一刀切。

章节来源

依赖关系分析

YudaoRedisAutoConfiguration 与 YudaoCacheAutoConfiguration 形成 Redis 基础设施层。
TimeoutRedisCacheManager 扩展 RedisCacheManager，提供动态 TTL。
BloomFilterUtils 依赖 RedissonClient，提供布隆能力。
CacheUtils 与本地缓存集成，提升热点命中率。
LocalCacheClearEvent 与 RuleUtil/RuleApiUtil 通过 Spring Cloud Bus 实现跨实例一致性。

Mermaid Diagram Code:

graph LR
YRA["YudaoRedisAutoConfiguration"] --> YCA["YudaoCacheAutoConfiguration"]
YCA --> TRCM["TimeoutRedisCacheManager"]
YRA --> RS["RedissonClient"]
RS --> BFU["BloomFilterUtils"]
CCU["CacheUtils"] --> YCA
RUtil["RuleUtil/RuleApiUtil"] --> LCE["LocalCacheClearEvent"]
LCE --> YCA

图表来源

性能与容量规划

本地缓存：针对高频、低变化数据，降低远端访问；注意内存占用与序列化开销。
分布式缓存：合理设置 TTL 与随机抖动，避免集中过期；使用 JSON 序列化时关注对象大小。
布隆过滤器：根据预期插入量与误判率计算容量；分区可提升吞吐但增加维护复杂度。
扫描批大小：YudaoCacheProperties.redisScanBatchSize 用于优化 SCAN 性能，需结合实例负载调优。

[本节为通用指导，无需特定文件引用]

故障排查指南

缓存键前缀异常：确认 computePrefixWith 生成的前缀末尾冒号是否符合预期。
TTL 未生效：检查缓存名是否采用“#ttl”语法，或模块级 TTL 配置是否覆盖。
序列化异常：确认 RedisTemplate/Redisson 的 JSON 配置是否包含 JavaTimeModule。
本地缓存未清理：检查 Spring Cloud Bus 是否可用，事件是否被正确发布与消费。
布隆过滤器误判/漏判：调整 falseProbability 与 expectedInsertions，必要时重建分区。

章节来源

结论

yudao-cloud 的 Redis 缓存架构通过“本地缓存 + 分布式缓存 + 布隆过滤器”的组合，实现了高并发下的低延迟与高可用。动态过期、随机抖动与一致性事件广播进一步增强了系统的稳定性与可维护性。建议在生产环境中结合业务特征，持续优化 TTL、分区与扫描参数，并完善监控与告警体系。

[本节为总结性内容，无需特定文件引用]

附录

缓存键命名与过期示例

命名：模块:领域:业务标识，如“user:profile:12345”
过期：menu:list#2h、advertisement:banner#1d

章节来源

配置参考

模块级 TTL：在 application.yaml 中设置 spring.cache.redis.time-to-live
扫描批大小：yudao.cache.redisScanBatchSize
随机抖动范围：yudao.cache.randomKeyExpireMinSecond / yudao.cache.randomKeyExpireMaxSecond

章节来源

目录​

简介​

项目结构​

核心组件​

架构总览​

组件详解​

Redis 配置与序列化​

缓存配置与前缀策略​

动态过期策略（TimeoutRedisCacheManager）​

缓存键命名规范​

过期策略与随机抖动​

布隆过滤器（BloomFilterUtils）​

本地缓存（LoadingCache）​

缓存一致性与预热​

缓存穿透/击穿/雪崩防护​

监控与运维​

依赖关系分析​

性能与容量规划​

故障排查指南​

结论​

附录​

缓存键命名与过期示例​

配置参考​

目录

简介

项目结构

核心组件

架构总览

组件详解

Redis 配置与序列化

缓存配置与前缀策略

动态过期策略（TimeoutRedisCacheManager）

缓存键命名规范

过期策略与随机抖动

布隆过滤器（BloomFilterUtils）

本地缓存（LoadingCache）

缓存一致性与预热

缓存穿透/击穿/雪崩防护

监控与运维

依赖关系分析

性能与容量规划

故障排查指南

结论

附录

缓存键命名与过期示例

配置参考