生产环境应选用 deleted_at 而非 is_deleted，因其支持时间审计、恢复判断及按时间批量清理；需统一字段类型为 datetime 或 None，封装 find_active 方法自动过滤，并在 update_one 中标记软删、重建复合索引、聚合管道中显式排除。
软删除字段该用 deleted_at 还是 is_deleted？
直接用布尔字段 is_deleted 最简单，但丢失时间信息；用 deleted_at（datetime 类型）更利于审计和恢复判断。生产环境建议选后者——它能自然区分“未删”（None）、“已软删”（有时间戳）、甚至支持按时间范围批量清理。MongoDB 本身不强制 schema，但所有文档统一字段类型才能用索引加速查询，所以务必确保该字段始终为 datetime 或 None，不要混用 0、False 等假值。
查询时如何自动过滤已软删文档？
硬编码每次查都加 {"deleted_at": {"$eq": None}} 容易遗漏。推荐封装一个基础查询方法：
def find_active(collection, filter_dict=None):
if filter_dict is None:
filter_dict = {}
# 自动排除软删项
filter_dict["deleted_at"] = {"$eq": None}
return collection.find(filter_dict)注意：如果传入的 filter_dict 已含 deleted_at 键（比如做恢复操作），这个逻辑会覆盖它——所以实际使用中应先判断是否存在该键，或改用 filter_dict.setdefault("deleted_at", {"$eq": None})。
delete_one() 和 update_one() 别混用
MongoDB 没有原生软删除命令，必须用 update_one() 替代 delete_one()：
立即学习“Python免费学习笔记（深入）”；
- ❌ 错误写法：
collection.delete_one({"_id": obj_id})—— 这是真删，不可逆 - ✅ 正确写法：
collection.update_one({"_id": obj_id}, {"$set": {"deleted_at": datetime.utcnow()}}) - ⚠️ 注意：更新前最好检查文档是否存在且未被软删，避免误标已删文档（可用
upsert=False+return_document=ReturnDocument.BEFORE配合判断）
索引和聚合管道里别漏掉软删除条件
加了 deleted_at 字段后，旧索引（如 {"name": 1}）对软删数据仍有效，但查询结果会包含已删文档。必须重建带过滤条件的复合索引：
collection.create_index([("name", 1), ("deleted_at", 1)])聚合管道中也一样——$match 阶段必须显式加 {"deleted_at": {"$eq": None}}，否则 $group 或 $lookup 可能统计/关联到已软删数据。这点容易在复杂聚合里被忽略，尤其当子管道复用主查询变量时。
软删除不是加个字段就完事，关键在所有读写路径的一致性：写用 update_one 标记，读用统一过滤逻辑，索引和聚合同步适配。漏掉任意一环，数据一致性就崩了。
