本教程深入探讨了在FastAPI中同时上传文件和Pydantic复杂数据结构（如字典列表）的挑战与解决方案。文章首先剖析了传统方法中遇到的HTTP协议限制和Pydantic模型定义问题，随后详细介绍了两种核心策略：通过Form参数传输JSON字符串并手动解析，以及利用Pydantic的model_validator自动处理Body中的JSON字符串。通过实际代码示例，本教程旨在帮助开发者高效地构建支持混合数据上传的FastAPI接口。
在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模型中的复杂对象列表通常期望作为请求体的一部分。
在深入探讨文件与JSON混合上传之前，我们首先需要理解如何在Pydantic模型中正确声明列表类型的查询参数。如果你的Pydantic模型字段是List[str]或List[float]等，你需要使用Query()将其包装在Field()中。
示例代码 1：Pydantic模型中列表查询参数的正确用法
说明：
- words: List[str] = Field(Query(...)) 明确告诉FastAPI words 是一个列表类型的查询参数，可以接收多个同名参数值（例如 ?words=a&words=b）。
- 如果缺少Query(...)，FastAPI将无法正确解析List类型的查询参数。
由于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
客户端请求示例 (使用 curl)：
假设你有一个名为 test.png 的文件。
说明：
- 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
客户端请求示例 (使用 curl)：
假设你有一个名为 test.png 的文件。
说明：
- 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 的示例输入结构。
- 选择合适的方法： 方法二（使用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列表字典数据的详细内容，更多请关注php中文网其它相关文章！