labmem
ab83ad96b4
- 使用 Squirrel 与 sqlx 实现分类查询 - 集中组装依赖并向 handler 注入 model 接口 - 显式转换分类响应 DTO，统一空列表输出 - 补充路由与 handler 测试，同步架构文档 BREAKING CHANGE: 将 GET /hello 替换为 GET /test，响应由问候字符串改为分类列表
67 lines
3.6 KiB
Markdown
67 lines
3.6 KiB
Markdown
# Lyra
|
||
|
||
链接、分类、设置等资源的后端服务（实现中）。目标结构与技术选型见
|
||
[docs/architecture.md](docs/architecture.md)。
|
||
|
||
## 当前状态
|
||
|
||
HTTP 通路已延伸到数据库：启动时加载本地 `.env.local` 与 `etc/lyra.toml`，经
|
||
sqlx 连接 PostgreSQL（注册 pgx stdlib 驱动，驱动名取自配置），组装依赖后注册
|
||
`GET /test`——由 `handler.TestHandler` 调用 `model.CategoryModel.FindAll` 查询
|
||
`public.categories`（当前固定 `sort >= 1`、按 sort/id 排序、limit 10），并经
|
||
显式转换为本轮新增的 `api.CategoryResponse` 响应 DTO 后输出。该接口用于验证
|
||
handler→model→数据库链路，不是完整业务 API。
|
||
|
||
数据库连接代码当前在入口 `main` 中，`internal/postgres` 与 `internal/service`
|
||
仍是占位（仅 `AGENTS.md`），业务 service 未实现；连接与查询未设置超时，连接
|
||
真实数据库的端到端验证本轮也未做。
|
||
|
||
`internal/model` 已落地 `Category` 结构、`CategoryModel` 接口与 Squirrel +
|
||
sqlx 实现。路由与 handler 均有基于替身的 httptest 回归测试（不监听实际端口、
|
||
不连接数据库），不证明真实 SQL 可用。各内部目录的职责与依赖约束记录在各目录
|
||
`AGENTS.md` 中。数据库迁移 SQL 已就位：`migrations/00001_init.sql`（初始函数
|
||
与三张表），通过手工 goose CLI 执行，操作手册见
|
||
[docs/goose.md](docs/goose.md)，迁移目录说明见
|
||
[migrations/README.md](migrations/README.md)；Goose 的 Go 依赖仍未引入。
|
||
架构文档中标注“待新增”的文件（links 等）尚未创建。
|
||
|
||
## 目录职责
|
||
|
||
| 路径 | 职责 |
|
||
|---|---|
|
||
| `cmd/lyra/` | 程序入口：启动、依赖组装、退出清理（数据库连接当前建在此处） |
|
||
| `internal/api/` | HTTP 请求/响应 DTO，按资源分文件（平铺） |
|
||
| `internal/config/` | 配置定义与加载 |
|
||
| `internal/postgres/` | PostgreSQL 连接的目标位置（占位：连接暂在入口 main） |
|
||
| `internal/router/` | 路由注册、项目路径前缀（router.go，平铺） |
|
||
| `internal/handler/` | 参数绑定、DTO 转换、响应输出；可按业务分包，服务级简单接口平铺在根包 |
|
||
| `internal/service/` | 业务规则、事务协调；可按业务分包，服务级简单接口平铺在根包（占位） |
|
||
| `internal/model/` | 数据结构定义与数据访问（SQL，平铺） |
|
||
| `internal/httpx/` | 公共响应辅助 |
|
||
| `migrations/` | Goose SQL 迁移文件（00001 初始迁移已就位） |
|
||
| `docs/` | 架构与计划文档 |
|
||
|
||
## 运行
|
||
|
||
Go 命令在本目录（module 根）下执行；`.env.local` 与配置路径 `etc/lyra.toml`
|
||
均按当前工作目录解析，换目录运行会找不到它们：
|
||
|
||
```bash
|
||
go run ./cmd/lyra # 启动 HTTP 服务，监听地址与端口见 etc/lyra.toml
|
||
go test ./... # 回归测试（不监听实际端口、不连接数据库）
|
||
```
|
||
|
||
启动前提：本地存在 `.env.local`（提供数据库口令等环境变量，已被 gitignore、
|
||
不入库，内容不在文档展开）、`etc/lyra.toml` 配置完整，且其指向的 PostgreSQL
|
||
可达；连接失败时启动即退出。
|
||
|
||
配置中的 `app.env` 直接传给 `gin.SetMode`，仅支持 `debug`/`release`/`test`。
|
||
环境变量方面当前仅 `database.password` 绑定了 `PG_PASSWORD`，其余配置项不
|
||
支持环境变量覆盖，也没有校验与默认值。
|
||
|
||
## 技术栈
|
||
|
||
已引入并使用：Gin（HTTP 路由）、Viper（读取 TOML 配置）、godotenv（加载
|
||
`.env.local`）、sqlx + Squirrel（查询构造与执行）、pgx stdlib（PostgreSQL
|
||
驱动）。Goose 仅以独立 CLI（v3.29.0）手工执行迁移，Go 依赖尚未引入。
|