gorm.DeletedAt是 GORM 用于实现软删除的特殊类型基于sql.NullTime或gorm.io/datatypes中的实现。基本特性表格特性说明类型本质sql.NullTime的扩展包含Time time.Time和Valid bool零值Validfalse表示记录未被删除删除时设置当前时间Validtrue查询时GORM 自动过滤Validtrue已删除的记录定义与使用goimport ( gorm.io/gorm time ) type User struct { ID uint gorm:primaryKey Name string CreatedAt time.Time UpdatedAt time.Time DeletedAt gorm.DeletedAt gorm:index // 软删除字段 }基本操作软删除不真正删除数据go// 删除用户设置 deleted_at 为当前时间 db.Delete(user) // SQL: UPDATE users SET deleted_at2026-07-24 08:23:00 WHERE id 1 // 批量软删除 db.Where(age ?, 60).Delete(User{})查询自动排除已删除go// 普通查询自动加 deleted_at IS NULL db.Find(users) // SQL: SELECT * FROM users WHERE deleted_at IS NULL db.First(user, 1) // SQL: SELECT * FROM users WHERE id 1 AND deleted_at IS NULL查询包含已删除的记录go// 使用 Unscoped 绕过软删除过滤 db.Unscoped().Find(users) // 查全部 db.Unscoped().First(user, 1) // 查单条包括已删除 // 只查已删除的 db.Unscoped().Where(deleted_at IS NOT NULL).Find(users)恢复软删除的记录go// 先找到记录包含已删除的 db.Unscoped().First(user, 1) // 恢复将 deleted_at 设为 NULL db.Model(user).Update(deleted_at, nil) // 或 db.Model(user).Update(deleted_at, gorm.DeletedAt{})永久删除go// 必须加 Unscoped否则只是软删除 db.Unscoped().Delete(user) // SQL: DELETE FROM users WHERE id 1与 null.Time 的关系go// gorm.DeletedAt 本质上就是 sql.NullTime 的别名扩展 type DeletedAt sql.NullTime // 所以它有 deletedAt.Time // 删除时间 deletedAt.Valid // true已删除, false未删除自定义软删除字段名gotype User struct { ID uint gorm:primaryKey Name string DeletedAt gorm.DeletedAt gorm:index;column:deleted_time // 自定义列名 }注意事项表格注意点说明必须加gorm:index否则查询性能差因为大部分查询都要过滤deleted_at IS NULL关联查询关联模型也会自动过滤已删除记录唯一索引软删除场景下唯一索引需要包含deleted_at否则删除后无法插入相同数据不兼容db.RowsAffected软删除返回的 RowsAffected 是更新数不是删除数唯一索引处理常见问题go// ❌ 错误这样删除后再插入相同 email 会报唯一冲突 type User struct { ID uint gorm:primaryKey Email string gorm:uniqueIndex DeletedAt gorm.DeletedAt gorm:index } // ✅ 正确唯一索引包含 deleted_at type User struct { ID uint gorm:primaryKey Email string gorm:uniqueIndex:idx_email_deleted DeletedAt gorm.DeletedAt gorm:uniqueIndex:idx_email_deleted }总结表格操作方法软删除db.Delete(user)查未删除db.Find(users)自动过滤查全部db.Unscoped().Find(users)恢复db.Model(user).Update(deleted_at, nil)永久删除db.Unscoped().Delete(user)
