labmem
c812cfb663
- 添加通用查询选项、分类过滤选项及动态缓存键生成 - 新增分类创建与更新时间字段 当前实现尚未完成，留待后续继续设计： - 明确通用查询选项、模型过滤条件与缓存策略的边界 - 补齐数据库回源，修正分类返回类型及过滤条件生效问题 - 修正分页偏移计算，增加参数边界校验和稳定排序 - 完善缓存故障降级、空结果缓存及写后失效策略 - 修正缓存键参数编码歧义，补齐查询名和版本前缀 - 补充测试并验证编译与查询行为
Lyra
链接、分类、设置等资源的后端服务（实现中）。目标结构与技术选型见 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，迁移目录说明见
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
均按当前工作目录解析，换目录运行会找不到它们：
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 依赖尚未引入。