---
name: redis-cache
version: 3.0.0
description: "为 Hyperf/Swoole 应用设计 Redis 缓存策略。当需要缓存、限流或 Session 存储时使用。涵盖 TTL 设计、缓存失效和高并发模式。"
---

# 🔴 Redis Cache (Hyperf + Swoole)

## 触发条件

用户需要为应用添加缓存层、会话存储、限流计数器或消息队列。

## Phase 0：场景确认

| 场景 | 数据结构 | 说明 |
|------|---------|------|
| API 响应 | STRING | key-value + TTL |
| Session/Token | HASH | 多字段 |
| 排行榜 | ZSET | 范围查询 |
| 限流 | ZSET 滑动窗口 | 精准窗口 |
| 标签/权限 | SET | 集合运算 |
| 消息队列 | LIST/STREAM | FIFO |
| 分布式锁 | STRING + SET NX | 原子性 |
| WebSocket | HASH | fd→userId |

## Phase 1：连接配置

`config/autoload/redis.php`：default 与 cache 独立连接池，环境变量 REDIS_HOST/PORT/AUTH/DB/CACHE_DB。

## Phase 2：缓存策略

Cache-Aside：`withCache($key, $ttl, $fetcher)`，fetcher 内查 DB，setex 加 jitter。invalidate/invalidatePattern。

CachedRepository：装饰器包装 Repository，getById/getPageList 走缓存，写后 invalidateAll。读写比 > 10:1 用装饰器，< 10:1 用 Service 内 CacheService，热点数据用 Redis 原生。完整实现见 **Tier 3**。

## Phase 3：TTL 与 Key 规范

Profile 30m、列表 5m、配置 1h、JWT 2h、Session 24h。Key 格式：`namespace:entity:id:field`。

## Phase 4：分布式锁

withLock($lockKey, $ttlMs, $fn)，SET NX PX，释放用 Lua 原子校验 value 后 DEL。

## Phase 5：穿透/击穿防护

穿透：空值缓存 NULL_PLACEHOLDER。击穿：热点 key 用 withLock 互斥 + double-check。

## Phase 6：监控

cache hit/miss 计数，redis-cli INFO stats。

## 验证

1. [ ] 连接使用环境变量
2. [ ] Key 命名规范
3. [ ] 所有 Key 有 TTL
4. [ ] 失效与更新逻辑同步
5. [ ] 锁用 Lua 原子释放
6. [ ] 使用连接池
7. [ ] 百万级有穿透/击穿防护
8. [ ] CachedRepository 写后 invalidateAll

## Tier 3 深度参考

| 文件 | 内容 |
|------|------|
| `references/cache-implementation.md` | 连接、Cache-Aside、CachedRepository、TTL、锁、穿透/击穿完整代码 |