FastAPI 教程翻译 - 用户指南 18 - 表单数据

FastAPI 教程翻译 - 用户指南 18 - 表单数据

FastAPI Tutorial - User Guide - Form Data

When you need to receive form fields instead of JSON, you can use Form.

当您需要接收表单字段而不是 JSON 时，可以使用 Form。

Info

信息

To use forms, first install python-multipart.

要使用表单，请先安装 python-multipart。

E.g. pip install python-multipart.

例如：pip install python-multipart。

Import Form

导入 Form

Import Form from fastapi:

从 fastapi 导入 Form：

from fastapi import FastAPI, Form

app = FastAPI()


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

Define Form parameters

定义 Form 参数

Create form parameters the same way you would for Body or Query:

创建表单参数的方式与使用 Body 和 Query 的方式相同：

from fastapi import FastAPI, Form

app = FastAPI()


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

For example, in one of the ways the OAuth2 specification can be used (called “password flow”) it is required to send a username and password as form fields.

例如：以一种可以使用 OAuth2 规范的方式（称为『密码流』），要求发送 username 和 password，并作为表单字段（而不是 JSON）发送。

The spec requires the fields to be exactly named username and password, and to be sent as form fields, not JSON.

规范要求这些字段必须精确命名为 username 和 password，并作为表单字段（而不是 JSON）发送。

With Form you can declare the same metadata and validation as with Body (and Query, Path, Cookie).

使用 Form 可以声明与 Body 相同的元数据和验证（以及 Query、Path、Cookie）。

Info

信息

Form is a class that inherits directly from Body.

Form 是直接从 Body 继承的类。

Tip

提示

To declare form bodies, you need to use Form explicitly, because without it the parameters would be interpreted as query parameters or body (JSON) parameters.

要声明表单主体，您需要显示使用 Form，因为如果没有它，参数将被解释为查询参数或主体（JSON）参数。

About “Form Fields”

关于『表单域』

The way HTML forms (``) sends the data to the server normally uses a “special” encoding for that data, it’s different from JSON.

HTML 表单将数据发送到服务器的方式通常对该数据使用『特殊』编码，这与 JSON 不同。

FastAPI will make sure to read that data from the right place instead of JSON.

FastAPI 将确保从正确的位置而不是 JSON 读取数据。

Technical Details

技术细节

Data from forms is normally encoded using the “media type” application/x-www-form-urlencoded.

来自表单的数据通常使用『媒体类型』application/x-www-form-urlencoded 进行编码。

But when the form includes files, it is encoded as multipart/form-data.

但是，当表单包含文件时，它将被编码为 multipart/form-data。

You’ll read about handling files in the next chapter.

您将在下一章了解有关处理文件的信息。

If you want to read more about these encodings and form fields, head to the MDN web docs for POST.

如果您想了解有关这些编码和表单字段的更多信息，请转到 用于POST的MDN Web文档https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Methods/POST)。

Warning

警告

You can declare multiple Form parameters in a path operation, but you can’t also declare Body fields that you expect to receive as JSON, as the request will have the body encoded using application/x-www-form-urlencoded instead of application/json.

您可以在路径操作中声明多个 Form 参数，但也不能声明希望以 JSON 形式接收的 Body 字段，因为请求将使用 application/x-www-form-urlencoded 而不是 application/json。

This is not a limitation of FastAPI, it’s part of the HTTP protocol.

这不是 FastAPI 的限制，它是 HTTP 协议的一部分。

Recap

回顾

Use Form to declare form data input parameters.

使用 Form 声明表单数据输入参数。