basic-go

module
v1.0.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 9, 2026 License: MIT

README

basic-go

通用的 Go 基础功能封装库。把配置、日志、数据库、缓存、生命周期等每个子项目都要重复编写的基础代码,收敛为一套开箱即用、可独立引入的模块,减少重复的样板代码,让业务项目聚焦业务本身。

模块总览

包 用途 详细文档
app 应用引导层:配置加载 → 日志 → 组件装配(Wire) → 资源初始化钩子 → 路由注册 → HTTP 启动与优雅停机,一条龙收敛 main 样板代码 README
config 基于 viper 的配置封装:默认值 / 环境变量 / 配置文件 / 目录扫描声明式加载,热更新与落盘保存 README
logger 基于 zap + lumberjack 的日志封装:多输出核、滚动归档、error 及以上独立分文件、全局句柄替换 README
database 基于 gorm 的数据库接入:统一接口、全局连接、闭包式事务助手、分页 scope、驱动子包按需引入(mysql / postgres / sqlite) README
cache 基于 go-redis 的缓存接入:基础命令封装(零 context 参数)、分布式锁、延迟队列 README
errcode 统一业务错误码:码约定「1 万位 + HTTP 状态码」(如 10404)自动映射 4xx/5xx,兼容 errors.Is/As,配合 ginx 输出统一 {code,msg,data} 响应 README
snowflake 雪花 ID 生成器:64 位趋势递增、时钟回拨防护、workerID 支持环境变量 / 出口 IP 推导,零外部依赖 README
cron 基于 robfig/cron/v3 的薄封装:时区 / 秒级 / 防堆积配置化,表达式注册期校验,panic 自动 recover,耗时自动记录 README
trace 基于 OpenTelemetry 的分布式链路追踪:OTLP 导出配置化(gRPC/HTTP 双协议)、HTTP 服务端 span、W3C 跨服务传递,trace id 桥接 X-Request-Id 日志约定 README
lifecycle 基于 context 的应用生命周期管理:优雅启停、系统信号处理 README
ginx 基于 gin 的 Web 服务封装:配置化启动、优雅停机、集中式路由注册;内置中间件(CORS / 限流 / TraceID / 绑定校验)、统一响应渲染与分页、可观测端点(metrics / pprof)、双探活与停机排空 README

环境要求

  • Go 1.26+

安装

go get gitee.com/usmos/basic-go

模块按包拆分,业务项目只 import 用到的包,未使用的模块不会进入依赖树(如只引入 database 时,cache 的 go-redis 依赖不会被拉取)。

快速开始

以 example/tata 为参考的实际操作模式,业务 main 只需三件事:声明配置结构体、注册路由、调用 app.MustRun:

package main

import (
	"errors"
	"strconv"

	"gitee.com/usmos/basic-go/app"
	"gitee.com/usmos/basic-go/cache"
	"gitee.com/usmos/basic-go/cron"
	"gitee.com/usmos/basic-go/database"
	"gitee.com/usmos/basic-go/database/mysql"
	"gitee.com/usmos/basic-go/errcode"
	"gitee.com/usmos/basic-go/ginx"
	"gitee.com/usmos/basic-go/ginx/middleware"
	"gitee.com/usmos/basic-go/logger"
	"gitee.com/usmos/basic-go/snowflake"
	"gitee.com/usmos/basic-go/trace"
	"github.com/gin-gonic/gin"
	"gorm.io/gorm"
)

// Conf 配置文件: 内嵌 app.Base 提供 server / log 配置节, 业务节自行声明
type Conf struct {
	app.Base
	Database mysql.MySQL `yaml:"database"`
	Redis    cache.Redis `yaml:"redis"`
	Cron     cron.Config `yaml:"cron"`
	Trace    trace.Config `yaml:"trace"`
}

// User 示例表模型, binding 标签用于参数校验
type User struct {
	ID    int64  `gorm:"primaryKey" json:"id"`
	Name  string `gorm:"size:64" binding:"required" json:"name"`
	Email string `gorm:"size:128" binding:"omitempty,email" json:"email"`
}

// 长驻业务组件, Init/Close 钩子间共享
var orderQueue *cache.DelayQueue

func main() {
	// 路由注册: ginx 集中式注册表, 启动时统一构建校验
	api := ginx.NewGroup("/api/v1")
	api.POST("/users", middleware.Bind(createUser)) // 校验失败统一 400 {code:10400}
	api.GET("/users/:id", getUser)                  // errcode 错误自动映射 404 {code:10404}
	api.GET("/users", listUsers)                    // 分页: BindPage + RenderPage

	// 一条龙: 配置加载 -> 日志 -> 组件装配(Wire) -> 业务初始化 -> HTTP 启动 -> 优雅停机后释放
	app.MustRun(&app.Boot[Conf]{
		EnvPrefix: "TATA_GO", // 环境变量前缀, 为空则不启用环境变量覆盖
		Watch:     true,      // 配置热更新, 文件改动自动回填并触发 OnChange
		Wire: func(c *Conf) []app.Component { // 基础组件一行一个: 按序 Init, 逆序 Close, 失败自动回滚
			return []app.Component{
				trace.NewBoot(c.Trace),                 // 首位: 逆序释放时最后关闭, 在途 span 全量刷盘
				snowflake.NewBoot(),                    // workerID 自动推导(环境变量 -> 出口 IP)
				database.NewBoot(&c.Database, &User{}), // 连接 + 自动迁移
				cache.NewBoot(&c.Redis),                // 连接(含 Ping 探活)
				cron.NewBoot(c.Cron, cron.Job{ // 建调度器 + 注册任务 + 启动
					Spec: "*/5 * * * *", Name: "clean-expired",
					Run: func() { logger.Info("定时任务触发: 清理过期数据") },
				}),
			}
		},
		Init: func(c *Conf) error { // 业务特有初始化, 返回错误会中断启动
			// 就绪检查: 注入后 readiness 才 200; 停机排空阶段自动 503 引导 LB 摘流
			ginx.SetReadyChecker(func() bool { return cache.Client() != nil })
			// 延迟队列: 消费协程随 Close 钩子优雅停止
			orderQueue = cache.NewDelayQueue("orders:delay", func(payload string) error {
				logger.Info("订单延迟处理: " + payload)
				return nil
			})
			return orderQueue.Start()
		},
		Close: func() { orderQueue.Stop() }, // HTTP 停机后先释放业务长驻组件, Wire 组件随后逆序释放
		OnChange: func(c *Conf) { // 热更新回调(需 Watch 开启), 可省略
			logger.Info("配置热更新完成, 新配置已回填")
		},
	})
}

// createUser 泛型绑定 + 雪花 ID + 闭包式事务 + 统一渲染
func createUser(c *gin.Context, req *User) {
	id, err := snowflake.Next()
	if err != nil {
		ginx.RenderError(c, err)
		return
	}
	req.ID = id
	err = database.Tx(func(tx *gorm.DB) error {
		return tx.Create(req).Error // 返回错误即回滚
	})
	ginx.Render(c, err, req)
}

// getUser 底层错误转语义化错误码, 响应自动映射 404
func getUser(c *gin.Context) {
	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
	if err != nil {
		ginx.RenderError(c, errcode.ErrInvalidParams.WithMsg("用户 ID 必须为数字"))
		return
	}
	var user User
	err = database.DB().First(&user, id).Error
	if errors.Is(err, gorm.ErrRecordNotFound) {
		ginx.RenderError(c, errcode.ErrNotFound.WithMsg("用户不存在").WithErr(err))
		return
	}
	ginx.Render(c, err, &user)
}

// listUsers 分页: ginx.BindPage + database.Paginate + ginx.RenderPage
func listUsers(c *gin.Context) {
	page := ginx.BindPage(c)
	var (
		total int64
		users []User
	)
	db := database.DB().Model(&User{})
	if err := db.Count(&total).Error; err != nil {
		ginx.RenderError(c, err)
		return
	}
	err := db.Scopes(database.Paginate(page.Page, page.Size)).Order("id DESC").Find(&users).Error
	ginx.RenderPage(c, err, page, users, total)
}

以上为精简版,完整示例(延迟队列投递 Push、TraceID 日志字段 middleware.TraceIDField 等)见 example/tata/cmd/server/main.go。

example 下另提供按组件划分、可独立运行的最小 demo(进入对应目录 go run . 即可):quickstart(最小启动)、web(参数校验/错误码/分页/内置中间件)、db(sqlite 接入与事务,零外部服务)、cache(redis 命令/分布式锁/延迟队列,需本地 redis)、cron(定时任务与雪花发号)、trace(链路追踪与可观测端点)。

Boot 按约定加载配置:默认扫描 ./ 下 config 前缀的 yaml 文件,按文件名排序依次合并。对应目录结构与配置文件:

tata/
├── cmd/server/main.go     # 入口
├── config.yaml            # server(HTTP) + log(日志) + cron(定时任务) + trace(链路追踪) 配置节
├── config-database.yaml   # database(mysql) + redis(缓存) 配置节
└── logs/                  # 日志输出目录
# config.yaml
server:
  host: 127.0.0.1
  port: 8483
  mode: release            # debug/release/test(默认 release)
  health_check_path: /healthz  # 存活探活路由(默认 /healthz): 进程存活即 200
  ready_check_path: /readyz    # 就绪探活路由(默认 /readyz): 未就绪/停机排空阶段 503
  telemetry:              # 可观测端点(省略则关闭)
    metrics: true         # 挂载 /metrics(Prometheus) 并采集请求耗时/QPS
    namespace: ""         # 指标名前缀(默认空, 多服务共用 Prometheus 时设为服务名)
    buckets: [0.005, 0.01, 0.05, 0.1, 0.5, 1, 5] # 耗时直方图分桶(秒, 默认 DefBuckets)
    pprof: true           # 挂载 /debug/pprof/*
  cors:                   # 配置本节点即启用跨域(省略则关闭)
    allow_origins: ["*"]
  rate_limit:             # 配置本节点即启用限流(省略则关闭)
    limit: 100            # 单窗口最大请求数(默认 100)
    window: 1s            # 统计窗口(默认 1s)
  shutdown_timeout: 5s    # 优雅停机最大等待(默认 5s)
  drain_delay: 1s         # 停机排空: readiness 置 503 后等待 LB 摘流再停机

log:
  level: debug            # debug/info/warn/error(默认 info)
  format: console         # console | json
  filename: logs/app.log
  error_filename: logs/app-error.log  # error 及以上独立分文件(空则不分流, 滚动策略同主文件)
  maxSize: 100            # 单文件 MB, 超过切分
  maxAge: 30              # 旧日志保留天数
  maxBackups: 10          # 旧日志保留份数
  compress: true          # 旧日志 gzip 压缩
  console: true           # 同时输出到控制台

cron:                     # 定时任务(见 cron 包)
  timezone: Asia/Shanghai
  with_seconds: false     # true 为 6 段式(含秒)表达式, 默认 5 段式"分 时 日 月 周"
  skip_if_busy: false     # 上一轮未跑完时跳过本轮(慢任务防堆积场景开启)

trace:                    # 分布式 tracing(见 trace 包, 接管 X-Request-Id 约定)
  service_name: tata      # 服务名(默认 basic-go), tracing 后端按服务聚合
  protocol: grpc          # OTLP 导出协议 grpc(默认, 4317) | http(4318)
  endpoint: 127.0.0.1:4317 # collector 地址(默认按协议取本地端口)
  secure: false           # TLS 加密连接(默认 false 明文, 生产务必开启)
  sample_ratio: 1.0       # 采样率 0.0~1.0(默认全量)
# config-database.yaml
database:
  host: 127.0.0.1
  port: 3306
  user: root
  password: "123456"
  db: tata
  charset: utf8mb4
  logger_level: warn       # SQL 日志级别(默认 warn)
  max_open_conns: 100      # 最大打开连接数

redis:
  host: 127.0.0.1
  port: 6379
  password: "123456"
  db: 1
  # 超时/连接池/锁配置省略时自动使用默认值

Run 内部按固定顺序完成启动:扫描加载配置 → 日志初始化 → 组件装配(Wire,组件按序 Init)→ Init 钩子 → 路由注册 → HTTP 服务阻塞运行;收到 Ctrl+C / kill 后按逆序优雅关停:readiness 先转 503 并等待 drain_delay 让 LB 摘流(停机排空,可经 OnDrain 钩子主动摘除实例)→ 停 HTTP(等在途请求处理完)→ Close 钩子释放业务长驻组件 → Wire 组件逆序释放(trace 首位装配则最后关闭)→ 日志刷盘 → 停止热更新监听。

业务特有逻辑(如延迟队列)在 Init / Close 钩子中编排;非 HTTP 长驻组件(后台消费协程、定时任务等)亦可交给 lifecycle,与主流程共用同一关停时序。各模块均可脱离 app 独立使用(如纯后台程序只用 config + logger),用法详见各包 README。

设计约定

各模块遵循一致的设计风格,熟悉一个即可上手全部:

  • 约定优于配置:app 引导层按约定扫描 config 前缀配置文件并组织启动/关停流程,零配置即可运行,约定均可通过 Boot 字段覆盖
  • 组件一行接入:基础组件(database / cache / trace / snowflake / cron)提供同构 NewBoot 适配器,在 Wire 装配钩子中一行接入——组件按序 Init、逆序 Close、失败自动回滚;适配器与 app 经结构化匹配解耦(双向零 import)
  • 全局注入:连接类资源(database.DB() / cache.Client())在 main 中完成初始化并注入全局,业务代码零参数传递
  • 统一响应约定:ginx 统一渲染 {code, msg, data},errcode 错误码自动映射 4xx/5xx(如 errcode.ErrNotFound → HTTP 404 + {"code":10404})
  • 配置即对象:配置结构体均带 yaml / toml / json / mapstructure 标签,配合 config 的 UnmarshalWithDefault 与 default 标签实现零值兜底
  • 按需引入:可选驱动(database 的 mysql / postgres / sqlite)独立成子包,未 import 的不进入依赖树
  • 文档分层:各包 README.md 面向使用者详解用法与配置;各包 doc.go 提供包级 API 文档,业务项目拉取本模块后可在 pkg.go.dev 浏览完整文档

目录结构

basic-go/
├── app/         应用引导层: 配置->日志->组件装配(Wire)->资源->HTTP 一条龙启动与关停
├── cache/       Redis 缓存接入: 基础命令封装 + 分布式锁 + 延迟队列
├── config/      配置加载: 默认值/环境变量/文件/热更新
├── cron/        定时任务: cron 表达式调度, panic 自动 recover
├── database/    数据库接入: gorm 统一封装 + 事务助手 + 分页, 驱动子包按需引入
│   ├── mysql/
│   ├── postgres/
│   └── sqlite/
├── errcode/     业务错误码: 码值"1 万位+HTTP 状态码", 统一 {code,msg,data} 响应
├── example/     使用示例: 按组件划分的最小 demo(quickstart/web/db/cache/cron/trace) + tata 全家桶集成
├── ginx/        Web 服务: gin 配置化启动 + 集中式路由管理
│   └── middleware/   内置中间件: CORS/限流/TraceID/绑定校验/可观测端点, 可脱离 ginx 用于原生 gin
├── lifecycle/   应用生命周期: 优雅启停 + 信号处理
├── logger/      日志: zap + lumberjack, error 级别独立分文件
├── snowflake/   雪花 ID: 趋势递增唯一 ID, 时钟回拨防护
└── trace/       分布式链路追踪: OpenTelemetry + OTLP(gRPC/HTTP), span 桥接 X-Request-Id 日志约定

参与贡献

  1. Fork 本仓库
  2. 新建 Feat_xxx 分支
  3. 提交代码
  4. 新建 Pull Request

Directories

Path Synopsis
Package app 提供应用引导层: 把配置加载、日志初始化、基础组件装配、资源初始化、 路由注册、HTTP 服务启动与优雅停机收敛为一个入口, 业务 main 只保留配置结构体 与少量钩子。
Package app 提供应用引导层: 把配置加载、日志初始化、基础组件装配、资源初始化、 路由注册、HTTP 服务启动与优雅停机收敛为一个入口, 业务 main 只保留配置结构体 与少量钩子。
Package cache 提供基于 Redis 的缓存接入:连接管理、基础命令封装、分布式锁与延迟队列。
Package cache 提供基于 Redis 的缓存接入:连接管理、基础命令封装、分布式锁与延迟队列。
Package config 基于 viper 内核的面向对象配置封装。
Package config 基于 viper 内核的面向对象配置封装。
Package cron 提供基于 robfig/cron 的定时任务薄封装。
Package cron 提供基于 robfig/cron 的定时任务薄封装。
Package database 提供基于 gorm 的数据库接入封装。
Package database 提供基于 gorm 的数据库接入封装。
mysql
Package mysql 提供 MySQL 数据库驱动接入。
Package mysql 提供 MySQL 数据库驱动接入。
postgres
Package postgres 提供 PostgreSQL 数据库驱动接入。
Package postgres 提供 PostgreSQL 数据库驱动接入。
sqlite
Package sqlite 提供 SQLite 数据库驱动接入(纯 Go 实现, 无需 cgo)。
Package sqlite 提供 SQLite 数据库驱动接入(纯 Go 实现, 无需 cgo)。
Package errcode 提供统一的业务错误码定义与 HTTP 状态映射。
Package errcode 提供统一的业务错误码定义与 HTTP 状态映射。
example
cache command
演示: Redis 接入 —— Wire 装配 cache + snowflake, 覆盖基础命令封装 / 分布式锁 / 延迟队列。
演示: Redis 接入 —— Wire 装配 cache + snowflake, 覆盖基础命令封装 / 分布式锁 / 延迟队列。
cron command
演示: 定时任务 + 雪花 ID —— Wire 一行装配 cron 与 snowflake, 零外部服务。
演示: 定时任务 + 雪花 ID —— Wire 一行装配 cron 与 snowflake, 零外部服务。
db command
演示: 数据库接入 —— Wire 一行装配 sqlite(零外部服务), 覆盖 CRUD / 统一错误映射 / 分页 / 闭包式事务。
演示: 数据库接入 —— Wire 一行装配 sqlite(零外部服务), 覆盖 CRUD / 统一错误映射 / 分页 / 闭包式事务。
quickstart command
演示: 最小 web 应用 —— app + ginx 两件套, 零基础组件、零外部服务。
演示: 最小 web 应用 —— app + ginx 两件套, 零基础组件、零外部服务。
tata command
trace command
演示: 分布式链路追踪 —— Wire 一行装配 trace, span 中间件自动注入, 零外部服务可跑。
演示: 分布式链路追踪 —— Wire 一行装配 trace, span 中间件自动注入, 零外部服务可跑。
web command
演示: web 层三件套 —— 统一响应(errcode) + 参数校验(middleware.Bind) + 分页(BindPage/RenderPage), 以及 CORS / 限流 / trace_id / 可观测端点四个内置能力的配置化开启。
演示: web 层三件套 —— 统一响应(errcode) + 参数校验(middleware.Bind) + 分页(BindPage/RenderPage), 以及 CORS / 限流 / trace_id / 可观测端点四个内置能力的配置化开启。
Package ginx 提供基于 gin 的 Web 服务封装:配置化启动 HTTP/HTTPS 服务与集中式路由管理。
Package ginx 提供基于 gin 的 Web 服务封装:配置化启动 HTTP/HTTPS 服务与集中式路由管理。
middleware
Package middleware 提供 ginx 的内置中间件集合, 每个中间件独立一个文件; 各中间件均可脱离 ginx, 直接用于原生 gin。
Package middleware 提供 ginx 的内置中间件集合, 每个中间件独立一个文件; 各中间件均可脱离 ginx, 直接用于原生 gin。
Package lifecycle 提供基于 context 的应用生命周期管理封装。
Package lifecycle 提供基于 context 的应用生命周期管理封装。
Package logger 提供基于 zap + lumberjack 的日志封装。
Package logger 提供基于 zap + lumberjack 的日志封装。
Package snowflake 提供雪花算法唯一 ID 生成器。
Package snowflake 提供雪花算法唯一 ID 生成器。
Package trace 提供基于 OpenTelemetry 的分布式链路追踪: OTLP 导出配置化 (gRPC/HTTP 双协议)、HTTP 服务端 span 中间件与 trace_id 日志联动。
Package trace 提供基于 OpenTelemetry 的分布式链路追踪: OTLP 导出配置化 (gRPC/HTTP 双协议)、HTTP 服务端 span 中间件与 trace_id 日志联动。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL