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, Optional
from pydantic import BaseModel, Field
from fastapi import Query
class 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, HTTPException
from pydantic import BaseModel, Field, ValidationError
from fastapi.encoders import jsonable_encoder
from typing import Optional, List
import json
app = 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, HTTPException
from pydantic import BaseModel, Field, model_validator, ValidationError
from typing import Optional, List
import json
app = 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_validator
class 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服务，提升应用的健壮性和用户体验。
