basic-go

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

模块总览

包 用途 详细文档
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 依赖不会被拉取)。

快速开始

一个典型的应用初始化流程(各模块均可独立使用):

package main

import (
	"context"

	"gitee.com/usmos/basic-go/cache"
	"gitee.com/usmos/basic-go/config"
	"gitee.com/usmos/basic-go/database"
	"gitee.com/usmos/basic-go/database/mysql"
	"gitee.com/usmos/basic-go/lifecycle"
	"gitee.com/usmos/basic-go/logger"
)

// Root 配置根结构, 字段 yaml 标签与配置文件对应, 可配 default 标签回填默认值
type Root struct {
	Log   logger.LogConfig `yaml:"log"`
	DB    mysql.MySQL      `yaml:"database"`
	Redis cache.Redis      `yaml:"redis"`
}

func main() {
	// 1. 配置: 声明式加载, 缺失键回填 default 标签
	cfg, err := config.New("yaml", config.WithFile("config.yaml"))
	if err != nil {
		panic(err)
	}
	var c Root
	if err := cfg.UnmarshalWithDefault(&c); err != nil {
		panic(err)
	}

	// 2. 日志: 初始化并替换全局句柄, database 的 SQL 日志同样经此输出
	if err := logger.Init(c.Log); err != nil {
		panic(err)
	}
	defer logger.Sync()

	// 3. 数据库 / 缓存: 连接注入全局, 任意位置直接使用
	if err := c.DB.Connect(); err != nil {
		panic(err)
	}
	defer database.Close()
	if err := c.Redis.Connect(); err != nil {
		panic(err)
	}
	defer cache.Close()

	// 4. 生命周期: Ctrl+C / kill 优雅退出
	app := lifecycle.NewApp()
	app.SetupSignalHandler()
	if err := app.Start(nil, func(ctx context.Context) error {
		logger.L.Info("server running")
		<-ctx.Done() // 监听停止信号
		return nil
	}, nil); err != nil {
		panic(err)
	}
}

对应配置文件:

log:
  level: info
  format: console
  console: true

database:
  host: 127.0.0.1
  port: 3306
  user: root
  password: "123456"
  db: note
  charset: utf8mb4

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

设计约定

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

  • 全局注入:连接类资源(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/
├── cache/       Redis 缓存接入: 基础命令封装 + 分布式锁
├── config/      配置加载: 默认值/环境变量/文件/热更新
├── database/    数据库接入: gorm 统一封装, 驱动子包按需引入
│   ├── mysql/
│   ├── postgres/
│   └── sqlite/
├── ginx/        Web 服务: gin 配置化启动 + 集中式路由管理
├── lifecycle/   应用生命周期: 优雅启停 + 信号处理
└── logger/      日志: zap + lumberjack

参与贡献

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

Directories

Path Synopsis
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)。
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