Python开发FastAPI怎么读取并校验上传的Excel文件_结合Pandas与Pydantic进行入参验证

立即学习“Python免费学习笔记（深入）”；

• 字段名必须和Excel列名完全一致（区分大小写），否则ValidationError会提示“field required”。
• 日期列如果包含空值，Pydantic默认不接受NaT，需要设置default=None或使用Optional[date]类型。
• 数值列中如果混入了文本（比如“N/A”、“-”），会导致float校验失败。建议先用pd.to_numeric(..., errors="coerce")将其转为NaN。

from pydantic import BaseModel, field_validator
from datetime import date

class ExcelRow(BaseModel):
    name: str
    age: int
    join_date: date

    @field_validator("join_date")
    def parse_date(cls, v):
        if isinstance(v, str):
            return date.fromisoformat(v)
        return v

校验逻辑示例（v2）

rows = df.to_dict("records")
validated = []
for i, row in enumerate(rows):
    try:
        validated.append(ExcelRow.model_validate(row))
    except ValidationError as e:
        raise HTTPException(422, f"第{i+1}行校验失败: {e}")

为什么不能直接用Pydantic的@validator校验整个DataFrame

原因在于，@validator作用于Pydantic模型的实例化过程，而DataFrame是pandas对象，并非Pydantic模型——它没有__pydantic_core_schema__。如果强行把DataFrame传进去，会直接报错TypeError: unsupported type。

当然，也有人尝试过自定义__get_pydantic_core_schema__来绕过限制，但代价高、维护难，而且会失去Pydantic对嵌套结构、类型转换、错误聚合的原生支持。相比之下，老老实实转换成字典再校验，反而是更稳妥、更高效的选择。

• 不要在Pydantic模型里定义df: pd.DataFrame这样的字段——Pydantic根本不认识pd.DataFrame。
• 别想着用pd.DataFrame.model_validate——这个方法根本不存在。
• 对于整表级别的约束（比如“name列不能有重复值”），需要在所有行都校验完之后，单独编写逻辑处理，这不在Pydantic的职责范围内。

常见报错和绕过方式

在实际操作中，你可能会遇到各种“坑”：上传大Excel文件（>10MB）容易触发client disconnected或Request body too large；读取加密的Excel会报Unsupported format；中文列名乱码显示为Unnamed: 0……需要明确的是，这些问题通常出在IO或pandas层，而不是Pydantic的锅。

• 遇到xlrd.biffh.XLRDError: Excel xlsx file; not supported？升级openpyxl库，并在read_excel中显式指定engine="openpyxl"。
• UnicodeDecodeError（常因误将CSV文件当作XLSX上传导致）？可以先检查file.content_type，确认是否是application/vnd.openxmlformats-officedocument.spreadsheetml.sheet。
• 出现MemoryError？可以尝试使用chunksize参数分块读取文件。不过要注意，这样一来Pydantic校验也得改成流式处理，不能一次性to_dict了。
• 列名带有空格或换行符？用df.columns = df.columns.str.strip()预处理一下即可。

从上传到最终校验，整个Excel处理链路比较长，每个环节都可能出问题。排查时建议按这个顺序来：先检查file.content_type和df.shape，再看df.dtypes——别一上来就急着调用Pydantic的model_dump。