一个基于 Gin 框架的企业级 Go Web 应用模板，采用清晰的分层架构设计，内置依赖注入、健康检查、配置管理等企业级功能。

• 🏗️ 清晰的分层架构：Controller → Service → DAO → Model
• 🔧 依赖注入：基于 Assembly 模式的依赖管理
• 🌐 多数据库支持：MySQL、PostgreSQL
• 📦 Redis 缓存：内置 Redis 支持
• 📊 健康检查：完整的健康检查机制
• 🔧 配置管理：基于 Viper 的配置管理
• 📝 结构化日志：基于 Zap 的高性能日志
• 🚀 优雅启停：支持优雅关闭
• 🔄 自动迁移：数据库表结构自动迁移

QQ	企业微信
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。

详细的开发规范请参考：

• 项目规范文档
• 模板初始化说明

1. Fork 项目
2. 创建功能分支：git checkout -b feature/AmazingFeature
3. 提交更改：git commit -m 'Add some AmazingFeature'
4. 推送到分支：git push origin feature/AmazingFeature
5. 开启 Pull Request

本项目基于 MIT 许可证，详情请查看 LICENSE 文件。