DeletedAt 字段必须是 *time.Time 类型,因为 GORM 通过类型(指针)和标签双重判定逻辑删除;若用 time.Time 零值会被误判为已删除,导致全表过滤。

为什么 DeletedAt 字段必须是 *time.Time
GORM 的逻辑删除依赖 gorm.DeletedAt 字段自动识别软删状态,但它不是靠字段名“DeletedAt”字符串匹配,而是靠类型和标签双重判定。如果定义成 time.Time(非指针),GORM 会认为该字段始终有值(零值 0001-01-01 00:00:00 +0000 UTC 也被视为“已删除”),导致所有记录默认被过滤掉。
正确做法是声明为指针类型,并配合 gorm.DeletedAt 标签(虽非强制,但显式声明更可靠):
type User struct {
ID uint `gorm:"primaryKey"`
Name string `gorm:"not null"`
DeletedAt *time.Time `gorm:"index"` // 建议加索引,避免全表扫描
}
注意:GORM v2 默认启用软删,只要存在 *time.Time 类型的 DeletedAt 字段(无论是否打标签),就会自动启用逻辑删除行为。
如何真正执行物理删除(绕过逻辑删除)
调用 Delete 方法时,GORM 默认只更新 DeletedAt。要彻底从数据库移除记录,必须显式禁用软删钩子:
- 用
Unscoped():跳过所有软删条件,包括查询、更新、删除 - 用
Unscoped().Delete()才能物理删除
常见错误写法:db.Delete(&user) 或 db.Unscoped().Where("id = ?", id).Delete(&User{}) —— 后者仍会生成 UPDATE 语句(因为 Delete 对结构体默认走软删)。
正确写法:
db.Unscoped().Where("id = ?", id).Delete(&User{}) // ✅ 物理删除
或更安全地指定主键:
db.Unscoped().Delete(&user) // ✅ user.ID 已赋值时可用
查询时如何包含已逻辑删除的记录
默认情况下,Find、First 等方法自动添加 WHERE deleted_at IS NULL 条件。要查出含软删数据的完整集合,必须用 Unscoped():
var users []User db.Unscoped().Find(&users) // 返回所有记录,含 deleted_at != NULL 的
但要注意:Unscoped() 是“全局绕过”,它同时禁用其他作用域(如租户隔离 scope),所以不要滥用。如只需查“已删除”的记录,应明确写条件:
db.Where("deleted_at IS NOT NULL").Find(&users)
这样既精准,又不干扰其他 scope 行为。
自定义逻辑删除字段名或禁用软删
如果你不想用 DeletedAt,比如想叫 IsDeleted(bool 类型)或 RemovedAt(*time.Time),GORM 支持通过 gorm.Model 或全局配置覆盖:
- 单模型禁用软删:
gorm.Model(&User{}).Unscoped()不够,得在 struct 上用gorm:" 隐藏字段,或更直接——在迁移时去掉该字段 - 改用布尔字段:GORM 原生不支持
IsDeleted bool自动软删,必须手动写Where("is_deleted = ?", false)并自行管理 - 改字段名:可保留
*time.Time类型,但用gorm:"column:removed_at;index"并配合gorm.DeletedAt标签(v2.2.5+ 支持)
最稳妥的自定义方式是:保持 DeletedAt *time.Time 字段,仅通过视图或查询条件模拟不同语义,避免偏离 GORM 软删机制本身。
逻辑删除看似简单,但字段类型、Unscoped() 的作用范围、以及它与其他 scope 的叠加关系,稍不注意就会查不到数据或误删。尤其在复合查询中混用 Unscoped() 和普通条件时,建议始终用 Session(&gorm.Session{DryRun: true}) 先看生成的 SQL。


















