2.6 KiB
2.6 KiB
4.9 缓存架构设计
:::tip 概述
缓存层以 Redis 为主、进程内内存为降级：启动时探测 Redis，不可用自动切内存模式并告警，业务代码无感知。缓存键统一由 consts 函数生成，禁止裸字符串拼键。
:::
双模式结构
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 缓存监控）。内存降级时监控页反映内存实现的对应视图。