GORM逻辑删除实现全解析

本文深入解析了 GORM 中逻辑删除的核心机制与最佳实践，重点阐明为何 DeletedAt 字段必须声明为 *time.Time 指针类型——根本原因在于 GORM 依赖类型（而非字段名）和标签双重识别软删行为，使用非指针 time.Time 会导致零值被误判为“已删除”，从而意外过滤全部数据；同时详述了如何正确启用逻辑删除、安全执行物理删除（必须配合 Unscoped() 与 Delete 的精准用法）、灵活查询含已删除记录的数据，以及自定义删除字段或禁用软删的高级配置方式，帮助 Go 开发者避免常见陷阱，写出健壮可靠的数据库操作代码。

为什么 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。

以上就是《GORM逻辑删除实现全解析》的详细内容，更多关于的资料请关注golang学习网公众号！