Documentation
¶
Overview ¶
Package mysql 提供 MySQL 数据库的 ORM 封装,基于 GORM,包含连接创建、连接池配置、表名处理与分页查询等辅助方法。
Index ¶
- type AllTableName
- type FindPageOptions
- type Instance
- func (c *Instance) AddError(err error)
- func (c *Instance) Close() error
- func (c *Instance) Debug() *Instance
- func (c *Instance) DisableAutoReconnect() *Instance
- func (c *Instance) EnableAutoReconnect() *Instance
- func (c *Instance) EnableContextAwareSQLLogging(fallbackLogger debugger.LoggerInterface, opts ...interface{}) *Instance
- func (c *Instance) EnableSQLLogging(debuggerLogger debugger.LoggerInterface, opts ...interface{}) *Instance
- func (c *Instance) Error() []error
- func (c *Instance) FindForPage(model interface{}, options *FindPageOptions) (jcbaseGo.ListData, error)
- func (c *Instance) GetAllTableName() (tableNames []AllTableName, err error)
- func (c *Instance) GetConf() interface{}
- func (c *Instance) GetDb() *gorm.DB
- func (c *Instance) GetDebuggerLogger() debugger.LoggerInterface
- func (c *Instance) GetReconnectConfig() ReconnectConfig
- func (c *Instance) IsContextAware() bool
- func (c *Instance) SetDebuggerLogger(debuggerLogger debugger.LoggerInterface)
- func (c *Instance) SetMaxRetries(maxRetries int) *Instance
- func (c *Instance) SetPingTimeout(timeout time.Duration) *Instance
- func (c *Instance) SetReconnectConfig(config ReconnectConfig)
- func (c *Instance) SetRetryInterval(interval time.Duration) *Instance
- func (c *Instance) TableName(tableName *string, quotes ...bool) *Instance
- type ReconnectConfig
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 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) Close ¶ added in v0.17.7
Close 关闭底层连接池并将实例标记为已关闭;用于测试、短生命周期进程收尾或多实例切换场景。
关闭语义:与 EnableAutoReconnect 对齐——显式关闭视为主动下线,关闭后 GetDb() 返回 nil, 且不会触发自动重连把连接池重新建起来(自动重连仅用于意外断连场景)。 重复调用安全,不会panic。
返回值:
- error: 底层连接池关闭失败时返回该错误;实例未建立过连接时返回 nil
使用示例:
inst, err := mysql.New(conf)
if err != nil {
panic(err)
}
defer func() { _ = inst.Close() }()
func (*Instance) DisableAutoReconnect ¶ added in v0.13.11
DisableAutoReconnect 禁用自动重连功能
func (*Instance) EnableAutoReconnect ¶ added in v0.13.11
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) 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 ¶
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
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
SetMaxRetries 设置最大重试次数
func (*Instance) SetPingTimeout ¶ added in v0.13.11
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
SetRetryInterval 设置重试间隔
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 返回默认的重连配置