FastAPI使用Union[dict, list]解析字典/字典列表时出现解析错误

当你在FastAPI中用Union[dict, list]定义参数类型，传入由多个字典组成的列表时触发解析错误，但改用Any就正常，核心问题是未明确列表的元素类型，导致Pydantic无法正确校验结构。

解决方案 #

把Union[dict, list]替换为Union[dict, List[dict]]，明确列表中的元素是字典类型：

from pydantic import BaseModel
from typing import Union, List  # 导入List类型

class NoticeDagTask(BaseModel):
    next_msg: Union[dict, List[dict]]  # 明确列表元素类型
    success_without_msg: bool = False 

async def notice_next(notice_node: NoticeDagTask, db: Session = Depends(get_db)):
    logger.info(f"request to notice_next with {notice_node=}")
    # 后续业务逻辑不变

原因说明 #

原代码中的list是无类型约束的泛型，Pydantic在解析包含字典的列表时，无法准确识别这是合法的类型分支，从而抛出解析错误。而Any会跳过所有类型校验，虽然能解析但丢失了类型检查的安全性。

改为Union[dict, List[dict]]后，Pydantic可以清晰识别两种合法输入：

• 单个字典对象
• 由字典组成的列表
  既能完成正确的解析校验，又保留了类型系统的严谨性。

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