第20章：SQLAlchemy级联、孤儿删除与关系完整性

一、项目背景

“一个用户注销了账号，结果他所有的历史订单也跟着消失了！”

星云电商上季度发生了一次匪夷所思的 P1 事故。运营部门在后台注销了一个长期不活跃的测试账号，结果后台的"全部订单"报表中出现了一大批"幽灵订单"——订单号存在但关联的用户信息全部丢失。更诡异的是，部分订单的明细也消失了。

排查后发现两个相互叠加的问题：

问题一：开发在 User 模型中配置了 relationship("Order", cascade="all, delete-orphan")。当这个用户被从系统中删除时，ORM 层自动级联删除了该用户的所有订单。而订单本身又被配置了 cascade="all, delete-orphan" 联动到 OrderItem——于是一条用户记录的删除，连锁删除了该用户的所有订单和订单明细。三层级联，一次删除，数千条记录灰飞烟灭。

问题二：数据库中订单表的 user_id 设置了 Foreign Key (user_id) REFERENCES users(id) ON DELETE SET NULL——数据库层会将被删除用户的订单中的 user_id 置为 NULL。但 ORM 层也同时配置了 cascade="all, delete-orphan"——它不了解数据库层的 ON DELETE，而是自己发射 DELETE 语句。两套机制互相冲突，导致数据库层把 user_id 设为 NULL 的同时，ORM 层也把整条 order 删了。

这次事故暴露了团队对级联机制的根本性误读——默认配置不等于安全配置，cascade 选项的真正语义远比"全开就完事了"复杂得多。

本章将从 cascade 的五个核心选项出发，理解数据库层 ON DELETE 与 ORM 层 cascade 的双重设计，并实战设计"删订单必删明细、删用户不级联删除历史订单"的安全方案。

二、项目设计

场景：周五上午，事故复盘会。小白准备了一份详细的 cascade 分析报告，小胖一脸后怕，大师带来了一个数据库沙箱来演示。

大师：“小胖，你来说说——当时为了’方便’，你都做了哪些 cascade 配置？”

小胖：“我当时就想——用户删了，订单留着也没用，干脆全删干净。就在 User.orders 的 relationship 上写了 cascade='all, delete-orphan'……”

大师：“然后订单的 Order.items 也写了同样的？”

小胖：“对，OrderItem 是订单的子对象，我觉得也应该跟着删……”

大师：“结果就是三层级联：删用户 → 级联删 200 条订单 → 每条订单又级联删 5 条明细 → 总共删了 1000+ 条记录。你觉得方便，数据可受不了。”

小白：“我梳理了一下，cascade 有 5 个主要选项——”

小胖：“原来 all, delete-orphan 是全部加孤儿删除——我以为只是’联合删除’！”

大师：“技术映射：cascade = 多米诺骨牌规则——你可以设定推倒第一张时，哪些牌跟着倒。”

小白：“那数据库层的 ON DELETE CASCADE 和 ORM 层的 cascade 是什么关系？”

大师：“两层设计。数据库的 ON DELETE 是 DDL 级别的约束——写在 CREATE TABLE 的 FOREIGN KEY 子句中。SQLAlchemy ORM 的 cascade 是 Python 应用层的逻辑——在 session.flush() 时执行。两者独立工作，可以重叠也可以互补。”

小胖：“技术映射：ON DELETE = 数据库物业（你搬走就自动清房）；cascade = Python 管家（按指令清单清房）。”

大师：“两者如何配合有一个最佳实践——数据库层的 ON DELETE 作为最后防线，ORM 层的 cascade 精确控制业务行为。例如：”

# 订单明细：父删子必删——两层都配置
class OrderItem(Base):
    order_id = mapped_column(ForeignKey("orders.id", ondelete="CASCADE"))  # DB 层
    order = relationship("Order", back_populates="items")  # ORM 层不配 cascade

class Order(Base):
    items = relationship("OrderItem", back_populates="order",
                         cascade="all, delete-orphan", passive_deletes=True)
    # cascade：ORM 层级联删除
    # passive_deletes=True：告诉 ORM "DB 层已经有 ON DELETE CASCADE，不需要 ORM 再单独加载子对象"

小白：“passive_deletes=True 是什么意思？”

大师：“当 ORM 删除父对象时，如果不加 passive_deletes，它会先把所有子对象加载到内存，然后逐个 DELETE（或者 emit 子对象的 DELETE 语句）。加了 passive_deletes=True 后，ORM 信任数据库层的 ON DELETE CASCADE 会处理子对象的删除，不再加载子对象——就像一个全权委托，省时省内存。”

小白：“技术映射：passive_deletes = 委托物业（DB）清理，管家（ORM）不操心。”

大师：“现在来看你们的订单系统应该怎么配置：”

class User(Base):
    orders: Mapped[list["Order"]] = relationship(back_populates="user")
    # 不加 cascade——删用户不删订单！

class Order(Base):
    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="SET NULL"))
    items: Mapped[list["OrderItem"]] = relationship(
        back_populates="order",
        cascade="all, delete-orphan",  # 删订单 → 删明细（业务正确）
        passive_deletes=True,
    )

class OrderItem(Base):
    order_id: Mapped[int] = mapped_column(ForeignKey("orders.id", ondelete="CASCADE"))

小胖：“所以关键是——删用户不级联订单（历史订单必须保留），删订单级联删除明细（明细是订单的组成部分）。”

大师：“正是。级联的设计要基于业务语义——不是技术上的’方便’，而是业务上的’正确’。”

三、项目实战

实战目标

设计订单系统的完整级联方案：验证 cascade 的五个选项行为，实现"删订单→删明细"的自动级联，以及"从集合中移除明细→孤儿删除"。最后验证数据库 ON DELETE 的防护效果。

步骤一：模型声明（正确的级联配置）

"""ch20_cascade.py —— 级联、孤儿删除与关系完整性"""

from sqlalchemy import (
    create_engine, String, Integer, Numeric, DateTime,
    ForeignKey, text, func, select, event,
)
from sqlalchemy.orm import (
    DeclarativeBase, Mapped, mapped_column, relationship,
    Session, sessionmaker,
)
from datetime import datetime
from typing import List

engine = create_engine(
    "postgresql+psycopg://nebula:nebula_dev@localhost:5432/order_center",
    echo=True,
)

class Base(DeclarativeBase):
    pass

class User(Base):
    __tablename__ = "cascade_users"
    id: Mapped[int] = mapped_column(primary_key=True)
    username: Mapped[str] = mapped_column(String(50))
    # 关键：不加 cascade！删用户时不级联删除订单
    orders: Mapped[List["Order"]] = relationship(back_populates="user")

class Order(Base):
    __tablename__ = "cascade_orders"
    id: Mapped[int] = mapped_column(primary_key=True)
    order_no: Mapped[str] = mapped_column(String(32))
    # ondelete="SET NULL"：用户被删时，订单的 user_id 置为 NULL
    user_id: Mapped[int | None] = mapped_column(
        ForeignKey("cascade_users.id", ondelete="SET NULL"), nullable=True
    )
    total_amount: Mapped[float] = mapped_column(Numeric(12, 2))
    status: Mapped[str] = mapped_column(String(20), default="pending")
    user: Mapped["User"] = relationship(back_populates="orders")
    # 级联：删订单 → 删明细（正确：明细是订单的组成部分）
    items: Mapped[List["OrderItem"]] = relationship(
        back_populates="order",
        cascade="all, delete-orphan",
        passive_deletes=True,  # 信任 DB 层的 ON DELETE CASCADE
    )

class OrderItem(Base):
    __tablename__ = "cascade_items"
    id: Mapped[int] = mapped_column(primary_key=True)
    # ondelete="CASCADE"：订单被删时，DB 层自动级联删除明细
    order_id: Mapped[int] = mapped_column(
        ForeignKey("cascade_orders.id", ondelete="CASCADE"), nullable=False
    )
    product_name: Mapped[str] = mapped_column(String(200))
    unit_price: Mapped[float] = mapped_column(Numeric(12, 2))
    quantity: Mapped[int] = mapped_column(Integer)
    order: Mapped["Order"] = relationship(back_populates="items")

Base.metadata.drop_all(engine)
Base.metadata.create_all(engine)

步骤二：验证 cascade 行为

# =============================================
# 测试 1：save-update 级联——add 父对象时子对象自动 add
# =============================================

print("=== 测试 1：save-update 级联 ===")
with Session(engine) as session:
    user = User(username="test_user")
    order = Order(order_no="ORD-001", total_amount=100)
    # 通过 relationship 将 order 关联到 user
    user.orders.append(order)
    # 只 add user（不显式 add order）
    session.add(user)
    # 预期：order 也因为 save-update 级联被自动 add
    print(f"order in session? {order in session}")  # True
    session.commit()
    print(f"用户 {user.username} 的订单: {[o.order_no for o in user.orders]}")
    # 清理
    session.delete(user)
    session.commit()

# =============================================
# 测试 2：delete 级联——删订单→删明细
# =============================================

print("\n=== 测试 2：delete 级联（订单→明细）===")
with Session(engine) as session:
    order = Order(order_no="ORD-CASCADE-TEST", total_amount=200)
    item1 = OrderItem(product_name="商品A", unit_price=50, quantity=2, order=order)
    item2 = OrderItem(product_name="商品B", unit_price=100, quantity=1, order=order)

    # 验证明细在 session 中
    print(f"item1 in session? {item1 in session}")  # True（cascade 自动 add）

    session.add(order)
    session.commit()

    item_ids = [item1.id, item2.id]
    print(f"明细 ID: {item_ids}")

    # 删除订单——明细自动级联删除
    session.delete(order)
    session.commit()

    # 验证明细也被删除了
    for item_id in item_ids:
        assert session.get(OrderItem, item_id) is None
    print("验证：明细已被级联删除")

# =============================================
# 测试 3：delete-orphan——从集合中移除 = 自动删除
# =============================================

print("\n=== 测试 3：delete-orphan（孤儿删除）===")
with Session(engine) as session:
    order = Order(order_no="ORD-ORPHAN-TEST", total_amount=300)
    item1 = OrderItem(product_name="商品C", unit_price=30, quantity=3, order=order)
    item2 = OrderItem(product_name="商品D", unit_price=40, quantity=2, order=order)
    session.add(order)
    session.commit()
    print(f"初始: {len(order.items)} 条明细 (IDs: {item1.id}, {item2.id})")

    # 从列表中移除 item1 → 触发 delete-orphan → 自动删除
    order.items.remove(item1)
    session.commit()
    print(f"移除 item1 后: {len(order.items)} 条明细")

    # 验证 item1 已从数据库中删除
    assert session.get(OrderItem, item1.id) is None
    assert session.get(OrderItem, item2.id) is not None
    print(f"  item1 (id={item1.id}) 已从数据库删除 ✓")
    print(f"  item2 (id={item2.id}) 仍在 ✓")

    session.delete(order)
    session.commit()

# =============================================
# 测试 4：无 cascade——删用户不删订单
# =============================================

print("\n=== 测试 4：无 cascade（删用户≠删订单）===")
with Session(engine) as session:
    user = User(username="vip_user")
    order1 = Order(order_no="VIP-001", total_amount=500, user=user)
    order2 = Order(order_no="VIP-002", total_amount=800, user=user)
    # 配置了 ondelete="SET NULL"，DB 层会把 user_id 置为 NULL
    item1 = OrderItem(product_name="VIP商品A", unit_price=100, quantity=5, order=order1)
    session.add(user)
    # cascade=save-update 自动把 order 和 item 也 add
    session.commit()

    order1_id = order1.id
    order2_id = order2.id
    item1_id = item1.id
    print(f"用户 {user.username} 订单: {[o.order_no for o in user.orders]}")

    # 删除用户——订单不应被级联删除！
    session.delete(user)
    session.commit()

    # 验证：订单仍然存在，但 user_id 为 NULL
    o1_still = session.get(Order, order1_id)
    o2_still = session.get(Order, order2_id)
    print(f"用户已删，订单 ORD-001 仍存在: {o1_still is not None}")
    print(f"  订单的 user_id: {o1_still.user_id}")  # None（ON DELETE SET NULL）
    print(f"  订单的明细仍存在: {len(o1_still.items)}")

    # 清理
    session.delete(o1_still)
    session.delete(o2_still)
    session.commit()

步骤三：数据库层 ON DELETE 的双重验证

# =============================================
# 测试 5：DB 层 ON DELETE CASCADE 自动生效
# =============================================

print("\n=== 测试 5：ON DELETE CASCADE（DB 层）===")
with Session(engine) as session:
    order = Order(order_no="DB-CASCADE-TEST", total_amount=100)
    item = OrderItem(product_name="X", unit_price=10, quantity=1)
    order.items.append(item)
    session.add(order)
    session.commit()
    item_id = item.id
    print(f"明细已创建: id={item.id}")

    # 通过 Core 直接执行 DELETE（绕过 ORM 的 cascade）
    from sqlalchemy import text as sa_text
    session.execute(sa_text("DELETE FROM cascade_orders WHERE id = :id"), {"id": order.id})
    session.commit()
    # DB 层的 ON DELETE CASCADE 应该自动删除了明细
    assert session.get(OrderItem, item_id) is None
    print(f"DB 层 ON DELETE CASCADE 生效: 明细 {item_id} 已自动删除 ✓")

步骤四：集合变更检测——小心隐式删除

# =============================================
# 测试 6：集合变更的危险操作
# =============================================

print("\n=== 测试 6：集合赋值 vs append/remove ===")
with Session(engine) as session:
    order = Order(order_no="COLL-TEST", total_amount=50)
    item_a = OrderItem(product_name="A", unit_price=10, quantity=1, order=order)
    item_b = OrderItem(product_name="B", unit_price=10, quantity=1, order=order)
    session.add(order)
    session.commit()
    print(f"初始明细: {[i.product_name for i in order.items]}")

    # 危险：直接赋值新列表——旧明细全部变为孤儿 → 自动删除！
    # order.items = [OrderItem(product_name="C", unit_price=10, quantity=1)]
    # 以上操作会触发 delete-orphan，A 和 B 都会被删除
    # 不要这样做！使用 append/remove 逐条修改

    # 安全：逐条操作
    new_item = OrderItem(product_name="C", unit_price=10, quantity=1, order=order)
    session.add(new_item)
    order.items.remove(item_b)  # 只删 B
    session.commit()
    print(f"安全修改后明细: {[i.product_name for i in order.items]}")

    session.delete(order)
    session.commit()

完整代码清单

"""ch20_cascade_complete.py —— 级联配置最佳实践"""

from sqlalchemy import ForeignKey, create_engine
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship, sessionmaker

engine = create_engine("postgresql+psycopg://nebula:nebula_dev@localhost:5432/order_center", echo=False)

class Base(DeclarativeBase):
    pass

# 最佳实践配置示例
class SafeUser(Base):
    __tablename__ = "safe_users"
    id: Mapped[int] = mapped_column(primary_key=True)
    orders: Mapped[list["SafeOrder"]] = relationship(back_populates="user")
    # 不加 cascade —— 删用户不删历史订单

class SafeOrder(Base):
    __tablename__ = "safe_orders"
    id: Mapped[int] = mapped_column(primary_key=True)
    user_id: Mapped[int | None] = mapped_column(
        ForeignKey("safe_users.id", ondelete="SET NULL"),  # DB 层保护
        nullable=True,
    )
    user: Mapped["SafeUser"] = relationship(back_populates="orders")
    items: Mapped[list["SafeOrderItem"]] = relationship(
        back_populates="order",
        cascade="all, delete-orphan",  # ORM 层级联删除明细
        passive_deletes=True,           # 信任 DB 层 ON DELETE CASCADE
    )

class SafeOrderItem(Base):
    __tablename__ = "safe_order_items"
    id: Mapped[int] = mapped_column(primary_key=True)
    order_id: Mapped[int] = mapped_column(
        ForeignKey("safe_orders.id", ondelete="CASCADE"),  # DB 层保护
    )
    order: Mapped["SafeOrder"] = relationship(back_populates="items")

# cascade 决策速查表
CASCADE_DECISION_TABLE = """
┌────────────────────┬──────────────────┬─────────────────────────────┐
│ 关系               │ ORM cascade      │ DB ondelete                │
├────────────────────┼──────────────────┼─────────────────────────────┤
│ User → Order       │ 不配 cascade     │ ondelete="SET NULL"         │
│ Order → OrderItem  │ all,delete-orphan│ ondelete="CASCADE"          │
│ OrderItem → 日志    │ save-update      │ ondelete="CASCADE"          │
│ 目录 → 子目录      │ all,delete-orphan│ ondelete="CASCADE"          │
└────────────────────┴──────────────────┴─────────────────────────────┘
"""

可能遇到的坑及解决方法

1. save-update cascade 导致跨 Session 的对象自动 add

• 现象：一个 detached 对象被 append 到另一个 Session 的父对象的列表中，被 cascade 自动 add，引发 ObjectAlreadyAttached 错误。
• 解决：使用 session.merge() 而不是直接 append detached 对象。

2. delete-orphan 导致意外删除——从列表中 remove 后又不小心 commit

• 现象：代码中为了临时排序，从列表 remove 了一个对象，忘记放回去，commit 时该对象被删除。
• 解决：临时排序使用 sorted(list, key=...) 而不修改原列表。不要轻率地从 relationship 列表中 remove。

3. passive_deletes=True 但没有配合 ON DELETE CASCADE

• 现象：设置 passive_deletes=True 但 DB 层没有 ON DELETE CASCADE，删除父对象时子对象留下孤儿行。
• 根因：ORM 信任 DB 层会删但 DB 层没有配置，子对象的 FK 还在但父对象没了。
• 解决：要么加上 ondelete="CASCADE"，要么去掉 passive_deletes。

4. ondelete 和 ORM cascade 重叠导致双重删除

• 现象：日志中出现了一条 DELETE 语句，但影响的行数报告为 0（因为 DB 层已经先删了）。
• 解决：这不是错误——ORM 发的 DELETE 被 DB 层拦截了。如果介意，加上 passive_deletes=True 让 ORM 不要发。

测试验证

# tests/test_ch20_cascade.py
import pytest
from sqlalchemy import create_engine, String, Integer, Numeric, ForeignKey, text
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship, sessionmaker

@pytest.fixture
def engine():
    return create_engine("sqlite:///:memory:", echo=False)

@pytest.fixture
def models(engine):
    class Base(DeclarativeBase):
        pass

    class Parent(Base):
        __tablename__ = "parent"
        id: Mapped[int] = mapped_column(primary_key=True)
        children: Mapped[list["Child"]] = relationship(back_populates="parent", cascade="all, delete-orphan")

    class Child(Base):
        __tablename__ = "child"
        id: Mapped[int] = mapped_column(primary_key=True)
        parent_id: Mapped[int] = mapped_column(ForeignKey("parent.id"))
        name: Mapped[str] = mapped_column(String(50))
        parent: Mapped["Parent"] = relationship(back_populates="children")

    Base.metadata.create_all(engine)
    return Parent, Child

def test_delete_parent_cascades_to_children(engine, models):
    """验证删除父对象时子对象被级联删除"""
    Parent, Child = models
    Factory = sessionmaker(bind=engine)
    with Factory() as s:
        p = Parent(id=1)
        c1 = Child(name="c1", parent=p)
        s.add(p)
        s.commit()
        child_id = c1.id
        s.delete(p)
        s.commit()
        assert s.get(Child, child_id) is None

def test_delete_orphan_removes_detached_child(engine, models):
    """验证从集合移除后 orphan 被删除"""
    Parent, Child = models
    Factory = sessionmaker(bind=engine)
    with Factory() as s:
        p = Parent(id=2)
        c = Child(name="orphan_test", parent=p)
        s.add(p)
        s.commit()
        child_id = c.id
        p.children.remove(c)
        s.commit()
        assert s.get(Child, child_id) is None

def test_no_cascade_keeps_children(engine):
    """验证不加 cascade 时子对象不受影响"""
    class Base2(DeclarativeBase):
        pass
    class P(Base2):
        __tablename__ = "p2"
        id: Mapped[int] = mapped_column(primary_key=True)
        kids: Mapped[list["C"]] = relationship(back_populates="parent")  # 不加 cascade！

    class C(Base2):
        __tablename__ = "c2"
        id: Mapped[int] = mapped_column(primary_key=True)
        parent_id: Mapped[int] = mapped_column(ForeignKey("p2.id"))
        parent: Mapped["P"] = relationship(back_populates="kids")

    Base2.metadata.create_all(engine)
    Factory = sessionmaker(bind=engine)
    with Factory() as s:
        p = P(id=1)
        c = C(id=1, parent=p)
        s.add(p)
        s.commit()
        s.delete(p)
        s.commit()
        # 无 cascade：子对象仍存在
        assert s.get(C, c.id) is not None

四、项目总结

cascade 决策矩阵

适用场景

1. 订单→订单明细（组合关系）——父删子必删。
2. 博客文章→评论（删除文章时连带删除评论）。
3. 购物车→购物车项（用户删了购物车项应该自动从数据库移除）。
4. 权限-角色关联（删除角色时连带删除关联记录）。

不推荐配置 cascade 的场景：

1. User → Order（历史订单必须保留）。
2. Product → OrderItem（下过的订单明细不应因商品下架而消失）。
3. 任何被其他业务引用的实体。

注意事项

1. cascade 和 ondelete 配置一致：如果 ORM 层配了 cascade 但 DB 层没配 ondelete，Core 操作就可能产生孤儿行。
2. passive_deletes=True 的前提是 ON DELETE CASCADE 在 DB 层已配置。
3. delete-orphan 要求集合关系是 list（不是 set 不是 scalar）。
4. 在异步环境下 cascade 的 flush 顺序更复杂：因为 flush 的依赖排序在不同 greenlet 间可能需要显式调整。

常见踩坑经验

案例 1：all, delete-orphan + 多对多关系导致中间表记录丢失

• 现象：role.permissions 用了 cascade="all, delete-orphan"，删除 role 时中间表记录没了，但 permission 本身也被删了。
• 根因：delete-orphan 作用于子对象（Permission），不只是中间表。
• 修复：多对多中间表不要配 cascade；手动维护中间表，或使用 secondary 的 relationship（由 SQLAlchemy 管理中间表）。

案例 2：迁移脚本中添加了 ON DELETE CASCADE 但忘记改模型

• 现象：Alembic 迁移执行了 ALTER TABLE ADD FOREIGN KEY ... ON DELETE CASCADE，但模型中的 relationship 没有加 passive_deletes=True。
• 修复：模型与迁移同步更新。写一个 lint 规则检查 ForeignKey 的 ondelete 与 relationship 的 passive_deletes 是否一致。

案例 3：flush 顺序导致违反外键约束

• 现象：创建父对象和子对象时，session.flush() 报 foreign key constraint violation。
• 根因：SQLAlchemy flush 时的拓扑排序在某些复杂自引用或循环引用下可能出错。
• 修复：使用 session.add(parent) 并保证子对象通过 relationship 关联（cascade save-update 会自动 add）。

思考题

1. 假设你的系统有一个"部门→员工"的关系。删除部门时，业务需求是"把该部门的员工移动到上级部门"，而不是级联删除员工。如果用 cascade="all" 会有什么后果？应该如何用事件系统（before_delete 事件）来实现这个需求？

2. 在微服务架构中，User 服务和 Order 服务使用不同的数据库。如果 User 数据库中的用户被删除，Order 数据库中的订单应该如何感知和处理？数据库层的 ON DELETE 约束和 ORM 层的 cascade 在这种跨库场景下是否还有意义？应该用什么机制来保证数据一致性？

参考答案参见附录 E。