106 lines
5.6 KiB
Markdown
106 lines
5.6 KiB
Markdown
---
|
||
name: 扁平化迁移脚本目录结构
|
||
overview: 把 pkg/migration/migrations/*.sql 上移一层到 pkg/migration/*.sql，embed 改为 *.sql + iofs.New(fs, ".")，并删除根目录多余的空占位目录 migrations/，同步更新 README 与验证。
|
||
todos:
|
||
- id: flatten-sql
|
||
content: 将 32 个迁移 SQL 上移到 pkg/migration 并删除空的 migrations 子目录
|
||
status: completed
|
||
- id: fix-embed
|
||
content: 修改 migration.go 的 embed 模式与 iofs 源路径为当前目录
|
||
status: completed
|
||
dependencies:
|
||
- flatten-sql
|
||
- id: clean-root-dir
|
||
content: 删除仓库根空的 migrations 占位目录
|
||
status: completed
|
||
- id: sync-readme
|
||
content: 同步 README 中所有 pkg/migration/migrations 路径引用
|
||
status: completed
|
||
dependencies:
|
||
- fix-embed
|
||
- id: verify-build
|
||
content: 编译与 go vet 校验，并用临时测试确认 embed 源可解析（验证后删除）
|
||
status: completed
|
||
dependencies:
|
||
- fix-embed
|
||
- sync-readme
|
||
- id: review-paths
|
||
content: 用 [subagent:code-explorer] 复核目录结构与路径引用无残留
|
||
status: completed
|
||
dependencies:
|
||
- verify-build
|
||
---
|
||
|
||
## 产品概述
|
||
|
||
调整已实现的数据库迁移目录结构：去掉 `pkg/migration/migrations/` 这一层多余嵌套，将版本化 SQL 直接放在 `pkg/migration/` 下，并清理仓库根已失效的 `migrations/` 占位目录；迁移入口 `cmd/migrate` 保留不动。
|
||
|
||
## 核心功能
|
||
|
||
- **SQL 目录扁平化**：32 个迁移脚本（`000001~000016` 的 up/down 配对）上移一层至 `pkg/migration/`，文件名与内容完全不变，删除空的 `migrations/` 子目录
|
||
- **embed 路径适配**：改为 `//go:embed *.sql` + `iofs.New(migrationFS, ".")`，迁移脚本与 `migration.go` 同级
|
||
- **清理根目录**：删除仓库根已无引用的空占位目录 `migrations/`（`sql/`、`scripts/`、`docs/` 保持不变）
|
||
- **文档同步**：README 目录树与「准备数据库」章节中的 `pkg/migration/migrations` 路径全部改为 `pkg/migration`
|
||
- **迁移能力不变**：`Up/Down/Steps/Version/Force` API、`cmd/migrate` 子命令、22 张表 SQL 内容均保持不变
|
||
|
||
## 技术栈
|
||
|
||
- Go 1.27，模块 `git.lzcwy.cn/zhengchiliu/zt-closet-backend`
|
||
- `github.com/golang-migrate/migrate/v4 v4.19.1`（`database/mysql` 驱动 + `source/iofs` 源）
|
||
- `github.com/go-sql-driver/mysql v1.10.0`
|
||
|
||
## 实现方案
|
||
|
||
采用「脚本与代码同级」的扁平布局：`//go:embed *.sql` 把同目录 SQL 打进 embed FS，`iofs.New(migrationFS, ".")` 以当前目录作为 golang-migrate 源根目录，文件名 `00000N_xxx.up.sql` / `.down.sql` 保持 golang-migrate 规范不变。
|
||
|
||
关键决策：
|
||
|
||
1. **去掉源子目录而非保留**：`iofs` 源只需一个目录根，SQL 与 `migration.go` 同级时路径最短、引用最少，且不损失任何能力（golang-migrate 按文件名而非目录识别版本）。
|
||
2. **`//go:embed *.sql` 只嵌入 SQL**：embed FS 中不会出现 `.go` 文件，避免 `iofs` 源扫描到无关文件。
|
||
3. **保留 `cmd/migrate`**：用户已确认接受 Go 标准布局；独立二进制使迁移不依赖主服务的 Redis/COS/支付等初始化。
|
||
4. **不改文件名与内容**：避免已应用环境的版本号/校验和变化，保证迁移历史兼容。
|
||
|
||
## 实现要点（防回归）
|
||
|
||
- `migration.go` 中 `migrationsDir` 常量改为 `"."` 并更新注释（迁移脚本与本文件同级）；`iofs.New(migrationFS, migrationsDir)` 调用不变。
|
||
- 文件名保持 `00000N_xxx.up.sql` / `00000N_xxx.down.sql`，**不要**重命名或改版本号。
|
||
- 验证用临时测试文件放在 `pkg/migration` 下（仅 `iofs.New` + `src.First()`，不连数据库），**验证后必须删除**。
|
||
- 不要改动 `cmd/migrate/main.go`、SQL 内容与迁移包对外 API。
|
||
- 不连接真实数据库：`configs/config.yaml` 的 MySQL 为内网地址，且该文件第 2 行 `Domain: *` 为非法 YAML（用户本地配置，本次不处理）。
|
||
|
||
## 架构设计
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A["cmd/migrate/main.go<br/>up/down/steps/version/force"] --> B["pkg/setting<br/>读取 Mysql 段"]
|
||
B --> C["pkg/migration.Run<br/>DSN multiStatements=true"]
|
||
C --> D["iofs.New(embed FS, .)"]
|
||
D --> E["pkg/migration/*.sql<br/>000001~000016 up/down"]
|
||
C --> F["mysql.WithInstance(*sql.DB)"]
|
||
E --> G["migrate.NewWithInstance"]
|
||
F --> G
|
||
G --> H["schema_migrations"]
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
pkg/migration/
|
||
├── migration.go # [MODIFY] //go:embed 由 migrations/*.sql 改为 *.sql；migrationsDir 常量由 "migrations" 改为 "."；
|
||
│ # Up/Down/Steps/Version/Force/Run 与 DSN 拼装逻辑不变
|
||
├── 000001_create_users.up.sql # [MOVE] 由 migrations/ 上移，内容不变
|
||
├── 000001_create_users.down.sql # [MOVE]
|
||
├── ...（000002~000016 的 up/down，共 32 个文件）[MOVE]
|
||
└── migrations/ # [DELETE] 空目录，扁平化后删除
|
||
migrations/ # [DELETE] 仓库根空占位目录，已无引用
|
||
README.md # [MODIFY] 目录树：pkg/migration 去掉 migrations 子层；
|
||
# 「准备数据库」章节与 sql/ 占位说明中的 pkg/migration/migrations 改为 pkg/migration
|
||
```
|
||
|
||
## Agent Extensions
|
||
|
||
### SubAgent
|
||
|
||
- **code-explorer**
|
||
- Purpose：扁平化完成后复核 `pkg/migration/` 目录结构与 README 中的路径引用，确认 `migrations/` 子目录与根占位目录已消失、无遗留 `pkg/migration/migrations` 文本引用、32 个 SQL 文件齐全且 up/down 配对完整
|
||
- Expected outcome：输出路径引用与文件清单核查结果，确保无残留旧路径 |