在SQLAlchemy中什么时候需要为foreign_keys参数传入多个外键？

你之前代码报错的核心原因 #

foreign_keys传入多个外键时，SQLAlchemy默认生成的是所有外键同时匹配的AND逻辑，等价于and_(Trial.id==Challenge.winner_id, Trial.id==Challenge.loser_id)，显然不符合你要的「匹配胜方/败方任意一个外键」的OR需求，所以才需要手动写primaryjoin指定关联逻辑，这和foreign_keys支持多值的设计并不冲突。

foreign_keys传入多个外键的常见适用场景 #

1. 复合主键的关联场景

这是最常用的场景，当被关联表使用多字段组成的复合主键时，关联表需要用对应的多个外键字段同时匹配才能定位唯一关联对象，这时候必须通过foreign_keys指定用到的所有外键。
实际业务代码示例：

# 订单表使用租户ID+订单ID作为复合主键
class Order(Model):
    __tablename__ = 'orders'
    tenant_id = Column(Integer, primary_key=True)
    order_id = Column(Integer, primary_key=True)
    items = relationship("OrderItem", back_populates="order")

# 订单商品表用租户ID、订单ID两个外键关联订单表
class OrderItem(Model):
    __tablename__ = 'order_items'
    id = Column(Integer, primary_key=True)
    tenant_id = Column(Integer, ForeignKey('orders.tenant_id'))
    order_id = Column(Integer, ForeignKey('orders.order_id'))
    order = relationship(
        "Order",
        back_populates="items",
        # 明确指定当前关联用到的两个外键
        foreign_keys=[tenant_id, order_id]
    )

这种场景下如果不指定foreign_keys，SQLAlchemy可能无法自动识别这两个外键是共同用于关联订单表的，会抛出关联歧义的错误。

2. 排除外键检测歧义

当你的表中存在多组指向不同表的外键，SQLAlchemy自动检测外键时无法区分哪些外键属于当前要定义的关系，就需要用foreign_keys显式指定当前关系用到的外键集合，过滤无关的外键。
比如一张交易记录表同时有user_tenant_id、user_id指向用户表的复合主键，还有merchant_tenant_id、merchant_id指向商户表的复合主键，你要定义指向用户的关联时，就需要指定foreign_keys=[user_tenant_id, user_id]，避免SQLAlchemy把商户相关的外键也纳入关联逻辑。

3. 自定义关联逻辑的辅助声明

当你手动写了primaryjoin自定义关联逻辑时，如果逻辑中用到了多个外键，也可以搭配foreign_keys显式声明用到的外键，帮助SQLAlchemy更准确地处理关联对象的增删改同步、惰性加载等逻辑，减少不可预期的错误。比如你本次的代码也可以补充该参数提升稳定性：

class Trial(SurrogatePK, Model):
    __tablename__ = 'trials'
    challenges = relationship(
        'Challenge', 
        primaryjoin='or_(Trial.id==Challenge.winner_id, Trial.id==Challenge.loser_id)',
        # 显式声明关联用到的两个外键
        foreign_keys='[Challenge.winner_id, Challenge.loser_id]'
    )

内容的提问来源于stack exchange，提问作者Harm