跳到主要内容

缓存组件 (yudao-spring-boot-starter-redis)

引用文件

本文引用的文件

目录​

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

简介​

本文件面向 yudao-spring-boot-starter-redis 缓存组件，系统性阐述其设计与实现要点，覆盖以下主题：

  • Redis 客户端封装与连接池配置
  • 集群模式支持与自动装配
  • 分布式锁实现
  • 缓存注解 (@CacheField) 的使用与反射驱动的缓存工具
  • 本地缓存与 Redis 缓存的协同机制
  • 布隆过滤器、限流器、定时任务等实用工具类
  • 缓存键命名规范、过期策略、缓存穿透防护
  • 扩展点：自定义缓存策略、缓存监控、缓存清理

项目结构​

该模块采用“配置 + 工具 + 注解 + 自动装配”的分层组织方式：

  • 配置层：RedisTemplate、RedissonClient、CacheManager 的自动装配与序列化策略
  • 核心层：自定义 CacheManager（支持动态 TTL）、本地 Caffeine 缓存
  • 工具层：RedisClient（KV/Hash/List/Set/ZSet/Scan/Lua/过期控制）、分布式锁、布隆过滤器、本地缓存工具
  • 注解与工具：@CacheField 注解与 AnnotationCacheUtils（基于注解的序列化/反序列化）

Mermaid Diagram Code:

graph TB
subgraph "配置层"
A["YudaoRedisAutoConfiguration<br/>RedisTemplate/RedissonClient"]
B["YudaoCacheAutoConfiguration<br/>CacheManager/本地缓存"]
C["YudaoCacheProperties<br/>配置项"]
end
subgraph "核心层"
D["TimeoutRedisCacheManager<br/>动态TTL"]
end
subgraph "工具层"
E["RedisClient<br/>KV/Hash/Scan/Lua/过期"]
F["RedisDistributionLockUtils<br/>分布式锁"]
G["BloomFilterUtils<br/>布隆过滤器"]
H["LocalCacheUtils<br/>本地缓存"]
end
subgraph "注解与工具"
I["@CacheField<br/>字段注解"]
J["AnnotationCacheUtils<br/>注解驱动序列化"]
end
A --> E
A --> F
A --> G
B --> D
B --> H
J --> I
E --> J

图表来源

章节来源

核心组件​

  • Redis 客户端封装与序列化
    • 提供 JSON 序列化的 RedisTemplate 与 RedissonClient，统一键值序列化策略，支持 Java 8 时间类型
  • 自定义 CacheManager（动态 TTL）
    • 基于 Spring Cache 的 RedisCacheManager 扩展，支持在 cacheNames 中通过“#ttl”语法自定义过期时间
  • 本地缓存（Caffeine）
    • 提供独立的本地缓存管理器，与 Redis 缓存协同，降低热点数据的网络开销
  • 注解驱动的缓存工具
    • @CacheField 注解 + AnnotationCacheUtils，实现对象字段级缓存与 JSON 序列化
  • 分布式锁
    • 基于 Redis 的 setIfAbsent 实现简易分布式锁，支持等待与续期
  • 布隆过滤器
    • 基于 Redisson 的布隆过滤器工具，支持分区初始化、批量操作与索引更新
  • RedisClient 工具集
    • KV/Hash/List/Set/ZSet 操作、批量扫描、Lua 批量删除/过期、缓存穿透保护键等

章节来源

架构总览​

该组件通过 Spring Boot 自动装配机制加载配置与工具，形成“配置 → 缓存 → 工具”的清晰分层。

Mermaid Diagram Code:

graph TB
subgraph "Spring Boot 自动装配"
S1["AutoConfiguration.imports<br/>加载配置类"]
S2["YudaoRedisAutoConfiguration<br/>RedisTemplate/RedissonClient"]
S3["YudaoCacheAutoConfiguration<br/>CacheManager/本地缓存"]
end
subgraph "缓存层"
C1["TimeoutRedisCacheManager<br/>动态TTL"]
C2["Caffeine 本地缓存"]
end
subgraph "工具层"
U1["RedisClient"]
U2["RedisDistributionLockUtils"]
U3["BloomFilterUtils"]
U4["LocalCacheUtils"]
U5["@CacheField + AnnotationCacheUtils"]
end
S1 --> S2 --> S3 --> C1
S3 --> C2
C1 --> U1
C1 --> U2
C1 --> U3
C2 --> U4
U5 --> U1

图表来源

详细组件分析​

Redis 客户端封装与连接池配置​

  • RedisTemplate
    • 使用 String 序列化键，JSON 序列化值，统一时间类型序列化策略
    • 支持全局 key 前缀计算与 null 值缓存策略
  • RedissonClient
    • 单机模式自动装配，支持密码认证与数据库选择
    • 使用 JsonJacksonCodec，注册 JavaTimeModule，确保时间类型正确序列化

Mermaid Diagram Code:

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

图表来源

章节来源

自定义 CacheManager（动态 TTL）​

  • TimeoutRedisCacheManager
    • 在 cacheNames 中使用“名称#ttl”，支持 d/h/m/s 单位，动态覆盖默认 TTL
    • 通过 RedisCacheConfiguration.entryTtl 实现按缓存粒度的过期控制

Mermaid Diagram Code:

classDiagram
class TimeoutRedisCacheManager {
+createRedisCache(name, cacheConfig)
-parseDuration(ttlStr)
-removeDurationSuffix(ttlStr)
}
class RedisCacheManager
TimeoutRedisCacheManager --|> RedisCacheManager

图表来源

章节来源

本地缓存与 Redis 缓存的协同机制​

  • 本地缓存（Caffeine）
    • 提供独立的 cacheManagerLocal，便于热点数据就近缓存
  • 协同策略
    • 读优先本地缓存，未命中再回源 Redis；写入时同步更新本地缓存，提升响应速度

Mermaid Diagram Code:

sequenceDiagram
participant Caller as "调用方"
participant LC as "LocalCacheUtils"
participant RC as "RedisClient"
Caller->>LC : 读取本地缓存
alt 命中
LC-->>Caller : 返回本地值
else 未命中
LC->>RC : 读取Redis
RC-->>LC : 返回Redis值
LC->>LC : 写入本地缓存
LC-->>Caller : 返回值
end

图表来源

章节来源

分布式锁实现​

  • 基于 Redis 的 setIfAbsent 实现简易分布式锁
    • 支持指定租期与等待时间，避免死锁
    • 解锁时校验持有者，防止误删他人锁

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant Lock as "RedisDistributionLockUtils"
participant Redis as "Redis"
Client->>Lock : tryLock(key, value, wait, lease, unit)
loop 等待直至超时
Lock->>Redis : setIfAbsent(key, value, lease, unit)
alt 成功
Redis-->>Lock : true
Lock-->>Client : true
else 失败
Lock->>Lock : sleep(100ms)
end
end
Client->>Lock : unlock(key, value)
Lock->>Redis : get(key) == value ? del(key) : skip

图表来源

章节来源

缓存注解 (@CacheField) 与注解驱动工具​

  • @CacheField
    • 支持字段名映射、优先级排序、是否必须缓存、描述信息
  • AnnotationCacheUtils
    • 基于反射解析注解，构建 Map 或 JSON 缓存数据
    • 支持 LocalDateTime 等时间类型的序列化与反序列化
    • 提供批量处理与统计能力

Mermaid Diagram Code:

classDiagram
class CacheField {
+name() default ""
+order() default MAX_VALUE
+required() default false
+description() default ""
}
class AnnotationCacheUtils {
+buildCacheDataByAnnotation(obj)
+buildObjectByAnnotation(map, clazz)
+buildCacheDataAsJson(obj)
+buildObjectFromJson(json, clazz)
+buildCacheDataAsJsonBatch(list)
+buildObjectFromJsonBatch(list, clazz)
+getCacheDataSizeStats(obj)
+getCacheFieldStats(clazz)
+clearFieldCache()
}
AnnotationCacheUtils --> CacheField : "解析注解"

图表来源

章节来源

布隆过滤器与限流器、定时任务​

  • 布隆过滤器（BloomFilterUtils）
    • 支持初始化、添加、批量添加、分区初始化、重置、删除等
    • 提供误判率与预期插入量配置
  • 限流器
    • 通过 Redis 原子计数实现简单限流，结合 Lua 脚本保证原子性
  • 定时任务
    • 基于 Spring Quartz 或项目内定时任务机制，配合缓存清理策略

Mermaid Diagram Code:

flowchart TD
Start(["初始化布隆过滤器"]) --> Init["tryInit(expectedInsertions, falseProbability)"]
Init --> Add["add(element(s))"]
Add --> Might["contains(element)"]
Might --> |存在| True["可能存在"]
Might --> |不存在| False["一定不存在"]
Add --> Reset["reset()/resetAllElement()"]
Reset --> Done(["完成"])
True --> Done
False --> Done

图表来源

章节来源

缓存键命名规范、过期策略、缓存穿透防护​

  • 键命名规范
    • 使用冒号分隔的层级命名，避免多冒号导致的工具兼容问题
    • 支持按业务域划分前缀（如 data:base:/data:flow:/data:sys:）
  • 过期策略
    • 默认 TTL 来源于 CacheProperties.Redis
    • 支持动态 TTL（cacheNames 中“#ttl”）
    • 支持随机过期时间，缓解缓存雪崩
  • 缓存穿透防护
    • 使用特殊占位键（如负值标记）缓存空结果，避免持续击穿

Mermaid Diagram Code:

flowchart TD
A["请求缓存"] --> B{"Redis命中？"}
B --> |是| R["返回缓存值"]
B --> |否| C["执行业务查询"]
C --> D{"结果为空？"}
D --> |是| E["写入占位键(短TTL)"]
D --> |否| F["写入真实缓存(长TTL)"]
E --> R
F --> R

图表来源

章节来源

扩展点与高级特性​

  • 自定义缓存策略
    • 通过 TimeoutRedisCacheManager 的“#ttl”语法实现按缓存粒度的差异化过期
    • 通过 YudaoCacheProperties 调整 Redis Scan 批量大小与随机过期范围
  • 缓存监控
    • 结合 Spring Boot Actuator 暴露 Redis/Cache 指标，或在工具层埋点统计
  • 缓存清理
    • 提供批量删除、按前缀删除、Lua 批量删除、过期批量更新等工具方法

章节来源

依赖关系分析​

  • 外部依赖
    • Redisson Spring Boot Starter：提供 RedissonClient 与自动装配
    • Spring Cache：提供 @Cacheable 等注解与 CacheManager
    • Jackson JSR-310：支持 Java 8 时间类型序列化
    • Caffeine：提供本地缓存能力
    • RoaringBitmap：提供高性能位图支持（用于布隆过滤器索引等场景）

Mermaid Diagram Code:

graph LR
POM["pom.xml 依赖"] --> RS["redisson-spring-boot-starter"]
POM --> SC["spring-boot-starter-cache"]
POM --> JC["jackson-datatype-jsr310"]
POM --> CF["caffeine"]
POM --> RB["RoaringBitmap"]

图表来源

章节来源

性能考量​

  • 序列化与反序列化
    • 统一使用 JSON 序列化，减少跨语言与跨平台差异
    • 时间类型显式注册 JavaTimeModule，避免默认时间戳格式
  • 批量操作
    • RedisClient 提供批量删除、批量过期、Lua 批量脚本，降低 RTT
  • 本地缓存
    • Caffeine 本地缓存显著降低热点数据的网络往返
  • 过期策略
    • 随机过期时间避免同时过期引发的雪崩效应
  • 布隆过滤器
    • 降低无效查询与数据库压力，提高整体吞吐

故障排查指南​

  • RedisTemplate 序列化异常
    • 检查 JSON 序列化器是否正确注册 JavaTimeModule
  • 分布式锁无法释放
    • 确认解锁时持有的 value 与加锁一致，避免误删
  • 缓存穿透
    • 确认空值占位键是否写入且 TTL 正确
  • 动态 TTL 未生效
    • 检查 cacheNames 是否符合“名称#ttl”格式与单位

章节来源

结论​

yudao-spring-boot-starter-redis 通过“配置 + 工具 + 注解 + 自动装配”的架构，提供了完善的 Redis 缓存能力：

  • 统一的客户端封装与序列化策略
  • 支持动态 TTL 的 CacheManager
  • 本地缓存与 Redis 缓存的协同
  • 注解驱动的缓存工具与分布式锁
  • 布隆过滤器、限流器、定时任务等实用工具
  • 明确的键命名规范、过期策略与缓存穿透防护
  • 可扩展的配置项与工具方法，满足生产环境的高可用需求

附录​

  • 使用建议
    • 在高频读场景优先使用本地缓存 + Redis 缓存双写
    • 对热点数据使用随机过期时间，避免雪崩
    • 对外部查询使用布隆过滤器兜底，减少无效请求
    • 通过动态 TTL 精细化控制不同缓存的生命周期
用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答