SQLAlchemy joinedload未即时加载关联对象问题排查

问题核心原因 #

你遇到的情况不是joinedload没生效，而是SQLAlchemy预加载的数据存在对象的内部缓存中，但FastAPI默认的序列化机制（依赖Pydantic）只会序列化被显式访问过的属性。

joinedload确实已经在一次查询中把关联的entita数据加载到了内存里，但如果没主动访问r.entita，Pydantic在序列化时不会主动去读取SQLAlchemy对象中预加载的关联属性，导致返回结果里没有这部分数据。而当你遍历打印r.entita时，相当于触发了属性访问，这部分数据才会被序列化器识别并输出。

解决方案 #

方法一：用Pydantic模型显式定义返回结构（推荐） #

通过定义Pydantic的响应模型，开启orm_mode，让Pydantic主动去读取ORM对象的关联属性，不管是否被提前访问过。

示例代码：

from pydantic import BaseModel

# 定义Entita的响应模型，根据实际表字段调整
class EntitaResponse(BaseModel):
    id: int  # 替换成entita表的主键字段
    # 添加其他需要返回的entita字段，比如name、create_time等

    class Config:
        orm_mode = True  # 允许从ORM对象直接序列化

# 定义Drivers的响应模型
class DriversResponse(BaseModel):
    id_entita: int
    entita: EntitaResponse  # 关联Entita的响应模型

    class Config:
        orm_mode = True

修改接口，指定response_model：

@router.get("/drivers", response_model=list[DriversResponse])
def getDrivers(db=Depends(get_db), user=Depends(get_current_user)):
    return db.query(DriversModel).options(joinedload(DriversModel.entita)).all()

方法二：主动触发关联属性加载（临时方案） #

如果不想定义Pydantic模型，可以在返回前遍历所有对象，主动访问关联属性，触发数据的序列化识别：

@router.get("/drivers")
def getDrivers(db=Depends(get_db), user=Depends(get_current_user)):
    res = db.query(DriversModel).options(joinedload(DriversModel.entita)).all()
    # 主动访问关联属性，让Pydantic序列化时能识别到
    for driver in res:
        _ = driver.entita  # 不需要打印，只要访问即可
    return res

补充说明 #

• joinedload确实是预加载，不会产生额外的SQL查询（可以通过开启SQLAlchemy的日志验证），只是序列化阶段的问题。
• 推荐使用Pydantic响应模型的方式，既能明确返回结构，又能避免手动触发属性访问的冗余代码，同时符合FastAPI的最佳实践。

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