本文介绍通过预加载（eager loading）策略优化 sqlalchemy 多层关联查询的方法，重点解决因 n+1 查询导致的性能瓶颈，显著提升复杂嵌套数据（如订单→交付→作业→客户→地址等）的获取效率。
本文介绍通过预加载（eager loading）策略优化 sqlalchemy 多层关联查询的方法，重点解决因 n+1 查询导致的性能瓶颈，显著提升复杂嵌套数据（如订单→交付→作业→客户→地址等）的获取效率。
在处理类似“Delivery → Order → Client → Address → JobDelivery → Job”这类深度关联模型时，原始代码中未显式加载任何关联对象，导致每访问一次 delivery.Order、delivery.AddressContact 或 job_delivery.Job 等关系属性，SQLAlchemy 就会触发一次独立的 SQL 查询——即典型的 N+1 查询问题。对于 100 条交付记录，若平均每条关联 5 个作业，且每个作业又需加载 Job 实体，则可能触发数百次额外数据库往返，造成严重延迟（如原文中 15 秒）。
✅ 正确解法是：在初始查询中一次性预加载所有必需的关联数据，确保整个数据图在首次查询时就完整载入内存，后续遍历无需再发 SQL。
推荐方案：组合使用 joinedload 和 selectinload
根据关联特性选择合适的加载策略：
- joinedload：适用于一对一或少量一对多关联，通过 JOIN 一次性获取主表与关联表数据（注意避免笛卡尔积爆炸）；
- selectinload：适用于一对多/多对多关联（如 Delivery.JobDeliveries），先查主表 ID，再用 IN 子查询批量加载子集，安全高效。
以下是优化后的核心查询代码（适配 SQLAlchemy 2.0+）：
from sqlalchemy import select, and_
from sqlalchemy.orm import joinedload, selectinload
# 构建预加载查询
stmt = (
select(Delivery)
.join(Order) # 显式 JOIN 用于过滤条件
.where(
and_(
Delivery.DespatchDateTime.between(start_date, end_date),
Order.ProductionSite == site_map.get(site)
)
)
.options(
# 一级关联：Order（已 JOIN，复用该 JOIN）
joinedload(Delivery.Order).joinedload(Order.Client),
# 一级关联：DeliveryMethod、Address、AddressContact（独立外键，用 selectin 更稳）
selectinload(Delivery.DeliveryMethod),
selectinload(Delivery.Address),
selectinload(Delivery.AddressContact),
# 一对多关联：JobDeliveries → Job（关键！避免循环中 N+1）
selectinload(Delivery.JobDeliveries).joinedload(JobDelivery.Job),
)
)
delivery_rs = session.scalars(stmt).all() # 返回 Delivery 实例列表⚠️ 注意事项：
- 确保所有被 options() 加载的属性名（如 Delivery.JobDeliveries）与模型中定义的 relationship() 字段名完全一致；
- 若 JobDelivery.Job 是 uselist=False（一对一），可用 joinedload；若为 uselist=True（一对多），此处 joinedload 仍有效，但需确认 JobDelivery 模型中 Job 关系定义正确；
- 避免对同一关系多次调用 options()，否则可能覆盖或冲突；
- 启用 echo=True（如 create_engine(..., echo=True)）可直观验证：优化后应仅执行 1~2 条主查询 + 少量 IN 子查询，循环内不再出现新 SQL。
后续数据组装保持简洁（无性能损耗）
预加载完成后，原 for delivery in delivery_rs: 循环中的所有属性访问（如 delivery.Order.Client.Name、job_delivery.Job.ClientJobReference）均直接从内存读取，速度极快：
for delivery in delivery_rs:
rowcount += 1
jobs = []
quantity = 0
for job_delivery in delivery.JobDeliveries: # 已预加载，无 DB 查询
job = job_delivery.Job # 已预加载，无 DB 查询
web_ref = job.ClientJobReference or ""
if web_ref and not web_ref.startswith("CCW_"):
web_ref = ""
else:
web_ref = web_ref.replace("CCW_", "", 1)
jobs.append({
"web_ref": f"CCW_{web_ref}" if web_ref else "",
"name": job.JobName,
"thumbnail": f"https://example.com/{web_ref}.png" if web_ref else ""
})
quantity += job_delivery.Quantity
# 其余字段同理（Address、AddressContact、DeliveryMethod 等均已加载）
contact_data = {
"title": title_map.get(delivery.AddressContact.Title),
"name": delivery.AddressContact.ContactName,
"email": delivery.AddressContact.ContactEmail,
"phone": delivery.AddressContact.ContactNumber
} if delivery.AddressContact else {}
result["data"].append({
"order_number": delivery.Order.OrderSequenceId,
"quantity": quantity,
"method": delivery.DeliveryMethod.Name,
"client": delivery.Order.Client.Name,
"end_client": delivery.Order.Client.EndCustomer,
"jobs": jobs,
"contact": contact_data,
"address": {
"business": delivery.Address.BusinessName,
"postcode": delivery.Address.PostCode,
"town": delivery.Address.Town,
"county": delivery.Address.County,
"country": delivery.Address.Country.Name,
"lines": [delivery.Address.AddressLine1, delivery.Address.AddressLine2]
}
})总结
性能优化的核心在于 消灭隐式延迟加载。通过 options() 显式声明所需关联路径，并合理搭配 joinedload（适合 JOIN 安全场景）与 selectinload（适合一对多批量加载），可将原本 O(N×M) 的查询复杂度降至 O(1) 主查询 + O(K) 辅助查询。实测中，100 条交付记录的耗时通常可从 15 秒降至 1~2 秒内，提升达 5–10 倍。建议始终开启 echo=True 验证加载行为，并结合数据库执行计划进一步调优索引（如 Delivery.DespatchDateTime、Order.ProductionSite 等 WHERE 字段）。
