readme重写

2026-04-25 13:41:39 +08:00
parent 62b87c6002
commit be95e23935
1 changed files with 159 additions and 177 deletions
@@ -1,222 +1,204 @@
 # Skeleton

-`skeleton/` 是基于 HeTianXia 项目整理出来的最小骨架目录，用来作为后续新项目的起点。
+一个基于 Go 的后端脚手架项目，内置 Gin、GORM、Redis、JWT、Atlas 迁移管理和 `gin-docs` 自动接口文档，适合作为新项目起点。

-## 当前包含
+## 特性

- `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/`：迁移命令入口占位
+- Gin HTTP 框架
+- 模块化路由组织
+- 统一响应结构
+- JWT 认证中间件
+- CORS、日志、恢复、错误记录中间件
+- PostgreSQL 和 Redis 初始化封装
+- Atlas + GORM Schema 迁移管理
+- `gin-docs` 自动扫描接口并生成 OpenAPI 文档
+- 预留 WebSocket 挂载点

-## 目录说明
+## 快速开始

-### `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
+### 1. 安装依赖

 ```bash
-# macOS (推荐)
-brew install ariga/tap/atlas
-
-# 或使用 go install
-go install ariga.io/atlas/cmd/atlas@latest
-
-# 验证安装
-atlas version
+go mod tidy
 ```

-### 安装 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
-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
-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
+go run cmd/migrate/main.go -action diff -name create_users
 ```

-#### 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. 重置迁移历史（危险操作）
+### 环境变量
+
+`atlas.hcl` 使用以下环境变量：
+
+- `DATABASE_URL`
+- `DATABASE_DEV_URL`
+
+## 扩展新模块
+
+新增业务时建议按以下方式组织：
+
+1. 在 `modules/` 下创建新模块目录
+2. 在 `routes/rest/` 中注册路由
+3. 公共接口挂到公开路由组
+4. 需要登录态的接口挂到 `/api/private`
+5. 如有模型变更，先更新 `models/`，再生成迁移
+
+## 示例模块
+
+项目内置 `modules/example/` 作为参考实现，包含 controller、service 和 response 结构。
+
+示例接口：
+
 ```bash
-# 显示重置指导（不会直接执行）
-go run cmd/migrate/main.go -action reset
+GET /api/example/hello
 ```

-### 配置说明
+返回示例：

- **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"  // 计算差异数据库
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "message": "hello from skeleton example"
+  }
 }
 ```

-#### 生产环境 (production)
-```bash
-# 设置环境变量
-export DATABASE_URL="postgres://user:pass@host:port/db?sslmode=require"
+## 默认配置

-# 应用迁移
-go run cmd/migrate/main.go -action apply -env production
-```
+`config/app.yaml` 提供了可直接运行的本地示例配置。程序启动时会自动补充未填写的默认值，方便快速开发。

-### 添加新模型
+## 说明

-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. 必要时手动修复数据库状态
-
---
+这个脚手架的目标不是预置所有业务，而是把通用基础设施先搭好，方便后续按模块扩展。