FastAPI 教程：从请求中获取 Form 表单参数详解

在构建 Web 应用时，处理 HTML 表单提交的数据是一项非常基础且频繁的需求。对于使用 FastAPI 这一现代 Python Web 框架的开发者来说，如何正确、高效地接收和处理表单参数是关键一步。今天我们就来深入探讨一下 FastAPI 中 Form 参数的使用方法。

为什么需要 Form 参数？

你可能已经熟悉了 FastAPI 的路径参数和查询参数。但当数据来自 HTML 表单（通常使用 application/x-www-form-urlencoded 或 multipart/form-data 编码）时，我们就需要用到 Form。这与接收 JSON 数据的 Body 字段是不同的数据格式。

准备工作：安装必要依赖

FastAPI 本身不包含处理表单数据的功能，它被分离到了 python-multipart 这个库中。所以，在使用 Form 参数前，请确保已经安装它。

pip install python-multipart

基础使用：定义 Form 参数

假设我们有一个用户登录的表单，包含 username 和 password 字段。在 FastAPI 中，你可以像定义查询参数一样使用 Form(...)。

首先，从 fastapi 导入 Form：

from fastapi import FastAPI, Form

app = FastAPI()

然后，在你的路径操作函数中声明参数：

@app.post("/login/")
async def login(username: str = Form(...), password: str = Form(...)):
    return {"username": username}

代码解析：

1. @app.post("/login/"): 定义了一个处理 POST 请求的路由。
2. username: str = Form(...): 声明 username 是一个必须的表单字段，类型为字符串。Form(...) 中的 ... 表示该字段是必需的。
3. 函数返回了一个包含用户名（出于安全考虑，不返回密码）的字典。

运行服务器后，你可以使用类似 cURL 的命令或 Postman 等工具进行测试：

curl -X POST "http://127.0.0.1:8000/login/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=testuser&password=testpass"

预期返回：

{"username": "testuser"}

可选参数与默认值

和查询参数一样，表单字段也可以是可选的，或者拥有默认值。

可选字段：将默认值设为 None，并指定 = Form(None)。

from typing import Union

@app.post("/items/")
async def create_item(
    name: str = Form(...),
    description: Union[str, None] = Form(None)  # 可选字段
):
    return {"name": name, "description": description}

默认值字段：在 Form() 中直接指定默认值。

@app.post("/items/with_default")
async def create_item_default(
    category: str = Form("general")  # 默认值为 "general"
):
    return {"category": category}

处理复杂数据：列表与嵌套

表单也能提交数组和更复杂的嵌套数据，但需要特定的客户端编码方式（通常需要 JavaScript 或专门的处理）。

接收列表：使用 typing.List。

from typing import List

@app.post("/submit-tags/")
async def submit_tags(tags: List[str] = Form(...)):
    return {"tags": tags}

要提交多个 tags，客户端需要发送类似 tags=tag1&tags=tag2&tags=tag3 的数据。

与 File 参数结合使用

当表单需要同时上传文件和普通字段时，编码类型会变为 multipart/form-data。你可以同时使用 File 和 Form。

from fastapi import File, UploadFile

@app.post("/upload/")
async def upload_file(
    file: UploadFile = File(...),
    token: str = Form(...)
):
    return {
        "filename": file.filename,
        "token": token,
        "content_type": file.content_type
    }

重要提示与最佳实践

1. 编码类型：确保客户端（如浏览器或API测试工具）设置的 Content-Type 头部正确。普通表单用 application/x-www-form-urlencoded，含文件上传时用 multipart/form-data。
2. 安全性：Form 数据本身不具备额外的安全验证。对于密码等敏感信息，务必在业务逻辑中进行哈希处理。对于其他输入，考虑使用 Pydantic 模型配合 Form 进行复杂验证和类型转换，这能极大地提升代码的健壮性和可维护性。
3. 性能：对于非常大的表单提交（尤其是包含大文件），FastAPI 的异步特性能够很好地处理，但要注意合理配置服务器和中间件。

掌握 Form 参数的处理，意味着你能轻松应对各种来自前端的传统表单提交，这是连接现代 API 与传统 Web 页面交互的重要桥梁。希望这篇教程能帮助你在 Python Web 开发中更加得心应手。如果你想深入了解更多 FastAPI 的高级特性或最佳实践，不妨到 技术文档 板块探索更多相关资料。