gin-advanced-layout

基于Gin的高级项目布局，采用清晰的分层架构和Wire依赖注入框架，实现了可维护、可测试的企业级Go Web应用结构。

特性

• 🏗️ 清晰的分层架构: 采用数据层、业务逻辑层、处理器层的经典分层设计
• 💉 Wire依赖注入: 使用Google Wire进行编译时依赖注入，消除全局状态
• 🔐 JWT认证: 完整的JWT token生成和验证机制
• ❄️ Snowflake ID: 分布式唯一ID生成服务
• 📝 结构化日志: 基于zap的高性能结构化日志
• 🗄️ 数据库集成: 支持MySQL和Redis的连接池管理
• 🔧 配置管理: 基于Viper的灵活配置系统

脚手架工具 👉 iaa

目录结构

├── api/                    # API响应和错误码定义
│   ├── api.go             # 通用API响应结构
│   ├── calc/              # 计算相关API定义
│   └── code.go            # 错误码常量
├── cmd/                   # 应用入口点
│   ├── gen/               # 代码生成工具
│   └── server/            # 主服务器入口
├── config/                # 配置文件
│   └── config.yaml        # 主配置文件
├── internal/              # 内部应用代码
│   ├── app/               # 应用层，Wire依赖注入配置
│   │   ├── app.go         # Provider函数定义  
│   │   ├── wire.go        # Wire注入器定义
│   │   └── wire_gen.go    # Wire生成的代码
│   ├── biz/               # 业务逻辑层
│   │   └── calc/          # 计算业务逻辑
│   ├── conf/              # 配置加载
│   ├── data/              # 数据访问层
│   │   └── calc/          # 计算数据访问
│   ├── handler/           # HTTP处理器层
│   │   └── calc/          # 计算处理器
│   ├── middleware/        # 中间件
│   │   └── auth.go        # JWT认证中间件
│   └── server/            # 服务器配置
├── pkg/                   # 可重用的包
│   ├── jwt/               # JWT服务
│   ├── logging/           # 日志服务  
│   └── snowflake/         # Snowflake ID生成服务
└── example_usage.go       # 使用示例

架构设计

分层架构

项目采用经典的分层架构设计：

┌─────────────────┐
│   HTTP Handler  │  ← 处理HTTP请求，参数验证
├─────────────────┤
│   Business Logic│  ← 业务逻辑处理
├─────────────────┤  
│   Data Access   │  ← 数据访问，数据库操作
├─────────────────┤
│   Infrastructure│  ← 基础设施（数据库、缓存、日志等）
└─────────────────┘

依赖注入

使用Google Wire进行编译时依赖注入：

• Provider: 在 internal/app/app.go 中定义所有服务的构造函数
• Injector: 在 internal/app/wire.go 中定义依赖关系
• Generated: Wire自动生成 wire_gen.go 完成依赖装配

快速开始

1. 安装依赖

go mod tidy

2. 安装Wire工具

go install github.com/google/wire/cmd/wire@latest

3. 生成依赖注入代码

wire ./internal/app

4. 配置数据库

修改配置文件 config/config.yaml 中的数据库配置：

mysql:
  host: "127.0.0.1"
  port: "3306"
  user: "root"
  password: "your_password"
  dbname: "your_database"

redis:
  host: "127.0.0.1"
  port: 6379
  password: ""
  db: 0

5. 运行服务

go run cmd/server/main.go

6. 测试接口

curl http://localhost:8080/ping
curl http://localhost:8080/api/v1/add?a=1&b=2

核心组件使用

JWT服务

// 通过依赖注入获取JWT服务
jwtService := jwt.NewJWT(cfg)

// 生成访问令牌
accessToken, err := jwtService.GenAccessToken(userID, username)

// 解析令牌
claims, err := jwtService.ParseAccessToken(token)

Snowflake ID生成

// 通过依赖注入获取Snowflake服务
snowflakeService, err := snowflake.NewSnowflake(cfg)

// 生成唯一ID
id, err := snowflakeService.NextID()

认证中间件

// 在路由中使用认证中间件
authMiddleware := middleware.Auth(jwtService, logger)
protected := r.Group("/api/v1")
protected.Use(authMiddleware)

开发指南

添加新的业务功能

1. 数据层: 在 internal/data/ 下创建数据访问接口和实现
2. 业务层: 在 internal/biz/ 下创建业务逻辑接口和实现
3. 处理器: 在 internal/handler/ 下创建HTTP处理器
4. Provider: 在 internal/app/app.go 中添加对应的Provider函数
5. Wire配置: 在 internal/app/wire.go 的ProviderSet中添加新的Provider
6. 重新生成: 运行 wire ./internal/app 重新生成依赖注入代码

项目规范

• 使用接口进行抽象，便于测试和替换实现
• 通过依赖注入管理组件生命周期
• 避免使用全局变量和单例模式
• 每层只依赖下层接口，不跨层调用
• 使用结构化日志记录关键操作

技术栈

• Web框架: Gin
• 依赖注入: Wire
• ORM: GORM
• 缓存: go-redis
• 日志: Zap
• 配置: Viper
• JWT: golang-jwt
• ID生成: Sonyflake

许可证

MIT License