Skeleton

skeleton/ 是基于 HeTianXia 项目整理出来的最小骨架目录，用来作为后续新项目的起点。

当前包含

• main.go：应用启动入口
• config/：配置结构与 YAML 示例
• middlewares/：日志、CORS、JWT 等基础中间件
• database/：PostgreSQL 和 Redis 连接层
• routes/：主路由、REST 注册器、WS 挂载点
• utils/：公共工具，如时区、分页、统一响应
• modules/example/：最小示例模块
• models/：最小模型占位，供 Atlas 和后续模块使用
• atlas.hcl 和 atlas_loader.go：Atlas CLI 迁移配置与模型加载入口
• cmd/migrate/：迁移命令入口占位

目录说明

main.go

保留启动流程骨架：

• 加载配置
• 初始化日志
• 初始化 JWT
• 初始化时区
• 初始化数据库
• 初始化 Redis
• 挂载路由
• 启动 HTTP 服务
• 优雅关闭

models/

这里放最小模型占位即可。当前只保留了 User，用于：

• 让 Atlas 有可扫描的模型
• 给后续业务模块提供基础实体

atlas_loader.go

这个文件的作用是告诉 Atlas CLI：

• 当前项目有哪些 GORM 模型
• 这些模型对应哪些表结构

它不是运行时初始化文件，也不是业务逻辑文件。

下一步如何扩展

1. 新增业务模块时，在 modules/ 下新建目录，例如 modules/order
2. 模块内部按需添加 controller.go、service.go、types.go、utils.go
3. 如果模型变化，先更新 models/，再更新 atlas_loader.go
4. 用 Atlas CLI 生成和应用迁移

说明

这个骨架的目标不是一次性把所有能力都放齐，而是先建立稳定的项目边界：

• 公共能力放 utils/
• HTTP 行为放 middlewares/ 和 routes/
• 数据连接放 database/
• 业务放 modules/
• 数据结构放 models/

📊 数据库迁移管理

本项目集成了 Atlas + GORM Provider 来实现自动化的数据库迁移管理。

安装 Atlas CLI

# macOS (推荐)
brew install ariga/tap/atlas

# 或使用 go install
go install ariga.io/atlas/cmd/atlas@latest

# 验证安装
atlas version

安装 GORM Provider 依赖

需要单独执行，不会被go mod tidy命令检测到，因为构建排除了atlas_loader.go文件

go get ariga.io/atlas-provider-gorm

迁移命令

0. 基线迁移（首次初始化）

如果你有一个现有的数据库需要纳入迁移管理，需要先创建基线：

atlas migrate diff baseline --env local

atlas migrate hash --env local

atlas migrate set $(ls migrations/*.sql | head -1 | grep -o '[0-9]\{14\}') --env local

⚠️ 基线迁移注意事项：

• 首次使用: 如果数据库是全新的，直接使用 apply 命令即可
• 现有数据库: 必须先设置基线，告诉Atlas当前数据库的状态
• 团队协作: 确保所有团队成员都从同一个基线开始

使用场景：

• 场景1 - 全新项目: 创建数据库 → 直接执行 apply 应用所有迁移
• 场景2 - 现有数据库: 已有表结构 → 使用 hash 或 set 建立基线 → 继续正常迁移
• 场景3 - 团队加入: 新成员 → 克隆代码 → 创建本地数据库 → 执行 apply
• 场景4 - 生产部署: 已有生产数据 → 谨慎设置基线 → 应用新迁移

1. 查看迁移状态

# 检查当前迁移状态
go run cmd/migrate/main.go -action status

# 指定环境
go run cmd/migrate/main.go -action status -env production

2. 生成迁移文件

# 基于当前模型生成迁移（自动命名）
go run cmd/migrate/main.go -action diff

# 生成带自定义名称的迁移
go run cmd/migrate/main.go -action diff -name create_users_table

3. 应用迁移

# 应用所有待执行的迁移
go run cmd/migrate/main.go -action apply

# 模拟执行（显示将要执行的SQL，不实际执行）
go run cmd/migrate/main.go -action apply -dry-run

4. 验证迁移

# 验证迁移文件的有效性
go run cmd/migrate/main.go -action validate

5. 重置迁移历史（危险操作）

# 显示重置指导（不会直接执行）
go run cmd/migrate/main.go -action reset

配置说明

• atlas.hcl: Atlas 主配置文件，定义数据源和环境
• atlas_loader.go: GORM 模型加载器，需要在此文件中注册所有数据模型
• migrations/: 存储生成的迁移文件

环境配置

本地开发环境 (local)

修改 atlas.hcl 中的 env "local" 配置：

env "local" {
  url = "postgres://username:password@localhost:5432/your_database?sslmode=disable" // 开发数据库
  dev = "postgres://username:password@localhost:5432/dev_database?sslmode=disable"  // 计算差异数据库
}

生产环境 (production)

# 设置环境变量
export DATABASE_URL="postgres://user:pass@host:port/db?sslmode=require"

# 应用迁移
go run cmd/migrate/main.go -action apply -env production

添加新模型

1. 在 models/ 目录下创建新的模型文件
2. 在 atlas_loader.go 中注册新模型：

   stmts, err := gormschema.New("postgres").Load(
       &models.User{},
       &models.NewModel{}, // 添加新模型
   )
   

3. 生成迁移：go run cmd/migrate/main.go -action diff -name add_new_model
4. 应用迁移：go run cmd/migrate/main.go -action apply

注意事项

⚠️ 重要提醒：

1. 备份数据库: 在生产环境应用迁移前务必备份数据库
2. 测试迁移: 先在开发环境测试迁移的正确性
3. 版本控制: 迁移文件应纳入版本控制系统
4. 环境隔离: 不同环境使用不同的数据库连接
5. 回滚策略: Atlas 支持迁移回滚，但需要谨慎操作

常见问题

Q: 如何回滚迁移？

# 回滚到指定版本
atlas migrate down --env local --to-version 20231201120000

Q: 如何重置迁移历史？

# 删除迁移历史表（谨慎操作）
atlas migrate reset --env local

Q: 生产环境迁移失败怎么办？

1. 检查迁移文件语法
2. 确认数据库权限
3. 查看详细错误日志
4. 必要时手动修复数据库状态

---