在fastapi应用开发中，我们经常需要处理多种类型的请求数据，例如文件上传（uploadfile）和结构化的json数据（pydantic basemodel）。当这些数据类型需要同时在一个请求中提交时，开发者可能会遇到一些挑战，特别是当json数据包含列表（list）或字典列表（list[basemodel]）时。
常见的错误尝试包括：
这些尝试通常会导致422 Unprocessable Entity错误，其根本原因在于HTTP协议对请求体编码的限制以及FastAPI/Pydantic对不同数据源的解析机制。
核心问题点：
在深入探讨文件与JSON混合上传之前，我们首先需要理解如何在Pydantic模型中正确声明列表类型的查询参数。如果你的Pydantic模型字段是List[str]或List[float]等，你需要使用Query()将其包装在Field()中。
示例代码 1：Pydantic模型中列表查询参数的正确用法
from fastapi import FastAPI, Query, Depends
from pydantic import BaseModel, Field
from typing import Optional, List
app = FastAPI()
class BaseQueryParams(BaseModel):
width: Optional[float] = Field(None, description="宽度")
height: Optional[float] = Field(None, description="高度")
words: List[str] = Field(Query(..., description="单词列表")) # 必须使用 Query(...)
@app.get("/query-example")
async def get_with_list_query(params: BaseQueryParams = Depends()):
"""
一个演示如何使用列表查询参数的端点。
示例请求: /query-example?width=10.5&words=apple&words=banana
"""
return params
说明：
由于HTTP协议的限制，我们不能直接将Pydantic模型（作为application/json）和文件（作为multipart/form-data）同时发送。解决方案的关键在于：将Pydantic模型的数据编码成一个字符串，并通过multipart/form-data的一部分（例如一个Form字段）发送，然后在服务器端进行解析。
以下介绍两种常用的实现方法。
这种方法将Pydantic模型的数据序列化为JSON字符串，然后作为Form参数的一部分提交。服务器端通过一个依赖函数手动解析这个JSON字符串。
示例代码 2：使用Form参数和依赖函数解析JSON数据
app.py
from fastapi import FastAPI, status, Form, UploadFile, File, Depends, Query
from pydantic import BaseModel, Field, ValidationError
from fastapi.exceptions import HTTPException
from fastapi.encoders import jsonable_encoder
from typing import Optional, List
import json # 导入 json 模块
app = FastAPI()
# 定义查询参数模型
class BaseQueryParams(BaseModel):
width: Optional[float] = Field(None, description="宽度")
height: Optional[float] = Field(None, description="高度")
words: List[str] = Field(Query(..., description="单词列表")) # 列表查询参数
# 定义复杂JSON数据模型中的子模型
class BaseBox(BaseModel):
l: float = Field(..., description="左坐标")
t: float = Field(..., description="上坐标")
r: float = Field(..., description="右坐标")
b: float = Field(..., description="下坐标")
# 定义复杂JSON数据模型
class BasePayload(BaseModel):
boxes: List[BaseBox] = Field(..., description="边界框列表")
comments: List[str] = Field(..., description="评论列表")
code: int = Field(..., description="状态码")
# 定义一个依赖函数，用于解析 Form 参数中的 JSON 字符串
def parse_json_form_data(data: str = Form(...)):
try:
# 尝试将 Form 参数中的字符串解析为 BasePayload 模型
return BasePayload.model_validate_json(data)
except ValidationError as e:
# 如果解析失败，抛出 422 错误
raise HTTPException(
detail=jsonable_encoder(e.errors()),
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
)
@app.post("/submit_form_json")
def submit_with_form_json(
query_params: BaseQueryParams = Depends(), # 查询参数
payload: BasePayload = Depends(parse_json_form_data), # JSON数据通过Form解析
files: List[UploadFile] = File(...), # 文件列表
):
"""
通过 Form 参数传递 JSON 字符串，并同时上传文件。
"""
return {
"Query Params": query_params,
"JSON Payload": payload,
"Filenames": [file.filename for file in files],
}
客户端请求示例 (使用 curl)：
假设你有一个名为 test.png 的文件。
curl -X 'POST' \
'http://localhost:8000/submit_form_json?width=10.5&height=20.0&words=apple&words=banana' \
-H 'accept: application/json' \
-H 'Content-Type: multipart/form-data' \
-F 'files=@test.png;type=image/png' \
-F 'data={"boxes": [{"l": 0,"t": 0,"r": 10,"b": 10}], "comments": ["first comment", "second comment"], "code": 123}'说明：
这种方法通过Pydantic模型自身的model_validator来处理从请求体中接收到的JSON字符串。它将JSON字符串视为一个特殊的输入格式，并在模型实例化之前进行解析。这种方式通常更简洁，并且在Swagger UI (/docs) 中能更好地展示请求体结构。
示例代码 3：使用model_validator解析Body中的JSON字符串
app.py
from fastapi import FastAPI, Body, UploadFile, File, Depends, Query
from pydantic import BaseModel, Field, model_validator
from typing import Optional, List
import json
app = FastAPI()
# 定义查询参数模型
class BaseQueryParams(BaseModel):
width: Optional[float] = Field(None, description="宽度")
height: Optional[float] = Field(None, description="高度")
words: List[str] = Field(Query(..., description="单词列表")) # 列表查询参数
# 定义复杂JSON数据模型中的子模型
class BaseBox(BaseModel):
l: float = Field(..., description="左坐标")
t: float = Field(..., description="上坐标")
r: float = Field(..., description="右坐标")
b: float = Field(..., description="下坐标")
# 定义复杂JSON数据模型，并添加 model_validator
class BasePayload(BaseModel):
boxes: List[BaseBox] = Field(..., description="边界框列表")
comments: List[str] = Field(..., description="评论列表")
code: int = Field(..., description="状态码")
@model_validator(mode="before")
@classmethod
def validate_to_json(cls, value):
"""
在模型验证之前，如果输入是字符串，尝试将其解析为JSON。
这允许客户端将JSON数据作为字符串发送。
"""
if isinstance(value, str):
try:
return cls(**json.loads(value))
except json.JSONDecodeError as e:
# 如果JSON解析失败，Pydantic会捕获并抛出ValidationError
# 这里可以添加更具体的错误处理，或让Pydantic默认处理
raise ValueError("Invalid JSON string for BasePayload") from e
return value
@app.post("/submit_body_json")
def submit_with_body_json(
query_params: BaseQueryParams = Depends(), # 查询参数
payload: BasePayload = Body(...), # JSON数据通过Body参数传递
files: List[UploadFile] = File(...), # 文件列表
):
"""
通过 Body 参数传递 JSON 字符串（由 model_validator 处理），并同时上传文件。
"""
return {
"Query Params": query_params,
"JSON Payload": payload,
"Filenames": [file.filename for file in files],
}
客户端请求示例 (使用 curl)：
假设你有一个名为 test.png 的文件。
curl -X 'POST' \
'http://localhost:8000/submit_body_json?width=10.5&height=20.0&words=apple&words=banana' \
-H 'accept: application/json' \
-H 'Content-Type: multipart/form-data' \
-F 'files=@test.png;type=image/png' \
-F 'payload={"boxes": [{"l": 0,"t": 0,"r": 10,"b": 10}], "comments": ["first comment", "second comment"], "code": 123}'说明：
通过上述两种方法，开发者可以有效地解决在FastAPI中同时上传文件和复杂Pydantic模型数据（特别是包含字典列表）的挑战，构建出功能强大且健壮的API接口。
以上就是FastAPI高级用法：如何同时上传文件与Pydantic列表字典数据的详细内容，更多请关注php中文网其它相关文章！
每个人都需要一台速度更快、更稳定的 PC。随着时间的推移，垃圾文件、旧注册表数据和不必要的后台进程会占用资源并降低性能。幸运的是，许多工具可以让 Windows 保持平稳运行。
广告
收藏
收藏
收藏
Copyright 2014-2025 https://www.php.cn/ All Rights Reserved | php.cn | 湘ICP备2023035733号
516
