FastAPI使用response_model返回深度嵌套JSON对象的问题排查

问题背景 #

你定义了如下Pydantic模型：

from pydantic import BaseModel
from typing import Optional


class HolidaySchema(BaseModel):
    year: int
    month: int
    country: str
    language: str


class HolidayDateSchema(BaseModel):
    name: str
    date: str
    holidays: HolidaySchema | None = None

    class Config:
        orm_mode = True

并配置FastAPI路由：

@router.get("/holidays/",response_model = List[HolidayDateSchema])

期望返回包含id字段和嵌套holidays对象的响应结构，但实际运行时触发ValidationError，提示value is not a valid dict，无法正常返回嵌套JSON。

错误原因 #

1. 字段缺失：期望响应中的id字段未在HolidayDateSchema中定义，Pydantic验证时会报错
2. 嵌套模型未开启ORM模式：如果holidays对应的是ORM对象（比如SQLAlchemy实例），HolidaySchema未开启orm_mode，Pydantic无法自动将ORM对象转换为字典结构
3. 类型注解兼容性：部分旧版本Pydantic对HolidaySchema | None的类型支持不如Optional[HolidaySchema]稳定

解决方案 #

1. 修正Pydantic模型定义 #

补全缺失字段，并为嵌套模型开启orm_mode（如果数据来自ORM）：

from pydantic import BaseModel
from typing import Optional, List


class HolidaySchema(BaseModel):
    year: int
    month: int
    country: str
    language: str

    class Config:
        orm_mode = True  # 允许解析ORM对象为字典


class HolidayDateSchema(BaseModel):
    id: int  # 添加期望响应中的id字段
    name: str
    date: str
    holidays: Optional[HolidaySchema] = None  # 兼容旧版本的Optional写法

    class Config:
        orm_mode = True

2. 确保数据结构匹配模型 #

• 如果是手动构造返回数据，严格按照模型结构提供字段：

@router.get("/holidays/", response_model=List[HolidayDateSchema])
def get_holidays():
    return [
        {
            "id": 13,
            "date": "2021-08-14",
            "name": "Independence Day",
            "holidays": {"year": 2022, "month":5, "country":"pk", "language":"en"}
        }
    ]

• 如果是从数据库获取ORM对象（比如SQLAlchemy），只要模型开启了orm_mode，可以直接返回查询结果：

from sqlalchemy.orm import Session
from fastapi import Depends

@router.get("/holidays/", response_model=List[HolidayDateSchema])
def get_holidays(db: Session = Depends(get_db)):
    db_holidays = db.query(HolidayDateModel).all()
    return db_holidays

3. 处理可选嵌套字段的边界情况 #

如果holidays字段可能返回空值，确保返回None而非空字典或其他不符合结构的值，避免验证失败。

最佳实践 #

• 始终保持response_model的字段与期望响应完全一致，不要遗漏必填字段
• 嵌套模型如果涉及ORM对象，必须开启orm_mode以支持自动转换
• 优先使用Optional[T]作为可选字段的类型注解，提升兼容性
• 手动构造数据时，严格遵循模型定义的字段类型和结构

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