如何配置ThinkPHP实现数据软删除功能？

本文共计1048个文字，预计阅读时间需要5分钟。

如果在使用ThinkPHP项目中启用软删除功能但数据仍然被物理删除，或查询时无法正确过滤已删除记录，可能是模型配置、数据库字段、操作方式三者未严格对齐。以下是配置软删除功能的步骤：

一、数据库添加软删除字段

软删除依赖一个可为空的时间标记字段，该字段必须存在于对应数据表中，且类型与框架预期一致。字段名默认为delete_time，MySQL中需设为DATETIME或TIMESTAMP类型，并允许NULL值。

1、执行SQL语句添加字段：ALTER TABLE user ADD delete_time DATETIME NULL DEFAULT NULL;

2、若使用迁移文件，应调用$table->softDeletes()（注意：ThinkPHP 6.x不支持Laravel风格迁移写法，此为兼容提示，实际应手写字段定义）。

立即学习“PHP免费学习笔记（深入）”；

3、已有表修改字段后，必须清空runtime/cache/目录，否则模型可能缓存旧结构导致软删除逻辑失效。

二、模型类启用SoftDelete trait并声明配置

仅引入trait不足以激活软删除，必须在模型中显式启用并确保与自动时间戳机制无冲突。框架通过trait注入行为，而非全局开关驱动。

1、在模型文件顶部导入命名空间：use think\model\concern\SoftDelete;

2、在模型类定义中声明trait并设置启用标志：use SoftDelete; protected $useSoftDelete = true;

3、指定软删除字段名（若非默认delete_time）：protected $deleteTime = 'deleted_at';

4、若模型启用自动时间戳（$autoWriteTimestamp = true），切勿将delete_time列入$createTime或$updateTime，否则新增时即写入时间，造成“刚插入即被删”。

三、验证字段类型与模型类型声明一致性

字段类型必须与模型中类型声明匹配，否则框架内部比对失败，导致whereNotNull('delete_time')永远不生效，软删除形同虚设。

1、若数据库字段为DATETIME，模型无需额外声明类型，保持默认即可。

2、若字段为BIGINT存储时间戳，必须在模型中添加：protected $type = ['delete_time' => 'integer'];

3、严禁将字段设为NOT NULL DEFAULT CURRENT_TIMESTAMP，否则新记录插入时delete_time已有值，被误判为已删除。

四、确保删除操作走模型方法而非Db类

软删除逻辑仅在模型层拦截，Db类操作完全绕过该机制，直接执行物理删除。所有删除动作必须通过模型实例或静态方法触发。

1、正确方式（触发软删除）：$user = User::find(123); $user->delete();

2、正确方式（批量软删除）：User::destroy([101, 102, 103]);

3、错误方式（导致真删）：Db::name('user')->where('id', 123)->delete();

4、错误方式（忽略模型逻辑）：User::where('id', 123)->delete();

五、配置查询默认行为与显式解除过滤

启用软删除后，所有模型查询（select、find、where()->select()）默认自动追加WHERE delete_time IS NULL条件。如需查看已删数据，必须主动干预查询链。

1、查全部（含已软删）：User::withTrashed()->select();

2、只查已软删（回收站）：User::onlyTrashed()->select();

3、恢复单条记录前，必须先查出软删状态实例：$user = User::onlyTrashed()->find(123); if ($user) $user->restore();

4、withTrashed()和onlyTrashed()必须在select()或find()前调用，否则无效；它们仅影响当次查询，不改变模型默认行为。