init
This commit is contained in:
Hericium-sys
@@ -0,0 +1,222 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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`文件
|
||||
|
||||
```bash
|
||||
go get ariga.io/atlas-provider-gorm
|
||||
```
|
||||
|
||||
### 迁移命令
|
||||
|
||||
#### 0. 基线迁移（首次初始化）
|
||||
|
||||
如果你有一个现有的数据库需要纳入迁移管理，需要先创建基线：
|
||||
|
||||
```bash
|
||||
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. 查看迁移状态
|
||||
```bash
|
||||
# 检查当前迁移状态
|
||||
go run cmd/migrate/main.go -action status
|
||||
|
||||
# 指定环境
|
||||
go run cmd/migrate/main.go -action status -env production
|
||||
```
|
||||
|
||||
#### 2. 生成迁移文件
|
||||
```bash
|
||||
# 基于当前模型生成迁移（自动命名）
|
||||
go run cmd/migrate/main.go -action diff
|
||||
|
||||
# 生成带自定义名称的迁移
|
||||
go run cmd/migrate/main.go -action diff -name create_users_table
|
||||
```
|
||||
|
||||
#### 3. 应用迁移
|
||||
```bash
|
||||
# 应用所有待执行的迁移
|
||||
go run cmd/migrate/main.go -action apply
|
||||
|
||||
# 模拟执行（显示将要执行的SQL，不实际执行）
|
||||
go run cmd/migrate/main.go -action apply -dry-run
|
||||
```
|
||||
|
||||
#### 4. 验证迁移
|
||||
```bash
|
||||
# 验证迁移文件的有效性
|
||||
go run cmd/migrate/main.go -action validate
|
||||
```
|
||||
|
||||
#### 5. 重置迁移历史（危险操作）
|
||||
```bash
|
||||
# 显示重置指导（不会直接执行）
|
||||
go run cmd/migrate/main.go -action reset
|
||||
```
|
||||
|
||||
### 配置说明
|
||||
|
||||
- **atlas.hcl**: Atlas 主配置文件，定义数据源和环境
|
||||
- **atlas_loader.go**: GORM 模型加载器，需要在此文件中注册所有数据模型
|
||||
- **migrations/**: 存储生成的迁移文件
|
||||
|
||||
### 环境配置
|
||||
|
||||
#### 本地开发环境 (local)
|
||||
修改 `atlas.hcl` 中的 `env "local"` 配置：
|
||||
```hcl
|
||||
env "local" {
|
||||
url = "postgres://username:password@localhost:5432/your_database?sslmode=disable" // 开发数据库
|
||||
dev = "postgres://username:password@localhost:5432/dev_database?sslmode=disable" // 计算差异数据库
|
||||
}
|
||||
```
|
||||
|
||||
#### 生产环境 (production)
|
||||
```bash
|
||||
# 设置环境变量
|
||||
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` 中注册新模型：
|
||||
```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: 如何回滚迁移？**
|
||||
```bash
|
||||
# 回滚到指定版本
|
||||
atlas migrate down --env local --to-version 20231201120000
|
||||
```
|
||||
|
||||
**Q: 如何重置迁移历史？**
|
||||
```bash
|
||||
# 删除迁移历史表（谨慎操作）
|
||||
atlas migrate reset --env local
|
||||
```
|
||||
|
||||
**Q: 生产环境迁移失败怎么办？**
|
||||
1. 检查迁移文件语法
|
||||
2. 确认数据库权限
|
||||
3. 查看详细错误日志
|
||||
4. 必要时手动修复数据库状态
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user