Gonio - 轻量级 Golang 后端脚手架

English | 中文

Gonio 是一个轻量级 Golang 后端脚手架，开箱即用，适合快速构建生产环境应用。基于 Gin + GORM + Redis + MySQL 技术栈，集成了分布式限流、JWT 认证、事务管理、缓存防护、消息队列等实用功能。

适用场景：中小型项目、API 服务、管理后台、快速原型开发、个人或团队项目

✨ 核心特性

🚀 开箱即用的实用功能

• 分布式限流：基于 Redis Lua 脚本的原子化限流，支持 IP + 路由 + 方法多维度控制
• 缓存防护体系：
  • Singleflight 防缓存击穿（Cache Stampede Prevention）
  • TTL 随机抖动防缓存雪崩（Cache Avalanche Prevention）
  • 空值缓存防缓存穿透（Cache Penetration Protection）
• 事务管理：跨 Repository 的事务支持，保证数据一致性
• 智能日志：请求体自动脱敏，避免大文件日志导致的内存问题
• 优雅停机：确保请求处理完成后再关闭服务

🏗️ 清晰的架构设计

• 分层架构：Handler -> Service -> Repository，职责清晰，易于测试
• 依赖注入：通过 ServiceContext 统一管理依赖，降低耦合
• 中间件体系：RequestID、Logger、Recovery、CORS、I18n、Auth、RateLimit
• 类型安全的消息队列：基于 Watermill 的泛型消息处理系统

🔒 安全与合规

• JWT 双端认证：App 端和 Admin 端独立的认证体系
• 环境变量强制：JWT Secret 等敏感配置必须通过环境变量设置
• 请求体大小限制：防止 OOM 攻击
• 安全响应头：自动添加 HTTP 安全相关响应头

📊 可观测性

• 结构化日志：基于 Zap 的高性能日志系统
• 请求链路追踪：RequestID 贯穿整个请求生命周期
• 数据库查询日志：GORM 慢查询监控
• Redis 操作日志：完整的缓存操作记录

🛠️ 技术栈

组件	技术选型	说明
Web 框架	Gin	高性能 HTTP 路由和中间件
ORM	GORM	支持事务、钩子、预加载
缓存	Redis	分布式缓存 + 限流 + 消息队列
数据库	MySQL 8.0+	主数据存储
消息队列	Watermill	支持 Redis Streams / MySQL 后端
日志	Zap	高性能结构化日志
配置	Viper	支持环境变量覆盖
校验	go-playground/validator	I18n 错误信息

📁 项目结构

.
├── cmd/
│   └── server/              # 服务启动入口
├── config/                  # 配置文件（YAML）
├── internal/
│   ├── config/             # 配置结构体与加载
│   ├── database/           # 数据库连接与迁移
│   ├── handler/            # HTTP 请求处理层
│   ├── middleware/         # 中间件（Auth、RateLimit、Logger 等）
│   ├── model/              # 数据模型（GORM）
│   ├── mq/                 # 消息队列（Publisher、Subscriber、Registry）
│   ├── pkg/
│   │   ├── cache/          # 缓存工具（Singleflight、TTL Jitter）
│   │   ├── errcode/        # 错误码定义
│   │   ├── ratelimit/      # Redis Lua 限流器
│   │   ├── response/       # 统一响应格式
│   │   └── validator/      # I18n 校验器
│   ├── repository/         # 数据访问层（支持事务）
│   ├── router/             # 路由注册
│   ├── service/            # 业务逻辑层
│   └── svc/                # ServiceContext 依赖注入容器
├── migration/              # 数据库迁移脚本
├── go.mod
└── Makefile

🚀 快速开始

环境要求

• Go 1.25+
• MySQL 8.0+
• Redis 6.0+

安装运行

# 克隆项目
git clone https://github.com/your-username/Gonio.git
cd Gonio

# 安装依赖
go mod tidy

# 配置环境变量（必需）
export JWT_SECRET="your-secret-key"
export DB_PASSWORD="your-db-password"

# 运行服务
make run

健康检查

curl http://localhost:8080/health

💡 核心功能示例

1. 分布式限流

基于 Redis Lua 脚本实现原子化限流，支持按 IP + 路由 + 方法 维度控制：

// 商品列表：每秒 1 次请求
router.GET("/products", 
    middleware.RateLimit(svcCtx, "1s", 1),
    handler.ListProducts)

// 商品创建：每 3 秒 1 次请求
router.POST("/products", 
    middleware.RateLimit(svcCtx, "3s", 1),
    handler.CreateProduct)

特点：

• 原子操作，无竞态条件
• 自动清理过期键
• 支持动态配置

2. 缓存防护体系

// Service 层使用 Singleflight 防止缓存击穿
product, err := s.cache.GetOrLoad(ctx, cacheKey, 
    func(ctx context.Context) (*model.Product, error) {
        return s.repo.GetByID(ctx, id)
    },
    cache.WithTTL(5*time.Minute),
    cache.WithJitter(0.1), // 10% TTL 随机抖动
)

防护机制：

• 击穿防护：Singleflight 合并并发请求
• 雪崩防护：TTL 随机抖动（±10%）
• 穿透防护：空值缓存

3. 跨 Repository 事务

err := s.db.Transaction(ctx, func(txCtx context.Context) error {
    // 创建订单
    order, err := s.orderRepo.Create(txCtx, orderData)
    if err != nil {
        return err
    }
    
    // 扣减库存
    err = s.productRepo.DecrementStock(txCtx, productID, quantity)
    if err != nil {
        return err
    }
    
    return nil
})

4. 类型安全的消息队列

// 定义消息类型
type OrderCreatedPayload struct {
    OrderID   string
    UserID    string
    Amount    float64
}

// 发布消息
err := publisher.Publish(ctx, mq.TopicOrderCreated, OrderCreatedPayload{
    OrderID: "ORD123",
    UserID:  "USR456",
    Amount:  99.99,
})

// 订阅消息（泛型处理器）
mq.RegisterHandler(TopicOrderCreated, func(ctx context.Context, payload OrderCreatedPayload) error {
    // 处理订单创建事件
    return sendNotification(ctx, payload)
})

📋 API 概览

App 端 API (/app/v1/*)

• 用户注册、登录、信息查询
• 商品列表、详情查询
• JWT 认证保护

Admin 端 API (/admin/v1/*)

• 管理员登录
• 商品管理（CRUD）
• 独立的 JWT 认证体系

系统 API

• GET /health - 健康检查（带依赖检测）

🎯 适用场景

场景	说明
中小型项目	快速搭建 API 服务，无需从零开始
管理后台	用户管理、权限控制、数据 CRUD
API 服务	RESTful API、微服务、BFF 层
快速原型	MVP 开发、概念验证、技术演示
学习实践	Go 后端开发学习、架构模式参考

🔧 配置说明

环境变量（必需）

# JWT 密钥（生产环境必须设置）
export JWT_SECRET="your-secret-key-min-32-chars"

# 数据库密码
export DB_PASSWORD="your-db-password"

配置文件 (config/config.yaml)

server:
  port: 8080
  mode: release  # debug / release

database:
  host: localhost
  port: 3306
  username: root
  database: gonio
  
redis:
  host: localhost
  port: 6379
  db: 0

🧪 测试

# 运行所有测试
make test

# 运行单元测试
go test ./internal/service/...

# 查看测试覆盖率
make test-coverage

🗺️ 开发路线

• 基础架构与中间件
• JWT 双端认证
• Redis 分布式限流
• 缓存防护体系（击穿、雪崩、穿透）
• 跨 Repository 事务支持
• 消息队列集成
• 智能请求日志
• 滑动窗口限流算法
• OpenAPI / Swagger 文档
• Prometheus 指标导出
• OpenTelemetry 链路追踪
• Docker / Kubernetes 部署配置

🤝 参与贡献

欢迎提交 Issue 和 Pull Request！

贡献指南

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 文件

🌟 Star History

如果这个项目对你有帮助，欢迎给个 ⭐ 支持！

🔧 推荐工具

RRdis - 现代化 Redis 管理客户端

在使用 Gonio 开发时，推荐使用 RRdis 来管理和调试 Redis：

• 流式数据加载：轻松处理 1MB+ 大数据，无卡顿
• 智能 CLI：内置命令行，支持自动补全和语法高亮
• 多窗口隔离：完美支持多数据库切换，互不干扰
• 原生性能：基于 Tauri 2 + Rust，启动快、内存占用低
• 开发者友好：JSON 自动格式化、一键复制、暗黑模式

下载地址：https://daichongdev.github.io/rrdis-web/

---

关键词：Golang 后端脚手架、轻量级 Go 框架、Gin 框架、Redis 限流、分布式限流、缓存击穿、缓存雪崩、JWT 认证、Clean Architecture、GORM 事务、消息队列、Go API 模板