本教程深入探讨了在FastAPI中同时上传文件和Pydantic复杂数据结构（如字典列表）的挑战与解决方案。文章首先剖析了传统方法中遇到的HTTP协议限制和Pydantic模型定义问题，随后详细介绍了两种核心策略：通过Form参数传输JSON字符串并手动解析，以及利用Pydantic的model_validator自动处理Body中的JSON字符串。通过实际代码示例，本教程旨在帮助开发者高效地构建支持混合数据上传的FastAPI接口。
1. 挑战：同时上传文件与复杂JSON数据
在fastapi应用开发中，我们经常需要处理多种类型的请求数据，例如文件上传（uploadfile）和结构化的json数据（pydantic basemodel）。当这些数据类型需要同时在一个请求中提交时，开发者可能会遇到一些挑战，特别是当json数据包含列表（list）或字典列表（list[basemodel]）时。
常见的错误尝试包括：
将Pydantic模型直接作为依赖项（Depends()）与UploadFile一起使用，期望它能自动解析JSON体。在Pydantic模型中定义List类型的字段作为查询参数，但未显式使用Query()。尝试通过multipart/form-data同时发送JSON数据和文件。
这些尝试通常会导致422 Unprocessable Entity错误，其根本原因在于HTTP协议对请求体编码的限制以及FastAPI/Pydantic对不同数据源的解析机制。
核心问题点：
HTTP协议限制： HTTP协议通常不允许在一个请求体中同时使用multipart/form-data（用于文件上传）和application/json（用于JSON数据）两种编码类型。当接口定义中包含File()参数时，FastAPI会将整个请求体视为multipart/form-data。List类型查询参数： 当Pydantic模型中包含List[str]或List[int]等列表类型的查询参数时，必须显式使用Field(Query(…))进行声明，否则FastAPI无法正确解析。List[dict]作为查询参数： List[BaseModel]（即字典列表）无法作为查询参数传递。Pydantic模型中的复杂对象列表通常期望作为请求体的一部分。
2. Pydantic模型中列表参数的正确声明
在深入探讨文件与JSON混合上传之前，我们首先需要理解如何在Pydantic模型中正确声明列表类型的查询参数。如果你的Pydantic模型字段是List[str]或List[float]等，你需要使用Query()将其包装在Field()中。
示例代码 1：Pydantic模型中列表查询参数的正确用法
from fastapi import FastAPI, Query, Dependsfrom pydantic import BaseModel, Fieldfrom typing import Optional, Listapp = 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
说明：
words: List[str] = Field(Query(…)) 明确告诉FastAPI words 是一个列表类型的查询参数，可以接收多个同名参数值（例如 ?words=a&words=b）。如果缺少Query(…)，FastAPI将无法正确解析List类型的查询参数。
3. 核心解决方案：同时上传文件与复杂JSON数据
由于HTTP协议的限制，我们不能直接将Pydantic模型（作为application/json）和文件（作为multipart/form-data）同时发送。解决方案的关键在于：将Pydantic模型的数据编码成一个字符串，并通过multipart/form-data的一部分（例如一个Form字段）发送，然后在服务器端进行解析。
以下介绍两种常用的实现方法。
3.1 方法一：通过Form参数传递JSON字符串并手动解析
这种方法将Pydantic模型的数据序列化为JSON字符串，然后作为Form参数的一部分提交。服务器端通过一个依赖函数手动解析这个JSON字符串。
示例代码 2：使用Form参数和依赖函数解析JSON数据
app.py
from fastapi import FastAPI, status, Form, UploadFile, File, Depends, Queryfrom pydantic import BaseModel, Field, ValidationErrorfrom fastapi.exceptions import HTTPExceptionfrom fastapi.encoders import jsonable_encoderfrom typing import Optional, Listimport 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}'
说明：
BaseQueryParams 用于处理 URL 中的查询参数，其中的 words 字段正确使用了 Query(…)。BasePayload 定义了我们期望的复杂JSON数据结构。parse_json_form_data 是一个关键的依赖函数。它接收一个 Form 参数 data（客户端将JSON字符串作为此字段发送），然后使用 BasePayload.model_validate_json() 尝试将其解析为 BasePayload 对象。如果JSON字符串格式不正确，ValidationError 会被捕获并转换为 HTTPException，返回 422 状态码和详细错误信息。files: List[UploadFile] = File(…) 用于接收一个或多个文件。
3.2 方法二：利用Pydantic的model_validator自动解析Body中的JSON字符串
这种方法通过Pydantic模型自身的model_validator来处理从请求体中接收到的JSON字符串。它将JSON字符串视为一个特殊的输入格式，并在模型实例化之前进行解析。这种方式通常更简洁，并且在Swagger UI (/docs) 中能更好地展示请求体结构。
示例代码 3：使用model_validator解析Body中的JSON字符串
app.py
from fastapi import FastAPI, Body, UploadFile, File, Depends, Queryfrom pydantic import BaseModel, Field, model_validatorfrom typing import Optional, Listimport jsonapp = 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_validatorclass 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}'
说明：
BasePayload 模型中新增了一个 model_validator(mode=”before”) 方法。validate_to_json 方法在Pydantic模型验证之前被调用。如果 value 是一个字符串（即客户端发送的JSON字符串），它会尝试使用 json.loads() 将其解析为字典，然后用这个字典来实例化 BasePayload。payload: BasePayload = Body(…) 声明 payload 是请求体的一部分。FastAPI会将其作为 multipart/form-data 中的一个字段来处理，而 model_validator 则负责将其从字符串解析为Pydantic对象。这种方法在FastAPI的/docs接口中显示更友好，因为它能自动生成 BasePayload 的示例输入结构。
4. 注意事项与总结
选择合适的方法： 方法二（使用model_validator）通常更推荐，因为它将JSON解析逻辑封装在Pydantic模型内部，使代码更简洁，且与FastAPI的文档生成集成度更高。客户端请求格式： 无论选择哪种方法，客户端都需要将Pydantic模型的数据序列化为JSON字符串，并作为multipart/form-data中的一个字段发送。查询参数： 对于URL中的列表类型查询参数，务必使用 Field(Query(…)) 进行声明。错误处理： 两种方法都包含了对JSON解析失败的错误处理，确保API在接收到无效数据时能返回清晰的错误信息。多文件上传： 示例中使用了 files: List[UploadFile] = File(…) 来支持多文件上传。如果只需要上传单个文件，可以将其改为 file: UploadFile = File(…)。
通过上述两种方法，开发者可以有效地解决在FastAPI中同时上传文件和复杂Pydantic模型数据（特别是包含字典列表）的挑战，构建出功能强大且健壮的API接口。
以上就是FastAPI高级用法：如何同时上传文件与Pydantic列表字典数据的详细内容，更多请关注创想鸟其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/1372603.html
微信扫一扫 
支付宝扫一扫 
