阅读本教程后,你将能够彻底掌握在Laravel应用中如何精准查询已被软删除(trashed)的数据记录、完成单条或批量数据恢复,以及执行最终物理粉碎删除的全流程操作,避免因数据“假死”引发的业务逻辑错误。
第一步:环境确认与模型软删除基础配置

在操作trashed相关逻辑前,必须确保数据表和Eloquent模型已激活软删除机制。
1. 检查数据库迁移文件:在目标表的迁移文件中,确认包含`$table->softDeletes();`字段定义,这会在数据库中生成一个可为NULL的`deleted_at`时间戳字段。若尚未添加,请创建新迁移执行`Schema::table('users', function (Blueprint $table) { $table->softDeletes(); });`并运行迁移。
2. 配置模型类:打开对应的模型文件(例如`app/Models/Post.php`),在类顶部引入Trait:`use Illuminate\Database\Eloquent\SoftDeletes;`,并在模型类内部声明`use SoftDeletes;`。
3. 测试基础软删除:执行`$post->delete();`,此时查看数据库,该条记录未被物理移除,而是`deleted_at`被填充为当前时间戳。该记录在默认的Eloquent查询(如`Post::all()`)中会被自动过滤。
第二步:包含软删除数据的混合查询(withTrashed)
当后台管理系统需要展示包含“已删除”在内的全量数据列表,或需要验证某个唯一值是否存在时,需穿透默认的软删除过滤作用域。
1. 查询全部数据(包含正常数据与trashed数据):
使用`withTrashed()`方法构建查询构造器:
`$allPosts = Post::withTrashed()->get();`
2. 条件过滤与分页:
`withTrashed()`可与常见查询链式组合使用:
`$posts = Post::withTrashed()->where('category_id', 1)->orderBy('id', 'desc')->paginate(15);`
3. 检查单条记录是否处于trashed状态:
使用模型实例内置的`trashed()`辅助判断方法:
`$post = Post::withTrashed()->find($id);`
`if ($post && $post->trashed()) { // 记录已被软删除,执行特定视图渲染或告警逻辑 }`
第三步:精准过滤仅被软删除的数据(onlyTrashed)
在构建“回收站”功能界面时,通常需要专门列出那些被废弃但尚未彻底清除的项,此时需要排除所有活跃数据。
1. 查询仅被软删除的列表:
调用`onlyTrashed()`方法:
`$trashedPosts = Post::onlyTrashed()->get();`
2. 统计回收站内的数据总量:
通过聚合查询统计trashed记录数以供前端徽章显示:
`$trashedCount = Post::onlyTrashed()->count();`
3. 回收站内部的数据检索:
若需在已软删除数据中搜索特定关键词:
`$searchTrashed = Post::onlyTrashed()->where('title', 'like', '%系统通知%')->get();`
第四步:恢复已软删除的数据(Restore)
当用户点击“撤销删除”或管理员需要从回收站还原内容时,通过更新`deleted_at`为NULL实现恢复。
1. 单条模型实例恢复:
先通过`withTrashed()`或`onlyTrashed()`拿到特定对象,调用`restore()`方法:
`$post = Post::onlyTrashed()->findOrFail($id);`
`$post->restore();`
2. 批量快速恢复:
直接在查询构造器上链式调用`restore()`,无需逐个实例化对象,提高执行效率:
`Post::onlyTrashed()->where('category_id', 2)->restore();`
3. 关联模型联合恢复:
若该模型拥有子级关联(如文章与其评论),需同步还原trashed关联:
`$post = Post::onlyTrashed()->findOrFail($id);`
`$post->restore();`
`$post->comments()->onlyTrashed()->restore();`
第五步:彻底物理粉碎软删除数据(forceDelete)
当回收站到期清理,或用户要求彻底注销数据隐私信息时,必须绕过软删除,执行真正的SQL `DELETE`。
1. 单实例物理删除:
在获取到trashed模型实例后,调用`forceDelete()`方法:
`$post = Post::withTrashed()->findOrFail($id);`
`$post->forceDelete();`
2. 批量物理清除(清空回收站):
通过针对`onlyTrashed()`结果集触发强删:
`Post::onlyTrashed()->forceDelete();`
这将在数据库层面直接执行`DELETE FROM posts WHERE deleted_at IS NOT NULL;`,物理释放存储空间。
常见陷阱与避坑提醒:
1. 数据库Unique唯一索引冲突:若数据表中某个业务字段(如`email`)设置了UNIQUE约束,软删除某用户后,由于记录仍然存在,新用户使用相同邮箱注册时会触发数据库层面的Duplicate entry报错。解决方案是建立联合唯一索引(如`email` + `deleted_at`),或者将唯一验证规则加上软删除过滤。
2. DB Facade查询穿透失效:使用原生`DB::table('posts')->get()`查询时,不会触发Eloquent的全局软删除作用域,默认会查出所有记录(包括`deleted_at`非空项)。若使用DB门面,必须手动追加`->whereNull('deleted_at')`。
3. 关联关系预加载遗漏:使用`$user->posts`获取关联数据时,默认不包含软删除的文章。若需要读取关联的trashed数据,必须在关联定义或查询链上明确声明,如`$user->posts()->withTrashed()->get()`。
4. 模型事件监听差异:执行批量`restore()`或`forceDelete()`直接操作Query Builder时,不会触发Eloquent的`restoring`、`restored`、`forceDeleting`、`forceDeleted`等模型事件;如果业务严重依赖Observer(观察者)同步第三方缓存或搜索引擎,必须通过循环迭代单模型方式执行。
