go-infra

README

go-infra

一个高性能、生产就绪的 Go 语言基础设施 SDK 库

📖 简介

go-infra 是一个经过生产环境验证的 Go 语言基础设施库，提供了微服务开发中常用的功能模块，包括日志、追踪、监控、数据库、缓存等，帮助开发者快速构建高性能、可观测的应用。

✨ 核心特性

• 🚀 高性能优化 - 对象池、连接池等优化，支持高并发场景
• 🔍 完整的可观测性 - 集成日志、追踪、监控（基于 OpenTelemetry）
• 🛡️ 生产就绪 - 经过性能优化和并发安全验证
• 📦 开箱即用 - 提供合理的默认配置
• 🔧 灵活配置 - 支持自定义配置，满足不同场景需求
• 🤖 AI 统一接入 - 提供 LLM 多厂商统一调用与主备切换能力
• 📝 详细文档 - 每个模块都有完整的使用示例

📦 功能模块

层级	模块	说明	文档
base	log	高性能异步日志（支持链路追踪）	查看文档
base	trace	分布式链路追踪（OpenTelemetry）	查看文档
base	config	通用配置加载（YAML + 环境覆盖 + 加密）	查看文档
base	errors	统一错误处理和 HTTP 状态码封装	查看文档
base	env	环境变量与模式管理	pkg/base/env/
base	uuid	Snowflake / UUID ID 生成	pkg/base/uuid/
base	datetime	API JSON 时间类型（2006-01-02 15:04:05）	pkg/base/datetime/
base	xutil	通用泛型工具函数（含日/周/月区间计算）	pkg/base/xutil/
infra	mysql	MySQL/GORM 客户端（连接池管理）	查看文档
infra	redis	Redis 客户端（单机/集群）	查看文档
infra	milvus	Milvus 向量数据库客户端（连接池）	查看文档
infra	metrics	Prometheus 监控指标采集	查看文档
infra	traffic	流量控制（限流/熔断接口）	查看文档
infra	http_client	HTTP 客户端（连接池复用）	查看文档
infra	grpc	gRPC 客户端/服务端统一封装（拦截器/治理）	查看文档
infra	websocket	WebSocket 长连接封装（心跳/重连/Hub）	查看文档
infra	llm	大模型统一调用 SDK（多厂商协议抽象）	查看文档
infra	apollo	Apollo 配置中心	pkg/infra/apollo/
infra	objstore	S3 兼容对象存储（KS3/OSS/OBS/MinIO 等）	查看文档
biz	login	多方式登录（密码/手机/邮箱/微信）+ JWT	查看文档
biz	account	账号管理与多登录方式绑定	查看文档
biz	pay	微信支付 APIv3 / 支付宝 RSA2	查看文档
biz	collab	跨端实时协作引擎（定序/去重/回放/订阅）	查看文档
biz	controller	Gin 基础控制器（统一响应格式）	pkg/biz/controller/
biz	middlewares	Gin 中间件（日志/追踪/CORS 等）	pkg/biz/middlewares/

🚀 快速开始

安装

go get github.com/liukunxin/go-infra

基础示例

package main

import (
    "github.com/gin-gonic/gin"
    "github.com/liukunxin/go-infra/pkg/base/log"
    "github.com/liukunxin/go-infra/pkg/base/trace"
    "github.com/liukunxin/go-infra/pkg/infra/metrics"
    "github.com/liukunxin/go-infra/pkg/biz/middlewares"
)

func main() {
    // 1. 初始化日志
    log.Init(log.Config{
        Level: log.LevelInfo,
    })

    // 2. 初始化链路追踪
    trace.Init(
        trace.WithServiceName("my-service"),
    )

    // 3. 创建 Gin 路由
    router := gin.Default()

    // 4. 初始化监控（自动注册 /metrics 路由）
    metrics.InitMetrics("my-service", router)

    // 5. 注册中间件
    router.Use(middlewares.GinTraceMiddleware())  // 链路追踪
    router.Use(middlewares.HttpLogRecord())       // 日志记录

    // 6. 定义路由
    router.GET("/hello", func(c *gin.Context) {
        log.WithContext(c.Request.Context()).Info("处理hello请求")
        c.JSON(200, gin.H{"message": "Hello World"})
    })

    // 7. 启动服务
    router.Run(":8080")
}

📚 详细文档

pkg/base — 原子基础能力

• 错误处理 (errors) - 统一的错误处理和状态码管理
• 日志系统 (log) - 高性能异步日志，支持链路追踪
• 链路追踪 (trace) - 基于 OpenTelemetry 的分布式追踪

pkg/infra — 基础设施能力

• MySQL - GORM 封装，连接池管理
• Redis - Redis 客户端，支持单机/集群模式
• Milvus - 向量数据库客户端，连接池管理
• 监控指标 (metrics) - Prometheus 指标采集
• HTTP 客户端 - 带连接池的 HTTP 客户端
• gRPC - gRPC 客户端/服务端统一封装
• WebSocket - WebSocket 长连接封装
• 流量控制 (traffic) - 限流/熔断接口
• LLM SDK - 大模型统一调用（支持 OpenAI 兼容协议）

pkg/biz — 业务基础能力

• 实时协作 (collab) - 跨端实时协作引擎（全局定序/幂等去重/历史回放/实时订阅）
• 登录 (login) - 多方式登录 + JWT
• 账号 (account) - 账号管理与登录绑定
• 支付 (pay) - 微信 / 支付宝支付封装

🏗️ 架构设计

可观测性架构

┌─────────────────────────────────────────────────────────┐
│                      应用程序                             │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │   Log    │  │  Trace   │  │ Metrics  │              │
│  │ (日志)    │  │ (追踪)    │  │ (监控)    │              │
│  └─────┬────┘  └─────┬────┘  └─────┬────┘              │
│        │             │              │                   │
│        └─────────────┴──────────────┘                   │
│                      │                                  │
│              OpenTelemetry SDK                          │
├─────────────────────────────────────────────────────────┤
│        Exporter (Jaeger/Prometheus/etc)                │
└─────────────────────────────────────────────────────────┘

连接池管理

应用程序
  ├─ MySQL连接池 (GORM)
  │   └─ 默认配置: MaxOpen=100, MaxIdle=10
  ├─ Redis连接池
  │   └─ 支持单机/集群模式
  ├─ HTTP连接池
  │   └─ 支持连接复用和超时控制
  └─ Milvus连接池
      └─ 自定义连接池实现

🔥 性能优化

本库在以下方面进行了性能优化：

• ✅ 对象池 - 日志、HTTP等模块使用sync.Pool减少GC压力
• ✅ 连接池 - 数据库、Redis、HTTP连接池复用
• ✅ 异步日志 - 基于环形队列的无锁日志系统
• ✅ 并发安全 - 所有模块都经过并发安全验证
• ✅ 零拷贝 - 减少不必要的内存分配和复制

🔐 配置加密

支持对敏感配置值（数据库密码、API Key 等）进行 AES-256-GCM 加密存储，运行时自动解密：

# configs/config.prod.yml
mysql:
  host: 10.0.1.100
  password: "ENC(nonce+ciphertext的base64)"
redis:
  password: "ENC(...)"

cfg := config.MustLoad[App](
    config.WithDecrypt(config.AESKeyFromEnv("CONFIG_ENCRYPT_KEY")),
)

• 不传 WithDecrypt 时行为完全不变，零侵入
• 密钥通过环境变量注入，推荐 K8s Secret 管理
• 使用 go-infra-cli keygen / encrypt / decrypt 命令生成密钥和加密值
• 详见 配置模块文档

💡 最佳实践

初始化顺序

建议按以下顺序初始化各模块：

1. 日志 (log)          - 最先初始化，其他模块可能依赖
2. 追踪 (trace)        - 尽早初始化，用于记录启动过程
3. 数据库 (mysql/redis) - 建立数据库连接
4. 路由 (gin)          - 创建HTTP服务
5. 监控 (metrics)      - 注册监控端点
6. 中间件              - 注册全局中间件

错误处理

import kerr "github.com/liukunxin/go-infra/pkg/base/errors"

// 业务逻辑中
if err != nil {
    return kerr.WarpError(kerr.StatusBadRequest, 40001, err)
}

// 在Controller中
func (b *GinBase) MyHandler(c *gin.Context) {
    if err := doSomething(); err != nil {
        b.ErrorResponse(c, err)  // 自动处理错误响应
        return
    }
    b.SuccessResponse(c, data)
}

日志记录

// 带上下文的日志（自动包含TraceID）
log.WithContext(ctx).Info("用户登录成功")

// 带字段的日志
log.WithContext(ctx).WithFields(map[string]interface{}{
    "user_id": 123,
    "action": "login",
}).Info("用户操作")

📊 监控指标

自动采集的指标：

• http_requests_total - HTTP请求总数（按method、path、status分组）
• http_request_duration_ms - HTTP请求延迟（直方图）

可通过 /metrics 端点访问。

🤝 贡献

欢迎提交Issue和Pull Request！

开发规范

• 所有公开API需要添加注释
• 新增功能需要提供使用示例
• 性能敏感模块需要进行基准测试
• 确保并发安全

新增包后的同步 Checklist

新增 pkg/infra/xxx 或 pkg/biz/xxx 包后，需同步更新 scaffold（否则 AI 辅助编码时不会感知到新包）：

• scaffold/skills/go-infra-reference/SKILL.md — 包地图表格新增一行
• scaffold/skills/go-infra-reference/reference.md — 补充典型用法代码示例
• scaffold/single-starter/.cursor/rules/11-go-infra-api.mdc — 如该包属于默认初始化能力，同步更新
• scaffold/monorepo-starter/.cursor/rules/11-go-infra-api.mdc — 同上

📄 许可证

MIT License - 详见 LICENSE 文件

🔗 相关链接

• OpenTelemetry
• Gin Web Framework
• GORM
• Prometheus

📮 联系方式

• GitHub: liukunxin/go-infra
• Issues: 提交问题

---

⭐ 如果这个项目对你有帮助，请给个Star！