本文介绍如何在 SQLAlchemy 2.0+ 中为 Cabinet 模型定义一个直接访问其所有 Item 的间接关系（经由 Shelve 中转），使用 secondary 参数与 viewonly=True 正确配置，避免映射冲突警告。
本文介绍如何在 sqlalchemy 2.0+ 中为 `cabinet` 模型定义一个直接访问其所有 `item` 的间接关系（经由 `shelve` 中转），使用 `secondary` 参数与 `viewonly=true` 正确配置，避免映射冲突警告。
在典型的三层嵌套结构中（Cabinet → Shelve → Item），虽然 Cabinet 和 Item 之间没有直接外键，但业务上常需便捷获取“某柜子下的所有物品”。SQLAlchemy 不支持自动推导这种跨两级的一对多间接关联，必须显式声明路径。核心方案是：将中间表 shelves 指定为 secondary，并设置 viewonly=True —— 这表示该关系仅用于查询，不参与 INSERT/UPDATE 操作。
以下是完整、可运行的模型定义（基于 SQLAlchemy 2.0 声明式风格）：
from sqlalchemy import ForeignKey, String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
from typing import List
class DeclarativeBase(DeclarativeBase):
pass
class Cabinet(DeclarativeBase):
__tablename__ = "cabinets"
id: Mapped[int] = mapped_column(primary_key=True)
# 直接关系：Cabinet ↔ Shelve（一对多）
shelves: Mapped[List["Shelve"]] = relationship(back_populates="cabinet")
# 间接关系：Cabinet → Items（经由 shelves 表 JOIN）
items: Mapped[List["Item"]] = relationship(
secondary="shelves", # 指定中间表名（字符串）或 Table 对象
primaryjoin="Cabinet.id == Shelve.cabinet_id",
secondaryjoin="Shelve.id == Item.shelve_id",
viewonly=True, # ⚠️ 关键！禁止写入，避免与 shelves.cabinet 冲突
order_by="Item.id"
)
class Shelve(DeclarativeBase):
__tablename__ = "shelves"
id: Mapped[int] = mapped_column(primary_key=True)
cabinet_id: Mapped[int] = mapped_column(ForeignKey("cabinets.id"))
items: Mapped[List["Item"]] = relationship(back_populates="shelve")
cabinet: Mapped["Cabinet"] = relationship(back_populates="shelves")
class Item(DeclarativeBase):
__tablename__ = "items"
id: Mapped[int] = mapped_column(primary_key=True)
shelve_id: Mapped[int] = mapped_column(ForeignKey("shelves.id"))
shelve: Mapped["Shelve"] = relationship(back_populates="items")
✅ 为什么必须加 viewonly=True？
若省略该参数，SQLAlchemy 会尝试为 Cabinet.items 自动生成写入逻辑（如级联插入 Item 时自动填充 shelve_id），但这与已存在的 Shelve.cabinet 和 Cabinet.shelves 关系产生列写入冲突（都试图向 shelves.cabinet_id 写入）。viewonly=True 明确告知 ORM：“此关系只读”，从而禁用写入行为，消除 SAWarning。
⚠️ 注意事项：
- secondary="shelves" 中的 "shelves" 是表名（字符串），非类名；若使用 Table 对象，需确保已正确声明元数据。
- primaryjoin 和 secondaryjoin 在复杂场景中建议显式指定（如上例），增强可读性与可控性；简单外键链下可省略，但显式更安全。
- back_populates 在 viewonly 关系中不可双向绑定（否则仍会触发冲突），因此 Item 类中无需、也不应为 cabinet 定义对称的 secondary 关系。
- 查询时，cabinet.items 会自动生成三表 JOIN：SELECT ... FROM cabinets JOIN shelves ON ... JOIN items ON ...，性能上注意索引（确保 shelves.cabinet_id 和 items.shelve_id 有索引）。
总结：实现跨表间接一对多，本质是定义一个只读的、基于中间表 JOIN 的视图式关系。secondary + viewonly=True 是标准解法，既保持 API 简洁（cabinet.items），又规避 ORM 映射歧义，是 SQLAlchemy 处理此类“路径关联”的推荐实践。
