这是一个基于 Gin 框架的 Go Web 应用最佳实践模板，采用领域驱动设计（DDD）风格的分层架构，包含了完整的项目结构和常用功能实现。
🚀 快速开始: 点击右上角 "Use this template" 按钮创建你的项目，或查看 使用指南
✨ 清晰的项目结构 - 采用 DDD 分层架构，职责明确，易于维护 🔐 JWT 认证 - 完整的用户认证和授权实现 📝 统一响应格式 - 标准化的 API 响应结构 ✅ 参数验证 - 基于 validator 的请求参数验证 🔄 中间件支持 - 日志、恢复、CORS、限流等常用中间件 💾 数据库集成 - 使用 GORM 进行数据库操作 📊 结构化日志 - 基于 zap 的结构化日志记录 🐳 Docker 支持 - 包含 Dockerfile 和 docker-compose 🔥 热重载 - 使用 Air 实现开发时热重载 🧪 完整测试 - Repository 单元测试示例
📚 Swagger 文档 - 自动生成交互式 API 文档 🧹 验证中间件 - 通用的 JSON 验证中间件 📈 Pprof 分析 - 内置性能分析工具 🔍 Sentry 监控 - 实时错误追踪和监控 🔗 OpenTelemetry - 分布式追踪支持
🧪 REST Client - VS Code 中直接测试 API 🎣 Pre-commit Hooks - 提交前自动代码检查 📏 golangci-lint - 全面的代码质量检查 ⚙️ EditorConfig - 统一的编辑器配置 🤖 GitHub Actions - 自动化 CI/CD 流程
gin-template/
├── cmd/
│ └── server/
│ └── main.go # 应用入口
├── internal/
│ ├── api/ # API 层
│ │ ├── handler/ # HTTP 处理器
│ │ ├── middleware/ # 中间件
│ │ └── router/ # 路由定义
│ ├── service/ # 业务逻辑层
│ ├── repository/ # 数据访问层
│ ├── model/ # 数据模型
│ └── dto/ # 数据传输对象
├── pkg/ # 可复用的公共库
│ ├── logger/ # 日志工具
│ ├── jwt/ # JWT 工具
│ ├── validator/ # 验证器
│ ├── response/ # 响应工具
│ └── database/ # 数据库工具
├── config/ # 配置文件
│ └── config.yaml
├── Makefile # Make 命令
├── Dockerfile # Docker 镜像构建
├── docker-compose.yml # Docker Compose 配置
└── .air.toml # Air 热重载配置
- Go 1.21+
- PostgreSQL 15+
- Redis 7+ (可选)
go mod tidy- 创建数据库：
createdb gin_template或使用 Makefile：
make init-db- 修改配置文件
config/config.yaml：
database:
host: localhost
port: 5432
database: gin_template
username: postgres
password: your_password直接运行：
go run cmd/server/main.go或使用 Makefile：
make run使用热重载（需要安装 Air）：
# 安装 Air
go install github.com/cosmtrek/air@latest
# 运行
air或：
make dev使用 Docker Compose：
docker-compose up应用将在 http://localhost:8080 启动。
启动应用后访问：
http://localhost:8080/swagger/index.html
生成/更新 Swagger 文档：
make swaggerGET /health注册用户：
POST /api/v1/users
Content-Type: application/json
{
"username": "testuser",
"email": "test@example.com",
"password": "password123",
"age": 25
}登录：
POST /api/v1/auth/login
Content-Type: application/json
{
"username": "testuser",
"password": "password123"
}返回示例：
{
"code": 0,
"message": "success",
"data": {
"token": "eyJhbGciOiJIUzI1NiIs...",
"user_id": "123",
"username": "testuser"
}
}获取用户列表：
GET /api/v1/users?page=1&page_size=10获取用户详情：
GET /api/v1/users/:id更新用户（需要认证）：
PUT /api/v1/users/:id
Authorization: Bearer <token>
Content-Type: application/json
{
"username": "newusername",
"email": "newemail@example.com"
}删除用户（需要认证和管理员权限）：
DELETE /api/v1/users/:id
Authorization: Bearer <token>- 在
internal/model中定义数据模型 - 在
internal/dto中定义 DTO - 在
internal/repository中实现数据访问层 - 在
internal/service中实现业务逻辑 - 在
internal/api/handler中实现 HTTP 处理器 - 在
internal/api/router中注册路由
make test生成测试覆盖率报告：
make test-coveragemake lintmake fmtmake build编译后的二进制文件将在 bin/server。
配置文件位于 config/config.yaml，支持以下配置项：
- server: 服务器配置（端口、模式、超时等）
- database: 数据库配置
- redis: Redis 配置
- jwt: JWT 配置（密钥、过期时间）
生产环境建议使用环境变量覆盖敏感配置：
export DB_PASSWORD=your_db_password
export JWT_SECRET=your_jwt_secret项目包含以下中间件：
- Logger: 请求日志记录
- Recovery: Panic 恢复
- CORS: 跨域资源共享
- Auth: JWT 认证
- RateLimit: 限流
- SecurityHeaders: 安全响应头
- Validate: 通用 JSON 验证中间件
- Pprof: 性能分析工具（可配置）
- Sentry: 错误监控（可配置）
- Tracing: OpenTelemetry 分布式追踪（可配置）
详细配置和使用方法请参考 高级功能指南
make docker-buildmake docker-rundocker-compose up -d这将启动以下服务：
- 应用服务（端口 8080）
- PostgreSQL 数据库（端口 5432）
- Redis 缓存（端口 6379）
本项目遵循以下最佳实践：
- 分层架构 - 清晰的职责分离，便于测试和维护
- 依赖注入 - 使用构造函数注入，提高可测试性
- 接口抽象 - Service 和 Repository 层使用接口定义
- 错误处理 - 统一的错误响应格式
- 参数验证 - 使用 validator 进行参数验证
- 安全实践 - 密码加密、JWT 认证、安全响应头
- 日志记录 - 结构化日志，便于问题排查
- 优雅关闭 - 处理完现有请求后再关闭服务
- 配置管理 - 使用配置文件和环境变量
- 容器化 - 提供 Docker 支持，便于部署
- 框架: Gin
- ORM: GORM
- 日志: Zap
- 配置: Viper
- JWT: golang-jwt
- 验证: validator
- 数据库: PostgreSQL
- 缓存: Redis（可选）
MIT License
欢迎提交 Issue 和 Pull Request！