basic-go

module
v1.0.2 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 应用引导层:配置加载 → 日志 → 资源初始化钩子 → 路由注册 → HTTP 启动与优雅停机,一条龙收敛 main 样板代码 README
config 基于 viper 的配置封装:默认值 / 环境变量 / 配置文件 / 目录扫描声明式加载,热更新与落盘保存 README
logger 基于 zap + lumberjack 的日志封装:多输出核、滚动归档、全局句柄替换 README
database 基于 gorm 的数据库接入:统一接口、全局连接、驱动子包按需引入(mysql / postgres / sqlite) README
cache 基于 go-redis 的缓存接入:基础命令封装(零 context 参数)、分布式锁 README
lifecycle 基于 context 的应用生命周期管理:优雅启停、系统信号处理 README
ginx 基于 gin 的 Web 服务封装:配置化启动、优雅停机、内置中间件(CORS / 限流)、集中式路由注册与管理 README

环境要求

  • Go 1.26+

安装

go get gitee.com/usmos/basic-go

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

快速开始

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

package main

import (
	"gitee.com/usmos/basic-go/app"
	"gitee.com/usmos/basic-go/cache"
	"gitee.com/usmos/basic-go/database"
	"gitee.com/usmos/basic-go/database/mysql"
	"gitee.com/usmos/basic-go/ginx"
	"gitee.com/usmos/basic-go/logger"
	"github.com/gin-gonic/gin"
)

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

func main() {
	// 路由注册: ginx 集中式注册表, 启动时统一构建校验
	api := ginx.NewGroup("/api/v1")
	api.GET("/users", func(ctx *gin.Context) {
		ctx.JSON(200, gin.H{"message": "Hello, World!"})
	})

	// 一条龙: 配置加载 -> 日志 -> 资源初始化 -> HTTP 启动 -> 优雅停机后释放
	app.MustRun(&app.Boot[Conf]{
		EnvPrefix: "TATA_GO", // 环境变量前缀, 为空则不启用环境变量覆盖
		Watch:     true,      // 配置热更新, 文件改动自动回填并触发 OnChange
		Init: func(c *Conf) error { // 资源初始化, 返回错误会中断启动
			if err := c.Database.Connect(); err != nil {
				return err
			}
			return c.Redis.Connect()
		},
		Close: func() { database.Close(); cache.Close() }, // HTTP 停机后释放连接
		OnChange: func(c *Conf) { // 热更新回调(需 Watch 开启), 可省略
			logger.Info("配置热更新完成, 新配置已回填")
		},
	})
}

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

tata/
├── cmd/server/main.go     # 入口
├── config.yaml            # server(HTTP) + log(日志) 配置节
├── config-database.yaml   # database(mysql) + redis(缓存) 配置节
└── logs/                  # 日志输出目录
# config.yaml
server:
  host: 127.0.0.1
  port: 8483
  mode: release            # debug/release/test(默认 release)
  cors:                    # 配置本节点即启用跨域(省略则关闭)
    allow_origins: ["*"]
  rate_limit:              # 配置本节点即启用限流(省略则关闭)
    limit: 100             # 单窗口最大请求数(默认 100)
    window: 1s             # 统计窗口(默认 1s)
  shutdown_timeout: 5s     # 优雅停机最大等待(默认 5s)

log:
  level: debug             # debug/info/warn/error(默认 info)
  format: console          # console | json
  filename: logs/app.log
  maxSize: 100             # 单文件 MB, 超过切分
  maxAge: 30               # 旧日志保留天数
  maxBackups: 10           # 旧日志保留份数
  compress: true           # 旧日志 gzip 压缩
  console: true            # 同时输出到控制台
# 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 内部按固定顺序完成启动:扫描加载配置 → 日志初始化 → Init 钩子 → 路由注册 → HTTP 服务阻塞运行;收到 Ctrl+C / kill 后按逆序优雅关停:先停 HTTP(等在途请求处理完)→ Close 钩子释放数据库/缓存连接 → 日志刷盘 → 停止热更新监听。

非 HTTP 长驻组件(后台消费协程、定时任务等)交给 lifecycle:在 Init 钩子中启动、Close 钩子中停止,与主流程共用同一关停时序。各模块亦可脱离 app 独立使用(如纯后台程序只用 config + logger),用法详见各包 README。

设计约定

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

  • 约定优于配置:app 引导层按约定扫描 config 前缀配置文件并组织启动/关停流程,零配置即可运行,约定均可通过 Boot 字段覆盖
  • 全局注入:连接类资源(database.DB() / cache.Client())在 main 中完成初始化并注入全局,业务代码零参数传递
  • 配置即对象:配置结构体均带 yaml / toml / json / mapstructure 标签,配合 config 的 UnmarshalWithDefault 与 default 标签实现零值兜底
  • 按需引入:可选驱动(database 的 mysql / postgres / sqlite)独立成子包,未 import 的不进入依赖树
  • 文档分层:各包 README.md 面向使用者详解用法与配置;各包 doc.go 提供包级 API 文档,业务项目拉取本模块后可在 pkg.go.dev 浏览完整文档

目录结构

basic-go/
├── app/         应用引导层: 配置->日志->资源->HTTP 一条龙启动与关停
├── cache/       Redis 缓存接入: 基础命令封装 + 分布式锁
├── config/      配置加载: 默认值/环境变量/文件/热更新
├── database/    数据库接入: gorm 统一封装, 驱动子包按需引入
│   ├── mysql/
│   ├── postgres/
│   └── sqlite/
├── example/     使用示例: tata 演示 app 引导层的完整启动流程
├── ginx/        Web 服务: gin 配置化启动 + 集中式路由管理
│   └── middleware/   内置中间件: CORS / 限流, 可脱离 ginx 用于原生 gin
├── lifecycle/   应用生命周期: 优雅启停 + 信号处理
└── logger/      日志: zap + lumberjack

参与贡献

  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 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)。
example
tata/cmd/server command
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 的日志封装。

Jump to

Keyboard shortcuts

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