feat(lyra): 为分类查询添加缓存并同步项目约定

- 实现分类列表缓存查询与故障降级 - 统一缓存键命名 - 同步日志、响应、依赖组装及测试约定 - 移除 postgres 占位目录
2026-10-20 17:42:41 +08:00
parent bef30be3fe
commit 97b26635fa
8 changed files with 69 additions and 10 deletions
@@ -0,0 +1,33 @@
+# lyra 项目约定
+
+## Redis 缓存键
+
+- 格式：`<项目>:cache:<资源>:<查询>:v<版本>`，例如 `CategoryListCacheKey = "lyra:cache:category:list:v1"`。
+- 常量命名：`<资源><查询>CacheKey`，集中定义在 `internal/pkg/constant/cacheKey.go`，业务代码引用常量，不硬编码键字符串。
+- 分段含义：项目名（本项目为 `lyra`）隔离不同应用；`cache` 区分缓存与其他 Redis 用途；版本用于隔离结构不兼容的缓存数据。
+- 参数化查询的键必须包含影响查询结果的条件参数；键中不得出现密码、令牌等敏感信息。
+
+## 日志
+
+- 请求链路（middleware、handler、service、model）需要日志时使用 `util.Logger(ctx)`，使用结构化属性记录上下文与错误。
+- `util` 只从 context 读取 request ID；request ID 由 `RequestIDMiddleware` 注入，不由 `util` 生成。
+- Gin 调用链向下传递 `c.Request.Context()`，不要继续传 `*gin.Context`。
+- 禁止在请求处理中使用 `fmt.Printf` 或包级 `slog` 记录业务日志。
+- 无请求上下文的进程启动、初始化日志可直接使用 `slog`，不强制统一为 `util.Logger`。
+
+## 错误处理
+
+- 底层错误在合适的处理边界记录一次，避免每层重复记录。
+- 公开响应只返回约定的业务码与对外文案，不暴露底层错误、SQL、连接信息等内部细节。
+
+## 启动与组装
+
+- `cmd/lyra/bootstrap.go` 负责数据库、Redis 等基础设施初始化；`cmd/lyra/dependency.go` 负责依赖组装；`cmd/lyra/main.go` 负责入口流程编排。
+- `internal/config` 只定义配置结构与加载，不创建客户端；数据库/Redis 初始化留在 `cmd/lyra`，不另建占位包。
+- 不全局创建数据库或 Redis 客户端，实例由入口创建并注入。
+- 运行路径以 module 根为工作目录解析（例如 `etc/lyra.toml`）。
+
+## 测试
+
+- 默认自动测试应独立于真实 PostgreSQL、Redis 和真实端口。
+- 需要真实服务的联调测试单独说明和执行，不混入默认测试。