Skeleton

一个基于 Go 的后端脚手架项目，内置 Gin、GORM、Redis、JWT、Atlas 迁移管理和 gin-docs 自动接口文档，适合作为新项目起点。

特性

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

快速开始

1. 安装依赖

go mod tidy

2. 配置环境

修改 config/app.yaml：

• app：主机、端口、版本、环境、时区
• logger：日志级别与输出方式
• database：PostgreSQL 连接信息
• redis：Redis 连接信息
• jwt：Token 配置

3. 启动项目

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 扩展入口

模板初始化

如果这是通过 GitHub Template 生成的新仓库，可以直接运行初始化脚本，把 go.mod 和源码里的包路径一次性改掉：

./scripts/init.sh github.com/yourname/yourrepo

脚本会自动完成：

• 更新 go.mod 的 module 名称
• 替换源码中的旧包路径
• 执行 go mod tidy

项目结构

.
├── main.go
├── config/
├── database/
├── middlewares/
├── models/
├── modules/
├── routes/
├── utils/
├── cmd/migrate/
├── atlas.hcl
├── atlas_loader.go
└── config/app.yaml

主要目录说明

• main.go：启动入口，负责初始化配置、日志、JWT、数据库、Redis、路由和文档
• routes/：REST 和 WebSocket 路由挂载
• middlewares/：日志、CORS、JWT、恢复处理
• database/：PostgreSQL 和 Redis 连接封装
• modules/：业务模块示例
• models/：GORM 模型
• utils/：响应、分页、时区等通用工具
• cmd/migrate/：迁移命令输出入口

数据库迁移

项目集成了 Atlas + GORM Provider，用于根据模型生成迁移。

相关文件

• atlas.hcl
• atlas_loader.go

安装 Atlas

brew install ariga/tap/atlas

或者：

go install ariga.io/atlas/cmd/atlas@latest

迁移命令

cmd/migrate 会根据参数输出对应的 Atlas 命令。

查看状态：

go run cmd/migrate/main.go -action status

生成迁移：

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 apply

验证迁移：

go run cmd/migrate/main.go -action validate

环境变量

atlas.hcl 使用以下环境变量：

• DATABASE_URL
• DATABASE_DEV_URL

扩展新模块

新增业务时建议按以下方式组织：

1. 在 modules/ 下创建新模块目录
2. 在 routes/rest/ 中注册路由
3. 公共接口挂到公开路由组
4. 需要登录态的接口挂到 /api/private
5. 如有模型变更，先更新 models/，再生成迁移

示例模块

项目内置 modules/example/ 作为参考实现，包含 controller、service 和 response 结构。

示例接口：

GET /api/example/hello

返回示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "message": "hello from skeleton example"
  }
}

默认配置

config/app.yaml 提供了可直接运行的本地示例配置。程序启动时会自动补充未填写的默认值，方便快速开发。

说明

这个脚手架的目标不是预置所有业务，而是把通用基础设施先搭好，方便后续按模块扩展。