本教程深入探讨了在FastAPI中同时上传文件和包含列表、字典等复杂结构的JSON数据时遇到的挑战及解决方案。文章详细阐述了422 Unprocessable Entity错误的原因，并提供了两种基于Pydantic BaseModel的专业方法，通过将JSON数据作为表单字符串或利用Pydantic的验证器，有效实现文件与复杂JSON数据的协同上传，并附带详细代码示例和使用说明。
1. 引言
fastapi以其高性能和易用性，已成为构建现代web api的热门选择。在实际应用中，我们经常需要处理文件上传，同时还需要接收包含复杂结构（如列表、字典嵌套）的json数据。然而，直接将文件和pydantic模型作为请求体参数混合使用时，开发者常常会遇到422 unprocessable entity错误。本教程将深入分析导致这些问题的原因，并提供两种专业且健壮的解决方案，帮助您高效地在fastapi中实现文件与复杂json数据的协同上传。
2. 理解挑战：为什么会遇到422错误？
在FastAPI中，当您尝试同时上传文件（UploadFile = File(…)）和一个基于Pydantic BaseModel的复杂JSON数据时，通常会遇到422 Unprocessable Entity错误。这背后的原因主要有以下几点：
2.1 Pydantic模型与查询参数的限制
列表型查询参数需要明确声明: 如果您的Pydantic模型中包含List类型的字段，且这些字段是作为查询参数（而非请求体）传递的，您需要使用Field(Query(…))进行明确声明。例如，words: List[str] = Field(Query(…))。否则，FastAPI可能无法正确解析。复杂对象列表不能作为查询参数: 像List[BaseBox]这样包含字典或Pydantic模型的列表，不能作为查询参数传递。HTTP协议的查询字符串设计不适合传递这种复杂结构。如果您尝试这样做，FastAPI会抛出断言错误，指出此类参数“只能是请求体（request body）”。
2.2 HTTP协议与数据编码冲突
这是核心问题。当您的FastAPI端点包含file: UploadFile = File(…)这样的参数时，FastAPI会将预期的请求体编码类型设置为multipart/form-data。这种编码方式通常用于发送文件和简单的表单字段。
然而，当您同时尝试通过Pydantic BaseModel接收一个JSON对象作为请求体时，FastAPI通常期望的编码类型是application/json。HTTP协议标准不允许在同一个请求体中同时使用multipart/form-data和application/json两种编码。因此，当FastAPI接收到一个multipart/form-data请求，但其中又包含一个它期望解析为application/json的Pydantic模型时，就会发生解析错误，导致422 Unprocessable Entity。
2.3 GET请求的限制
此外，值得注意的是，HTTP GET或HEAD请求方法不应包含请求体。GET请求应仅用于请求数据，不应附带数据。因此，如果您尝试在GET请求中发送Pydantic模型作为请求体，FastAPI也会报错。文件上传通常是POST请求，但理解这一限制也很重要。
3. 核心概念与解决方案
为了克服上述挑战，我们需要采用一些策略来确保文件和复杂JSON数据都能被正确地打包和解析。核心思想是：将复杂的JSON数据序列化为字符串，作为multipart/form-data中的一个普通表单字段进行传输，然后在服务器端进行反序列化。
3.1 处理列表型查询参数
在继续讨论文件和JSON混合上传之前，先明确如何正确处理列表型查询参数，这在某些场景下仍然适用。
from typing import List, Optionalfrom pydantic import BaseModel, Fieldfrom fastapi import Queryclass QueryParams(BaseModel): width: Optional[float] = Field(None) height: Optional[float] = Field(None) words: List[str] = Field(Query(...)) # 明确声明为列表查询参数
上述QueryParams模型可以作为依赖注入到FastAPI端点中，用于解析URL中的查询参数，例如：/submit?width=10&words=apple&words=banana。
3.2 解决文件与JSON数据混合上传的策略
以下是两种在FastAPI中同时上传文件和复杂JSON数据的推荐策略。
策略一：将JSON数据作为表单字符串传输并手动解析
这种方法的核心是将复杂的JSON对象序列化为一个JSON字符串，然后将其作为multipart/form-data请求中的一个普通文本字段（Form参数）发送。在服务器端，我们定义一个自定义依赖项（Depends），负责接收这个字符串并将其反序列化为Pydantic模型。
优点:
逻辑清晰，JSON解析过程明确。兼容性较好，客户端只需将JSON对象转换为字符串即可。
缺点:
在FastAPI的交互式API文档（Swagger UI）中，JSON字段会显示为一个普通的字符串输入框，缺乏自动生成的JSON结构示例，用户体验稍差。客户端需要手动将JSON对象序列化为字符串。
代码示例 (app.py):
from fastapi import FastAPI, status, Form, UploadFile, File, Depends, Query, HTTPExceptionfrom pydantic import BaseModel, Field, ValidationErrorfrom fastapi.encoders import jsonable_encoderfrom typing import Optional, Listimport jsonapp = FastAPI()# 定义查询参数模型class BaseParams(BaseModel): width: Optional[float] = Field(None) height: Optional[float] = Field(None) words: List[str] = Field(Query(...)) # 列表型查询参数# 定义嵌套的JSON对象模型class BaseBox(BaseModel): l: float = Field(...) t: float = Field(...) r: float = Field(...) b: float = Field(...)# 定义复杂的JSON数据模型class Base(BaseModel): boxes: List[BaseBox] = Field(...) comments: List[str] = Field(...) code: int = Field(...)# 自定义依赖项，用于解析作为表单字符串传输的JSON数据def parse_json_form_data(data: str = Form(...)): try: # 尝试将字符串解析为Base模型 return Base.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")def submit( base_params: BaseParams = Depends(), # 依赖注入查询参数 base: Base = Depends(parse_json_form_data), # 依赖注入解析后的JSON数据 files: List[UploadFile] = File(...), # 接收文件列表): """ 接收查询参数、JSON数据（作为表单字符串）和文件列表。 """ return { "Params": base_params, "JSON Payload": base, "Filenames": [file.filename for file in files], }# 启动应用：uvicorn app:app --reload
客户端请求示例:
当使用curl或其他HTTP客户端发送请求时，需要将Base模型的数据序列化为JSON字符串，并作为multipart/form-data中的一个字段发送。
curl -X 'POST' 'http://localhost:8000/submit?width=10.5&height=20.0&words=hello&words=world' -H 'accept: application/json' -H 'Content-Type: multipart/form-data' -F 'data={"boxes": [{"l": 0,"t": 0,"r": 0,"b": 0}, {"l": 10,"t": 10,"r": 20,"b": 20}], "comments": ["foo", "bar"], "code": 123}' -F 'files=@./test_image.png;type=image/png' -F 'files=@./another_file.txt;type=text/plain'
data: 包含序列化JSON字符串的表单字段。files: 包含要上传的文件。
策略二：利用Pydantic的model_validator优化JSON数据解析
这种方法与策略一类似，但它利用Pydantic v2的model_validator（或Pydantic v1的@root_validator）在模型实例化之前对传入的数据进行预处理。如果传入的是字符串，model_validator会尝试将其解析为JSON。结合Body(…)使用，可以使FastAPI在Swagger UI中更好地展示JSON模型的结构。
优点:
Swagger UI对JSON数据有更好的展示和自动生成示例，用户体验更佳。客户端发送请求时，如果Content-Type允许，可以直接发送结构化JSON（但在multipart/form-data场景下，仍需发送字符串）。代码更简洁，将解析逻辑封装在Pydantic模型内部。
缺点:
需要Pydantic v2或更高版本才能使用model_validator。model_validator的实现对于初学者可能略显复杂。
代码示例 (app.py):
from fastapi import FastAPI, Body, UploadFile, File, Depends, Query, HTTPExceptionfrom pydantic import BaseModel, Field, model_validator, ValidationErrorfrom typing import Optional, Listimport jsonapp = FastAPI()# 定义查询参数模型class BaseParams(BaseModel): width: Optional[float] = Field(None) height: Optional[float] = Field(None) words: List[str] = Field(Query(...))# 定义嵌套的JSON对象模型class BaseBox(BaseModel): l: float = Field(...) t: float = Field(...) r: float = Field(...) b: float = Field(...)# 定义复杂的JSON数据模型，并添加model_validatorclass Base(BaseModel): boxes: List[BaseBox] = Field(...) comments: List[str] = Field(...) code: int = Field(...) # Pydantic v2的model_validator，在模型实例化前对值进行预处理 @model_validator(mode="before") @classmethod def validate_to_json(cls, value): if isinstance(value, str): try: return cls(**json.loads(value)) except json.JSONDecodeError as e: raise ValueError(f"Invalid JSON string for Base model: {e}") return value@app.post("/submit")def submit( base_params: BaseParams = Depends(), # 依赖注入查询参数 base: Base = Body(...), # Pydantic模型作为请求体，由model_validator处理 files: List[UploadFile] = File(...), # 接收文件列表): """ 接收查询参数、JSON数据（由model_validator处理）和文件列表。 """ return { "Params": base_params, "JSON Payload": base, "Filenames": [file.filename for file in files], }# 启动应用：uvicorn app:app --reload
客户端请求示例:
与策略一类似，客户端仍然需要将JSON数据序列化为字符串，并作为multipart/form-data中的一个字段发送。Body(…)结合model_validator使得FastAPI能够处理这种字符串形式的JSON输入。
curl -X 'POST' 'http://localhost:8000/submit?width=10.5&height=20.0&words=alpha&words=beta' -H 'accept: application/json' -H 'Content-Type: multipart/form-data' -F 'base={"boxes": [{"l": 0,"t": 0,"r": 0,"b": 0}], "comments": ["hello", "world"], "code": 456}' -F 'files=@./document.pdf;type=application/pdf'
base: 包含序列化JSON字符串的表单字段。files: 包含要上传的文件。
4. 总结与注意事项
通过本教程，我们深入探讨了在FastAPI中同时上传文件和复杂JSON数据时可能遇到的422 Unprocessable Entity错误的原因，并提供了两种有效的解决方案。
核心冲突: 理解multipart/form-data和application/json在同一请求体中的编码冲突是解决问题的关键。策略选择:策略一（表单字符串与手动解析）：适用于对Swagger UI展示要求不高，或偏好明确分离解析逻辑的场景。策略二（model_validator优化解析）：提供更好的Swagger UI体验，将解析逻辑内聚于Pydantic模型，代码更优雅，但需要Pydantic v2。客户端配合: 无论选择哪种策略，客户端在构建multipart/form-data请求时，都必须将复杂的JSON数据序列化为字符串，并作为表单字段发送。Pydantic的强大: Pydantic的Field(Query(…))和model_validator等功能为处理复杂数据结构提供了极大的灵活性和便利性。
选择哪种策略取决于您的具体项目需求和团队偏好。通过这些方法，您可以有效地构建出能够同时处理文件和复杂结构化数据的FastAPI服务，提升应用的健壮性和用户体验。
以上就是FastAPI高级实践：高效上传文件与复杂JSON数据（含列表和字典）的详细内容，更多请关注创想鸟其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/1372549.html
微信扫一扫 
支付宝扫一扫 
