# 4.9 缓存架构设计

:::tip 概述
缓存层以 Redis 为主、进程内内存为降级：启动时探测 Redis，不可用自动切内存模式并告警，业务代码无感知。缓存键统一由 `consts` 函数生成，禁止裸字符串拼键。
:::

## 双模式结构

```text
utility/cache 对外 API（Set/Get/Del/Exists/SetNX/Incr/ZSet...）
        │
        ├── Redis 模式（默认）：go-redis/v9 连接池
        │
        └── 内存降级模式（探测失败自动切换，InMemory() 可查当前模式）
```

`cache.Init(ctx)` 在启动序列早期执行；`cache.Close()` 在优雅关闭末段调用。

## 对外 API

| API | 说明 |
|---|---|
| Set / Get / Del / Exists | 基础读写（带 TTL） |
| SetNX | 不存在才写入（任务锁、并发防护） |
| Incr | 计数器（限流窗口） |
| ZAdd / ZRem / ZRangeByScore / ZCard / ZRemRangeByScore | 有序集合（在线令牌按过期时间排序） |
| PING / Info / DBSize | Redis 原始操作（缓存监控页用） |

## 缓存键规范

键名唯一定义在 `internal/consts/cache_key.go`，统一前缀 `easygoadmin:`：

| 键函数 | 用途 |
|---|---|
| CacheKeyTokenBlacklist(jti) | Token 黑名单（TTL = token 剩余有效期） |
| CacheKeyOnlineJtiSet / CacheKeyOnlineInfo | 在线令牌集合与明细 |
| CacheKeyCaptcha(uuid) | 图形验证码答案 |
| CacheKeyDictItem(code) | 字典项集合（变更时删除对应键） |

业务代码**禁止**裸字符串拼键——改键名时遗漏引用会脏数据滞留。

## 缓存了什么

| 场景 | 键模式 | 失效策略 |
|---|---|---|
| 验证码 | captcha:{uuid} | TTL 到期（captcha.expire） |
| 字典项 | dict:{code} | 字典变更时主动 Del |
| Token 黑名单 | token:blacklist:{jti} | TTL 自然过期 |
| 在线用户 | online:jti:set + online:info:{jti} | 登出撤销 / 过期清理 |
| 身份/租户 | —— | auth 模块按需缓存 |
| 限流窗口 | 计数键 | 窗口过期 |

## 降级语义

Redis 不可用时：

- Init 探测失败 → 切内存模式 → 打 Warn 告警（含后果说明）
- 内存模式单进程有效：重启即空、多实例不共享
- 依赖缓存正确性的功能（黑名单、在线列表）在内存降级下**退化为单机语义**——生产环境应保证 Redis 可用

## 监控

缓存监控页经 PING/Info/DBSize 展示 Redis 运行状态与键空间分布（见 [6.19 缓存监控](/zh/modules/cache-monitor.html)）。内存降级时监控页反映内存实现的对应视图。

## 下一步

→ [4.10 数据库设计](/zh/architecture/database-design.html)