Documentation
¶
Index ¶
- func EnsureSelects(tx *gorm.DB, fieldNames ...string)
- func SetFieldDefault(model interface{}, fieldName string, value string, aliasKeys ...string)
- func SetFieldIfExist(model interface{}, fieldName string, value string)
- func SetTimeFieldDefaults(tx *gorm.DB, strTime string, fieldNames ...string)
- type CommonBaseModel
- func (b *CommonBaseModel) BeforeCreate(tx *gorm.DB) (err error)
- func (b *CommonBaseModel) BeforeUpdate(tx *gorm.DB) (err error)
- func (b *CommonBaseModel) GetConfigAlias(model interface{}) string
- func (b *CommonBaseModel) ModelParse(modelType reflect.Type) (tableName string, fields []string, softDeleteField string, ...)
- type MysqlBaseModel
- type SqliteBaseModel
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnsureSelects ¶ added in v0.13.10
EnsureSelects 在使用 Select 限定插入/更新字段时,确保必要字段被包含 典型场景:在钩子中设置 CreatedAt/UpdatedAt 等字段,但外部使用了 Select 导致未持久化 函数名:EnsureSelects 参数:
- tx *gorm.DB:当前事务上下文
- fieldNames ...string:结构体字段名列表(如 "UpdatedAt")
返回值:无(直接修改 tx.Statement.Selects) 异常:无(只在 Schema 可用时生效) 使用示例:
EnsureSelects(tx, "CreatedAt", "UpdatedAt")
func SetFieldDefault ¶ added in v0.17.5
SetFieldDefault 设置字段默认值(仅当字段未设置时写入) 与 SetFieldIfExist 的区别:字段已有值时跳过设置,保留调用方显式指定的时间, 对齐 GORM 原生 autoCreateTime/autoUpdateTime 与 default 标签的"零值才填充"语义。 两种目标类型的"未设置"判定与存在性语义:
- struct:字段必须存在(FieldByName 查不到则静默跳过),且值为零值 (string 为空 / time.Time 为零值 / 指针为 nil)时才写入;
- map:字段名与 aliasKeys 中任意 key 已存在即视为已设置(哪怕值为空字符串), 全部不存在时才以 fieldName 为 key 添加默认值。
函数名:SetFieldDefault 参数:
- model interface{}:模型对象指针或 map
- fieldName string:结构体字段名(非列名),同时作为 map 添加时的 key
- value string:默认值字符串(时间格式:2006-01-02 15:04:05)
- aliasKeys ...string:map 目标的备选 key(如数据库列名 updated_at)
返回值:无 异常:无(内部忽略不可设或类型不匹配的字段) 使用示例:
// 结构体:仅当 CreatedAt 为零值时才填充默认时间 SetFieldDefault(&user, "CreatedAt", "2026-01-01 00:00:00", "created_at") // map:UpdatedAt 与 updated_at 均不存在时才添加默认时间 SetFieldDefault(dest, "UpdatedAt", "2026-01-01 00:00:00", "updated_at")
func SetFieldIfExist ¶ added in v0.10.4
SetFieldIfExist 设置字段值(如果字段存在且可设置) 支持字符串类型和 time.Time 类型字段的自动设置 函数名:SetFieldIfExist 参数:
- model interface{}:模型对象或其指针
- fieldName string:结构体字段名(非列名)
- value string:用于设置的字符串值(时间格式:2006-01-02 15:04:05)
返回值:无 异常:无(内部忽略不可设或类型不匹配的字段) 使用示例:
SetFieldIfExist(&user, "UpdatedAt", "2025-01-01 00:00:00")
func SetTimeFieldDefaults ¶ added in v0.17.5
SetTimeFieldDefaults 通过 GORM 事务上下文为未设置的时间字段批量填充默认值 供基础模型钩子内部使用,也可在业务模型自定义 BeforeCreate/BeforeUpdate 钩子中复用(如为业务自有时间字段兜底)。 内部包含三层保护:
- Schema 校验:字段不存在于模型中时直接跳过,避免向 map Dest 添加 GORM 无法解析的 key(未识别的 key 会被当作裸列名生成 SQL 而报错);
- Omit 检查:被 Omit 的字段(按字段名或列名匹配)不设置;
- 列名解析:将字段名解析为数据库列名,作为 map 场景的备选 key (map 更新时调用方通常使用列名)。
函数名:SetTimeFieldDefaults 参数:
- tx *gorm.DB: 当前 GORM 事务上下文(钩子回调参数)
- strTime: 默认时间字符串(格式 2006-01-02 15:04:05)
- fieldNames: 结构体字段名列表(如 "UpdatedAt")
返回值:无 异常:无 使用示例:
// 业务模型自定义钩子中为自有时间字段兜底
func (u *User) BeforeCreate(tx *gorm.DB) (err error) {
if err = u.MysqlBaseModel.BeforeCreate(tx); err != nil {
return err
}
base.SetTimeFieldDefaults(tx, time.Now().Format("2006-01-02 15:04:05"), "LoginAt")
return nil
}
Types ¶
type CommonBaseModel ¶ added in v0.13.22
type CommonBaseModel struct{}
CommonBaseModel 跨数据库通用基础模型 不绑定具体数据库驱动,字段由业务模型自行定义。 提供 CRUD trait 所需的 ModelParse 方法以及 GORM 创建/更新钩子。
func (*CommonBaseModel) BeforeCreate ¶ added in v0.13.22
func (b *CommonBaseModel) BeforeCreate(tx *gorm.DB) (err error)
BeforeCreate 创建前钩子 GORM 在创建记录前自动调用。若模型中不存在对应字段,设置操作会被静默忽略。 仅当 CreatedAt/Created/UpdatedAt/Updated 字段为空值时才填充当前时间; 已显式指定时间的字段(如数据迁移、导入历史数据)不会被覆盖, 对齐 GORM 原生 autoCreateTime 语义。被 Omit 的字段同样跳过。
参数:
- tx *gorm.DB: 当前 GORM 事务上下文,包含 Statement.Dest 与 Statement.Selects
返回值:
- err error: 错误信息,当前实现始终返回 nil
异常:
- 无显式异常,内部通过反射安全设置字段值
使用示例:
type User struct {
base.CommonBaseModel
Username string `gorm:"column:username" json:"username"`
}
db.Create(&user) // CreatedAt/UpdatedAt 为空时自动填充;已指定则保留
func (*CommonBaseModel) BeforeUpdate ¶ added in v0.13.22
func (b *CommonBaseModel) BeforeUpdate(tx *gorm.DB) (err error)
BeforeUpdate 更新前钩子 GORM 在更新记录前自动调用。若模型中不存在对应字段,设置操作会被静默忽略。 仅当 UpdatedAt/Updated 字段为空值时才填充当前时间;已显式指定时间的字段 不会被覆盖,对齐 GORM 原生 autoUpdateTime 语义。被 Omit 的字段同样跳过。
参数:
- tx *gorm.DB: 当前 GORM 事务上下文,包含 Statement.Dest 与 Statement.Selects
返回值:
- err error: 错误信息,当前实现始终返回 nil
异常:
- 无显式异常,内部通过反射安全设置字段值
使用示例:
type User struct {
base.CommonBaseModel
Username string `gorm:"column:username" json:"username"`
}
// UpdatedAt 为空时自动填充;map 中已带 updated_at 则保留
db.Model(&user).Updates(map[string]interface{}{"username": "new"})
func (*CommonBaseModel) GetConfigAlias ¶ added in v0.13.22
func (b *CommonBaseModel) GetConfigAlias(model interface{}) string
GetConfigAlias 获取数据库配置别名 若模型实现了 ConfigAlias() string 方法,则使用模型自定义的别名;否则返回默认别名 "db"。
参数:
- model: 模型实例
返回值:
- string: 配置别名,对应环境变量中的 jc_mysql_<alias> 或 jc_sql_lite_<alias>
func (*CommonBaseModel) ModelParse ¶ added in v0.13.22
func (b *CommonBaseModel) ModelParse(modelType reflect.Type) (tableName string, fields []string, softDeleteField string, softDeleteCondition string)
ModelParse 解析模型信息(供 CRUD trait 使用) 参数:
- modelType: 具体模型的反射类型
返回值:
- tableName: 数据表名称,优先使用 TableName() 方法
- fields: 模型字段列表(包含匿名嵌入结构体的字段)
- softDeleteField: 软删除字段名
- softDeleteCondition: 软删除条件
type MysqlBaseModel ¶
type MysqlBaseModel struct {
CommonBaseModel
}
MysqlBaseModel gorm基础模型 继承 CommonBaseModel 的 BeforeCreate、BeforeUpdate 等方法, 默认配置别名为 "db"。
func (*MysqlBaseModel) ModelParse ¶
func (b *MysqlBaseModel) ModelParse(modelType reflect.Type) (tableName string, fields []string, softDeleteField string, softDeleteCondition string)
ModelParse 解析模型信息(供 CRUD trait 使用) 复用 CommonBaseModel 的解析逻辑,默认优先读取 MySQL 配置。
参数:
- modelType: 具体模型的反射类型
返回值:
- tableName: 数据表名称
- fields: 模型字段列表
- softDeleteField: 软删除字段名
- softDeleteCondition: 软删除条件
type SqliteBaseModel ¶
type SqliteBaseModel struct {
CommonBaseModel
}
SqliteBaseModel gorm基础模型 继承 CommonBaseModel 的 BeforeCreate、BeforeUpdate 等方法, 默认配置别名为 "main"。
func (*SqliteBaseModel) GetConfigAlias ¶ added in v0.11.1
func (b *SqliteBaseModel) GetConfigAlias(model interface{}) string
GetConfigAlias 获取数据库配置别名 SQLite 默认使用 "main" 作为配置别名。
参数:
- model: 模型实例
返回值:
- string: 配置别名
func (*SqliteBaseModel) ModelParse ¶
func (b *SqliteBaseModel) ModelParse(modelType reflect.Type) (tableName string, fields []string, softDeleteField string, softDeleteCondition string)
ModelParse 解析模型信息(供 CRUD trait 使用) 复用 CommonBaseModel 的解析逻辑,默认优先读取 SQLite 配置。
参数:
- modelType: 具体模型的反射类型
返回值:
- tableName: 数据表名称
- fields: 模型字段列表
- softDeleteField: 软删除字段名
- softDeleteCondition: 软删除条件