database

package
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 Imports: 7 Imported by: 0

README

database 数据库访问包

基于 gorm 的数据库接入封装:核心包提供统一接口与全局连接管理,MySQL / PostgreSQL / SQLite 三种驱动各自独立成子包,按需引入,未使用的驱动不会进入业务项目的依赖树。

特性

  • 驱动按需引入:核心包零驱动依赖,业务项目 import 哪个驱动子包才拉取哪个驱动(Go 1.17+ 模块图裁剪)
  • 统一接口:所有驱动实现 database.Database 接口(DSN() + Connect()),切换数据库只需换 import 与配置
  • 全局连接管理:连接成功后注入全局,任意位置通过 DB() 获取 gorm 句柄
  • 连接池标准化:统一的 DatabasePool 连接池配置,随连接自动生效
  • zap 日志对接:gorm 的 SQL 日志(慢查询、错误)经 zap 输出,级别可配置
  • 事务助手 + 分页 scope:Tx / TxWith 闭包式事务(返回 nil 提交、返回 error 或 panic 自动回滚,嵌套走 SAVEPOINT);Paginate 与 ginx 的 BindPage 归一化约定一致

目录结构

database/
├── init.go      核心包: Database 接口、DatabasePool、全局连接管理
├── tx.go        事务助手: Tx/TxWith 闭包式事务(自动提交/回滚)
├── page.go      分页 scope: Paginate(与 ginx.BindPage 配合)
├── zap_log.go   gorm 日志器, 输出对接 zap
├── boot.go      组件适配器: NewBoot 一行接入 app 的 Wire 装配钩子
├── mysql/       MySQL 驱动适配器
├── postgres/    PostgreSQL 驱动适配器
└── sqlite/      SQLite 驱动适配器(纯 Go 实现, 无需 cgo)

快速开始

以 MySQL 为例(其余驱动仅 import 路径与配置字段不同):

package main

import (
	"gitee.com/usmos/basic-go/database"
	"gitee.com/usmos/basic-go/database/mysql"
)

func main() {
	db := &mysql.MySQL{
		LoggerLevel: "warn",
		Host:        "127.0.0.1",
		Port:        3306,
		User:        "root",
		Password:    "123456",
		DB:          "note_mq",
		Charset:     "utf8mb4",
	}

	// 连接(含连接池配置与 Ping 探活), 成功后注入全局
	if err := db.Connect(); err != nil {
		panic(err)
	}
	defer database.Close()

	// 任意位置获取 gorm 句柄
	database.DB().Create(&User{Name: "note"})

	// 自动迁移表结构
	database.AutoMigrate(&User{})
}

与 config 配合,从配置文件加载:

type Root struct {
	Database mysql.MySQL `yaml:"database"`
}

var c Root
cfg, _ := config.New("yaml", config.WithFile("config.yaml"))
_ = cfg.UnmarshalWithDefault(&c)
_ = c.Database.Connect()

对应配置文件:

database:
  logger_level: warn      # silent, error, warn, info
  host: 127.0.0.1
  port: 3306
  user: root
  password: "123456"
  db: note_mq
  charset: utf8mb4
  conn_max_idle_time: 5m  # 连接最大空闲时间
  conn_max_lifetime: 30m  # 连接最大生命周期
  max_idle_conns: 10      # 最大空闲连接数
  max_open_conns: 100     # 最大打开连接数

快捷接入 app

app 的 Wire 装配钩子中一行接入——建连、迁移、关停释放由适配器托管:

app.MustRun(&app.Boot[Conf]{
	Wire: func(c *Conf) []app.Component {
		return []app.Component{database.NewBoot(&c.Database, &User{})}
	},
})

连接为全局单数据源:Connect 注入包级全局 DB(),Wire 中放置多个 database.Boot 会互相覆盖(多数据源请直接使用 gorm 多实例)。

配置字段

通用连接池(DatabasePool,各驱动内嵌,见 init.go):

字段 类型 说明
conn_max_idle_time time.Duration 连接最大空闲时间(0 = 不限制,如 5m)
conn_max_lifetime time.Duration 连接最大生命周期(0 = 不限制,如 30m)
max_idle_conns int 连接池最大空闲连接数(0 = database/sql 默认 2)
max_open_conns int 连接池最大打开连接数(0 = 不限制)

各驱动专有字段(各驱动均还含 logger_level——gorm SQL 日志级别:silent / error / warn / info,与上述连接池字段):

驱动 包 专有字段
MySQL database/mysql host port user password db charset
PostgreSQL database/postgres host port user password db ssl_mode time_zone
SQLite database/sqlite path(:memory: 为内存库)

字段均带 yaml / toml / json / mapstructure 标签,可配 default 标签配合 config 的 UnmarshalWithDefault 使用。

接口总览

核心包(init.go):

方法 说明
Database 接口 DSN() string + Connect() error,各驱动的统一抽象
DB() 获取全局 *gorm.DB 句柄(未连接时为 nil)
SetDB(db) 注入连接(各驱动 Connect() 内部自动调用)
AutoMigrate(models...) 自动迁移表结构
Close() 关闭连接并清空全局句柄,可重复调用
NewBoot(dsn, models...) app Wire 组件适配器(boot.go):Init 建连 + 可选 AutoMigrate,Close 释放连接

核心包(zap_log.go):

方法 说明
NewLogger(level) 创建对接 zap 的 gorm 日志器;慢 SQL(>200ms)Warn,错误 SQL Error

核心包(tx.go):

方法 / 标识符 说明
Tx(fn) 全局连接上的闭包式事务:fn 返回 nil 提交,返回 error 或 panic 自动回滚(panic 不会击穿进程);未连接时返回 ErrNotConnected
TxWith(conn, fn) 在指定句柄上开启事务:conn 为 nil 时回退全局连接(等价 Tx);传入事务句柄时 gorm 自动以 SAVEPOINT 嵌套
ErrNotConnected 未建立数据库连接的哨兵错误,用 errors.Is 判断

核心包(page.go):

方法 说明
Paginate(page, size) 分页查询 scope,配合 Scopes 按 offset/limit 截取当前页;page 从 1 开始(<=0 按 1 计)、size<=0 默认 20、上限 100,与 ginx 的 BindPage 归一化约定一致

各驱动子包(以 mysql/mysql.go 为例):

方法 说明
DSN() 生成数据库连接字符串
Connect() 建连 → 应用连接池配置 → Ping 探活 → 注入全局

事务与分页

Tx 闭包式事务免去手动 Begin / Commit / Rollback 样板——创建订单并扣减余额,任一步失败整体回滚:

err := database.Tx(func(tx *gorm.DB) error {
	if err := tx.Create(&Order{UserID: uid, Amount: amount}).Error; err != nil {
		return err // 返回错误即回滚
	}
	res := tx.Model(&User{ID: uid}).
		Where("balance >= ?", amount).
		Update("balance", gorm.Expr("balance - ?", amount))
	if res.Error != nil {
		return res.Error // 回滚
	}
	if res.RowsAffected == 0 {
		return errors.New("余额不足") // 同样回滚
	}
	return nil // 返回 nil 提交
})

闭包内需要嵌套事务时,直接对 tx 调用 TxWith(tx, ...):gorm 检测到事务句柄后自动以 SAVEPOINT 嵌套,内层回滚不影响外层;也可把 tx 直接传给内部函数,与外层收敛为同一个事务(推荐,更简单)。

分页与 ginx 一行配合(BindPage 归一化 page/size,Paginate 截取当前页,RenderPage 统一渲染):

page := ginx.BindPage(c) // page/size 已归一化(1 起、默认 20、上限 100)
var (
	total int64
	users  []User
)
database.DB().Model(&User{}).Count(&total)
database.DB().Scopes(database.Paginate(page.Page, page.Size)).Find(&users)
ginx.RenderPage(c, nil, page, users, total)

按需引入机制

驱动适配器与核心包分属不同 Go 包,依赖随 import 精确传播:

import "gitee.com/usmos/basic-go/database/mysql" // 仅此路径引入 gorm.io/driver/mysql
  • 业务项目只 import 用到的驱动子包,未使用驱动的模块不进入其 go.mod、不会被下载、不参与编译
  • 核心包 database 可独立使用(配合 SetDB 手动注入任意 gorm 连接)
  • SQLite 采用 github.com/glebarez/sqlite 纯 Go 驱动,无 cgo 依赖,交叉编译友好

注意事项

  • SQLite 单写者模型:高并发写入场景建议 MaxOpenConns: 1,避免 database is locked
  • PostgreSQL SSLMode:本地开发通常 disable,生产环境建议 require 及以上
  • 全局单连接:SetDB 全局仅保存一个连接,多数据源场景请直接使用 gorm 多实例,不走本包全局方法
  • 日志依赖:gorm 日志经 zap.L() 输出,业务项目需完成 zap 初始化(或接受默认输出)

Documentation

Overview

Package database 提供基于 gorm 的数据库接入封装。

核心包定义统一接口与全局连接管理: 所有驱动实现 Database 接口(DSN + Connect), 连接成功后注入全局, 任意位置通过 DB() 获取 gorm 句柄, AutoMigrate 自动迁移表结构; 另提供 Tx 闭包式事务助手(错误/panic 自动回滚, 支持 SAVEPOINT 嵌套) 与 Paginate 分页 scope(与 ginx.BindPage 配合)。 MySQL / PostgreSQL / SQLite 三种驱动各自独立成子包(mysql/postgres/sqlite), 业务项目仅 import 用到的驱动子包, 未使用的驱动不会进入依赖树。

app.Boot 场景经 Wire 一行接入(建连 + 可选迁移 + 关停释放):

app.MustRun(&app.Boot[Conf]{
	Wire: func(c *Conf) []app.Component {
		return []app.Component{database.NewBoot(&c.Database, &User{})}
	},
})

数据库为全局单数据源约定: Connect 注入包级全局 DB(), Wire 中放置多个 database.Boot 会互相覆盖(多数据源请直接使用 gorm 多实例)。

独立使用(以 MySQL 为例, 其余驱动仅 import 路径与配置字段不同):

db := &mysql.MySQL{
	Host:     "127.0.0.1",
	Port:     3306,
	User:     "root",
	Password: "123456",
	DB:       "note",
	Charset:  "utf8mb4",
}
if err := db.Connect(); err != nil { // 建连(含连接池配置与 Ping 探活), 成功后注入全局
	panic(err)
}
defer database.Close()

database.DB().Create(&User{Name: "note"}) // 任意位置获取 gorm 句柄
_ = database.AutoMigrate(&User{})         // 自动迁移表结构

Index

Constants

This section is empty.

Variables

View Source
var ErrNotConnected = errors.New("database: 未连接数据库, 请先调用驱动子包的 Connect")

ErrNotConnected 未建立数据库连接, 需先调用驱动子包的 Connect

Functions

func AutoMigrate

func AutoMigrate(dist ...any) error

AutoMigrate 自动迁移数据库表

func Close

func Close() error

Close 关闭数据库连接

func DB

func DB() *gorm.DB

DB 获取数据库连接

func NewLogger

func NewLogger(level string) logger.Interface

NewLogger 创建 gorm 日志器, 输出对接 zap, 供各驱动子包使用

func Paginate added in v1.0.4

func Paginate(page, size int) func(db *gorm.DB) *gorm.DB

Paginate 分页查询 scope, 与 gorm 的 Scopes 配合按 offset/limit 截取当前页:

page := ginx.BindPage(c) // page/size 已归一化
var (
	total  int64
	users  []User
)
database.DB().Model(&User{}).Count(&total)
database.DB().Scopes(database.Paginate(page.Page, page.Size)).Find(&users)

page 从 1 开始(<=0 按 1 计); size<=0 时默认 20, 超过上限按 100 截断。

func SetDB

func SetDB(d *gorm.DB)

SetDB 设置数据库连接

func Tx added in v1.0.4

func Tx(fn func(tx *gorm.DB) error) error

Tx 闭包式事务: 在全局连接上开启事务执行 fn, 免去手动 Begin/Commit/Rollback 样板:

err := database.Tx(func(tx *gorm.DB) error {
	if err := tx.Create(&order).Error; err != nil {
		return err // 返回错误即回滚
	}
	return tx.Model(&user).Update("balance", gorm.Expr("balance - ?", amount)).Error
})

fn 返回 nil 时提交; 返回 error 或 panic 时自动回滚(panic 不会击穿进程)。

嵌套收敛: fn 内需要嵌套事务时, 直接对 tx 调用 TxWith(tx, ...) 即可, gorm 检测到事务句柄后会以 SAVEPOINT 嵌套, 内层回滚不影响外层; 也可将 tx 直接传给内部函数, 与外层收敛为同一个事务(推荐, 更简单)。

func TxWith added in v1.0.4

func TxWith(conn *gorm.DB, fn func(tx *gorm.DB) error) error

TxWith 在指定句柄上开启事务: conn 为 nil 时回退全局连接(等价于 Tx); 传入事务句柄时 gorm 自动以 SAVEPOINT 嵌套, 用于 Tx 闭包内的子事务。

Types

type Boot added in v1.0.4

type Boot struct {
	// DSN 数据库驱动配置, *mysql.MySQL / *postgres.PostgreSQL / *sqlite.SQLite 均满足
	DSN Database
	// Models 建连后自动迁移的表模型, 为空则跳过迁移
	Models []any
}

Boot 组件适配器: 一行接入 app.Boot 的 Wire 装配钩子(结构化匹配 app.Component 约定, 无需 import app), 也可用于任何"按序初始化、 逆序释放"的装配场景。

数据库为全局单数据源约定: Connect 注入包级全局 DB(), Wire 中放置多个 database.Boot 会互相覆盖(多数据源支持见 ROADMAP 待开发项)。

func NewBoot added in v1.0.4

func NewBoot(dsn Database, models ...any) *Boot

NewBoot 构建数据库组件适配器: Init 建立全局连接并按需 AutoMigrate, Close 释放连接。

database.NewBoot(&c.Database, &User{}) // 连接 + 迁移 + 关停释放, 一行接入

func (*Boot) Close added in v1.0.4

func (b *Boot) Close()

Close 释放全局数据库连接(幂等, 未连接时为空操作)。

func (*Boot) Init added in v1.0.4

func (b *Boot) Init() error

Init 建立全局数据库连接; Models 非空时执行 AutoMigrate。 连接成功而迁移失败时, 已建立的连接仍会被 Close 释放(组件回滚语义)。

func (*Boot) Name added in v1.0.4

func (b *Boot) Name() string

Name 组件名, 用于启动失败错误与关停日志标识。

type Database

type Database interface {
	DSN() string    // 数据库连接字符串
	Connect() error // 连接数据库
}

Database 数据库接口, 定义数据库连接和关闭方法以及数据库使用方法 统一数据库操作接口, 方便切换数据库驱动

type DatabasePool

type DatabasePool struct {
	ConnMaxIdleTime time.Duration `yaml:"conn_max_idle_time" toml:"conn_max_idle_time" json:"conn_max_idle_time" mapstructure:"conn_max_idle_time"` // 数据库连接最大空闲时间
	ConnMaxLifetime time.Duration `yaml:"conn_max_lifetime" toml:"conn_max_lifetime" json:"conn_max_lifetime" mapstructure:"conn_max_lifetime"`     // 数据库连接最大生命周期
	MaxIdleConns    int           `yaml:"max_idle_conns" toml:"max_idle_conns" json:"max_idle_conns" mapstructure:"max_idle_conns"`                 // 数据库连接池最大空闲连接数
	MaxOpenConns    int           `yaml:"max_open_conns" toml:"max_open_conns" json:"max_open_conns" mapstructure:"max_open_conns"`                 // 数据库连接池最大打开连接数
}

DatabasePool 数据库连接池

Directories

Path Synopsis
Package mysql 提供 MySQL 数据库驱动接入。
Package mysql 提供 MySQL 数据库驱动接入。
Package postgres 提供 PostgreSQL 数据库驱动接入。
Package postgres 提供 PostgreSQL 数据库驱动接入。
Package sqlite 提供 SQLite 数据库驱动接入(纯 Go 实现, 无需 cgo)。
Package sqlite 提供 SQLite 数据库驱动接入(纯 Go 实现, 无需 cgo)。

Jump to

Keyboard shortcuts

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