hi-server/doc/cache-convention-zh.md

GORM + Redis 缓存调用规范

本文档约定了项目内 GORM 与 Redis 缓存的推荐调用方式，目标是避免“有的地方自动清缓存，有的地方手动清缓存”的分散写法。

统一入口

项目缓存统一由 pkg/cache/CachedConn 提供，常用方法：

• QueryCtx：读缓存，未命中回源 DB 并写缓存
• ExecCtx：写 DB，成功后删除指定缓存 key
• QueryNoCacheCtx：只查 DB，不读写缓存
• ExecNoCacheCtx：只写 DB，不自动清缓存
• TransactCtx：事务执行

推荐使用规则

1) 主键/唯一键查询（有稳定 key）

优先使用 QueryCtx，必须显式构建缓存 key。

2) 列表/复杂筛选查询

仅当 key 规则稳定时用 QueryCtx；否则用 QueryNoCacheCtx。

3) 写操作（新增/更新/删除）

优先使用“统一 helper”封装为一条路径：

1. 执行 DB 写入
2. 按模型计算 key
3. 清理关联缓存

避免在业务逻辑层分散调用 DelCache。

user_subscribe 规范落地

internal/model/user/subscribe.go 已提供统一 helper：

• execSubscribeMutation(...)

InsertSubscribe / UpdateSubscribe / DeleteSubscribe / DeleteSubscribeById 统一通过该 helper 执行，避免每个方法重复写“ExecNoCacheCtx + defer 清缓存”。

key 生成约定

模型缓存 key 统一在模型侧定义，不在 handler/logic 手写：

• internal/model/user/cache.go
  • (*Subscribe).GetCacheKeys()
  • ClearSubscribeCacheByModels(...)

说明：user_subscribe 当前会同时清理普通列表 key 与 :all 列表 key，避免删改后列表残留旧缓存。

新增模型时的最小模板

1. 在 model 中定义 getCacheKeys(...) 或 GetCacheKeys()
2. 查询方法优先 QueryCtx
3. 写方法统一走 helper（DB 写 + 缓存失效）
4. 避免在 handler/logic 直接操作缓存 key