github.com/bafuka/HotArmor @2.0.0-RELEASE
Chat with this repoWhat it actually does AI analysis from the code graph — generated when you open this
README
HotArmor 🛡️
智能热点数据防护框架 · 解决高并发缓存击穿难题
一行注解，让热点数据自动晋升本地缓存
💡 它解决什么问题？
HotArmor（热铠） 是一款专为高并发场景设计的热点数据防护中间件。在电商秒杀、热点事件等场景下，少数热点数据（如爆款商品、热门话题）会带来严重的性能问题：
| 问题 | 典型场景 | 技术影响 | HotArmor 方案 |
|---|---|---|---|
| ⚡ 缓存击穿 | 热点 Key 失效瞬间 | 数千请求同时打穿缓存直达数据库，DB 瞬间被打垮 | L4 分布式锁 + Double-Check，确保单点回源 |
| 🔥 热点过载 | 明星商品被高频访问 | Redis 连接池耗尽、网络带宽占满、响应变慢 | L1-L3 智能识别热点并晋升到本地缓存（微秒级） |
| 🔄 分布式缓存一致性 | 集群多节点部署 | 节点 A 更新数据，节点 B/C/D 本地缓存未失效产生脏读 | Pub/Sub 失效广播 + 热点晋升广播，全节点同步 |
| 🗑️ DB-Cache 一致性 | 高并发读写竞态 | 更新 DB 后删除缓存，并发查询将旧数据回写 Redis | 延迟双删策略，消除写后读竞态窗口期 |
🚀 核心特性
// 只需一行注解，框架自动处理热点防护
@HotArmorCache(resource = "product:detail", key = "#id")
public Product getProduct(Long id) {
return productMapper.selectById(id); // 热点数据自动晋升本地缓存
}
- ✨ 开箱即用 - 注解声明式使用，零侵入接入
- 🧠 智能识别 - 基于 Sentinel 的热点参数流控，精准识别热点数据
- 🔄 四级防护 - L1 本地缓存 → L2 噪音过滤 → L3 热点探测 → L4 安全回源
- 📡 最终一致性 - 延迟双删 + Redis Pub/Sub 广播，保证集群缓存同步
- ⚡ 极致性能 - 热点数据从 Redis 毫秒级 → Caffeine 微秒级响应
🏗️ 架构设计
系统架构
┌─────────────────────────────────────────────────────────────────────┐
│ 业务应用层 │
│ │
│ @HotArmorCache(resource="...", key="...") ← 查询缓存 │
│ @HotArmorEvict(resource="...", key="...") ← 失效缓存 │
└──────────────────────────┬──────────────────────────────────────────┘
│
│ AOP 拦截
↓
┌─────────────────────────────────────────────────────────────────────┐
│ HotArmor 核心引擎 │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ 切面层 (Aspect) │ │
│ │ • HotArmorAspect - AOP 拦截器 │ │
│ │ • SpEL 表达式解析器 - 解析 key/condition │ │
│ │ • HotArmorContext - 请求上下文对象 │ │
│ └─────────────────────────┬─────────────────────────────────────┘ │
│ ↓ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ 处理器层 (Handler) │ │
│ │ • DefaultHotArmorAspectHandler │ │
│ │ - handleCache() : 读流程四级漏斗 │ │
│ │ - handleEvict() : 写流程缓存失效 │ │
│ └─────────────────────────┬─────────────────────────────────────┘ │
│ ↓ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ 数据平面 (Data Plane) │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
│ │ │ L1: 本地缓存层 (CaffeineL1CacheEngine) │ │ │
│ │ │ • Caffeine 高性能本地缓存 │ │ │
│ │ │ • 微秒级响应 (~1μs) │ │ │
│ │ │ • 独立配置容量和过期时间 │ │ │
│ │ └─────────────────────────────────────────────────────────┘ │ │
│ │ ↓ Miss │ │
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
│ │ │ L2: 噪音过滤层 (CaffeineL2NoiseFilter) │ │ │
│ │ │ • 轻量级访问计数器 │ │ │
│ │ │ • 过滤冷数据 (访问频率 < 阈值) │ │ │
│ │ │ • 保护 Sentinel 资源 │ │ │
│ │ └─────────────────────────────────────────────────────────┘ │ │
│ │ ↓ Pass │ │
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
│ │ │ L3: 热点探测层 (SentinelL3HotspotDetector) │ │ │
│ │ │ • Sentinel 参数流控 │ │ │
│ │ │ • 热点判定 (QPS > 阈值) │ │ │
│ │ │ • 自动触发热点晋升 │ │ │
│ │ └─────────────────────────────────────────────────────────┘ │ │
│ │ ↓ Block (热点！) │ │
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
│ │ │ L4: 安全回源层 (RedissonL4SafeLoader) │ │ │
│ │ │ • Redisson 分布式锁 │ │ │
│ │ │ • Double-Check 机制 │ │ │
│ │ │ • 重试 + 指数退避 │ │ │
│ │ │ • 防止缓存击穿 │ │ │
│ │ └─────────────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ 控制平面 (Control Plane) │ │
│ │ │ │
│ │ • DefaultRuleManager - 规则管理器 │ │
│ │ - loadRules() : 加载规则配置 │ │
│ │ - updateRules() : 动态更新规则 │ │
│ │ - validateRule() : 规则验证 │ │
│ │ • HotArmorRule - 规则模型 (L1-L4 配置) │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ 一致性引擎 (Consistency Engine) │ │
│ │ │ │
│ │ • DefaultConsistencyManager - 一致性管理器 │ │
│ │ - handleUpdate() : 处理缓存更新 │ │
│ │ - handlePromotion() : 处理热点晋升广播 │ │
│ │ - invalidateCache() : 立即删除缓存 │ │
│ │ • RedisBroadcastNotifier - Redis Pub/Sub 广播 │ │
│ │ - 缓存失效广播 │ │
│ │ - 热点晋升广播 (NEW) │ │
│ │ • DelayedDeleteProducer - 延迟双删 (RocketMQ) │ │
│ └───────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│
┌────────────────┼────────────────┐
│ │ │
↓ ↓ ↓
┌──────────────────┐ ┌────────────┐ ┌─────────────────┐
│ Redis │ │ RocketMQ │ │ 数据库 │
│ • 二级缓存 │ │ • 延迟消息 │ │ • MySQL │
│ • Pub/Sub 广播 │ │ (可选) │ │ • PostgreSQL │
│ • 分布式锁 │ └────────────┘ │ 等 │
└──────────────────┘ └─────────────────┘
───────────────────────────────────────────────────────────────────────
数据流向说明：
读流程：
用户请求 → AOP拦截 → L1本地缓存 → L2噪音过滤 → L3热点探测
→ L4安全回源 → Redis/DB → 晋升L1(热点) → 发送晋升广播
→ 其他节点收到广播并晋升L1 → 返回
写流程：
用户请求 → AOP拦截 → 更新DB → 删除L1+Redis → 发送失效广播
→ 其他节点清L1 → 延迟双删(可选) → 完成
───────────────────────────────────────────────────────────────────────
核心流程
读取流程（四级漏斗）
``` 用户请求 ↓ ┌─────────────────────────────────────────┐ │ @HotArmorCache 注解方法 │ └────────────┬────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ HotArmorAspect.aroundCache() │ │ • 解析 SpEL key 表达式 │ │ • 解析 condition 条件 │ │ • 构建 HotArmorContext │ └────────────┬────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ DefaultHotArmorAspectHandler │ │ .handleCache() │ └────────────┬────────────────────────────┘ ↓ │ ┌────────────▼───────────────────────────┐ │ L1: CaffeineL1CacheEngine.get() │ │ 检查本地缓存 │ └────────────┬───────────────────────────┘ │ ┌───────────┴────────────┐ │ │ 缓存命中 缓存未命中 │ │ ↓ ↓ 返回数据 ✅ ┌─────────────────────────┐ (~1μs) │ L2: L2NoiseFilter │ │ .shouldPass() │ │ • 计数器检查访问频率 │ └──────────┬──────────────┘ │ ┌───────────┴────────────┐ │ │ 访问频率 < 阈值 访问频率 >= 阈值 (冷数据) (热数据) │ │ ↓ ↓ 直接回源加载 ┌────────────────────┐ (不占用Sentinel) │ L3: SentinelL3 │ │ │ .isHotspot() │ │ │ • Sentinel热点检测│ │ └──────┬─────────────┘ │ │ │ ┌───────────┴────────────┐ │ │ │ │ QPS < 阈值 QPS >= 阈值 │ (非热点) (热点！) │ │ │ └───────────┼────────────────────────┘ ↓ ┌───────────────────────────────────┐ │ L4: RedissonL4SafeLoader.load() │ │ 安全回源 │ └────────────┬──────────────────────┘ ↓ ┌────────────────────────────────────┐ │ 1. getFromRedis() │ │ 先查 Redis 缓存 │ └────────────┬───────────────────────┘ │ ┌───────────┴────────────┐ │ │ Redis 命中 Redis 未命中 │ │ ↓ ↓ 返回数据 ✅ ┌────────────────────┐ │ 2. 获取分布式锁 │ │ redissonClient │ │ .getLock() │ └──────┬─────────────┘ │ ┌───────────┴────────────┐ │ │ 获取锁成功 获取锁失败 │ │ ↓ ↓ ┌──────────────────────┐ ┌──────────────────┐ │ 3. Double-Check │ │ 重试机制 │ │ 再次查Redis │ │ • 等待 + 重试 │ └──────┬───────────────┘ │ • 指数退避 │ │ │ • 最终降级查DB │ ┌────┴─────┐ └────────┬─────────┘ │ │ │ 命中 未命中 │ │ │ │ │ ↓ │ │ ┌──────────────┐ │ │ │ 4. 查询数据库 │ │ │ │ joinPoint │ │ │ │ .proceed() │ │ │ └──────┬───────┘ │ │ │ │ │ ↓ │ │ ┌──────────────┐ │ │ │ 5. 回写Redis │ │ │ │ putToRedis() │ │ │ └──────┬───────┘ │ │ │ │ └──────────┴───────────────────────┘ ↓ ┌──────────────────┐ │ 是否为热点？ │ └────────┬─────────┘ │ ┌───────────┴────────────┐ │ │ 是热点 非热点 │ │ ↓ ↓ ┌──────────────────┐ 直接返回 ✅ │ 6. 晋升到 L1 │ │ L1CacheEngine │ │ .put() │ └────────┬─────────┘ ↓ ┌──────────────────────────────────────┐ │ 7. 发送热点晋升广播 │ │ ConsistencyManager.handlePromotion() │ │ • 检查是否启用晋升广播 │ │ • 通过 Redis Pub/Su
Extension points exported contracts — how you extend this code
ConfigSource (Interface)Core symbols most depended-on inside this repo
putShape
Languages
Modules by API surface
For agents
$ claude mcp add HotArmor \
-- python -m otcore.mcp_server <graph>