DeletedAt 字段必须为 *time.Time 类型,GORM 通过 nil 判断未删除;命名须为 DeletedAt(驼峰),否则需全局配置 SoftDeleteField;软删除依赖字段类型、命名、索引及查询方式,关联预加载默认不过滤已删记录。

DeletedAt 字段类型必须是 *time.Time,不是 time.Time
GORM 用 nil 判断记录是否“未删除”,*time.Time 的 nil 值天然对应数据库的 NULL;而 time.Time 是值类型,零值 0001-01-01 00:00:00 +0000 UTC 会被当成已删除,新插入的记录查不到。
常见错误:加了 DeletedAt time.Time `gorm:"default:null"`,看着像支持 NULL,但 GORM 不认——它只看 Go 类型,不是看 SQL 约束。
- 正确写法:
DeletedAt *time.Time `gorm:"index"` - 最省事写法:直接嵌入
gorm.Model(它自带*time.Time类型的DeletedAt) - 别漏
gorm:"index":否则WHERE deleted_at IS NULL查询在大数据量时可能全表扫
GORM 不会自动识别 _Deleted_At 这类自定义字段名
默认只认 DeletedAt(驼峰、首字母大写、无下划线)。你命名成 _Deleted_At 或 removed_at,GORM 完全无视,软删除逻辑不会触发。
想用非标准字段名,必须全局配置:gorm.Config{SoftDeleteField: "removed_at"};单模型覆盖不可行,SetupJoinTable 对软删除字段无效。
- 如果已有表结构用的是
_Deleted_At,别硬改字段名,老老实实配全局SoftDeleteField - 配完还得确保迁移时该字段是
DATETIME或TIMESTAMP类型、允许NULL,不能是TINYINT或BOOLEAN -
NowFunc建议设为time.Now().UTC(),避免时区错乱导致deleted_at时间不准
Delete() 默认就是软删除,但前提是你没绕过 GORM
db.Delete(&u) 或 db.Delete(&User{}, 123) 才会触发软删除逻辑;任何原生 SQL(比如 db.Exec("DELETE FROM users WHERE id = ?"))或 db.Where().Delete()(没传指针)都不会动 DeletedAt,等于物理删了还留着“幽灵状态”。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器,提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象,支持命名依赖等
- 批量软删:
db.Where("status = ?", "draft").Delete(&Post{})→ 生成UPDATE ... SET deleted_at = NOW() - 误用
db.Unscoped().Delete(&u)就是物理删,不走钩子、不更新关联、不触发AfterDelete - 恢复软删记录只能靠:
db.Unscoped().Model(&u).Update("deleted_at", nil),注意是nil,不是time.Time{}
关联查询(Preload)默认不遵守软删除规则
db.Preload("Orders").Find(&user) 会把用户关联的已软删订单也查出来——GORM 不自动给关联表加 WHERE deleted_at IS NULL。
这不是 bug,是设计:每个模型的软删逻辑独立,除非你显式干预。
- 安全写法:
db.Preload("Orders", func(db *gorm.DB) *gorm.DB { return db.Where("deleted_at IS NULL") }) -
Unscoped()是透传的:db.Unscoped().Preload("Orders").Find(&user)会让主表和关联表都跳过软删过滤 - 外键约束不受影响:软删主表,子表记录还在,哪怕子表也有
DeletedAt字段,也不会被自动软删
软删除真正难的不是配置字段,而是让所有查询路径(尤其是关联、统计、后台列表、定时任务)都意识到“已删数据仍存在”。最容易被忽略的,是 Count() 默认不包含软删记录,但业务指标如“总注册用户数”往往需要它。










