FastAPI接收Excel需用UploadFile配合BytesIO和pandas.read_excel解析，再通过Pydantic模型逐行校验字典化数据，不可直接校验DataFrame；注意文件类型、编码、空值及大文件处理。
FastAPI里怎么接收Excel文件上传
FastAPI不直接支持解析Excel，File和UploadFile只能拿到原始字节流，必须手动读取并交给pandas.read_excel处理。别指望Form或Body自动转成DataFrame——它连Excel格式都识别不了。
关键点：上传接口必须用POST，Content-Type是multipart/form-data，后端用UploadFile接收，再用BytesIO把文件内容喂给pandas.read_excel。
- 不要用
File(...)直接当参数类型，得用UploadFile - 别在
read_excel里传路径（UploadFile.filename只是客户端名字，不是服务器路径） - 务必用
await file.read()或file.file.read()获取字节，再包进BytesIO
from io import BytesIO
import pandas as pd
<p>@app.post("/upload-excel/")
async def upload_excel(file: UploadFile):
content = await file.read() # 必须先读取
df = pd.read_excel(BytesIO(content)) # BytesIO才能被pandas读
用Pydantic模型校验Excel每行数据是否合法
Pydantic本身不校验DataFrame，但可以校验单行——把df.to_dict("records")转成Python字典列表，再批量丢给Pydantic模型parse_obj_list（v1）或model_validate（v2）。失败时抛ValidationError，能精准定位哪一行、哪个字段出错。
注意：Pydantic v2推荐用MyModel.model_validate(row)逐行校验，比parse_obj_list更容易捕获具体行号；v1用户得自己加enumerate做索引追踪。
立即学习“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
<p>class ExcelRow(BaseModel):
name: str
age: int
join_date: date</p><pre class="brush:php;toolbar:false;">@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作用于模型实例化过程，而DataFrame不是Pydantic模型——它是pandas对象，没有__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……这些都不是Pydantic的问题，而是IO或pandas层的坑。
-
xlrd.biffh.XLRDError: Excel xlsx file; not supported→ 升级openpyxl并显式指定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解析和校验链路长，每个环节都可能断：上传、IO读取、pandas解析、类型转换、Pydantic校验。出问题先查file.content_type和df.shape，再看df.dtypes——别一上来就调Pydantic的model_dump。
