# 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 和真实端口。
- 需要真实服务的联调测试单独说明和执行，不混入默认测试。