4.8 缓存架构设计

:::tip 概述缓存实现为 utility/cache 统一门面：Redis 优先，连接失败或运行期出错自动降级进程内存 gcache（UsingMemory() 可查）。三层缓存各司其职，Redis 键统一前缀 easygoadmin:。 :::

缓存分层图

请求 ──▶ ① 进程内缓存（sync.Map，无 Redis 交互，重启即清）
           dictTextCache(300s) · reqFieldCache/textPlanCache(反射计划,永不过期)
           maskReCache(正则,永不过期)
       ──▶ ② Redis（跨实例共享，TTL 自动回收）
           黑名单/在线/验证码/字典/租户摘要/身份/限流/任务锁
       ──▶ ③ 数据库（唯一真相，dao.Ctx 全量过滤条件）

设计原则：② ③ 之间的一切缓存都必须有明确的失效点或短 TTL 兜底；
         ① 仅缓存"计算计划/只读文本"，不允许缓存业务状态。

Redis 键全集

键模式	TTL	写入方	读取方
`easygoadmin:token:blacklist:{jti}`	剩余有效期+60s	Logout/Refresh 轮换/RemoveToken/ForceLogout	JWT 中间件 Exists 判定
`easygoadmin:online:jti:set`（zset）	成员随 info（score=过期 ts）	MarkOnline/MarkOffline	OnlineUser.Page（ZRangeByScore≥now）
`easygoadmin:online:info:{jti}`	access 剩余+60s	MarkOnline/MarkOffline	OnlineUser.Page/Detail/ForceLogout
`easygoadmin:captcha:{uuid}`	300s	Captcha 生成	Login/Verify（一次性）
`easygoadmin:dict:item:{code}`	3600s	dict.setCache/RefreshCache	dict_item 快捷接口/AliasList
`easygoadmin:tenant:info:{id}`	60s	Tenant 中间件/Login 路径	Tenant 中间件/Login
`easygoadmin:user:identity:{uid}`	300s	JWT 中间件（回源 Loader）	JWT 中间件（Roles/Perms/DataScope/DeptId JSON）
`easygoadmin:user:perms:{uid}` / `user:roles:{uid}`	约定键（保留扩展）	—	主路径用 identity 合并键，变更时一并清理
`ratelimit:{ip}:{path}:{窗口起点}`	window+5s	RateLimit incr	RateLimit
`job:lock:{jobId}`	300s 兜底	jobTryLock(NX)	jobTryLock（执行完 defer Del）

主动失效点清单

身份缓存 user:identity:{uid} 删除时机：

* role.SavePermission 保存角色权限 → clearRoleIdentityCache(roleId)
  → 查该角色全部 user → 逐个 Del
* role.Update 修改角色（含 data_scope 变更）→ AfterUpdate → 同上
* user.AssignRoles 分配/调整角色 → clearIdentityCache(userId)
  （user.Update / user.Add 均经 AssignRoles——改部门 dept_id 亦在此清缓存）
* 版本兼容：Identity 新增字段反序列化缺省为 0，读侧 GetDataScope 回退"全部"
  ——升级无需强清存量缓存

其他：租户摘要在 tenant 状态/过期变更时由 AfterUpdate clearCache 钩子清理；字典 Redis 缓存由 RefreshCache 主动重建（dict_item 变更不主动清，最长 1 小时延迟）；黑名单靠 TTL 自然过期（过期即令牌本身已失效）；验证码命中即删。

进程内缓存明细

缓存	位置	内容	TTL
dictTextCache	base.go	{code}:{value} → 显示名	300s
reqFieldCache / textPlanCache / childrenIdxCache	module_spec.go	反射索引与填充计划	永不过期（类型不变即安全）
maskReCache	middleware/util.go	脱敏正则	永不过期

内存降级的影响面

Redis 不可用时 UsingMemory()=true，以下能力退化单机语义：

限流计数   各实例各自计数（阈值实际翻倍）
任务锁     job:lock 退化单机，多实例可能并发执行任务
在线用户   只看本实例登录的会话
JWT 黑名单 本实例签发的登出/强退不拦截其他实例
验证码     单实例内有效
字典缓存   各实例独立回源

运维可通过 GET /api/cache/info 的 mode 字段确认当前模式（redis/memory）。

TTL 设计原则（新增缓存遵循）

1) 状态判定类（黑名单/租户状态）：TTL ≤ 业务有效期，且必须有主动失效点；
   宁可短 TTL 多回源，不可长 TTL 陈旧放行
2) 展示文本类（字典/归属地）：TTL 300s~3600s + 刷新接口，接受分钟级延迟
3) 高频读聚合类（identity）：合并为单键 JSON（一次回源装多个集合），
   TTL 300s，变更路径主动 Del
4) 计数/锁类：键内嵌窗口起点或场景唯一 id，TTL 只做回收不参与语义
5) 任何经 cache.Set 的值必须可 JSON 序列化；读侧 Unmarshal 失败视为未命中回源

排障速查

键不存在/值陈旧     先查是否内存降级（redis-cli KEYS 'easygoadmin:*' 对比）
权限不生效          DEL easygoadmin:user:identity:{uid}
租户被禁仍可访问    等 60s 或 DEL easygoadmin:tenant:info:{id}
多实例行为不一致    确认 Redis 可用（/api/cache/info mode 应为 redis）

4.8 KiB Raw Blame History Unescape Escape