easy-cache 缓存组件设计

本文档描述 components/easy-cache 的设计。 定位：基于 Spring Cache 增强的轻量缓存组件，不替代 Spring Cache、不重复造轮子， 而是补齐其在分布式场景的短板（注解级 TTL、两级缓存、穿透/击穿/雪崩防护、本地失效广播、命中率监控）。

设计借鉴：JetCache（注解原生 TTL、两级缓存、防穿透单飞）、J2Cache（Caffeine L1 + Redis L2、失效广播）。

目录

1. 背景与问题
2. 组件定位与边界
3. 核心能力设计
4. 两级缓存读写流程
5. 失效广播流程
6. 注解设计
7. 模块结构与核心类
8. 配置项
9. 与现有框架的集成点
10. 使用示例
11. 关键设计决策汇总

一、背景与问题

1.1 Spring Cache 的能力与短板

Spring Cache 提供 @Cacheable/@CachePut/@CacheEvict + SpEL key + 多后端抽象，但存在业界公认短板：

1.2 开源框架借鉴

二、组件定位与边界

flowchart TD
    subgraph "Business System"
        BIZ["业务方法<br/>标注 @EasyCacheable"]
    end

    subgraph "easy-cache 组件"
        direction TB
        ANN["注解<br/>EasyCacheable / EasyCachePut / EasyCacheEvict"]
        AOP["EasyCacheAspect<br/>single-flight 防击穿"]
        CORE["CacheTemplate<br/>统一编程式 API"]
        MULTI["MultiLevelCache<br/>L1 Caffeine + L2 Redis"]
        BCAST["CacheEvictBroadcaster<br/>Redis Pub/Sub 广播失效"]
        STAT["CacheStatistics<br/>命中率统计"]
        AUTO["自动配置<br/>EasyCacheAutoConfiguration"]
    end

    subgraph "复用能力"
        K1["Spring Cache<br/>CacheManager 抽象"]
        K2["kernel-common<br/>JsonMapper"]
        K3["Redis<br/>RedisTemplate"]
        K4["easy-messaging<br/>Redis Pub/Sub"]
    end

    BIZ -->|"引入依赖 + 配置"| AUTO
    BIZ -->|"标注注解"| ANN
    ANN --> AOP
    AOP --> CORE
    CORE --> MULTI
    MULTI --> BCAST
    MULTI --> STAT
    MULTI --> K1
    MULTI --> K2
    MULTI --> K3
    BCAST --> K4

组件边界：

三、核心能力设计

四、两级缓存读写流程

flowchart TD
    REQ["业务方法调用"] --> ANN["EasyCacheAspect<br/>解析注解 + SpEL key"]
    ANN --> FLY{"single-flight<br/>同 key 并发?"}
    FLY -->|"是"| WAIT["等待已有回源任务结果"]
    FLY -->|"否"| L1["读 L1 Caffeine"]
    L1 -->|"命中"| RET["返回"]
    L1 -->|"未命中"| L2["读 L2 Redis"]
    L2 -->|"命中"| BACK["回填 L1<br/>返回"]
    L2 -->|"未命中"| DB["执行业务方法回源"]
    DB --> WRITE["写 L2 + 写 L1"]
    WRITE --> NULL{"结果为 null<br/>且 cacheNullValue?"}
    NULL -->|"是"| NULLCACHE["缓存 null 占位<br/>防穿透"]
    NULL -->|"否"| RET2["返回结果"]
    RET --> END
    BACK --> END
    RET2 --> END

要点：

• 读链：L1 → L2 → DB；BOTH 模式下 L1 吸收热点，降低 L2 网络瓶颈（J2Cache 思路）。
• single-flight 在切面层实现（ConcurrentHashMap<String, Future>），仅 BOTH/REMOTE 生效，LOCAL 本地 Caffeine 已原子化。
• 随机过期：实际TTL = ttl * (1 ± 10%)，仅开启 ttl-jitter-enabled 时。

五、失效广播流程

flowchart TD
    WRITE["实例 A 写/删缓存<br/>EasyCachePut / EasyCacheEvict / 手工 evict"]
    WRITE --> L2A["写 L2 Redis<br/>(主数据源)"]
    WRITE --> PUB["CacheEvictBroadcaster<br/>Redis Pub/Sub 发布<br/>cacheName + key"]
    PUB --> SUB["实例 B / C 订阅者<br/>收到广播"]
    SUB --> L1B["清除本地 L1 对应 key"]
    L1B --> DONE["保证跨实例本地缓存一致"]

要点：

• L2（Redis）是主数据源，广播只用于清除各实例 L1，保证”最终一致 + 极低延迟”。
• 广播通道复用框架已有 Redis 基础设施（RedisTemplate Pub/Sub，或 easy-messaging Redis connector）。
• 单机模式可关闭广播（broadcast.enabled=false），避免无谓的 Pub/Sub。

六、注解设计

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface EasyCacheable {
    String cacheName();                       // 缓存命名空间（对应 Redis key 前缀）
    String key();                             // SpEL，如 "#id" 或 "#user.id"
    long ttl() default 0L;                    // 过期秒数，0 表示永不过期
    CacheType cacheType() default CacheType.BOTH;   // LOCAL / REMOTE / BOTH
    boolean cacheNullValue() default false;   // 空值缓存（防穿透）
    String condition() default "";            // SpEL，false 不走缓存
}

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface EasyCachePut {
    String cacheName();
    String key();                             // SpEL
    long ttl() default 0L;
    CacheType cacheType() default CacheType.BOTH;
    String condition() default "";            // 可引用 #result
}

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface EasyCacheEvict {
    String cacheName();
    String key();                             // SpEL，支持 #key=null 全清
    CacheType cacheType() default CacheType.BOTH;
}

关键决策：cacheName 显式命名（对标 J2Cache Region / JetCache name）， 避免 Spring Cache 默认”全参数拼接 key”导致的键爆炸；TTL 注解级原生（对标 JetCache）。

七、模块结构与核心类

components/easy-cache/
├── pom.xml
└── src/main/java/io/matrix/cache/
    ├── annotation/                 # 三个注解
    │   ├── EasyCacheable.java
    │   ├── EasyCachePut.java
    │   └── EasyCacheEvict.java
    ├── core/
    │   ├── CacheType.java          # LOCAL / REMOTE / BOTH
    │   ├── CacheTemplate.java      # 编程式 API（get/put/evict/getOrLoad）
    │   ├── MultiLevelCache.java    # 两级缓存实现（L1 Caffeine + L2 Redis）
    │   └── SingleFlight.java       # per-key 互斥回源
    ├── aop/
    │   └── EasyCacheAspect.java    # 注解切面（解析注解 + single-flight + 统计）
    ├── broadcast/
    │   └── CacheEvictBroadcaster.java  # Redis Pub/Sub 广播与订阅
    ├── statistics/
    │   └── CacheStatistics.java    # 命中率 / 回源计数
    └── autoconfigure/
        ├── EasyCacheAutoConfiguration.java
        └── EasyCacheProperties.java

核心类职责：

八、配置项

前缀 easy.cache：

九、与现有框架的集成点

十、使用示例

// 1. 引入依赖 + 开启
// @SpringBootApplication 无需额外 @EnableCaching（自动配置注册切面）

// 2. 注解式缓存（推荐）
@Service
public class UserQueryService {

    @EasyCacheable(cacheName = "user", key = "#userId", ttl = 300, cacheType = CacheType.BOTH)
    public User findById(Long userId) {
        return userMapper.selectById(userId);   // 回源
    }

    @EasyCachePut(cacheName = "user", key = "#user.id", ttl = 300, condition = "#result != null")
    public User update(User user) {
        userMapper.updateById(user);
        return user;                             // 更新后写缓存
    }

    @EasyCacheEvict(cacheName = "user", key = "#userId")
    public void delete(Long userId) {
        userMapper.deleteById(userId);           // 删除后失效缓存（广播清 L1）
    }
}

// 3. 编程式 API
@Autowired
private CacheTemplate cacheTemplate;

public User getUser(Long userId) {
    return cacheTemplate.getOrLoad("user", userId, () -> userMapper.selectById(userId), 300);
}

十一、关键设计决策汇总