readme重写
This commit is contained in:
Hericium-sys
@@ -1,222 +1,204 @@
|
|||||||
# Skeleton
|
# Skeleton
|
||||||
|
|
||||||
`skeleton/` 是基于 HeTianXia 项目整理出来的最小骨架目录，用来作为后续新项目的起点。
|
一个基于 Go 的后端脚手架项目，内置 Gin、GORM、Redis、JWT、Atlas 迁移管理和 `gin-docs` 自动接口文档，适合作为新项目起点。
|
||||||
|
|
||||||
## 当前包含
|
## 特性
|
||||||
|
|
||||||
- `main.go`：应用启动入口
|
- Gin HTTP 框架
|
||||||
- `config/`：配置结构与 YAML 示例
|
- 模块化路由组织
|
||||||
- `middlewares/`：日志、CORS、JWT 等基础中间件
|
- 统一响应结构
|
||||||
- `database/`：PostgreSQL 和 Redis 连接层
|
- JWT 认证中间件
|
||||||
- `routes/`：主路由、REST 注册器、WS 挂载点
|
- CORS、日志、恢复、错误记录中间件
|
||||||
- `utils/`：公共工具，如时区、分页、统一响应
|
- PostgreSQL 和 Redis 初始化封装
|
||||||
- `modules/example/`：最小示例模块
|
- Atlas + GORM Schema 迁移管理
|
||||||
- `models/`：最小模型占位，供 Atlas 和后续模块使用
|
- `gin-docs` 自动扫描接口并生成 OpenAPI 文档
|
||||||
- `atlas.hcl` 和 `atlas_loader.go`：Atlas CLI 迁移配置与模型加载入口
|
- 预留 WebSocket 挂载点
|
||||||
- `cmd/migrate/`：迁移命令入口占位
|
|
||||||
|
|
||||||
## 目录说明
|
## 快速开始
|
||||||
|
|
||||||
### `main.go`
|
### 1. 安装依赖
|
||||||
保留启动流程骨架：
|
|
||||||
|
|
||||||
- 加载配置
|
|
||||||
- 初始化日志
|
|
||||||
- 初始化 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
|
```bash
|
||||||
# macOS (推荐)
|
go mod tidy
|
||||||
brew install ariga/tap/atlas
|
|
||||||
|
|
||||||
# 或使用 go install
|
|
||||||
go install ariga.io/atlas/cmd/atlas@latest
|
|
||||||
|
|
||||||
# 验证安装
|
|
||||||
atlas version
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 安装 GORM Provider 依赖
|
### 2. 配置环境
|
||||||
|
|
||||||
需要单独执行，不会被`go mod tidy`命令检测到，因为构建排除了`atlas_loader.go`文件
|
修改 [`config/app.yaml`](/Users/xchou/Documents/code/skeleton/config/app.yaml)：
|
||||||
|
|
||||||
|
- `app`：主机、端口、版本、环境、时区
|
||||||
|
- `logger`：日志级别与输出方式
|
||||||
|
- `database`：PostgreSQL 连接信息
|
||||||
|
- `redis`：Redis 连接信息
|
||||||
|
- `jwt`：Token 配置
|
||||||
|
|
||||||
|
### 3. 启动项目
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
go get ariga.io/atlas-provider-gorm
|
go run .
|
||||||
|
```
|
||||||
|
|
||||||
|
默认监听地址由配置决定，示例为 `0.0.0.0:8080`。
|
||||||
|
|
||||||
|
## 接口文档
|
||||||
|
|
||||||
|
项目在启动时通过 `gin-docs` 自动挂载接口文档，无需手写 Swagger 注释。
|
||||||
|
|
||||||
|
默认文档地址：
|
||||||
|
|
||||||
|
- `/docs`
|
||||||
|
|
||||||
|
常见输出：
|
||||||
|
|
||||||
|
- `/docs/openapi.json`
|
||||||
|
- `/docs/openapi.yaml`
|
||||||
|
- `/docs/export/postman`
|
||||||
|
- `/docs/export/insomnia`
|
||||||
|
|
||||||
|
文档会根据 Gin 路由和 GORM 模型自动推断生成。
|
||||||
|
|
||||||
|
## 路由结构
|
||||||
|
|
||||||
|
所有 API 默认挂载在 `/api` 下。
|
||||||
|
|
||||||
|
### 公开接口
|
||||||
|
|
||||||
|
- `GET /api/ping`
|
||||||
|
- `GET /api/health`
|
||||||
|
- `GET /api/example/hello`
|
||||||
|
|
||||||
|
### 私有接口
|
||||||
|
|
||||||
|
- `/api/private/*`
|
||||||
|
|
||||||
|
该分组默认挂载 JWT 认证中间件，适合后续需要登录态的业务接口。
|
||||||
|
|
||||||
|
### WebSocket
|
||||||
|
|
||||||
|
- `routes/ws/` 预留 WebSocket 扩展入口
|
||||||
|
|
||||||
|
## 项目结构
|
||||||
|
|
||||||
|
```text
|
||||||
|
.
|
||||||
|
├── main.go
|
||||||
|
├── config/
|
||||||
|
├── database/
|
||||||
|
├── middlewares/
|
||||||
|
├── models/
|
||||||
|
├── modules/
|
||||||
|
├── routes/
|
||||||
|
├── utils/
|
||||||
|
├── cmd/migrate/
|
||||||
|
├── atlas.hcl
|
||||||
|
├── atlas_loader.go
|
||||||
|
└── config/app.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
## 主要目录说明
|
||||||
|
|
||||||
|
- [`main.go`](/Users/xchou/Documents/code/skeleton/main.go)：启动入口，负责初始化配置、日志、JWT、数据库、Redis、路由和文档
|
||||||
|
- [`routes/`](/Users/xchou/Documents/code/skeleton/routes)：REST 和 WebSocket 路由挂载
|
||||||
|
- [`middlewares/`](/Users/xchou/Documents/code/skeleton/middlewares)：日志、CORS、JWT、恢复处理
|
||||||
|
- [`database/`](/Users/xchou/Documents/code/skeleton/database)：PostgreSQL 和 Redis 连接封装
|
||||||
|
- [`modules/`](/Users/xchou/Documents/code/skeleton/modules)：业务模块示例
|
||||||
|
- [`models/`](/Users/xchou/Documents/code/skeleton/models)：GORM 模型
|
||||||
|
- [`utils/`](/Users/xchou/Documents/code/skeleton/utils)：响应、分页、时区等通用工具
|
||||||
|
- [`cmd/migrate/`](/Users/xchou/Documents/code/skeleton/cmd/migrate/main.go)：迁移命令输出入口
|
||||||
|
|
||||||
|
## 数据库迁移
|
||||||
|
|
||||||
|
项目集成了 Atlas + GORM Provider，用于根据模型生成迁移。
|
||||||
|
|
||||||
|
### 相关文件
|
||||||
|
|
||||||
|
- [`atlas.hcl`](/Users/xchou/Documents/code/skeleton/atlas.hcl)
|
||||||
|
- [`atlas_loader.go`](/Users/xchou/Documents/code/skeleton/atlas_loader.go)
|
||||||
|
|
||||||
|
### 安装 Atlas
|
||||||
|
|
||||||
|
```bash
|
||||||
|
brew install ariga/tap/atlas
|
||||||
|
```
|
||||||
|
|
||||||
|
或者：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
go install ariga.io/atlas/cmd/atlas@latest
|
||||||
```
|
```
|
||||||
|
|
||||||
### 迁移命令
|
### 迁移命令
|
||||||
|
|
||||||
#### 0. 基线迁移（首次初始化）
|
`cmd/migrate` 会根据参数输出对应的 Atlas 命令。
|
||||||
|
|
||||||
如果你有一个现有的数据库需要纳入迁移管理，需要先创建基线：
|
查看状态：
|
||||||
|
|
||||||
```bash
|
```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
|
||||||
|
|
||||||
# 指定环境
|
|
||||||
go run cmd/migrate/main.go -action status -env production
|
|
||||||
```
|
```
|
||||||
|
|
||||||
#### 2. 生成迁移文件
|
生成迁移：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 基于当前模型生成迁移（自动命名）
|
|
||||||
go run cmd/migrate/main.go -action diff
|
go run cmd/migrate/main.go -action diff
|
||||||
|
go run cmd/migrate/main.go -action diff -name create_users
|
||||||
# 生成带自定义名称的迁移
|
|
||||||
go run cmd/migrate/main.go -action diff -name create_users_table
|
|
||||||
```
|
```
|
||||||
|
|
||||||
#### 3. 应用迁移
|
应用迁移：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 应用所有待执行的迁移
|
|
||||||
go run cmd/migrate/main.go -action apply
|
go run cmd/migrate/main.go -action apply
|
||||||
|
|
||||||
# 模拟执行（显示将要执行的SQL，不实际执行）
|
|
||||||
go run cmd/migrate/main.go -action apply -dry-run
|
|
||||||
```
|
```
|
||||||
|
|
||||||
#### 4. 验证迁移
|
验证迁移：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 验证迁移文件的有效性
|
|
||||||
go run cmd/migrate/main.go -action validate
|
go run cmd/migrate/main.go -action validate
|
||||||
```
|
```
|
||||||
|
|
||||||
#### 5. 重置迁移历史（危险操作）
|
### 环境变量
|
||||||
|
|
||||||
|
`atlas.hcl` 使用以下环境变量：
|
||||||
|
|
||||||
|
- `DATABASE_URL`
|
||||||
|
- `DATABASE_DEV_URL`
|
||||||
|
|
||||||
|
## 扩展新模块
|
||||||
|
|
||||||
|
新增业务时建议按以下方式组织：
|
||||||
|
|
||||||
|
1. 在 `modules/` 下创建新模块目录
|
||||||
|
2. 在 `routes/rest/` 中注册路由
|
||||||
|
3. 公共接口挂到公开路由组
|
||||||
|
4. 需要登录态的接口挂到 `/api/private`
|
||||||
|
5. 如有模型变更，先更新 `models/`，再生成迁移
|
||||||
|
|
||||||
|
## 示例模块
|
||||||
|
|
||||||
|
项目内置 `modules/example/` 作为参考实现，包含 controller、service 和 response 结构。
|
||||||
|
|
||||||
|
示例接口：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 显示重置指导（不会直接执行）
|
GET /api/example/hello
|
||||||
go run cmd/migrate/main.go -action reset
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 配置说明
|
返回示例：
|
||||||
|
|
||||||
- **atlas.hcl**: Atlas 主配置文件，定义数据源和环境
|
```json
|
||||||
- **atlas_loader.go**: GORM 模型加载器，需要在此文件中注册所有数据模型
|
{
|
||||||
- **migrations/**: 存储生成的迁移文件
|
"code": 200,
|
||||||
|
"message": "success",
|
||||||
### 环境配置
|
"data": {
|
||||||
|
"message": "hello from skeleton example"
|
||||||
#### 本地开发环境 (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"
|
|
||||||
|
|
||||||
# 应用迁移
|
`config/app.yaml` 提供了可直接运行的本地示例配置。程序启动时会自动补充未填写的默认值，方便快速开发。
|
||||||
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