docs(lyra): 记录技术选型与分层架构

- 记录 Gin、PostgreSQL、Squirrel、sqlx 和 Goose 选型 - 明确 handler、service、model 调用链及 API 职责边界 - 整理目标目录结构、待定事项与后续验证要求
2026-10-16 14:52:32 +08:00
parent d45d713a50
commit 3280c8a7bc
2 changed files with 194 additions and 0 deletions
@@ -0,0 +1,71 @@
+# Lyra 目标结构
+
+日期：2026-10-16
+
+本文记录已确认的目标目录结构与职责边界。Lyra 当前仅有 go.mod 和文档，代码尚未实施；以下文件为计划形态，不代表已存在。选型与讨论过程见 [plans/2026-10-16-lyra-architecture.md](plans/2026-10-16-lyra-architecture.md)。
+
+## 已确认技术栈
+
+Gin（HTTP 路由）、PostgreSQL、Squirrel + sqlx（数据访问，pgx stdlib 驱动）、Goose（数据库迁移）。
+
+## 目录结构
+
+```text
+lyra/
+├── cmd/lyra/main.go                  # 启动、依赖组装、退出清理
+├── internal/
+│   ├── api/                          # HTTP 请求/响应 DTO，按资源分文件
+│   │   ├── links.go                  # links 资源示例（下同）
+│   │   ├── categories.go
+│   │   └── settings.go
+│   ├── config/
+│   │   └── config.go                 # 配置定义与加载
+│   ├── postgres/
+│   │   └── postgres.go               # 数据库连接
+│   ├── router/
+│   │   └── router.go                 # 路由注册、项目路径前缀
+│   ├── handler/
+│   │   └── links.go                  # 参数绑定、DTO 转换、响应输出
+│   ├── service/
+│   │   ├── links.go                  # 业务规则、事务协调
+│   │   └── links_test.go             # 测试与源文件同目录
+│   ├── model/
+│   │   ├── link.go                   # Link 数据结构定义
+│   │   ├── link_model.go             # 数据访问对象：CRUD 与 SQL（示例）
+│   │   └── link_model_test.go        # 查询测试（示例）
+│   └── httpx/
+│       └── response.go               # 公共响应辅助，按需实现
+├── migrations/                       # Goose SQL 迁移文件
+├── docs/
+│   ├── plans/
+│   └── architecture.md               # 本文
+├── README.md
+├── go.mod
+└── go.sum                            # 引入依赖后由 Go 工具生成
+```
+
+- 标注示例的文件展示一个资源在各层的文件分布；分类、设置等资源按同样方式在 api/handler/service/model 新增对应文件。model/link.go 定义 Link 数据结构，model/link_model.go 定义数据访问与 SQL，model/link_model_test.go 测试查询，均为示例，实际文件随实现新增。
+- 只创建实际需要的文件；不预建空目录或空测试文件，具体迁移文件名随首个迁移确定。
+
+## 组织原则
+
+- 不按业务项目建代码子目录（无 polaris 等项目目录）；项目通过 `/api/polaris` 等路由前缀区分，代码按技术职责分组，包内文件按资源划分。
+- 不保留 platform/modules 分类层；配置在 internal/config，连接在 internal/postgres，HTTP 辅助在 internal/httpx。
+- 简单接口不强制走完整三层，也不按每张表机械复制层级。
+
+## 层间边界
+
+- 主调用链为 handler→service→model→PostgreSQL；service 负责业务规则及需要的事务协调，model 支持同一事务内的数据库操作，不将跨多次写入各自独立提交当成原子业务。
+- 请求/响应 DTO 集中在 internal/api，与内部模型分开；即使初期字段相近，也不默认把数据库模型直接暴露为响应，接受必要的显式转换代码。
+- handler 引用 API DTO 完成绑定与转换；service/model 不依赖 Gin，也不依赖 internal/api DTO；api 包不反向引用 handler/service/model，避免传输契约与实现耦合或循环引用。
+- model 承载数据结构定义与数据访问：Squirrel/SQL 构造、sqlx 执行与结果映射，驱动为 pgx stdlib；不是 ORM 自动持久化，也不要求每种类型机械建立一套结构。
+- service/model 使用标准 context.Context，不接收 gin.Context。
+
+## 尚未确定
+
+以下仍为计划中的推荐或待确认项，未定为已决：
+
+- 代码尚未实施，也未进行数据库连接或结构修改。
+- Goose 的部署执行入口与并发控制（串行执行或数据库锁）方案。
+- PostgreSQL 按项目划分 schema 的做法（组织边界，不等于权限隔离）。
+- 日志方案（候选标准库 slog）与中间件集成方式。