Compare commits
3
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 labmem
|
ab83ad96b4 | ||
|
labmem
|
8c0c9978e5 | ||
|
labmem
|
3f16384376 |
+2
-1
@@ -45,4 +45,5 @@ Thumbs.db
|
||||
|
||||
# ---- Note 目录 ----
|
||||
note/项目/
|
||||
docs/plans
|
||||
docs/plans
|
||||
go/projects/lyra/data
|
||||
+44
-20
@@ -1,42 +1,66 @@
|
||||
# Lyra
|
||||
|
||||
链接、分类、设置等资源的后端服务（规划中）。目标结构与技术选型见
|
||||
链接、分类、设置等资源的后端服务（实现中）。目标结构与技术选型见
|
||||
[docs/architecture.md](docs/architecture.md)。
|
||||
|
||||
## 当前状态
|
||||
|
||||
已搭建目录骨架与程序入口 `main.go`，各内部目录的职责与依赖约束记录在 `AGENTS.md` 中。
|
||||
`internal/api/response.go` 定义公共响应结构；仅含 `AGENTS.md` 的目录暂不构成 Go 包。
|
||||
业务逻辑、数据库访问、HTTP API 与迁移文件均未实现；架构文档中标注示例的
|
||||
文件（links 等）尚未创建。当前运行程序后直接退出——不连接数据库，
|
||||
也不启动 HTTP 服务。
|
||||
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，按资源分文件 |
|
||||
| `cmd/lyra/` | 程序入口：启动、依赖组装、退出清理（数据库连接当前建在此处） |
|
||||
| `internal/api/` | HTTP 请求/响应 DTO，按资源分文件（平铺） |
|
||||
| `internal/config/` | 配置定义与加载 |
|
||||
| `internal/postgres/` | PostgreSQL 连接（pgx stdlib） |
|
||||
| `internal/router/` | 路由注册、项目路径前缀 |
|
||||
| `internal/handler/` | 参数绑定、DTO 转换、响应输出 |
|
||||
| `internal/service/` | 业务规则、事务协调 |
|
||||
| `internal/model/` | 数据结构定义与数据访问（SQL） |
|
||||
| `internal/httpx/` | 公共响应辅助，按需实现 |
|
||||
| `migrations/` | Goose SQL 迁移文件（暂无） |
|
||||
| `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 根）下执行：
|
||||
Go 命令在本目录（module 根）下执行；`.env.local` 与配置路径 `etc/lyra.toml`
|
||||
均按当前工作目录解析，换目录运行会找不到它们：
|
||||
|
||||
```bash
|
||||
go run ./cmd/lyra # 当前直接退出，不连接数据库、不启动 HTTP
|
||||
go test ./... # 当前无测试文件，仅验证各包可编译
|
||||
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 与 Viper（读取 TOML 配置），go.sum 已生成；
|
||||
PostgreSQL、Squirrel + sqlx（pgx stdlib 驱动）与 Goose 为目标选型，随后续功能引入。
|
||||
已引入并使用：Gin（HTTP 路由）、Viper（读取 TOML 配置）、godotenv（加载
|
||||
`.env.local`）、sqlx + Squirrel（查询构造与执行）、pgx stdlib（PostgreSQL
|
||||
驱动）。Goose 仅以独立 CLI（v3.29.0）手工执行迁移，Go 依赖尚未引入。
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"lyra/internal/config"
|
||||
"lyra/internal/handler"
|
||||
"lyra/internal/model"
|
||||
"lyra/internal/router"
|
||||
|
||||
"github.com/jmoiron/sqlx"
|
||||
)
|
||||
|
||||
type Dependencies struct {
|
||||
Config *config.Config
|
||||
CategoryModel model.CategoryModel
|
||||
}
|
||||
|
||||
// buildHandlers 集中组装各路由的处理器，入口启动时调用一次。
|
||||
func buildHandlers(dpd *Dependencies) router.Handlers {
|
||||
return router.Handlers{
|
||||
TestHandler: handler.NewTestHandler(dpd.CategoryModel).Hello(),
|
||||
}
|
||||
}
|
||||
|
||||
func buildDependencies(cfg *config.Config, db *sqlx.DB) *Dependencies {
|
||||
return &Dependencies{
|
||||
Config: cfg,
|
||||
CategoryModel: model.NewCategoryModel(db),
|
||||
}
|
||||
}
|
||||
@@ -1,20 +1,51 @@
|
||||
// Command lyra 是 Lyra 的程序入口，负责启动、依赖组装与退出清理。
|
||||
//
|
||||
// 当前仅搭建目录骨架：运行后直接退出，不连接数据库，也不启动 HTTP 服务。
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"log"
|
||||
"lyra/internal/config"
|
||||
"lyra/internal/router"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
"github.com/jmoiron/sqlx"
|
||||
"github.com/joho/godotenv"
|
||||
|
||||
// 注册 pgx 驱动，供 sqlx 以 "pgx" 驱动名使用。
|
||||
_ "github.com/jackc/pgx/v5/stdlib"
|
||||
)
|
||||
|
||||
func main() {
|
||||
// 加载 .env.local 文件，覆盖环境变量
|
||||
if err := godotenv.Load(".env.local"); err != nil {
|
||||
log.Fatal("加载环境变量失败，请检查文件是否存在")
|
||||
}
|
||||
// 加载配置（internal/config）
|
||||
cfg, err := config.Load("etc/config.toml")
|
||||
cfg, err := config.Load("etc/lyra.toml")
|
||||
if err != nil {
|
||||
panic(err)
|
||||
log.Fatal("加载配置失败，请检查配置文件和环境变量")
|
||||
}
|
||||
gin.SetMode(cfg.App.Env)
|
||||
ginEngine := gin.Default()
|
||||
//没有反向代理，在启动前关闭代理信任：
|
||||
if err := ginEngine.SetTrustedProxies(nil); err != nil {
|
||||
log.Fatal("设置代理信任失败，请检查配置")
|
||||
}
|
||||
dataSourceName := fmt.Sprintf("host=%s port=%d user=%s dbname=%s password=%s sslmode=disable", cfg.Database.Host, cfg.Database.Port, cfg.Database.User, cfg.Database.Name, cfg.Database.Password)
|
||||
|
||||
ctx := context.Background()
|
||||
db, err := sqlx.ConnectContext(ctx, cfg.Database.Driver, dataSourceName)
|
||||
if err != nil {
|
||||
log.Fatal("连接 PostgreSQL 失败，请检查连接配置、认证和网络")
|
||||
}
|
||||
defer db.Close()
|
||||
|
||||
deps := buildDependencies(cfg, db)
|
||||
handlers := buildHandlers(deps)
|
||||
router.RegisterRoutes(ginEngine, handlers)
|
||||
addr := fmt.Sprintf("%s:%d", cfg.HTTP.Host, cfg.HTTP.Port)
|
||||
if err := ginEngine.Run(addr); err != nil {
|
||||
log.Fatal("启动 HTTP 服务失败，请检查端口是否被占用")
|
||||
}
|
||||
fmt.Printf("%+v\n", cfg)
|
||||
// TODO: 组装依赖——建立 PostgreSQL 连接（internal/postgres）、注册路由（internal/router）。
|
||||
// TODO: 启动 HTTP 服务，并在退出时关闭连接、释放资源。
|
||||
}
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
version: "3.8"
|
||||
|
||||
services:
|
||||
postgres:
|
||||
image: abcfy2/zhparser:16-alpine
|
||||
container_name: lab-postgres
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
POSTGRES_DB: lab
|
||||
POSTGRES_USER: admin
|
||||
POSTGRES_PASSWORD: ${PG_PASSWORD}
|
||||
volumes:
|
||||
- ./data/postgres:/var/lib/postgresql/data
|
||||
# 测试环境不用刻意限制内存，让 Docker 自然调度即可
|
||||
networks:
|
||||
- net-db # 只加入数据库专用网络
|
||||
# 如果外部需要直连调试，可临时 expose 端口
|
||||
ports:
|
||||
- "127.0.0.1:5432:5432"
|
||||
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
container_name: lab-redis
|
||||
restart: unless-stopped
|
||||
# 测试环境保留持久化更省心，不用关闭
|
||||
command: redis-server --maxmemory 128mb --maxmemory-policy allkeys-lru
|
||||
volumes:
|
||||
- ./data/redis:/data
|
||||
networks:
|
||||
- net-db
|
||||
ports:
|
||||
- "127.0.0.1:6379:6379"
|
||||
|
||||
networks:
|
||||
net-db:
|
||||
external: true # 使用预先创建的外部网络
|
||||
@@ -1,88 +1,105 @@
|
||||
# Lyra 目标结构
|
||||
|
||||
日期：2026-10-16
|
||||
日期：2026-10-17
|
||||
|
||||
本文记录已确认的目标目录结构与职责边界，并与当前真实实现同步。目录树是**目标结构**，并非全部已存在：当前只有 `cmd/lyra/main.go`、`internal/config/config.go`、`internal/api/{code,response}.go`、`internal/httpx/response.go` 是 Go 代码；`internal/{handler,model,postgres,router,service}` 仅含 `AGENTS.md`（记录职责与依赖约束），暂不构成 Go 包。选型与讨论过程见 [plans/2026-10-16-lyra-architecture.md](plans/2026-10-16-lyra-architecture.md)。
|
||||
本文记录已确认的目标目录结构与职责边界，并与当前真实实现同步。目录树是**目标结构**，并非全部已存在：标注“待新增”的文件尚未创建；标注“占位”的目录（`internal/postgres`、`internal/service`）仅含 `AGENTS.md`（记录职责与依赖约束），暂不构成 Go 包。当前已有 Go 代码的是 `cmd/lyra` 与 `internal/{api,config,handler,httpx,model,router}`。仓库内另有本地 `.env.local`（已被 gitignore、不入库）等文件，不属于目标结构，不在此展开。选型与讨论过程见 [plans/2026-10-16-lyra-architecture.md](plans/2026-10-16-lyra-architecture.md)；handler/service 业务分包的调整记录见 [plans/2026-10-17-business-package-layout.md](plans/2026-10-17-business-package-layout.md)。
|
||||
|
||||
## 已确认技术栈
|
||||
|
||||
- 已引入：Gin v1.12.0（HTTP 路由）、Viper v1.21.0（配置读取，TOML）。`go.sum` 已由 Go 工具生成。
|
||||
- 目标选型（选型已确认，尚未作为代码依赖引入）：PostgreSQL、Squirrel + sqlx（pgx stdlib 驱动）、Goose（数据库迁移）。
|
||||
- 已引入并使用：Gin v1.12.0（HTTP 路由）、Viper v1.21.0（配置读取，TOML）、godotenv v1.5.1（启动时加载本地 `.env.local`）、sqlx v1.4.0 + Squirrel v1.5.4（查询构造与执行）、pgx v5.11.0 stdlib（PostgreSQL 驱动，由 sqlx 以 "pgx" 驱动名使用）。`go.sum` 已由 Go 工具生成。
|
||||
- Goose：迁移 SQL 已就位，以独立 goose CLI（v3.29.0）执行，Go 依赖尚未引入。
|
||||
- PostgreSQL 已在启动时连接；连接代码当前在入口 `main`，收拢到 `internal/postgres` 是目标结构。
|
||||
|
||||
## 当前进度
|
||||
|
||||
- 程序入口按相对工作目录的 `etc/config.toml` 加载配置（Viper，`mapstructure` 标签），打印结果后退出；不启动 HTTP 服务，也不连接数据库。
|
||||
- 已定义公共响应契约：`api.Response`（success/data/error）、`api.ErrorInfo`（code/message/debug）与错误码类型 `api.ErrorCode` 及其默认文案 `Message()`。
|
||||
- 已实现响应输出辅助 `httpx.OK`、`httpx.Fail`。
|
||||
- 尚未实现：业务逻辑、路由注册、数据库访问与迁移 SQL；配置校验、环境变量覆盖与默认值；`ErrorInfo.Debug` 的填充与按环境开关。日志方案未定。
|
||||
- 程序入口在 module 根目录以 `go run ./cmd/lyra` 启动，流程为：`godotenv.Load` 读取本地 `.env.local`（不覆盖已存在的进程环境变量）→ `config.Load` 读取相对当前工作目录的 `etc/lyra.toml`（Viper，`mapstructure` 标签）→ `gin.SetMode` → 以 `gin.Default()` 创建引擎并 `SetTrustedProxies(nil)` 关闭代理信任 → `sqlx.ConnectContext` 建立 PostgreSQL 连接（失败即退出，`defer db.Close()`）→ `buildDependencies`/`buildHandlers` 组装依赖 → `RegisterRoutes` → 监听配置的地址与端口。`.env.local` 与 `etc/lyra.toml` 均按当前工作目录解析，换目录执行会找不到。连接与查询当前未设置超时。
|
||||
- 已注册 `GET /test`：`internal/router/router.go` 的 `RegisterRoutes` 将其指向入口注入的 `router.Handlers.TestHandler`（`gin.HandlerFunc`，由 `handler.NewTestHandler(...).Hello()` 构造）。处理器调用 `model.CategoryModel.FindAll` 查询 `public.categories`——当前固定 `sort >= 1`、按 `sort`/`id` 排序、`limit 10`——经显式转换为本轮新增的 `api.CategoryResponse` 后由 `httpx.OK` 输出；查询出错经 `httpx.Fail` 返回 500 与 `api.CodeInternalError`。该接口用于验证 handler→model→数据库链路，不是完整业务 API。
|
||||
- `internal/model` 已落地：`Category` 结构（id/slug/title/sort）、`CategoryModel` 接口与 `defaultCategoryModel` 实现——Squirrel 构造 SQL（Dollar 占位符），sqlx `SelectContext` 执行与映射。
|
||||
- 已定义公共响应契约：`api.Response`（success/data/error）、`api.ErrorInfo`（code/message/debug）与错误码类型 `api.ErrorCode` 及其默认文案 `Message()`；响应输出辅助 `httpx.OK`、`httpx.Fail` 已实现并被 handler 使用。
|
||||
- 配置：`database.password` 绑定了环境变量 `PG_PASSWORD`（可经 `.env.local` 或进程环境提供），其余配置项暂不支持环境变量覆盖；没有校验与默认值。`Redis` 配置项已定义但暂无消费方。
|
||||
- 测试：路由注册有 httptest 回归测试，覆盖 `GET /test` 注入替身处理器的调用，以及未知路径/不支持方法返回 404；handler 有基于假 `CategoryModel` 的替身测试，覆盖 DTO 转换、空结果输出 `data:[]`、模型出错返回 500 且不泄漏内部错误信息、请求 context 透传。两类测试均不监听实际端口、不连接数据库，因此不证明真实 SQL 可用——连接真实数据库的端到端验证本轮未做。
|
||||
- 数据库迁移已就位：`migrations/00001_init.sql`（`set_updated_at()` 函数、users/categories/links 三张表、约束、注释、索引与触发器，建库内容与 [demo.sql](demo.sql) 一致），由手工 goose CLI（v3.29.0）执行，见 [../migrations/README.md](../migrations/README.md)。
|
||||
- 尚未实现：业务 service 层与完整业务 API；连接收拢到 `internal/postgres`（当前连接代码在入口 `main`）；Goose Go 依赖；配置校验与默认值；`ErrorInfo.Debug` 的填充与按环境开关；连接/查询超时。日志方案未定。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```text
|
||||
lyra/
|
||||
├── cmd/lyra/main.go # 启动、依赖组装、退出清理
|
||||
├── cmd/lyra/
|
||||
│ ├── main.go # 启动流程：加载 .env.local 与配置、连接数据库、组装依赖
|
||||
│ └── dependency.go # Dependencies 与 handler 组装
|
||||
├── internal/
|
||||
│ ├── api/ # HTTP 请求/响应 DTO、错误码与响应契约
|
||||
│ │ ├── response.go # Response/ErrorInfo 结构
|
||||
│ │ ├── code.go # ErrorCode 与错误码常量、默认文案
|
||||
│ │ ├── links.go # links 资源 DTO 示例（待新增）
|
||||
│ │ ├── categories.go # 待新增
|
||||
│ │ └── settings.go # 待新增
|
||||
│ ├── api/ # HTTP 请求/响应 DTO、错误码与响应契约（平铺，按资源分文件）
|
||||
│ │ ├── response.go # Response/ErrorInfo 结构
|
||||
│ │ ├── code.go # ErrorCode 与错误码常量、默认文案
|
||||
│ │ ├── category.go # CategoryResponse 分类响应 DTO
|
||||
│ │ ├── links.go # links 资源 DTO 示例（待新增）
|
||||
│ │ └── settings.go # 待新增
|
||||
│ ├── config/
|
||||
│ │ └── config.go # 配置定义与加载
|
||||
│ ├── postgres/
|
||||
│ │ └── postgres.go # 数据库连接（待新增）
|
||||
│ │ └── config.go # 配置定义与加载
|
||||
│ ├── postgres/ # 数据库连接的目标位置（占位：仅 AGENTS.md，连接暂在 cmd/lyra/main.go）
|
||||
│ ├── router/
|
||||
│ │ └── router.go # 路由注册、项目路径前缀（待新增）
|
||||
│ │ ├── router.go # 路由注册、项目路径前缀
|
||||
│ │ └── router_test.go # 路由 httptest 回归测试
|
||||
│ ├── handler/
|
||||
│ │ └── links.go # 参数绑定、DTO 转换、响应输出（待新增）
|
||||
│ ├── service/
|
||||
│ │ ├── links.go # 业务规则、事务协调（待新增）
|
||||
│ │ └── links_test.go # 测试与源文件同目录（待新增）
|
||||
│ │ ├── test.go # GET /test 处理：调用 model、显式 DTO 转换、响应输出
|
||||
│ │ ├── test_test.go # handler 替身测试
|
||||
│ │ ├── links.go # 参数绑定、DTO 转换、响应输出（待新增）
|
||||
│ │ └── polaris/ # 按明确业务分包的示例（待新增，不预建空包）
|
||||
│ ├── service/ # 业务规则、事务协调（占位：仅 AGENTS.md）
|
||||
│ │ ├── links.go # 业务规则、事务协调（待新增）
|
||||
│ │ ├── links_test.go # 测试与源文件同目录（待新增）
|
||||
│ │ └── polaris/ # 按明确业务分包的示例（待新增，不预建空包）
|
||||
│ ├── model/
|
||||
│ │ ├── link.go # Link 数据结构定义（待新增）
|
||||
│ │ ├── link_model.go # 数据访问对象：CRUD 与 SQL（待新增）
|
||||
│ │ └── link_model_test.go # 查询测试（待新增）
|
||||
│ │ ├── category.go # Category 结构、CategoryModel 接口与 Squirrel+sqlx 实现
|
||||
│ │ ├── link.go # Link 数据结构定义（待新增）
|
||||
│ │ ├── link_model.go # 数据访问对象：CRUD 与 SQL（待新增）
|
||||
│ │ └── link_model_test.go # 查询测试（待新增）
|
||||
│ └── httpx/
|
||||
│ └── response.go # 公共响应输出辅助（OK/Fail）
|
||||
│ └── response.go # 公共响应输出辅助（OK/Fail）
|
||||
├── etc/
|
||||
│ └── config.toml # 运行配置（App/HTTP）
|
||||
├── migrations/ # Goose SQL 迁移文件（暂无）
|
||||
│ └── lyra.toml # 运行配置（App/HTTP/Database/Redis）
|
||||
├── migrations/ # Goose SQL 迁移文件（00001_init.sql 初始迁移 + README）
|
||||
├── docs/
|
||||
│ ├── plans/
|
||||
│ └── architecture.md # 本文
|
||||
│ └── architecture.md # 本文
|
||||
├── README.md
|
||||
├── go.mod
|
||||
└── go.sum # 已生成
|
||||
└── go.sum # 已生成
|
||||
```
|
||||
|
||||
- 标注“待新增”的文件只是职责分布示例，随实现按需新增，不预建空文件或空目录；`internal/` 各目录均以 `AGENTS.md` 记录职责与依赖约束。
|
||||
- model 下的 `link*.go` 展示一个资源在各层的文件分布；分类、设置等资源按同样方式在 api/handler/service/model 新增对应文件。具体迁移文件名随首个迁移确定。
|
||||
- 标注“待新增”的文件只是职责分布示例，随实现按需新增，不预建空文件或空目录；`internal/` 各目录均以 `AGENTS.md` 记录职责与依赖约束（树中未逐一画出）。`internal/postgres`、`internal/service` 目前仅有 `AGENTS.md`，为占位目录，不构成 Go 包。
|
||||
- model 下的 `link*.go` 展示一个资源在各层的文件分布；分类资源已按此方式在 api/model 落地（`api/category.go`、`model/category.go`，handler 为链路验证用的 `test.go`），设置等资源按同样方式新增。首个迁移已落地为 `migrations/00001_init.sql`。
|
||||
- `handler/polaris/`、`service/polaris/` 仅示意业务分包的形态：实际分包与否随业务边界明确时决定，路由、api、model 不照搬同样的分包。
|
||||
|
||||
## 组织原则
|
||||
|
||||
- 不按业务项目建代码子目录（无 polaris 等项目目录）；项目通过 `/api/polaris` 等路由前缀区分，代码按技术职责分组，包内文件按资源划分。
|
||||
- 不保留 platform/modules 分类层；配置在 internal/config，连接在 internal/postgres，HTTP 辅助在 internal/httpx。
|
||||
- 简单接口不强制走完整三层，也不按每张表机械复制层级。
|
||||
- handler、service 可以按明确业务分包（如 `polaris/`），仅在业务边界清晰时新增；服务级简单接口（如 `hello`）保留在各自根包内平铺，不强制分包。
|
||||
- router、api、model 等其他层暂时平铺，不按业务项目建代码子目录；项目通过 `/api/polaris` 等路由前缀区分，包内文件按资源划分。
|
||||
- 公共基础能力全局唯一：配置在 internal/config，连接在 internal/postgres，HTTP 辅助在 internal/httpx，不随业务项目复制或按项目再拆。
|
||||
- 不保留 platform/modules 分类层；简单接口不强制走完整三层，也不按每张表机械复制层级。
|
||||
- 不预建空业务包，分包随实际业务代码一起落地。
|
||||
|
||||
## 层间边界
|
||||
|
||||
- 主调用链为 handler→service→model→PostgreSQL；service 负责业务规则及需要的事务协调，model 支持同一事务内的数据库操作，不将跨多次写入各自独立提交当成原子业务。
|
||||
- 请求/响应 DTO 集中在 internal/api，与内部模型分开；即使初期字段相近，也不默认把数据库模型直接暴露为响应，接受必要的显式转换代码。
|
||||
- 真实业务的主调用链为 handler→service→model→PostgreSQL；简单接口可以不经过 service——当前 `GET /test` 即由 handler 直接调用 model（service 层尚未实现）。service 负责业务规则及需要的事务协调，model 支持同一事务内的数据库操作，不将跨多次写入各自独立提交当成原子业务。
|
||||
- 请求/响应 DTO 集中在 internal/api，与内部模型分开；即使初期字段相近，也不默认把数据库模型直接暴露为响应，接受必要的显式转换代码（分类列表已经 handler 的 `toCategoryResponses` 转为 `api.CategoryResponse`）。
|
||||
- handler 引用 API DTO 完成绑定与转换；service/model 不依赖 Gin，也不依赖 internal/api DTO；api 包不反向引用 handler/service/model，避免传输契约与实现耦合或循环引用。
|
||||
- internal/api 拥有响应契约与业务错误码（`Response`/`ErrorInfo`/`ErrorCode`）；不依赖 Gin。
|
||||
- internal/httpx 负责响应输出：`OK` 固定 HTTP 200；`Fail` 接收 HTTP 状态码与业务错误码，`message` 为空时回退错误码默认文案。HTTP 状态码表示传输/结果类别，`ErrorCode` 表示自定义业务错误，两者分开。
|
||||
- 配置由入口 `main` 加载后组装并传递（约定/目标）：`internal/config` 只负责配置定义与加载，运行配置来自 `etc/config.toml`；当前 `main` 仅加载并打印，尚未向其他组件传递。
|
||||
- model 承载数据结构定义与数据访问：Squirrel/SQL 构造、sqlx 执行与结果映射，驱动为 pgx stdlib；不是 ORM 自动持久化，也不要求每种类型机械建立一套结构。
|
||||
- internal/router 负责把 handler 挂到路由上：当前注册 `GET /test`，指向入口组装注入的 `Handlers.TestHandler`，后续按业务项目路径前缀（如 `/api/polaris`）扩展。
|
||||
- 配置由入口 `main` 加载后组装并传递：`internal/config` 只负责配置定义与加载，运行配置来自 `etc/lyra.toml`；当前 `app.env` 直接传给 `gin.SetMode`（仅 `debug`/`release`/`test`），HTTP 地址端口供启动使用，数据库相关配置由入口 `main` 组装 DSN 并用于连接（`database.password` 可来自 `PG_PASSWORD`），`Redis` 配置暂无消费方。
|
||||
- model 承载数据结构定义与数据访问：Squirrel/SQL 构造、sqlx 执行与结果映射，驱动为 pgx stdlib（已按此落地 `internal/model/category.go`）；不是 ORM 自动持久化，也不要求每种类型机械建立一套结构。
|
||||
- service/model 使用标准 context.Context，不接收 gin.Context。
|
||||
|
||||
## 尚未确定 / 待实现
|
||||
|
||||
以下均为计划中的推荐或待确认项，尚未实现，也未定为已决：
|
||||
|
||||
- 配置校验、环境变量覆盖与默认值：尚未实现（当前无任何校验、覆盖或默认值）。
|
||||
- 配置校验与默认值：尚未实现。环境变量覆盖当前仅 `database.password` 绑定 `PG_PASSWORD`，其余配置项不支持。
|
||||
- 连接与查询超时：尚未设置，也未确定超时策略。
|
||||
- `ErrorInfo.Debug` 的填充与按环境（dev）开关：尚未实现，目前仅有字段。
|
||||
- 分页响应约定（如 data/meta 结构）与统一错误处理中间件：尚未引入，仅为历史讨论。
|
||||
- Goose 的部署执行入口与并发控制（串行执行或数据库锁）方案。
|
||||
- Goose 迁移的部署执行入口已确定为手工 CLI（见 [../migrations/README.md](../migrations/README.md)），并发控制以“单操作者串行执行”为约定，数据库锁未引入，服务启动不自动迁移。
|
||||
- PostgreSQL 按项目划分 schema 的做法（组织边界，不等于权限隔离）。
|
||||
- 日志方案（候选标准库 slog）与中间件集成方式。
|
||||
|
||||
@@ -71,16 +71,12 @@ CREATE TABLE public.links (
|
||||
pinned_sort integer,
|
||||
created_at timestamptz NOT NULL DEFAULT now(),
|
||||
updated_at timestamptz NOT NULL DEFAULT now(),
|
||||
CONSTRAINT links_category_fk
|
||||
FOREIGN KEY (category_id) REFERENCES public.categories (id)
|
||||
ON DELETE RESTRICT,
|
||||
CONSTRAINT links_category_fk FOREIGN KEY (category_id) REFERENCES public.categories (id) ON DELETE RESTRICT,
|
||||
CONSTRAINT links_title_not_empty CHECK (btrim(title) <> ''),
|
||||
CONSTRAINT links_url_not_empty CHECK (btrim(url) <> ''),
|
||||
CONSTRAINT links_pinned_sort_consistent CHECK (pinned = (pinned_sort IS NOT NULL)),
|
||||
CONSTRAINT links_keywords_one_dimension
|
||||
CHECK (cardinality(keywords) = 0 OR array_ndims(keywords) = 1),
|
||||
CONSTRAINT links_keywords_no_null_elements
|
||||
CHECK (array_position(keywords, NULL) IS NULL)
|
||||
CONSTRAINT links_keywords_one_dimension CHECK (cardinality(keywords) = 0 OR array_ndims(keywords) = 1),
|
||||
CONSTRAINT links_keywords_no_null_elements CHECK (array_position(keywords, NULL) IS NULL)
|
||||
);
|
||||
|
||||
COMMENT ON TABLE public.links IS '链接表，归属分类';
|
||||
|
||||
@@ -0,0 +1,179 @@
|
||||
# Goose 迁移操作手册
|
||||
|
||||
Lyra 数据库迁移的**唯一完整操作手册**。`migrations/` 目录是数据库结构的
|
||||
唯一正式执行来源；[demo.sql](demo.sql) 仅保留作参考，不要再手工执行它。
|
||||
迁移目录本身的说明见 [migrations/README.md](../migrations/README.md)。
|
||||
|
||||
## 目录与前提
|
||||
|
||||
- 所有 goose 命令都在 Lyra module 根目录（`migrations/` 的上一级）执行：
|
||||
|
||||
```bash
|
||||
cd go/projects/lyra # 从仓库根出发
|
||||
```
|
||||
|
||||
- 目标数据库**已创建**：迁移不负责建库，`lab` 库需先存在。
|
||||
- 首次迁移要求目标对象**尚不存在**：如果之前手工执行过 demo.sql 建过
|
||||
同名对象，`up` 会报 `already exists`，先按故障表评估处理。
|
||||
|
||||
## 安装 goose CLI（固定 v3.29.0）
|
||||
|
||||
goose 只作为独立命令行工具使用（Go 应用尚未引入 goose 依赖）：
|
||||
|
||||
```bash
|
||||
go install -tags='no_clickhouse no_libsql no_mssql no_mysql no_sqlite3 no_vertica no_ydb' github.com/pressly/goose/v3/cmd/goose@v3.29.0
|
||||
goose -version # 应输出 v3.29.0
|
||||
```
|
||||
|
||||
- 固定 `@v3.29.0`，保证各机器行为一致。
|
||||
- `-tags=...` 是可选的 PostgreSQL 专用精简构建（`no_*` 标签已在 goose
|
||||
v3.29.0 源码中核实）；不追求精简可省略。
|
||||
- 二进制装到 `$(go env GOPATH)/bin`（设了 `GOBIN` 则装到 `GOBIN`）。
|
||||
`goose -version` 提示找不到命令时，把该目录加入 `PATH`：
|
||||
|
||||
```bash
|
||||
export PATH="$PATH:$(go env GOPATH)/bin" # 可写入 ~/.bashrc
|
||||
```
|
||||
|
||||
## 配置连接：.env.local
|
||||
|
||||
goose **不读取**应用的 `etc/lyra.toml`，也不会只凭 `PG_PASSWORD` 之类的
|
||||
应用环境变量自动拼出连接串——它只认自己环境变量里的 `GOOSE_DBSTRING`。
|
||||
在 module 根创建 `.env.local` 并追加以下内容（**全部是占位值**，换成实际
|
||||
信息；`lab` 库需已创建）：
|
||||
|
||||
```bash
|
||||
GOOSE_DRIVER=postgres
|
||||
GOOSE_MIGRATION_DIR=./migrations
|
||||
GOOSE_DBSTRING="postgres://example_user:URL_ENCODED_PASSWORD@127.0.0.1:5432/lab?sslmode=disable"
|
||||
```
|
||||
|
||||
要点：
|
||||
|
||||
- `GOOSE_DRIVER=postgres` 是 **goose 的驱动名**；Go 应用内用的是 pgx
|
||||
（驱动名 `pgx`），两边名字不同但都连 PostgreSQL，不要混填。
|
||||
- 本仓库 `.gitignore` 已忽略 `.env*`，`.env.local` 不会提交；建议再执行
|
||||
`chmod 600 .env.local` 收紧文件权限。
|
||||
- `127.0.0.1` 与端口必须换成**实际可达**的地址和端口（远程/容器按实际
|
||||
映射填写）。
|
||||
- `sslmode=disable` 仅适用于本地确认无 TLS 要求的场景；远程环境按部署的
|
||||
TLS 要求调整该参数。
|
||||
- 本手册所有 goose 命令统一用 `-env=.env.local` 显式加载该文件：goose
|
||||
默认读的是 `.env`，`-env=.env.local` 既明确来源、又避免误用其他本地
|
||||
配置。连接信息配置一次即可，无需每次交互输入密码。
|
||||
- 系统环境里已有的同名变量（如曾 `export` 过 `GOOSE_DBSTRING`）可能优先
|
||||
于 `.env.local` 生效：改了 `.env.local` 仍行为异常时，先查是否存在同名
|
||||
环境变量——只列变量名、不打印值，避免泄露连接串：
|
||||
|
||||
```bash
|
||||
env | cut -d= -f1 | grep -i '^GOOSE'
|
||||
```
|
||||
|
||||
## 连接串特殊字符：URL 编码
|
||||
|
||||
`GOOSE_DBSTRING` 是 URL 格式：**用户名、密码**中的特殊字符必须逐个做
|
||||
百分号编码，否则主机名/路径解析会错位。
|
||||
|
||||
- 对用户名和密码分别编码，**不要把整串 URL 一起编码**，也不要为迁就 DSN
|
||||
去修改数据库里的实际密码。避免对已经编码的内容重复编码。
|
||||
- 不要把真实密码交给在线网站转换；按下表手工替换即可。
|
||||
|
||||
| 字符 | 编码 | 字符 | 编码 |
|
||||
|---|---|---|---|
|
||||
| `@` | `%40` | `:` | `%3A` |
|
||||
| `#` | `%23` | `/` | `%2F` |
|
||||
| `%` | `%25` | `?` | `%3F` |
|
||||
|
||||
示例：密码 `demo#pass`（演示值）在 DSN 中写成 `demo%23pass`。
|
||||
|
||||
## 常用命令
|
||||
|
||||
```bash
|
||||
# 离线检查迁移文件能否被 goose 解析（注解与语句拆分）；
|
||||
# 不连接数据库，也不验证 SQL 在 PostgreSQL 上的语义
|
||||
goose -env=.env.local validate
|
||||
|
||||
# goose 工具自身版本（与数据库里的迁移版本是两回事）
|
||||
goose -version
|
||||
|
||||
# 连接数据库：查看迁移状态 / 当前版本
|
||||
goose -env=.env.local status
|
||||
goose -env=.env.local version
|
||||
|
||||
# 执行迁移（连接数据库）
|
||||
goose -env=.env.local up
|
||||
```
|
||||
|
||||
注意：v3.29.0 的 `validate` **不接受位置路径参数**，迁移目录只由
|
||||
`GOOSE_MIGRATION_DIR`（`.env.local` 已设 `./migrations`）或 `-dir` 标志
|
||||
决定。`validate` 通过只证明文件能解析，不证明连接正常或 SQL 语义正确。
|
||||
|
||||
## 首次初始化
|
||||
|
||||
前提：`lab` 库已创建，且 00001 中的对象（函数、三张表、索引、触发器）
|
||||
都不存在——**不要**先手工执行 demo.sql 再 `up`。
|
||||
|
||||
```bash
|
||||
goose -env=.env.local validate # 离线确认文件可解析
|
||||
goose -env=.env.local status # 显示 00001 Pending：连接成功，该迁移尚未应用
|
||||
goose -env=.env.local up # 执行 00001，并在 goose_db_version 中记录版本：
|
||||
# set_updated_at() 函数、users/categories/links 三张表、
|
||||
# 约束、注释、索引与触发器
|
||||
goose -env=.env.local status # 00001 显示应用时间
|
||||
goose -env=.env.local version # 显示 version 1
|
||||
```
|
||||
|
||||
- `up` 可重复执行：已应用版本按 `goose_db_version` 自动跳过。
|
||||
- **已执行过的迁移文件不再修改**；要变更结构就新增迁移文件（见下节）。
|
||||
|
||||
## 日常新增迁移
|
||||
|
||||
```bash
|
||||
goose -env=.env.local -s create add_example_column sql
|
||||
```
|
||||
|
||||
`-s` 表示顺序编号：在现有 00001 基础上生成
|
||||
`migrations/00002_add_example_column.sql`（实际编号按目录中现有最大版本
|
||||
延续）。例如给 users 表加一列，编辑生成的文件：
|
||||
|
||||
```sql
|
||||
-- +goose Up
|
||||
ALTER TABLE public.users
|
||||
ADD COLUMN avatar_url text NOT NULL DEFAULT '';
|
||||
|
||||
-- +goose Down
|
||||
ALTER TABLE public.users
|
||||
DROP COLUMN avatar_url;
|
||||
```
|
||||
|
||||
然后按顺序执行：
|
||||
|
||||
```bash
|
||||
goose -env=.env.local validate
|
||||
goose -env=.env.local status
|
||||
goose -env=.env.local up
|
||||
goose -env=.env.local status
|
||||
```
|
||||
|
||||
Up/Down 成对编写，保证迁移可回滚。
|
||||
|
||||
## 回滚警告
|
||||
|
||||
```bash
|
||||
goose -env=.env.local down # ⚠ 危险操作，见下
|
||||
```
|
||||
|
||||
- `down` 只回滚**最近一个**已应用迁移的 Down 部分，**不是**清库或重建的
|
||||
通用命令。
|
||||
- **回滚 00001 会删除 `links`/`categories`/`users` 三张表及表中全部数据。**
|
||||
- 执行任何 `down` 之前：阅读对应迁移 SQL、评估数据损失、备份数据库。
|
||||
不建议随手“试一下” `down`，也不要把它列入日常维护流程。
|
||||
|
||||
## 故障速查
|
||||
|
||||
| 报错特征 | 常见原因与处理 |
|
||||
|---|---|
|
||||
| `hostname resolving error`（主机名里混入非法字符） | DBSTRING 格式或 URL 编码不对：检查用户名/密码特殊字符是否已按上表编码、`://` 与 `@` `:` 分隔符是否完整 |
|
||||
| `password authentication failed` | 用户名或密码不对：核对 `.env.local`（编码后）的值；再排查系统环境同名变量是否优先生效（只查变量名，不打印值） |
|
||||
| `connection refused` / `i/o timeout` | 主机端口不可达：确认 PostgreSQL 实际监听地址、端口、容器端口映射与防火墙 |
|
||||
| `already exists`（对象已存在） | 目标对象曾被手工创建（如执行过 demo.sql）：先评估现有对象与迁移的差异再决定处理方式；**不要直接删数据**，也不要手工往 `goose_db_version` 插版本记录伪造状态 |
|
||||
@@ -0,0 +1,42 @@
|
||||
# 架构审查与提交前收尾
|
||||
|
||||
日期：2026-10-17
|
||||
|
||||
状态：审查及已批准修正完成，父会话已复查代码与文档；等待更新暂存区及确认提交信息。
|
||||
|
||||
## 当前结论
|
||||
|
||||
- 当前实际调用链为 main → buildDependencies → buildHandlers → router 的 GET /test → TestHandler.Hello → CategoryModel.FindAll → PostgreSQL。
|
||||
- 显式注入、入口容器边界、model 接口和路由依赖方向成立；当前单条只读查询不需要额外 service 或事务框架。
|
||||
- 审查发现的 DTO 边界与当前状态文档问题已修正：handler 显式转换为 api.CategoryResponse，README 与架构文档已同步。
|
||||
- 超时、DSN 编码、优雅关闭和查询语义命名列为后续增强，不扩入本轮修正。
|
||||
|
||||
## 已批准的最小方案
|
||||
|
||||
1. 增加分类响应 DTO，以明确 JSON 字段，由现有 TestHandler 显式转换；空列表保持 []，不改变 SQL。
|
||||
2. 用假的 CategoryModel 补 handler 测试，覆盖成功、空列表、失败和 context 传递，不连接数据库。
|
||||
3. 更新 README.md 和 docs/architecture.md 的当前实现说明，历史计划保留为历史。
|
||||
4. 最终执行格式检查、go test ./... -count=1、go build ./...、go vet ./...，父会话审阅最终差异。
|
||||
5. 依 git-commit 流程确认暂存范围；任何重新暂存后重新检查全部索引文件的完整内容，再展示提交信息并等待明确确认。
|
||||
|
||||
## 实施分工与范围
|
||||
|
||||
- 代码 lane（复用 fixer）：仅写 internal/api/category.go、internal/handler/test.go、internal/handler/test_test.go，负责 DTO 转换与成功/空结果/失败/context 测试及 Go 验证。
|
||||
- 文档 lane（独立 fixer）：仅写 README.md、docs/architecture.md，按当前磁盘源代码更新现状；不得声称真实数据库查询已验证。
|
||||
- 父会话维护本计划、整合终态并检查实际差异；不修改 SQL、路由名称、连接逻辑、依赖版本或其他历史计划。
|
||||
- 两个写入范围互不重叠；全部终态后确认验证证据仍适用，再进入重新暂存与完整索引安全检查。
|
||||
|
||||
## 已有验证及边界
|
||||
|
||||
- 当前未修正版本的 go test ./... -count=1、go build ./...、go vet ./...、gofmt -l . 全部通过。
|
||||
- 当前路由测试不连接数据库，仅验证路由分发；真实 handler 与 SQL 查询尚未验证。
|
||||
- 当前暂存的十个非删除文件完整内容已检查，未发现新增疑似真实敏感值或意外生成物；未暂存新的修正内容。
|
||||
- 审查所有者：oracle 静态审查、fixer 独立验证、父会话负责取舍及提交安全检查。
|
||||
|
||||
## 修正后的证据
|
||||
|
||||
- 新增分类响应 DTO 和 handler 替身测试；成功映射、空切片与 nil 结果输出 []、失败返回通用 500、请求 context 透传均已验证。
|
||||
- 代码 lane 在最终 Go 代码上执行 go test ./internal/handler -v -count=1、go test ./... -count=1、go build ./...、go vet ./... 均通过，新增及修改 Go 文件的格式检查通过。
|
||||
- 文档 lane 仅修改 README.md 与 docs/architecture.md；父会话已读取 DTO、handler、测试与两份文档并复查，未发现新的阻断问题。
|
||||
- 不重复运行未发生变化的 Go 代码验证；真实 SQL 与数据库端到端路径仍未验证。
|
||||
- 更新暂存区后必须重新检查全部暂存文件的完整版本，之前索引安全检查不自动适用于新内容。
|
||||
@@ -0,0 +1,30 @@
|
||||
# Handler 与 Service 的业务分包调整
|
||||
|
||||
## 已确认范围
|
||||
|
||||
- handler、service 可以按明确业务分包；服务级简单接口保留在根包。
|
||||
- 将 `/hello` 从 `internal/handler/lyra` 移至 `internal/handler`，同步路由引用；入口路由文件使用 `router.go`。
|
||||
- router、api、model 等其他层暂时保持平铺，公共基础能力不随业务重复拆分。
|
||||
- 不预建空业务包，不改变 `/hello` 路径、响应契约或配置环境语义，不顺带改变启动错误处理。
|
||||
- 同步架构文档、README、相关目录约定与过时的入口注释；历史方案保留为历史记录。
|
||||
|
||||
## 工作分工与顺序
|
||||
|
||||
1. 代码执行 lane：负责 handler 移动、router 引用和文件名、入口过时注释，以及路由回归测试。
|
||||
2. 文档执行 lane：并行负责 architecture.md、README.md、必要的目录 AGENTS.md，解释业务分包与当前实现状态。
|
||||
3. 父代理：整合两条 lane 的结果，审查最终差异并登记验证结论。
|
||||
|
||||
## 验证路径与归属
|
||||
|
||||
- 代码 lane：新增或利用 `httptest` 路由测试，不监听实际端口、不连接数据库，确认 `GET /hello` 返回 HTTP 200 且维持现有响应契约。
|
||||
- 父代理：在 Lyra module 根执行 `go test ./...`、`go vet ./...`，确认移动后的包引用与编译正确；若执行 lane 已完成同等检查且最终代码未变则复用证据。
|
||||
- 文档 lane：核对当前配置文件名、HTTP 启动状态与目录组织说明，不把未来规划写成已实现能力。
|
||||
- 父代理：检查最终 diff、旧包路径残留和敏感信息风险，保留用户既有未提交改动。
|
||||
|
||||
## 状态
|
||||
|
||||
- 代码与文档 lane 均已完成，最终差异已审查。
|
||||
- `/hello` 已移至 handler 根包，路由引用已更新；未创建空业务包。
|
||||
- 架构文档、README 与 handler/service/router 的目录约定已同步。
|
||||
- 验证通过：`go test ./...`、`go vet ./...`、`git diff --check`；路由测试确认 HTTP 200 与原有 JSON 响应一致。
|
||||
- 验证未监听实际端口、未连接数据库；保留工作区既有配置与其他用户改动。
|
||||
@@ -0,0 +1,71 @@
|
||||
# Goose 初始迁移
|
||||
|
||||
日期：2026-10-17
|
||||
|
||||
## 目标与范围
|
||||
|
||||
用户已同意创建首个 Goose 迁移并提供后续自行管理的说明。以当前工作区的
|
||||
`docs/demo.sql` 为来源，保留已有未提交改动，不修改其表结构设计。
|
||||
本次不连接或修改用户数据库，不把迁移嵌入服务启动，也不修改 Go 应用依赖。
|
||||
|
||||
## 实施步骤
|
||||
|
||||
1. 核对 Goose 官方 SQL 注解、事务行为及 CLI 命令。
|
||||
2. 新建 `migrations/00001_init.sql`，Up 保留示例中的函数、三张表、约束、
|
||||
注释、索引与触发器；去掉外层事务，以 StatementBegin/StatementEnd
|
||||
包裹 PL/pgSQL 函数。Down 按依赖逆序删除表，最后删除函数，不使用 CASCADE。
|
||||
3. 更新 `migrations/README.md`，说明 CLI 使用、连接信息的安全提供、首次
|
||||
初始化、状态检查、后续迁移及回滚风险。采用固定 CLI 版本 v3.29.0，命令在 Lyra
|
||||
module 根执行；数据库必须已创建，首个迁移要求目标对象尚不存在。
|
||||
4. 同步项目 README 与架构文档的迁移进度。`docs/demo.sql` 保留为参考，
|
||||
正式迁移以 migrations 为准，避免双重执行。
|
||||
|
||||
## 工作分工与验证
|
||||
|
||||
- librarian：只读核对官方规则与 CLI 能力。
|
||||
- fixer：仅负责首个 SQL 迁移及上述三个说明文档；不修改其他代码或配置，
|
||||
不运行任何连接数据库的命令。
|
||||
- 父会话：维护计划、检查最终 diff 与文案，确认无意外改动及敏感信息。
|
||||
- fixer 验证：静态对比 Up 与当前 demo 的 SQL 内容，检查 Down 依赖顺序；
|
||||
使用 v3.29.0 的 `goose -env=none -dir ./migrations validate` 检查文件解析，
|
||||
此命令不连接数据库。校验用工具仅构建到 `/tmp/opencode`，不修改应用依赖。
|
||||
- 不为仅 SQL/文档变更重复运行无关 Go HTTP 测试。不宣称数据库集成验证通过；
|
||||
未在 PostgreSQL 实际执行的限制在交付时明确说明。
|
||||
|
||||
## 已核对的规则
|
||||
|
||||
- 官方 v3.29.0：Up/Down 默认使用事务；函数体需 StatementBegin/StatementEnd。
|
||||
- 后续新建迁移使用 `goose -s create <名称> sql`，延续顺序编号。
|
||||
- CLI 默认读取 `.env`；说明中的命令统一加 `-env=none`，显式使用环境变量，
|
||||
避免误用本地配置。`-version` 为工具版本，`version` 为数据库版本。
|
||||
- 官方来源：https://pressly.github.io/goose/documentation/annotations/
|
||||
与 https://github.com/pressly/goose/releases/tag/v3.29.0。
|
||||
|
||||
## 实施与验收记录
|
||||
|
||||
- 已完成初始迁移与使用文档；父会话已检查 SQL 与相关文档差异。
|
||||
- 实测修正：v3.29.0 的 validate 不使用位置参数，必须通过 `-dir` 或
|
||||
`GOOSE_MIGRATION_DIR` 选择目录；已按实际行为编写说明。
|
||||
- fixer 已构建 v3.29.0 PostgreSQL 专用 CLI 至 `/tmp/opencode/lyra-goose-bin`，
|
||||
离线解析得到 Up=40、Down=4；与 demo 的 Up 内容逐行对比完全一致。
|
||||
- 后续编号 00002 已在临时目录验证；没有修改应用依赖或连接数据库。
|
||||
- 最终文案校正：目标库为空是执行前提，不当作已验证事实；普通 down 是否
|
||||
丢数据取决于迁移内容，00001 的 Down 则确定会删除三张表及其数据。
|
||||
- `git diff --check` 通过。PostgreSQL 上的实际执行尚未验证。
|
||||
|
||||
## 后续：整理日常操作手册
|
||||
|
||||
用户已要求将实际操作步骤写入 Lyra docs。以下为新增文档任务，不改已有迁移。
|
||||
|
||||
1. 新建 `docs/goose.md`，作为唯一完整操作手册：固定版本安装、项目根目录、
|
||||
`.env.local` 配置、密码 URL 编码、validate/status/up/version、后续新增迁移、
|
||||
回滚警告与常见故障。所有数据库操作命令使用 `-env=.env.local`。
|
||||
2. 将 `migrations/README.md` 收敛为迁移目录说明和手册链接，移除旧的交互输入
|
||||
密码流程，避免两份操作步骤不一致；项目 README 增加手册入口。
|
||||
3. 仅使用演示占位值，不读取 .env.local、真实连接配置或既有错误中的疑似凭据。
|
||||
不运行服务、不连接数据库、不更改 SQL、依赖和配置，也不暂存用户改动。
|
||||
4. fixer 负责上述三个文档和静态链接/命令一致性检查；父会话负责最终差异与
|
||||
文案审查。已有 CLI 验证证据复用，不为文档改动重复构建或执行数据库命令。
|
||||
|
||||
说明：用户已确认 status 成功并显示 00001 Pending；这是连接及迁移发现成功的
|
||||
证据，不足以宣称 Up 或 Down 已完成数据库集成验证。
|
||||
@@ -0,0 +1,32 @@
|
||||
# PostgreSQL 启动连接检查
|
||||
|
||||
日期：2026-10-17
|
||||
|
||||
## 已批准目标
|
||||
|
||||
用户要求在 main.go 中通过 sqlx 查询数据库信息，检查尚无业务表的数据库连接。
|
||||
查询只读取 current_database()、current_user、version()，不依赖业务表，不执行 DDL。
|
||||
|
||||
## 实施范围
|
||||
|
||||
1. 保留当前工作区所有用户改动，仅在 cmd/lyra/main.go 中注册项目已选定的
|
||||
pgx stdlib 驱动，使用带超时的连接及 GetContext 查询，输出数据库信息。
|
||||
2. 通过 go.mod/go.sum 加入 pgx/v5/stdlib 所需依赖；etc/lyra.toml 仅将
|
||||
driver 的 postgres 改为 pgx，与驱动注册名保持一致，不读出或改动敏感配置。
|
||||
3. 补充数据库连接关闭；不重构配置加载、不实现 dotenv、不涉及 Goose 或业务表。
|
||||
|
||||
## 分工与证据路径
|
||||
|
||||
- fixer：写入范围限定 main.go、go.mod、go.sum、TOML 的 driver 一行；
|
||||
首次修改检查缩进和换行，保留已有修改。负责 gofmt、go test ./... 与构建验证。
|
||||
- 父会话：检查新增查询、超时、驱动名与范围，检查无明文凭据及意外文件改动。
|
||||
- 不打印配置文件完整内容或完整 DSN；不读取 .env.local 或 compose 中的敏感值。
|
||||
- 不运行服务、不连接真实数据库；编译/测试只证明查询代码可编译和现有测试通过，
|
||||
实际连接是否成功由用户本地启动后观察查询输出确认。
|
||||
|
||||
## 验收
|
||||
|
||||
- 已加入 pgx/v5 v5.11.0 驱动、五秒超时连接与系统信息查询，保留 HTTP 通路。
|
||||
- fixer 执行 `go build ./...`、`go test ./...` 均通过，未连接真实数据库。
|
||||
- 最终安全校正：连接与查询失败时只记录固定的阶段提示，不直接输出驱动原始
|
||||
错误，避免连接串解析错误意外携带敏感配置。
|
||||
@@ -0,0 +1,19 @@
|
||||
# 重写当前路由回归测试
|
||||
|
||||
日期：2026-10-17
|
||||
|
||||
## 已批准范围
|
||||
|
||||
用户要求重写 router_test。当前路由为 GET /test，注册入口接收 router.Handlers，其中 TestHandler 为 gin.HandlerFunc。
|
||||
|
||||
- 仅新增或重写 internal/router/router_test.go，不修改生产代码、依赖或用户已调整的模型字段。
|
||||
- 测试使用 package router_test、gin.New、httptest 和注入的替身 handler，不启动端口、不访问数据库。
|
||||
- 覆盖 GET /test 调用注入处理器，并保留处理器自定义的状态码和响应体。
|
||||
- 覆盖未知路径和不支持的方法均不调用处理器；使用 gin.New 默认设置，两者预期 404。
|
||||
- 每个用例创建独立引擎；不使用 t.Parallel，避免 Gin 全局模式设置竞争。
|
||||
|
||||
## 验证所有者与证据
|
||||
|
||||
- fixer：只写测试文件，gofmt，执行 go test ./internal/router -v -count=1 与 go test ./...。
|
||||
- 父会话：检查最终差异、替身调用次数断言、当前路由名以及无数据库依赖。
|
||||
- 本轮证据仅覆盖路由注册与分发，不覆盖真实 TestHandler 或数据库查询。
|
||||
@@ -0,0 +1,66 @@
|
||||
# Squirrel + sqlx 最小查询练习
|
||||
|
||||
日期：2026-10-17
|
||||
|
||||
## 范围与状态
|
||||
|
||||
- 前期由用户自行实现；2026-10-17 用户明确批准代改依赖组装示例。本轮仍不启动服务、不连接数据库。
|
||||
- 使用隔离的本地 PostgreSQL 测试库，不复用真实或共享环境。
|
||||
- 当前范围调整：用户先在已有 /hello handler 中手动验证查询；下方 categories 集成测试步骤保留为后续练习。
|
||||
- 临时在 handler 中只读查询 current_database()，不依赖业务表；正式业务查询再迁至 model。
|
||||
|
||||
## 当前 Hello 实验
|
||||
|
||||
### 本轮已批准实施：集中依赖组装
|
||||
|
||||
- 以用户现有代码为准：Hello 已通过 CategoryModel.FindAll 查询分类，保留该 SQL、过滤条件和结果映射，不改成系统信息查询。
|
||||
- 新增 cmd/lyra/dependencies.go，buildHandlers(db) 返回 router.Handlers，当前只装配 Hello(db)。
|
||||
- router.go 定义仅包含 Hello gin.HandlerFunc 的 Handlers，RegisterRoutes 接收它，不再导入 handler 或 sqlx。
|
||||
- main.go 仅把路由注册改为先 buildHandlers(db)，再 RegisterRoutes；保留配置、连接和其他用户改动。
|
||||
- Hello 保持 Hello(db) 闭包接口，在返回闭包前创建 CategoryModel，避免每个请求重新构造；修复先返回问候再返回列表的重复响应，错误分支返回 HTTP 500 后立即 return。
|
||||
- 路由测试注入固定响应的替身 handler，验证 /hello 确实调用传入的处理器并维持现有响应契约，不触碰数据库。
|
||||
- 写入范围：cmd/lyra/main.go、cmd/lyra/dependencies.go、internal/router/router.go、internal/router/router_test.go、internal/handler/hello.go；不改 model、依赖文件或敏感配置。
|
||||
- fixer 负责首次编辑前确认缩进与换行、gofmt、go test ./... 和 go build ./...；父会话负责审阅最终差异、依赖方向和用户改动保留情况。
|
||||
- 验证边界：httptest 证明路由注入生效，构建证明组装链编译通过；不宣称真实数据库查询已验证。
|
||||
|
||||
实施结果：上述五个 Go 文件已完成调整。fixer 执行 gofmt、go test ./...、go build ./...、go vet ./... 均通过；父会话已审阅实际差异与新增 dependencies.go，git diff --check 通过。未启动服务或连接数据库，真实查询及 Hello 成功/失败分支尚无运行时验证。用户已有 model/category.go 和依赖文件改动保持不变。
|
||||
|
||||
### 历史练习建议（由上方现状覆盖）
|
||||
|
||||
1. 沿用闭包：Hello(db *sqlx.DB) gin.HandlerFunc，捕获 main 已创建的连接池。
|
||||
2. router.RegisterRoutes 接收 gin.HandlerFunc，不依赖数据库；main 调用 handler.Hello(db) 完成组装。
|
||||
3. 每个请求从 Request.Context 派生五秒超时，使用 Squirrel 构造 SELECT current_database()，sqlx.GetContext 执行并映射字符串。
|
||||
4. 失败使用现有 httpx.Fail 与通用错误码，不返回数据库原始错误；成功使用 httpx.OK 返回当前数据库名。
|
||||
5. 路由测试注入返回固定响应的替身 handler，不连接数据库；保留现有路径、状态码和响应体断言。该测试不覆盖真实 Hello 查询逻辑。
|
||||
6. 用户在隔离本地环境运行服务并请求 /hello 验证真实查询；实验不要对外暴露数据库信息。
|
||||
|
||||
## 后续 categories 练习顺序
|
||||
|
||||
### 依赖组装组织建议（讨论记录，未代改代码）
|
||||
|
||||
- 继续使用显式构造函数注入，不引入 Wire、全局连接或通用依赖容器。
|
||||
- 组装代码可以放在 cmd/lyra/dependencies.go，仍属于 package main；main 只调用 buildHandlers(db) 并注册路由。
|
||||
- router 可定义只包含 gin.HandlerFunc 的 Handlers 结构，RegisterRoutes 接收该结构，避免路由增加导致参数列表不断增长。
|
||||
- 当前只需要 Hello 字段，其他路由随实际实现添加，不提前创建 model/service 等占位代码。
|
||||
- 后续组装顺序为 db → model → 按需 service → handler；每层只接收实际需要的依赖，不传递整个应用容器。
|
||||
- 该方式减少 main 的杂乱，但不消除新增组件时必须更新组装关系的工作；对象在启动时构造，请求复用连接池。
|
||||
- Dependencies 位置建议：当前若确需该结构，直接定义在 cmd/lyra/dependencies.go，不为单个类型新建包。以后多个入口确实需要复用组装逻辑时，再迁移到 internal/app；该包作为组装上层可引用 model/service/handler/router，业务包不得反向引用 app。当前不创建新目录或依赖容器。
|
||||
|
||||
1. 在 module 根目录引入 github.com/Masterminds/squirrel。
|
||||
2. 准备已执行现有迁移的隔离测试库；如需数据，用户单独准备至少一个分类，测试本身不写数据。
|
||||
3. 测试从 LYRA_TEST_DATABASE_URL 读取连接串；缺失时跳过，不回退到开发配置。
|
||||
4. 注册 pgx stdlib 驱动，创建五秒超时 Context，以 sqlx.ConnectContext 连接并清理连接。
|
||||
5. 定义带 db 标签的局部结果结构，使用 Squirrel 显式声明列、可选 sort 条件、sort/id 排序、有限条数和 Dollar 占位符。
|
||||
6. 调用 ToSql 获取 SQL 和 args，通过 db.SelectContext 执行并映射切片。
|
||||
7. 先验证 SQL/args，再验证真实查询；通过后再提取正式 model 方法。
|
||||
|
||||
## 验证与注意事项
|
||||
|
||||
- Go 命令在 go/projects/lyra 执行。
|
||||
- 查询构造测试应验证使用 $1 而非 ?，过滤值位于 args 中而非拼入 SQL。
|
||||
- 集成测试验证目标库身份、查询无错误、字段映射、过滤与排序。
|
||||
- 空表返回空切片属于成功，但不能证明非空数据映射和排序正确；需要已知数据才能完成这些验收。
|
||||
- 环境变量缺失导致 SKIP 不算数据库查询已通过。
|
||||
- 不记录 DSN、密码或可能包含凭据的连接错误原文。
|
||||
- 完成后执行 go test ./internal/model -run TestCategoryQuery -v -count=1。
|
||||
- 正式复用时使用 sqlx.SelectContext(ctx, executor, ...) 支持 *sqlx.DB 和 *sqlx.Tx；sqlx.ExtContext 接口本身没有 SelectContext 方法。
|
||||
@@ -1,7 +0,0 @@
|
||||
[app]
|
||||
name = "lyra"
|
||||
env = "dev"
|
||||
|
||||
[http]
|
||||
host = "0.0.0.0"
|
||||
port = 7777
|
||||
@@ -0,0 +1,18 @@
|
||||
[app]
|
||||
name = "lyra"
|
||||
env = "debug" #gin支持 release | test | debug 3种mode，如果需要自定义，需要映射到这3种mode中去，gin的默认模式是debug模式
|
||||
|
||||
[http]
|
||||
host = "0.0.0.0"
|
||||
port = 7777
|
||||
|
||||
[database]
|
||||
driver = "pgx"
|
||||
host = "localhost"
|
||||
port = 5432
|
||||
user = "admin"
|
||||
name = "lab"
|
||||
|
||||
[redis]
|
||||
host = "localhost"
|
||||
port = 6379
|
||||
@@ -4,10 +4,13 @@ go 1.27.1
|
||||
|
||||
require (
|
||||
github.com/gin-gonic/gin v1.12.0
|
||||
github.com/jackc/pgx/v5 v5.11.0
|
||||
github.com/jmoiron/sqlx v1.4.0
|
||||
github.com/spf13/viper v1.21.0
|
||||
)
|
||||
|
||||
require (
|
||||
github.com/Masterminds/squirrel v1.5.4 // indirect
|
||||
github.com/bytedance/gopkg v0.1.3 // indirect
|
||||
github.com/bytedance/sonic v1.15.0 // indirect
|
||||
github.com/bytedance/sonic/loader v0.5.0 // indirect
|
||||
@@ -21,8 +24,14 @@ require (
|
||||
github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
|
||||
github.com/goccy/go-json v0.10.5 // indirect
|
||||
github.com/goccy/go-yaml v1.19.2 // indirect
|
||||
github.com/jackc/pgpassfile v1.0.0 // indirect
|
||||
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
|
||||
github.com/jackc/puddle/v2 v2.2.2 // indirect
|
||||
github.com/joho/godotenv v1.5.1 // indirect
|
||||
github.com/json-iterator/go v1.1.12 // indirect
|
||||
github.com/klauspost/cpuid/v2 v2.3.0 // indirect
|
||||
github.com/lann/builder v0.0.0-20180802200727-47ae307949d0 // indirect
|
||||
github.com/lann/ps v0.0.0-20150810152359-62de8c46ede0 // indirect
|
||||
github.com/leodido/go-urn v1.4.0 // indirect
|
||||
github.com/mattn/go-isatty v0.0.20 // indirect
|
||||
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
|
||||
@@ -43,6 +52,7 @@ require (
|
||||
golang.org/x/arch v0.22.0 // indirect
|
||||
golang.org/x/crypto v0.48.0 // indirect
|
||||
golang.org/x/net v0.51.0 // indirect
|
||||
golang.org/x/sync v0.19.0 // indirect
|
||||
golang.org/x/sys v0.41.0 // indirect
|
||||
golang.org/x/text v0.34.0 // indirect
|
||||
google.golang.org/protobuf v1.36.10 // indirect
|
||||
|
||||
@@ -1,3 +1,7 @@
|
||||
filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
|
||||
filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
|
||||
github.com/Masterminds/squirrel v1.5.4 h1:uUcX/aBc8O7Fg9kaISIUsHXdKuqehiXAMQTYX8afzqM=
|
||||
github.com/Masterminds/squirrel v1.5.4/go.mod h1:NNaOrjSoIDfDA40n7sr2tPNZRfjzjA400rg+riTZj10=
|
||||
github.com/bytedance/gopkg v0.1.3 h1:TPBSwH8RsouGCBcMBktLt1AymVo2TVsBVCY4b6TnZ/M=
|
||||
github.com/bytedance/gopkg v0.1.3/go.mod h1:576VvJ+eJgyCzdjS+c4+77QF3p7ubbtiKARP3TxducM=
|
||||
github.com/bytedance/sonic v1.15.0 h1:/PXeWFaR5ElNcVE84U0dOHjiMHQOwNIx3K4ymzh/uSE=
|
||||
@@ -27,6 +31,8 @@ github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJn
|
||||
github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
|
||||
github.com/go-playground/validator/v10 v10.30.1 h1:f3zDSN/zOma+w6+1Wswgd9fLkdwy06ntQJp0BBvFG0w=
|
||||
github.com/go-playground/validator/v10 v10.30.1/go.mod h1:oSuBIQzuJxL//3MelwSLD5hc2Tu889bF0Idm9Dg26cM=
|
||||
github.com/go-sql-driver/mysql v1.8.1 h1:LedoTUt/eveggdHS9qUFC1EFSa8bU2+1pZjSRpvNJ1Y=
|
||||
github.com/go-sql-driver/mysql v1.8.1/go.mod h1:wEBSXgmK//2ZFJyE+qWnIsVGmvmEKlqwuVSjsCm7DZg=
|
||||
github.com/go-viper/mapstructure/v2 v2.4.0 h1:EBsztssimR/CONLSZZ04E8qAkxNYq4Qp9LvH92wZUgs=
|
||||
github.com/go-viper/mapstructure/v2 v2.4.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
|
||||
github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
|
||||
@@ -36,6 +42,18 @@ github.com/goccy/go-yaml v1.19.2/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7Lk
|
||||
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
|
||||
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
|
||||
github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
|
||||
github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
|
||||
github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
|
||||
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
|
||||
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
|
||||
github.com/jackc/pgx/v5 v5.11.0 h1:IzBBtyK9AHqf98cctWFifYSci2hgQR/cd56wB4p+ogg=
|
||||
github.com/jackc/pgx/v5 v5.11.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
|
||||
github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
|
||||
github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
|
||||
github.com/jmoiron/sqlx v1.4.0 h1:1PLqN7S1UYp5t4SrVVnt4nUVNemrDAtxlulVe+Qgm3o=
|
||||
github.com/jmoiron/sqlx v1.4.0/go.mod h1:ZrZ7UsYB/weZdl2Bxg6jCRO9c3YHl8r3ahlKmRT4JLY=
|
||||
github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
|
||||
github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
|
||||
github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
|
||||
github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
|
||||
github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
|
||||
@@ -44,10 +62,18 @@ github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
|
||||
github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
|
||||
github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
|
||||
github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
|
||||
github.com/lann/builder v0.0.0-20180802200727-47ae307949d0 h1:SOEGU9fKiNWd/HOJuq6+3iTQz8KNCLtVX6idSoTLdUw=
|
||||
github.com/lann/builder v0.0.0-20180802200727-47ae307949d0/go.mod h1:dXGbAdH5GtBTC4WfIxhKZfyBF/HBFgRZSWwZ9g/He9o=
|
||||
github.com/lann/ps v0.0.0-20150810152359-62de8c46ede0 h1:P6pPBnrTSX3DEVR4fDembhRWSsG5rVo6hYhAB/ADZrk=
|
||||
github.com/lann/ps v0.0.0-20150810152359-62de8c46ede0/go.mod h1:vmVJ0l/dxyfGW6FmdpVm2joNMFikkuWg0EoCKLGUMNw=
|
||||
github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
|
||||
github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
|
||||
github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw=
|
||||
github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
|
||||
github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
|
||||
github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
|
||||
github.com/mattn/go-sqlite3 v1.14.22 h1:2gZY6PC6kBnID23Tichd1K+Z0oS6nE/XwU+Vz/5o4kU=
|
||||
github.com/mattn/go-sqlite3 v1.14.22/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
|
||||
github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
|
||||
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
|
||||
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
|
||||
@@ -79,7 +105,9 @@ github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+
|
||||
github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
|
||||
github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
|
||||
github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
|
||||
github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=
|
||||
github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
|
||||
github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
|
||||
github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
|
||||
github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
|
||||
github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
|
||||
@@ -104,6 +132,8 @@ golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
|
||||
golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
|
||||
golang.org/x/net v0.51.0 h1:94R/GTO7mt3/4wIKpcR5gkGmRLOuE/2hNGeWq/GBIFo=
|
||||
golang.org/x/net v0.51.0/go.mod h1:aamm+2QF5ogm02fjy5Bb7CQ0WMt1/WVM7FtyaTLlA9Y=
|
||||
golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
|
||||
golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
|
||||
golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
|
||||
golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
|
||||
golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
package api
|
||||
|
||||
// CategoryResponse 分类列表响应 DTO，字段名显式约定小写 JSON 键。
|
||||
type CategoryResponse struct {
|
||||
ID int64 `json:"id"`
|
||||
Slug string `json:"slug"`
|
||||
Title string `json:"title"`
|
||||
Sort int `json:"sort"`
|
||||
}
|
||||
@@ -7,8 +7,10 @@ import (
|
||||
)
|
||||
|
||||
type Config struct {
|
||||
App AppConfig `mapstructure:"app"`
|
||||
HTTP HTTPConfig `mapstructure:"http"`
|
||||
App AppConfig `mapstructure:"app"`
|
||||
HTTP HTTPConfig `mapstructure:"http"`
|
||||
Database DatabaseConfig `mapstructure:"database"`
|
||||
Redis RedisConfig `mapstructure:"redis"`
|
||||
}
|
||||
|
||||
type AppConfig struct {
|
||||
@@ -21,6 +23,20 @@ type HTTPConfig struct {
|
||||
Port int `mapstructure:"port"`
|
||||
}
|
||||
|
||||
type DatabaseConfig struct {
|
||||
Driver string `mapstructure:"driver"`
|
||||
Host string `mapstructure:"host"`
|
||||
Port int `mapstructure:"port"`
|
||||
User string `mapstructure:"user"`
|
||||
Name string `mapstructure:"name"`
|
||||
Password string `mapstructure:"password"`
|
||||
}
|
||||
|
||||
type RedisConfig struct {
|
||||
Host string `mapstructure:"host"`
|
||||
Port int `mapstructure:"port"`
|
||||
}
|
||||
|
||||
func Load(path string) (*Config, error) {
|
||||
v := viper.New()
|
||||
// 指定文件，按 .toml 扩展名识别格式
|
||||
@@ -29,7 +45,10 @@ func Load(path string) (*Config, error) {
|
||||
if err := v.ReadInConfig(); err != nil {
|
||||
return nil, fmt.Errorf("读取配置失败: %w", err)
|
||||
}
|
||||
|
||||
v.AllowEmptyEnv(true)
|
||||
if err := v.BindEnv("database.password", "PG_PASSWORD"); err != nil {
|
||||
return nil, fmt.Errorf("绑定数据库密码环境变量失败: %w", err)
|
||||
}
|
||||
var cfg Config
|
||||
if err := v.Unmarshal(&cfg); err != nil {
|
||||
return nil, fmt.Errorf("解析配置失败: %w", err)
|
||||
|
||||
@@ -3,3 +3,4 @@
|
||||
- 负责参数绑定、API DTO 与内部模型的相互转换、响应输出。
|
||||
- 引用 internal/api 的 DTO，使用 Gin 完成绑定与响应。
|
||||
- 调用 service 时传递标准 context.Context，不下传 gin.Context。
|
||||
- 可按明确业务分包（如 `polaris/`）；服务级简单接口保留在根包平铺，不预建空业务包。
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
package handler
|
||||
|
||||
import (
|
||||
"lyra/internal/api"
|
||||
"lyra/internal/httpx"
|
||||
"lyra/internal/model"
|
||||
"net/http"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
)
|
||||
|
||||
type TestHandler struct {
|
||||
categoryModel model.CategoryModel
|
||||
}
|
||||
|
||||
func NewTestHandler(categoryModel model.CategoryModel) *TestHandler {
|
||||
return &TestHandler{categoryModel: categoryModel}
|
||||
}
|
||||
|
||||
func (h *TestHandler) Hello() gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
categories, err := h.categoryModel.FindAll(c.Request.Context())
|
||||
if err != nil {
|
||||
httpx.Fail(c, http.StatusInternalServerError, api.CodeInternalError, "获取分类列表失败")
|
||||
return
|
||||
}
|
||||
httpx.OK(c, toCategoryResponses(categories))
|
||||
}
|
||||
}
|
||||
|
||||
// toCategoryResponses 显式把内部模型转换为响应 DTO；make 保证空结果输出 data:[] 而非 null。
|
||||
func toCategoryResponses(categories []*model.Category) []api.CategoryResponse {
|
||||
responses := make([]api.CategoryResponse, 0, len(categories))
|
||||
for _, category := range categories {
|
||||
responses = append(responses, api.CategoryResponse{
|
||||
ID: category.ID,
|
||||
Slug: category.Slug,
|
||||
Title: category.Title,
|
||||
Sort: category.Sort,
|
||||
})
|
||||
}
|
||||
return responses
|
||||
}
|
||||
@@ -0,0 +1,128 @@
|
||||
package handler_test
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"lyra/internal/handler"
|
||||
"lyra/internal/model"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
)
|
||||
|
||||
type fakeCategoryModel struct {
|
||||
categories []*model.Category
|
||||
err error
|
||||
calls int
|
||||
gotCtx context.Context
|
||||
}
|
||||
|
||||
func (f *fakeCategoryModel) FindAll(ctx context.Context) ([]*model.Category, error) {
|
||||
f.calls++
|
||||
f.gotCtx = ctx
|
||||
return f.categories, f.err
|
||||
}
|
||||
|
||||
func serveHello(t *testing.T, fake *fakeCategoryModel, req *http.Request) *httptest.ResponseRecorder {
|
||||
t.Helper()
|
||||
gin.SetMode(gin.TestMode)
|
||||
engine := gin.New()
|
||||
engine.GET("/test", handler.NewTestHandler(fake).Hello())
|
||||
recorder := httptest.NewRecorder()
|
||||
engine.ServeHTTP(recorder, req)
|
||||
return recorder
|
||||
}
|
||||
|
||||
func newHelloRequest() *http.Request {
|
||||
return httptest.NewRequest(http.MethodGet, "/test", nil)
|
||||
}
|
||||
|
||||
func TestHelloMapsCategoriesToResponse(t *testing.T) {
|
||||
fake := &fakeCategoryModel{categories: []*model.Category{
|
||||
{ID: 1, Slug: "go-basics", Title: "Go 基础", Sort: 1},
|
||||
{ID: 2, Slug: "sql-practice", Title: "SQL 练习", Sort: 2},
|
||||
}}
|
||||
|
||||
recorder := serveHello(t, fake, newHelloRequest())
|
||||
|
||||
if fake.calls != 1 {
|
||||
t.Fatalf("模型调用次数 = %d, want 1", fake.calls)
|
||||
}
|
||||
if recorder.Code != http.StatusOK {
|
||||
t.Fatalf("status = %d, want %d", recorder.Code, http.StatusOK)
|
||||
}
|
||||
want := `{"success":true,"data":[{"id":1,"slug":"go-basics","title":"Go 基础","sort":1},{"id":2,"slug":"sql-practice","title":"SQL 练习","sort":2}]}`
|
||||
if got := recorder.Body.String(); got != want {
|
||||
t.Fatalf("body = %q, want %q", got, want)
|
||||
}
|
||||
}
|
||||
|
||||
func TestHelloReturnsEmptyArrayForNoCategories(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
categories []*model.Category
|
||||
}{
|
||||
{name: "空切片", categories: []*model.Category{}},
|
||||
{name: "nil结果", categories: nil},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
fake := &fakeCategoryModel{categories: tt.categories}
|
||||
|
||||
recorder := serveHello(t, fake, newHelloRequest())
|
||||
|
||||
if fake.calls != 1 {
|
||||
t.Fatalf("模型调用次数 = %d, want 1", fake.calls)
|
||||
}
|
||||
if recorder.Code != http.StatusOK {
|
||||
t.Fatalf("status = %d, want %d", recorder.Code, http.StatusOK)
|
||||
}
|
||||
want := `{"success":true,"data":[]}`
|
||||
if got := recorder.Body.String(); got != want {
|
||||
t.Fatalf("body = %q, want %q", got, want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestHelloReturnsInternalErrorOnModelFailure(t *testing.T) {
|
||||
modelErr := errors.New("数据库连接被拒绝: 10.0.0.8:5432")
|
||||
fake := &fakeCategoryModel{err: modelErr}
|
||||
|
||||
recorder := serveHello(t, fake, newHelloRequest())
|
||||
|
||||
if fake.calls != 1 {
|
||||
t.Fatalf("模型调用次数 = %d, want 1", fake.calls)
|
||||
}
|
||||
if recorder.Code != http.StatusInternalServerError {
|
||||
t.Fatalf("status = %d, want %d", recorder.Code, http.StatusInternalServerError)
|
||||
}
|
||||
want := `{"success":false,"error":{"code":10002,"message":"获取分类列表失败"}}`
|
||||
if got := recorder.Body.String(); got != want {
|
||||
t.Fatalf("body = %q, want %q", got, want)
|
||||
}
|
||||
if strings.Contains(recorder.Body.String(), modelErr.Error()) {
|
||||
t.Fatalf("响应泄漏了内部错误信息: %q", recorder.Body.String())
|
||||
}
|
||||
}
|
||||
|
||||
type contextKey struct{}
|
||||
|
||||
func TestHelloPassesRequestContextToModel(t *testing.T) {
|
||||
fake := &fakeCategoryModel{categories: []*model.Category{}}
|
||||
reqCtx := context.WithValue(context.Background(), contextKey{}, "req-42")
|
||||
req := newHelloRequest().WithContext(reqCtx)
|
||||
|
||||
serveHello(t, fake, req)
|
||||
|
||||
if fake.gotCtx != reqCtx {
|
||||
t.Fatalf("模型收到非请求 context: %v", fake.gotCtx)
|
||||
}
|
||||
if got, _ := fake.gotCtx.Value(contextKey{}).(string); got != "req-42" {
|
||||
t.Fatalf("context 值 = %q, want %q", got, "req-42")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,46 @@
|
||||
package model
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
|
||||
sq "github.com/Masterminds/squirrel"
|
||||
"github.com/jmoiron/sqlx"
|
||||
)
|
||||
|
||||
type Category struct {
|
||||
ID int64 `db:"id"`
|
||||
Slug string `db:"slug"`
|
||||
Title string `db:"title"`
|
||||
Sort int `db:"sort"`
|
||||
}
|
||||
|
||||
type CategoryModel interface {
|
||||
FindAll(ctx context.Context) ([]*Category, error)
|
||||
}
|
||||
type defaultCategoryModel struct {
|
||||
db *sqlx.DB
|
||||
}
|
||||
|
||||
func NewCategoryModel(db *sqlx.DB) CategoryModel {
|
||||
return &defaultCategoryModel{db: db}
|
||||
}
|
||||
func (m *defaultCategoryModel) FindAll(ctx context.Context) ([]*Category, error) {
|
||||
query, args, err := sq.
|
||||
Select("id", "slug", "title", "sort").
|
||||
From("public.categories").
|
||||
Where(sq.GtOrEq{"sort": 1}).
|
||||
OrderBy("sort ASC", "id ASC").
|
||||
Limit(10).
|
||||
PlaceholderFormat(sq.Dollar).
|
||||
ToSql()
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("squirrel 出错: %w", err)
|
||||
}
|
||||
rows := make([]*Category, 0)
|
||||
err = m.db.SelectContext(ctx, &rows, query, args...)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("数据库查询出错: %w", err)
|
||||
}
|
||||
return rows, err
|
||||
}
|
||||
@@ -1,5 +1,6 @@
|
||||
# router 包
|
||||
|
||||
- 负责路由注册与项目路径前缀，例如 `/api/polaris`。
|
||||
- 负责路由注册与项目路径前缀，例如 `/api/polaris`；入口文件为 `router.go`，对外暴露 `RegisterRoutes`。
|
||||
- Gin 的路由与请求处理逻辑留在 HTTP 层；service 和 model 不依赖 Gin。
|
||||
- 路由随资源实现逐步补充，不按业务项目建立代码子目录。
|
||||
- 路由随资源实现逐步补充；包暂时平铺，不按业务项目建立代码子目录。
|
||||
- 路由变更以 httptest 回归测试守护，不监听实际端口、不连接数据库。
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
package router
|
||||
|
||||
import (
|
||||
"github.com/gin-gonic/gin"
|
||||
)
|
||||
|
||||
// Handlers 汇总各路由所需的处理器，由入口在启动时组装注入。
|
||||
type Handlers struct {
|
||||
TestHandler gin.HandlerFunc
|
||||
}
|
||||
|
||||
// RegisterRoutes 将处理器挂载到引擎的路由表。
|
||||
func RegisterRoutes(engine *gin.Engine, handlers Handlers) {
|
||||
engine.GET("/test", handlers.TestHandler)
|
||||
}
|
||||
@@ -0,0 +1,77 @@
|
||||
package router_test
|
||||
|
||||
import (
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"testing"
|
||||
|
||||
"lyra/internal/router"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
)
|
||||
|
||||
const (
|
||||
stubStatus = http.StatusAccepted
|
||||
stubBody = "injected test handler"
|
||||
)
|
||||
|
||||
// newStubHandlers 返回记录调用次数并输出固定状态码与响应体的替身处理器。
|
||||
func newStubHandlers(calls *int) router.Handlers {
|
||||
return router.Handlers{
|
||||
TestHandler: func(c *gin.Context) {
|
||||
*calls++
|
||||
c.String(stubStatus, stubBody)
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func TestRouteInvokesInjectedHandler(t *testing.T) {
|
||||
gin.SetMode(gin.TestMode)
|
||||
|
||||
var calls int
|
||||
engine := gin.New()
|
||||
router.RegisterRoutes(engine, newStubHandlers(&calls))
|
||||
|
||||
recorder := httptest.NewRecorder()
|
||||
engine.ServeHTTP(recorder, httptest.NewRequest(http.MethodGet, "/test", nil))
|
||||
|
||||
if calls != 1 {
|
||||
t.Fatalf("GET /test 替身调用次数 = %d, want 1", calls)
|
||||
}
|
||||
if recorder.Code != stubStatus {
|
||||
t.Fatalf("GET /test status = %d, want %d", recorder.Code, stubStatus)
|
||||
}
|
||||
if got := recorder.Body.String(); got != stubBody {
|
||||
t.Fatalf("GET /test body = %q, want %q", got, stubBody)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRouteSkipsHandlerForUnknownPathOrMethod(t *testing.T) {
|
||||
gin.SetMode(gin.TestMode)
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
method string
|
||||
path string
|
||||
}{
|
||||
{name: "未知路径", method: http.MethodGet, path: "/unknown"},
|
||||
{name: "不支持的方法", method: http.MethodPost, path: "/test"},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
var calls int
|
||||
engine := gin.New()
|
||||
router.RegisterRoutes(engine, newStubHandlers(&calls))
|
||||
|
||||
recorder := httptest.NewRecorder()
|
||||
engine.ServeHTTP(recorder, httptest.NewRequest(tt.method, tt.path, nil))
|
||||
|
||||
if calls != 0 {
|
||||
t.Fatalf("%s %s 替身调用次数 = %d, want 0", tt.method, tt.path, calls)
|
||||
}
|
||||
if recorder.Code != http.StatusNotFound {
|
||||
t.Fatalf("%s %s status = %d, want %d", tt.method, tt.path, recorder.Code, http.StatusNotFound)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -3,3 +3,4 @@
|
||||
- 承载业务规则与事务协调，通过 model 完成数据访问。
|
||||
- 需要原子性时，在同一事务内协调多次写入，不把各自独立提交的多次写入当成原子业务。
|
||||
- 使用标准 context.Context，不依赖 Gin，也不依赖 internal/api 的 DTO。
|
||||
- 可按明确业务分包（如 `polaris/`）；服务级简单接口保留在根包平铺，不预建空业务包。
|
||||
|
||||
@@ -0,0 +1,134 @@
|
||||
-- Lyra 初始迁移：与 docs/demo.sql 的建库内容保持一致（函数、三张表、约束、注释、索引、触发器）。
|
||||
|
||||
-- +goose Up
|
||||
-- updated_at 维护函数
|
||||
-- +goose StatementBegin
|
||||
CREATE FUNCTION public.set_updated_at()
|
||||
RETURNS trigger
|
||||
LANGUAGE plpgsql
|
||||
AS $$
|
||||
BEGIN
|
||||
NEW.updated_at := now();
|
||||
RETURN NEW;
|
||||
END;
|
||||
$$;
|
||||
-- +goose StatementEnd
|
||||
|
||||
-- 用户表
|
||||
CREATE TABLE public.users (
|
||||
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
|
||||
account text NOT NULL UNIQUE,
|
||||
password_hash text NOT NULL,
|
||||
display_name text NOT NULL,
|
||||
created_at timestamptz NOT NULL DEFAULT now(),
|
||||
updated_at timestamptz NOT NULL DEFAULT now(),
|
||||
CONSTRAINT users_account_not_empty CHECK (btrim(account) <> ''),
|
||||
CONSTRAINT users_display_name_not_empty CHECK (btrim(display_name) <> '')
|
||||
);
|
||||
|
||||
COMMENT ON TABLE public.users IS '后台管理用户表';
|
||||
COMMENT ON COLUMN public.users.id IS '用户 ID';
|
||||
COMMENT ON COLUMN public.users.account IS '登录账号，当前大小写敏感';
|
||||
COMMENT ON COLUMN public.users.password_hash IS '密码哈希';
|
||||
COMMENT ON COLUMN public.users.display_name IS '展示昵称';
|
||||
COMMENT ON COLUMN public.users.created_at IS '创建时间';
|
||||
COMMENT ON COLUMN public.users.updated_at IS '更新时间，触发器自动刷新';
|
||||
|
||||
-- 分类表
|
||||
CREATE TABLE public.categories (
|
||||
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
|
||||
slug text NOT NULL UNIQUE,
|
||||
title text NOT NULL,
|
||||
description text NOT NULL DEFAULT '',
|
||||
icon text NOT NULL,
|
||||
sort integer NOT NULL DEFAULT 0,
|
||||
created_at timestamptz NOT NULL DEFAULT now(),
|
||||
updated_at timestamptz NOT NULL DEFAULT now(),
|
||||
CONSTRAINT categories_slug_format CHECK (slug ~ '^[a-z0-9]+(-[a-z0-9]+)*$'),
|
||||
CONSTRAINT categories_title_not_empty CHECK (btrim(title) <> '')
|
||||
);
|
||||
|
||||
COMMENT ON TABLE public.categories IS '链接分类表';
|
||||
COMMENT ON COLUMN public.categories.id IS '分类 ID，内部关联用';
|
||||
COMMENT ON COLUMN public.categories.slug IS '页面地址（路由）标识';
|
||||
COMMENT ON COLUMN public.categories.title IS '分类标题';
|
||||
COMMENT ON COLUMN public.categories.description IS '分类描述';
|
||||
COMMENT ON COLUMN public.categories.icon IS '分类图标标识';
|
||||
COMMENT ON COLUMN public.categories.sort IS '分类排序，越小越靠前';
|
||||
COMMENT ON COLUMN public.categories.created_at IS '创建时间';
|
||||
COMMENT ON COLUMN public.categories.updated_at IS '更新时间，触发器自动刷新';
|
||||
|
||||
-- 链接表
|
||||
CREATE TABLE public.links (
|
||||
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
|
||||
category_id bigint NOT NULL,
|
||||
title text NOT NULL,
|
||||
description text NOT NULL DEFAULT '',
|
||||
url text NOT NULL,
|
||||
icon text,
|
||||
keywords text[] NOT NULL DEFAULT ARRAY[]::text[],
|
||||
sort integer NOT NULL DEFAULT 0,
|
||||
pinned boolean NOT NULL DEFAULT false,
|
||||
pinned_sort integer,
|
||||
created_at timestamptz NOT NULL DEFAULT now(),
|
||||
updated_at timestamptz NOT NULL DEFAULT now(),
|
||||
CONSTRAINT links_category_fk FOREIGN KEY (category_id) REFERENCES public.categories (id) ON DELETE RESTRICT,
|
||||
CONSTRAINT links_title_not_empty CHECK (btrim(title) <> ''),
|
||||
CONSTRAINT links_url_not_empty CHECK (btrim(url) <> ''),
|
||||
CONSTRAINT links_pinned_sort_consistent CHECK (pinned = (pinned_sort IS NOT NULL)),
|
||||
CONSTRAINT links_keywords_one_dimension CHECK (cardinality(keywords) = 0 OR array_ndims(keywords) = 1),
|
||||
CONSTRAINT links_keywords_no_null_elements CHECK (array_position(keywords, NULL) IS NULL)
|
||||
);
|
||||
|
||||
COMMENT ON TABLE public.links IS '链接表，归属分类';
|
||||
COMMENT ON COLUMN public.links.id IS '链接 ID';
|
||||
COMMENT ON COLUMN public.links.category_id IS '所属分类 ID，删分类前需先处理链接';
|
||||
COMMENT ON COLUMN public.links.title IS '链接标题';
|
||||
COMMENT ON COLUMN public.links.description IS '链接描述';
|
||||
COMMENT ON COLUMN public.links.url IS '链接地址，应用层校验，去尾斜杠后全局唯一';
|
||||
COMMENT ON COLUMN public.links.icon IS '链接图标，可空，前端回退';
|
||||
COMMENT ON COLUMN public.links.keywords IS '搜索关键词数组，供本地搜索匹配';
|
||||
COMMENT ON COLUMN public.links.sort IS '分类内排序，越小越靠前';
|
||||
COMMENT ON COLUMN public.links.pinned IS '首页快捷入口（手动固定），非点击排行';
|
||||
COMMENT ON COLUMN public.links.pinned_sort IS '首页快捷入口顺序，越小越靠前';
|
||||
COMMENT ON COLUMN public.links.created_at IS '创建时间';
|
||||
COMMENT ON COLUMN public.links.updated_at IS '更新时间，触发器自动刷新';
|
||||
|
||||
-- 索引
|
||||
CREATE INDEX categories_order_idx
|
||||
ON public.categories (sort, id);
|
||||
|
||||
CREATE INDEX links_category_order_idx
|
||||
ON public.links (category_id, sort, id);
|
||||
|
||||
CREATE INDEX links_pinned_order_idx
|
||||
ON public.links (pinned_sort, id)
|
||||
WHERE pinned;
|
||||
|
||||
CREATE UNIQUE INDEX links_normalized_url_unique
|
||||
ON public.links (rtrim(url, '/'));
|
||||
|
||||
-- 触发器
|
||||
CREATE TRIGGER users_set_updated_at
|
||||
BEFORE UPDATE ON public.users
|
||||
FOR EACH ROW
|
||||
EXECUTE FUNCTION public.set_updated_at();
|
||||
|
||||
CREATE TRIGGER categories_set_updated_at
|
||||
BEFORE UPDATE ON public.categories
|
||||
FOR EACH ROW
|
||||
EXECUTE FUNCTION public.set_updated_at();
|
||||
|
||||
CREATE TRIGGER links_set_updated_at
|
||||
BEFORE UPDATE ON public.links
|
||||
FOR EACH ROW
|
||||
EXECUTE FUNCTION public.set_updated_at();
|
||||
|
||||
-- +goose Down
|
||||
-- 按依赖逆序删除：链接表 → 分类表 → 用户表 → 函数。
|
||||
-- 删表会一并移除表上的触发器与索引，故无需单独 DROP；
|
||||
-- 不用 CASCADE / IF EXISTS，出现意外依赖时让删除直接报错。
|
||||
DROP TABLE public.links;
|
||||
DROP TABLE public.categories;
|
||||
DROP TABLE public.users;
|
||||
DROP FUNCTION public.set_updated_at();
|
||||
@@ -1,7 +1,21 @@
|
||||
# migrations
|
||||
|
||||
未来存放 [Goose](https://pressly.github.io/goose/) SQL 迁移文件的目录。
|
||||
Lyra 的 [Goose](https://pressly.github.io/goose/) SQL 迁移目录，是数据库结构的**唯一正式执行来源**。
|
||||
[docs/demo.sql](../docs/demo.sql) 仅保留作参考，不要再手工执行它，避免与迁移重复建表。
|
||||
|
||||
当前没有任何迁移文件；首个迁移的文件名与写法随实现确定。部署执行入口、
|
||||
并发控制（串行执行或数据库锁）与 schema 划分方案尚未确定，见
|
||||
[../docs/architecture.md](../docs/architecture.md) 的"尚未确定"部分。
|
||||
## 操作手册
|
||||
|
||||
安装 goose CLI、配置 `.env.local` 连接、首次初始化、日常新增迁移、回滚警告与
|
||||
故障排查等全部操作步骤，见唯一完整手册：[docs/goose.md](../docs/goose.md)。
|
||||
|
||||
## 现有迁移
|
||||
|
||||
| 文件 | 内容 |
|
||||
|---|---|
|
||||
| `00001_init.sql` | 初始结构：`set_updated_at()` 函数、`users`/`categories`/`links` 三张表、约束、注释、索引与触发器，建库内容与 `docs/demo.sql` 一致 |
|
||||
|
||||
## 执行模型约定
|
||||
|
||||
- 迁移只作用于 `public` schema，沿用现有设计，暂不做 schema 划分。
|
||||
- 单个操作者串行执行，不引入数据库锁等并发控制。
|
||||
- 部署执行入口是手工 CLI，服务启动时**不会**自动执行迁移。
|
||||
|
||||
Reference in New Issue
Block a user