软删除字段必须用 *time.time 而非 bool 或 time.time，因其能无歧义区分“未删除”（nil）和“已删除”（有时间戳）；bool 无法记录时间，非指针 time.time 的零值会被误判为已删除。
软删除字段为什么必须用 *time.Time 而不是 bool 或 time.Time
因为只有 *time.Time 能无歧义地区分“未删除”（nil）和“已删除”（有具体时间戳）。用 bool deleted 无法记录删除时间，审计困难；用非指针的 deleted_at time.Time 会导致零值 0001-01-01 00:00:00 +0000 UTC 被误判为已删除——GORM 查不到这条记录，但你查数据库时它明明存在。
正确写法：
type User struct {
ID uint `gorm:"primaryKey"`
Name string
DeletedAt *time.Time `gorm:"index"`
}
- GORM v2 默认只识别字段名严格为
DeletedAt（大小写敏感）且类型为*time.Time时才启用软删除逻辑 - 若字段名是
is_deleted或类型是bool，GORM 完全不干预，所有查询都得手动加条件 - 别忘了在迁移时加索引：
gorm:"index"，否则带WHERE deleted_at IS NULL的查询会慢
Unscoped().Save() 为什么恢复不了数据
因为 Save() 不更新受控字段（比如 DeletedAt），即使你写了 user.DeletedAt = nil，GORM 也会忽略这个赋值。
恢复操作必须显式触发字段变更：
- 推荐用内置方法：
db.Unscoped().Model(&user).Restore()—— 它会安全地设DeletedAt = nil并校验是否真被软删除过 - 或者手动更新：
db.Unscoped().Model(&user).Update("deleted_at", nil) - 切忌直接
db.Unscoped().Save(&user)，它不会碰DeletedAt字段 - 恢复前建议先查一次：
db.Unscoped().Where("id = ? AND deleted_at IS NOT NULL", id).First(&user)，避免重复恢复引发状态不一致
Gin 接口里怎么让软删除对前端“透明”
默认情况下，Gin 返回的数据已经过滤掉软删除记录，但前端往往需要知道“这条记录曾存在过”，或做回收站功能。这时候不能只依赖 GORM 默认行为。
- 列表接口如需包含已删除项，加
db.Unscoped()，但别裸用——应配合权限或参数控制，例如：if c.Query("include_deleted") == "true" { db = db.Unscoped() } - 单条查询（如
/users/123）默认应返回 404，但如果业务需要返回“已删除”，就得显式查：db.Unscoped().First(&user, id)，再判断user.DeletedAt != nil - 响应体里带上
"deleted_at": "2026-07-22T14:30:00Z"字段，前端可据此决定展示灰显、禁用或提供“恢复”按钮 - 别忘了禁用缓存：
c.Header("Cache-Control", "no-cache, no-store, must-revalidate")，否则用户刚删完还看到旧数据
关联数据的软删除一致性怎么保障
GORM 不自动级联软删除。删一个 Order，它的 OrderItems 还在，这会导致统计错、导出漏、恢复失败。
- 最稳妥的是在业务层显式处理：先查出子项 ID 列表，再批量更新其
deleted_at - 或用
BeforeDelete钩子，在父记录软删除前同步标记子项：db.Unscoped().Model(&Item{}).Where("order_id = ?", order.ID).Update("deleted_at", time.Now()) - 注意：钩子中调用
db.Unscoped()是必须的，否则查不到已被软删除的父记录 - 如果子表也有软删除字段，恢复父记录时**不会自动恢复子项**，必须单独处理——这点极易被忽略
DeletedAt 类型、所有接口的软删除语义、以及所有关联操作的边界定义。一旦某处漏了 Unscoped() 或用了 bool 字段，后续排查成本远高于初期多写几行校验。
