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 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 日志约定
参与贡献
- Fork 本仓库
- 新建
Feat_xxx 分支
- 提交代码
- 新建 Pull Request