FastAPI文件上传与JSON处理教程

在FastAPI中同时上传文件和处理包含列表、字典等复杂结构的JSON数据是一项常见的挑战，开发者经常会遇到422 Unprocessable Entity错误。本文针对这一问题，深入分析了错误原因，主要源于HTTP协议中multipart/form-data与application/json编码的冲突。为解决此问题，本教程提供了两种基于Pydantic BaseModel的专业方法：一是将JSON数据序列化为字符串，作为表单字段传输并在后端手动解析；二是利用Pydantic的model_validator在模型实例化前预处理JSON数据。两种方法都附带详细的代码示例和使用说明，旨在帮助开发者高效地在FastAPI中实现文件与复杂JSON数据的协同上传，提升Web API的健壮性和用户体验，避免422错误。

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错误的原因，并提供了两种有效的解决方案。

1. 核心冲突: 理解multipart/form-data和application/json在同一请求体中的编码冲突是解决问题的关键。
2. 策略选择:
   • 策略一（表单字符串与手动解析）：适用于对Swagger UI展示要求不高，或偏好明确分离解析逻辑的场景。
   • 策略二（model_validator优化解析）：提供更好的Swagger UI体验，将解析逻辑内聚于Pydantic模型，代码更优雅，但需要Pydantic v2。
3. 客户端配合: 无论选择哪种策略，客户端在构建multipart/form-data请求时，都必须将复杂的JSON数据序列化为字符串，并作为表单字段发送。
4. Pydantic的强大: Pydantic的Field(Query(...))和model_validator等功能为处理复杂数据结构提供了极大的灵活性和便利性。

选择哪种策略取决于您的具体项目需求和团队偏好。通过这些方法，您可以有效地构建出能够同时处理文件和复杂结构化数据的FastAPI服务，提升应用的健壮性和用户体验。

到这里，我们也就讲完了《FastAPI文件上传与JSON处理教程》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！