mysql

package
v0.18.4 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 19 Imported by: 1

Documentation

Overview

Package mysql 提供 MySQL 数据库的 ORM 封装,基于 GORM,包含连接创建、连接池配置、表名处理与分页查询等辅助方法。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AllTableName

type AllTableName struct {
	TableName string `gorm:"table_name"`
}

AllTableName 用于映射 information_schema 查询结果的表名字段。

type FindPageOptions added in v0.11.1

type FindPageOptions struct {
	// 查询配置
	Page        int  `default:"1"`     // 页码,默认 1
	PageSize    int  `default:"10"`    // 分页大小,默认 10,最大 1000
	ShowDeleted bool `default:"false"` // 是否显示软删除数据,默认 false

	// 模型配置
	PkId            string `default:"id"` // 主键字段名,默认 "id"
	ModelTableAlias string `default:""`   // 模型表别名,默认为表名

	// 回调
	ListQuery  func(*gorm.DB) *gorm.DB                   // 可选,自定义查询回调
	ListSelect func(*gorm.DB) *gorm.DB                   // 可选,自定义查询字段回调
	ListOrder  func() interface{}                        // 可选,自定义排序回调
	ListEach   func(interface{}) interface{}             // 可选,自定义遍历回调
	ListReturn func(jcbaseGo.ListData) jcbaseGo.ListData // 可选,自定义返回回调
}

FindPageOptions 定义分页查询选项,语义与 CRUD list 保持一致;

type Instance

type Instance struct {
	Dsn  string
	Conf jcbaseGo.DbStruct
	Db   *gorm.DB

	Errors []error
	// contains filtered or unexported fields
}

Instance 表示 MySQL 连接实例,封装 DSN、数据库配置、连接句柄、调试状态与错误收集。

func New

func New(dbConfig jcbaseGo.DbStruct, opts ...string) (*Instance, error)

New 创建一个 MySQL 实例并建立数据库连接; 可通过可选参数 `opts[0]` 指定配置别名以存入环境变量。

func NewWithDebugger added in v0.13.8

func NewWithDebugger(dbConfig jcbaseGo.DbStruct, debuggerLogger debugger.LoggerInterface, opts ...string) (*Instance, error)

NewWithDebugger 创建MySQL实例并集成debugger日志记录 参数:

  • dbConfig: 数据库配置
  • debuggerLogger: debugger日志记录器
  • opts: 可选参数,第一个参数为配置别名

返回:

  • *Instance: MySQL实例

func (*Instance) AddError

func (c *Instance) AddError(err error)

AddError 将错误追加到实例的错误收集切片中(忽略 nil)。

func (*Instance) Close added in v0.17.7

func (c *Instance) Close() error

Close 关闭底层连接池并将实例标记为已关闭;用于测试、短生命周期进程收尾或多实例切换场景。

关闭语义:与 EnableAutoReconnect 对齐——显式关闭视为主动下线,关闭后 GetDb() 返回 nil, 且不会触发自动重连把连接池重新建起来(自动重连仅用于意外断连场景)。 重复调用安全,不会panic。

返回值:

  • error: 底层连接池关闭失败时返回该错误;实例未建立过连接时返回 nil

使用示例:

inst, err := mysql.New(conf)
if err != nil {
    panic(err)
}
defer func() { _ = inst.Close() }()

func (*Instance) Debug

func (c *Instance) Debug() *Instance

Debug 开启调试模式,后续通过 `GetDb()` 获取的 *gorm.DB 将启用 Debug。

func (*Instance) DisableAutoReconnect added in v0.13.11

func (c *Instance) DisableAutoReconnect() *Instance

DisableAutoReconnect 禁用自动重连功能

func (*Instance) EnableAutoReconnect added in v0.13.11

func (c *Instance) EnableAutoReconnect() *Instance

EnableAutoReconnect 启用自动重连功能

func (*Instance) EnableContextAwareSQLLogging added in v0.15.0

func (c *Instance) EnableContextAwareSQLLogging(fallbackLogger debugger.LoggerInterface, opts ...interface{}) *Instance

EnableContextAwareSQLLogging 为当前数据库实例启用上下文感知的SQL日志记录(模式B)

本方法全局只需在初始化阶段调用一次:运行期每条SQL会依据 context.Context 中 携带的请求级Logger路由到对应请求的日志中,并发请求之间互不覆盖。 需要 debugger 中间件已开启,它会把请求级Logger自动注入 request 的 context。

参数:

  • fallbackLogger: 兜底Logger,context 中无Logger时使用; 建议传 dbg.GetMainLogger(),使启动迁移、定时任务等无请求上下文的SQL也能落盘
  • opts: 可选参数(日志级别、慢查询阈值),语义同 EnableSQLLogging

返回:

  • *Instance: 已启用上下文感知SQL日志的数据库实例

使用示例:

library.Mysql.EnableContextAwareSQLLogging(dbg.GetMainLogger())
library.Mysql.EnableContextAwareSQLLogging(dbg.GetMainLogger(), debugger.LevelInfo, 100*time.Millisecond)

func (*Instance) EnableSQLLogging added in v0.13.8

func (c *Instance) EnableSQLLogging(debuggerLogger debugger.LoggerInterface, opts ...interface{}) *Instance

EnableSQLLogging 为当前数据库实例启用SQL日志记录 参数:

  • debuggerLogger: debugger日志记录器
  • logLevel: GORM日志级别(可选,默认logger.Info)
  • slowThreshold: 慢查询阈值(可选,默认200ms)

返回:

  • *Instance: 支持SQL日志记录的数据库实例

func (*Instance) Error

func (c *Instance) Error() []error

Error 返回已收集的非 nil 错误列表。

func (*Instance) FindForPage added in v0.11.1

func (c *Instance) FindForPage(model interface{}, options *FindPageOptions) (jcbaseGo.ListData, error)

FindForPage 按分页选项查询并返回列表数据;

func (*Instance) GetAllTableName

func (c *Instance) GetAllTableName() (tableNames []AllTableName, err error)

GetAllTableName 查询并返回当前数据库中的所有表名(过滤视图与系统表)。

func (*Instance) GetConf added in v0.10.2

func (c *Instance) GetConf() interface{}

GetConf 返回当前实例的原始配置结构。

func (*Instance) GetDb

func (c *Instance) GetDb() *gorm.DB

GetDb 返回当前数据库连接;若已开启调试模式返回 Debug 包装的连接。 调试模式优先级:debuggerLogger > debug标志 注意:此方法会验证连接有效性并在需要时尝试重连,支持并发安全

func (*Instance) GetDebuggerLogger added in v0.13.8

func (c *Instance) GetDebuggerLogger() debugger.LoggerInterface

GetDebuggerLogger 获取debugger日志记录器

func (*Instance) GetReconnectConfig added in v0.13.11

func (c *Instance) GetReconnectConfig() ReconnectConfig

GetReconnectConfig 获取当前的重连配置

func (*Instance) IsContextAware added in v0.15.0

func (c *Instance) IsContextAware() bool

IsContextAware 判断当前实例是否处于上下文感知的SQL日志模式

返回:

  • bool: 上下文感知模式返回 true,固定Logger模式返回 false

func (*Instance) SetDebuggerLogger added in v0.13.8

func (c *Instance) SetDebuggerLogger(debuggerLogger debugger.LoggerInterface)

SetDebuggerLogger 设置debugger日志记录器(固定Logger模式)

本方法为模式A入口:所有SQL日志固定写入传入的Logger。 每次调用都会替换GORM实例的Logger,高并发HTTP场景下并发调用会互相覆盖, 需要按请求归属SQL日志的项目请改用 EnableContextAwareSQLLogging。

参数:

  • debuggerLogger: debugger日志记录器实例

func (*Instance) SetMaxRetries added in v0.13.11

func (c *Instance) SetMaxRetries(maxRetries int) *Instance

SetMaxRetries 设置最大重试次数

func (*Instance) SetPingTimeout added in v0.13.11

func (c *Instance) SetPingTimeout(timeout time.Duration) *Instance

SetPingTimeout 设置Ping测试超时时间

func (*Instance) SetReconnectConfig added in v0.13.11

func (c *Instance) SetReconnectConfig(config ReconnectConfig)

SetReconnectConfig 设置连接重连配置 参数:

  • config: 重连配置参数

func (*Instance) SetRetryInterval added in v0.13.11

func (c *Instance) SetRetryInterval(interval time.Duration) *Instance

SetRetryInterval 设置重试间隔

func (*Instance) TableName

func (c *Instance) TableName(tableName *string, quotes ...bool) *Instance

TableName 根据配置的表前缀拼接并可选包裹反引号,返回处理后的表名。 参数:

  • tableName: 传入待处理的表名指针
  • quotes: 可选,是否为表名添加反引号

type ReconnectConfig added in v0.13.11

type ReconnectConfig struct {
	MaxRetries          int           // 最大重试次数,默认3次
	RetryInterval       time.Duration // 重试间隔,默认1秒
	PingTimeout         time.Duration // Ping测试超时时间,默认2秒
	EnableAutoReconnect bool          // 是否启用自动重连,默认true
}

ReconnectConfig 定义连接重连配置 用于控制连接失效时的重连行为

func DefaultReconnectConfig added in v0.13.11

func DefaultReconnectConfig() ReconnectConfig

DefaultReconnectConfig 返回默认的重连配置

Jump to

Keyboard shortcuts

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