Go语言软删除实现，GORMDeletedAt详解

本文深入剖析了Go语言中使用GORM实现数据库软删除的关键细节与常见陷阱，重点强调DeletedAt字段必须声明为*time.Time指针类型以避免零值误判、Unscoped()方法在查询和删除中的双重作用与风险、物理删除对钩子函数及数据一致性的破坏性影响，以及自定义软删除字段名的局限性；它不仅揭示了GORM软删除机制在查询过滤、关联加载、生命周期钩子等环节的自动注入逻辑，更警示开发者：软删除绝非简单添加字段即可，而需系统理解其默认行为与显式覆盖之间的微妙平衡，否则极易导致数据不可见、误删、缓存失效等线上隐患。

为什么 DeletedAt 字段必须是 *time.Time

因为 GORM 的软删除依赖字段是否为 nil 来判断记录是否“已删除”——nil 表示未删除，非 nil 表示已逻辑删除。如果定义成 time.Time（值类型），零值 0001-01-01 00:00:00 +0000 UTC 会被误判为“已删除”，导致新插入记录直接不可见。

• 正确写法：DeletedAt *time.Time `gorm:"index"`
• 错误写法：DeletedAt time.Time（哪怕加了 sql:"default:null" 也没用）
• 不加 index 标签会导致 WHERE deleted_at IS NULL 查询变慢，尤其数据量大时

GORM 默认不自动启用软删除，必须显式调用 Unscoped() 才能查到已删记录

这是最容易踩的坑：你写了 DeletedAt 字段，但 db.First(&u, 1) 查不到已被软删除的用户，不是 bug，是设计行为。GORM 在所有普通查询中自动追加 WHERE deleted_at IS NULL。

• 查“存活”记录：db.Where("name = ?", "foo").First(&u) ✅ 自动过滤
• 查包括已删记录：db.Unscoped().Where("name = ?", "foo").First(&u) ✅
• 只查已删记录：db.Unscoped().Where("deleted_at IS NOT NULL").Find(&users) ✅
• Unscoped() 是会透传到关联查询里的，比如 db.Unscoped().Preload("Orders").First(&u)，连 Orders 表也会跳过软删除过滤

硬删除前务必确认是否真要物理清除，否则用 Unscoped().Delete() 会绕过所有钩子

Delete() 方法在有 DeletedAt 字段时默认只做软删除；但一旦加了 Unscoped()，就变成直连数据库执行 DELETE FROM，不仅跳过 BeforeDelete 钩子，还可能破坏外键约束或触发器逻辑。

• 软删除（推荐日常使用）：db.Delete(&user)
• 物理删除（谨慎！）：db.Unscoped().Delete(&user)
• 批量物理删除更危险：db.Unscoped().Where("created_at —— 这种操作建议先 SELECT 出 ID 列表人工核对
• 如果你依赖 AfterDelete 清理缓存或发消息，物理删除会让这些逻辑完全失效

自定义软删除字段名时，GORM 不识别 gorm.Model 的 DeletedAt，得手动配置

如果你不想用 DeletedAt 这个字段名（比如叫 is_deleted 或 removed_at），GORM 不会自动识别——它只对固定字段名开箱即用。必须通过 SetupJoinTable 之外的方式干预，实际只能靠全局配置。

• 统一改名（整个项目）：gorm.Config{NowFunc: func() time.Time { return time.Now() }, SoftDeleteField: "RemovedAt"}
• 单个模型覆盖：func (User) TableName() string { return "users" } 不起作用；必须用 gorm.Model(&User{}).SetupJoinTable(...)？不行。真实做法是：不改字段名，或者接受 GORM 只认 DeletedAt
• 用布尔型字段（如 IsDeleted bool）实现软删除？可以，但得自己写全部查询条件、禁用 GORM 软删除机制（DisableForeignKeyConstraintWhenMigrating 无关），基本等于放弃插件

今天关于《Go语言软删除实现，GORMDeletedAt详解》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！