合并来自 develop 的合并请求 #21
一个基于 Gin 框架的企业级 Go Web 应用模板，采用清晰的分层架构设计，内置依赖注入、健康检查、配置管理等企业级功能。
- 🏗️ 清晰的分层架构：Controller → Service → DAO → Model
- 🔧 依赖注入：基于 Assembly 模式的依赖管理
- 🌐 多数据库支持：MySQL、PostgreSQL
- 📦 Redis 缓存：内置 Redis 支持
- 📊 健康检查：完整的健康检查机制
- 🔧 配置管理：基于 Viper 的配置管理
- 📝 结构化日志：基于 Zap 的高性能日志
- 🚀 优雅启停：支持优雅关闭
- 🔄 自动迁移：数据库表结构自动迁移
| 企业微信 | |
|---|---|
 |  |
| QQ群：1021660914 点击链接加入群聊【木雷坞开源家】 | 扫描上方二维码加入微信群 |
git clone https://cnb.cool/mliev/examples/go-web
cd go-web
项目Fork后执行初始化脚本，自动替换模块路径：
./init.sh
# 复制配置文件
cp config.yaml.example config.yaml
# 编辑配置文件
vim config.yaml
go mod tidy
# 开发模式
go run main.go
# 或使用 Makefile
make run
go-web/
├── main.go # 程序入口
├── go.mod # Go模块定义
├── go.sum # 依赖版本锁定
├── README.md # 项目说明文档
├── config.yaml.example # 配置文件示例
├── config.yaml # 配置文件
├── init.sh # 项目初始化脚本
├── Dockerfile # Docker构建文件
├── docker-compose.yml # Docker编排文件
├── Makefile # 构建脚本
├── LICENSE # 许可证文件
├── app/ # 应用核心代码
│ ├── controller/ # 控制器层
│ │ ├── base_response.go # 统一响应封装
│ │ ├── health_controller.go # 健康检查
│ │ └── index_controller.go # 首页控制器
│ ├── service/ # 服务层（业务逻辑）
│ ├── dao/ # 数据访问层
│ │ └── test_demo_dao.go
│ ├── model/ # 数据模型
│ │ └── test_demo.go
│ ├── dto/ # 数据传输对象
│ │ ├── health_dto.go
│ │ └── response_dto.go
│ └── middleware/ # 中间件
│ └── cors_middleware.go
├── cmd/ # 命令行入口
│ └── run.go # 启动逻辑
├── config/ # 配置管理
│ ├── assembly.go # 依赖注入配置
│ ├── config.go # 基础配置
│ ├── migration.go # 迁移配置
│ ├── server.go # 服务器配置
│ └── autoload/ # 自动加载配置
│ ├── base.go
│ ├── database.go
│ ├── middleware.go
│ ├── redis.go
│ └── router.go
├── constants/ # 常量定义
│ └── errors.go # 错误码定义
├── docs/ # 文档
│ ├── PROJECT_SPECIFICATION.md
│ └── TEMPLATE_INIT.md
├── internal/ # 内部包
│ ├── helper/ # 内部助手
│ │ └── helper.go
│ ├── interfaces/ # 接口定义
│ │ ├── assembly.go
│ │ ├── config.go
│ │ ├── database.go
│ │ ├── env.go
│ │ ├── helper.go
│ │ ├── logger.go
│ │ ├── redis.go
│ │ └── server.go
│ ├── pkg/ # 内部包实现
│ │ ├── config/ # 配置包
│ │ ├── database/ # 数据库包
│ │ ├── demo/ # 示例包
│ │ ├── env/ # 环境变量包
│ │ ├── http_server/ # HTTP服务器包
│ │ ├── logger/ # 日志包
│ │ └── redis/ # Redis包
│ └── service/ # 内部服务
│ └── migration/ # 迁移服务
│ └── migration.go
└── util/ # 工具函数
├── base_62.go
└── generate_utils.go
| 技术 | 版本 | 描述 |
|---|---|---|
| Go | 1.23.2 | 编程语言 |
| Gin | 1.10.1 | Web框架 |
| GORM | 1.25.12 | ORM框架 |
| MySQL/PostgreSQL | - | 关系型数据库 |
| Redis | - | 缓存数据库 |
| Viper | 1.19.0 | 配置管理 |
| Zap | 1.27.0 | 结构化日志 |
┌─────────────────────────────────┐
│ HTTP Layer │
│ (Gin Router & Middleware) │
├─────────────────────────────────┤
│ Controller Layer │
│ (Request/Response Handling) │
├─────────────────────────────────┤
│ Service Layer │
│ (Business Logic) │
├─────────────────────────────────┤
│ DAO Layer │
│ (Data Access Objects) │
├─────────────────────────────────┤
│ Model Layer │
│ (Database Models) │
└─────────────────────────────────┘
项目采用 Assembly 模式实现依赖注入：
// Assembly 接口
type AssemblyInterface interface {
Assembly()
}
// 配置装配顺序
func (receiver AssemblyConfig) Get() []interfaces.AssemblyInterface {
return []interfaces.AssemblyInterface{
assembly.Env{}, // 环境配置
assembly.Logger{}, // 日志系统
assembly.Database{}, // 数据库连接
assembly.Redis{}, // Redis连接
}
}
# 完整健康检查
GET /health
# 简单健康检查
GET /health/simple
响应示例：
{
"code": 0,
"message": "操作成功",
"data": {
"status": "UP",
"timestamp": 1703123456,
"services": {
"database": {
"status": "UP"
},
"redis": {
"status": "UP"
}
}
}
}
GET /
# 服务配置
addr: ":8080"
mode: "debug" # debug, release
# 数据库配置
db:
driver: "postgresql" # postgresql, mysql
host: "127.0.0.1"
port: 5432
username: "test"
password: "123456"
dbname: "test"
# Redis配置
redis:
host: "127.0.0.1"
port: 6379
password: ""
db: 0
# 数据库迁移配置
database:
halt_on_migration_failure: true
- 使用
gofmt格式化代码 - 遵循 Go 官方命名规范
- 导出函数和类型必须添加注释
- 优先使用小接口，遵循单一职责原则
项目使用统一的错误码和响应格式：
// 错误码定义
const (
ErrCodeSuccess = 0 // 成功
ErrCodeBadRequest = 400 // 请求参数错误
ErrCodeUnauthorized = 401 // 未授权
ErrCodeNotFound = 404 // 资源不存在
ErrCodeInternal = 500 // 内部服务器错误
)
// 统一响应格式
type Response struct {
Code int `json:"code"`
Message string `json:"message"`
Data interface{} `json:"data,omitempty"`
}
使用 DAO 层封装数据库操作：
// app/dao/user_dao.go
func GetUserByUsername(username string) (*model.User, error) {
var user model.User
if err := helper.Database().Where("username = ?", username).First(&user); err != nil {
return nil, err
}
return &user, nil
}
# 构建镜像
docker build -t go-web-app .
# 运行容器
docker run -d -p 8080:8080 go-web-app
# 启动服务（包含数据库和Redis）
docker-compose up -d
# 查看日志
docker-compose logs -f
# 停止服务
docker-compose down
# 编译
go build -o bin/go-web main.go
# 运行
./bin/go-web
项目支持 Makefile 快速操作：
# 启动开发服务器
make run
# 构建项目
make build
# 运行测试
make test
# 格式化代码
make fmt
# 静态检查
make vet
# 清理构建文件
make clean
- 完整检查：
GET /health- 检查数据库、Redis等所有依赖服务 - 简单检查：
GET /health/simple- 仅检查服务是否启动
项目使用 Zap 进行结构化日志记录：
// 记录结构化日志
helper.Logger().Info("用户创建成功",
zap.String("username", username),
zap.Int("userID", userID),
)
支持通过环境变量覆盖配置文件：
export DB_HOST=localhost
export DB_PORT=5432
export DB_USERNAME=myuser
export DB_PASSWORD=mypass
export DB_DBNAME=mydb
export REDIS_HOST=localhost
export REDIS_PORT=6379
A: 在 config/autoload/router.go 中添加路由配置，在 app/controller/ 中实现控制器。
A: 在 app/middleware/ 中实现中间件，然后在 config/autoload/middleware.go 中注册。
A: 项目启动时会自动执行 AutoMigrate()，根据 Model 定义创建或更新表结构。
A: 修改 config.yaml 中的 db.driver 配置，支持 postgresql 和 mysql。
详细的开发规范请参考：
- Fork 项目
- 创建功能分支：
git checkout -b feature/AmazingFeature - 提交更改：
git commit -m 'Add some AmazingFeature' - 推送到分支：
git push origin feature/AmazingFeature - 开启 Pull Request
本项目基于 MIT 许可证，详情请查看 LICENSE 文件。
35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen
