FastAPI使用Pydantic处理文件上传遇value_error.missing问题求助

问题根源 #

直接用自定义Pydantic模型接收multipart/form-data类型的文件上传请求时，FastAPI无法正确解析（Pydantic默认适配JSON格式请求体），导致校验失败抛出字段缺失错误。以下是两种可行的解决方式：

方案1：直接使用FastAPI内置的File和Form参数（推荐） #

这种方式无需自定义Pydantic模型，直接通过File和Form参数接收数据，适配文件上传场景：

from fastapi import FastAPI, File, UploadFile, Form

app = FastAPI()

@app.post("/upload/")
async def handle_upload(
    file: UploadFile = File(...),  # 必填文件字段
    password: str | None = Form(None)  # 可选密码字段，默认None
):
    # 示例处理逻辑
    return {
        "uploaded_filename": file.filename,
        "password_provided": password is not None
    }

Postman操作步骤 #

1. 选择POST请求，输入接口URL
2. 切换到Body标签，选中form-data选项
3. 添加字段：
   • 键名file，类型选File，点击右侧按钮选择要上传的文件
   • 键名password，类型选Text，可填写内容或留空（留空则后端接收为None）
4. 发送请求即可正常响应

方案2：结合Pydantic模型做校验（需自定义依赖） #

如果必须用Pydantic模型统一校验规则，需要通过自定义依赖函数中转表单数据：

步骤1：定义Pydantic校验模型 #

from pydantic import BaseModel
from fastapi import UploadFile

class UploadRequest(BaseModel):
    file: UploadFile
    password: str | None = None

步骤2：创建依赖函数解析表单数据 #

from fastapi import Form, Depends

async def parse_upload_form(
    file: UploadFile = File(...),
    password: str | None = Form(None)
) -> UploadRequest:
    return UploadRequest(file=file, password=password)

步骤3：路由中使用依赖 #

@app.post("/upload-with-validation/")
async def upload_with_validation(request: UploadRequest = Depends(parse_upload_form)):
    # 基于模型的处理逻辑
    return {
        "filename": request.file.filename,
        "password_provided": request.password is not None
    }

常见错误排查点 #

• 确保Postman的字段名与代码中参数名完全一致（大小写敏感）
• 不要选择raw或JSON请求格式，必须用form-data
• 若用Pydantic模型，禁止直接将模型作为路由参数，必须通过依赖函数中转

内容的提问来源于stack exchange，提问作者Saad Shirgaonkar