SQLAlchemy软删除怎么实现

wen python案例 2026-07-12 1

SQLAlchemy软删除实践指南：从原理到完整实现方案

📖 文章导读

章节	内容说明
什么是软删除？	概念解析与核心价值
为什么需要软删除？	对比物理删除的5大优势
SQLAlchemy软删除实现方案	3种主流实现方式详解
完整代码示例	可复用的软删除Mixin
查询时自动过滤	如何让软删除透明化
软删除的陷阱与最佳实践	常见问题与规避策略
问答环节	5个高频实务问题解答

什么是软删除？

软删除（Soft Delete） 是指不真正从数据库中物理删除记录，而是通过标记（如is_deleted字段或deleted_at时间戳）来标识该记录已被“删除”，被标记的记录在常规查询中被过滤,但数据本身仍保留在表中。

SQLAlchemy软删除怎么实现

# 示例：软删除标记字段
class User(Base):
    __tablename__ = 'users'
    id = Column(Integer, primary_key=True)
    name = Column(String(50))
    is_deleted = Column(Boolean, default=False)  # 软删除标记
    deleted_at = Column(DateTime, nullable=True) # 删除时间

为什么需要软删除？

对比维度	物理删除	软删除
数据恢复	❌ 需要binlog或备份	✅ 直接取消标记
历史审计	❌ 丢失记录	✅ 完整保留轨迹
关联数据	❌ 可能级联删除失误	✅ 保留关联完整性
回滚操作	❌ 不可逆	✅ 可逆
查询性能	无影响（数据物理消失）	需添加过滤条件

核心价值：软删除是数据资产安全的最后一道防线，尤其适用于金融、医疗、电商等对数据追溯有严格要求的场景。

SQLAlchemy软删除实现方案

手动标记法（最基础）

class Article(Base):
    __tablename__ = 'articles'
    id = Column(Integer, primary_key=True)
    is_deleted = Column(Boolean, default=False)
    def soft_delete(self):
        self.is_deleted = True

缺点：每次查询需手动加过滤,容易遗漏。

使用`@hybrid_property` + 默认过滤器（推荐）

from sqlalchemy.ext.hybrid import hybrid_property
class SoftDeleteMixin:
    @hybrid_property
    def deleted(self):
        return self.is_deleted
    @deleted.expression
    def deleted(cls):
        return cls.is_deleted == True

结合`Query`事件拦截（专业级）

利用@event.listens_for监听查询,自动注入过滤条件。

from sqlalchemy import event
from sqlalchemy.orm import Query
class SoftDeleteQuery(Query):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self._soft_delete_filter = True
    def get(self, ident):
        obj = super().get(ident)
        return obj if obj and not obj.is_deleted else None

完整代码示例：可复用的软删除Mixin

from sqlalchemy import Column, Boolean, DateTime, func
from sqlalchemy.ext.declarative import declared_attr
from datetime import datetime
class SoftDeleteMixin:
    """软删除基类混合器"""
    @declared_attr
    def is_deleted(cls):
        return Column(Boolean, default=False, nullable=False, 
                      comment='软删除标记')
    @declared_attr
    def deleted_at(cls):
        return Column(DateTime, nullable=True, 
                      comment='删除时间')
    # 实例方法
    def soft_delete(self):
        self.is_deleted = True
        self.deleted_at = datetime.utcnow()
    def restore(self):
        self.is_deleted = False
        self.deleted_at = None
    # 查询过滤器（配合自定义Query使用）
    @classmethod
    def not_deleted(cls, query):
        return query.filter(cls.is_deleted == False)
# 使用示例
class User(Base, SoftDeleteMixin):
    __tablename__ = 'users'
    id = Column(Integer, primary_key=True)
    name = Column(String(50))
# 软删除
user = session.query(User).first()
user.soft_delete()
session.commit()
# 恢复
user.restore()
session.commit()

查询时自动过滤：让软删除透明化

重写Session的`query`方法（侵入性高）

class MySession(Session):
    def query(self, *entities, **kwargs):
        query = super().query(*entities, **kwargs)
        # 为所有带SoftDeleteMixin的实体添加过滤
        for entity in entities:
            if isinstance(entity, type) and SoftDeleteMixin in entity.__bases__:
                query = query.filter(entity.is_deleted == False)
        return query

使用SQLAlchemy 2.0的`with_loader_criteria`（推荐）

from sqlalchemy.orm import with_loader_criteria
for user in session.execute(
    select(User).options(
        with_loader_criteria(User, User.is_deleted == False)
    )
).scalars():
    print(user.name)

全局事件监听（零侵入）

@event.listens_for(Query, "before_compile", retval=True)
def soft_delete_filter(query):
    for entity in query.column_descriptions:
        entity_type = entity['type']
        if hasattr(entity_type, 'is_deleted'):
            query = query.filter(entity_type.is_deleted == False)
    return query

软删除的陷阱与最佳实践

⚠️ 常见陷阱

唯一约束冲突：软删除的记录仍会占用唯一键，如用户名。
- 解决方案：使用复合唯一索引 (username, is_deleted) 或使用唯一删除标记
关联查询遗漏：外键关联未考虑软删除，导致级联问题。
- 解决方案：在关联表上也添加软删除，或使用lazy='dynamic'自过滤
统计、报告数据偏差：COUNT(*)包含软删除记录。
- 解决方案：始终使用filter(is_deleted==False)