# 表单数据

接收的不是 JSON，而是表单字段时，要使用 `Form`。

!!! info "说明"

    要使用表单，需预先安装 <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>。

    例如，`pip install python-multipart`。

## 导入 `Form`

从 `fastapi` 导入 `Form`：

```Python hl_lines="1"
{!../../../docs_src/request_forms/tutorial001.py!}
```

## 定义 `Form` 参数

创建表单（`Form`）参数的方式与 `Body` 和 `Query` 一样：

## Sponsors

<!-- sponsors -->

{% if sponsors %}
{% for sponsor in sponsors.gold -%}
<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}" style="border-radius:15px"></a>
{% endfor -%}
{%- for sponsor in sponsors.silver -%}

    assert response.status_code == 422, response.text


def test_tuple_form_valid():
    response = client.post("/tuple-form/", data={"values": ("1", "2")})
    assert response.status_code == 200, response.text
    assert response.json() == [1, 2]


def test_tuple_form_invalid():
    response = client.post("/tuple-form/", data={"values": ("1", "2", "3")})
    assert response.status_code == 422, response.text

from fastapi import FastAPI, Form

app = FastAPI()


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

## 什么是 「表单数据」

与 JSON 不同，HTML 表单（`<form></form>`）向服务器发送数据通常使用「特殊」的编码。

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

!!! note "技术细节"

    不包含文件时，表单数据一般用 `application/x-www-form-urlencoded`「媒体类型」编码。

    但表单包含文件时，编码为 `multipart/form-data`。使用了 `File`，**FastAPI** 就知道要从请求体的正确位置获取文件。

    client = TestClient(app)
    return client


def test_post_body_form(client: TestClient):
    response = client.post("/login/", data={"username": "Foo", "password": "secret"})
    assert response.status_code == 200
    assert response.json() == {"username": "Foo"}


def test_post_body_form_no_password(client: TestClient):
    response = client.post("/login/", data={"username": "Foo"})

* `description`: a `str` with a short description for the tag. It can have Markdown and will be shown in the docs UI.
* `externalDocs`: a `dict` describing external documentation with:
    * `description`: a `str` with a short description for the external docs.
    * `url` (**required**): a `str` with the URL for the external documentation.

### Create metadata for tags

Let's try that in an example with tags for `users` and `items`.

all = [
    "fastapi-cli >=0.0.2",
    # # For the test client
    "httpx >=0.23.0",
    # For templates
    "jinja2 >=2.11.2",
    # For forms and file uploads
    "python-multipart >=0.0.7",
    # For Starlette's SessionMiddleware, not commonly used with FastAPI
    "itsdangerous >=1.1.0",
    # For Starlette's schema generation, would not be used with FastAPI
    "pyyaml >=5.3.1",
    # For UJSONResponse

Here are several pointers to other places in the docs, for general or frequent questions.

## Filter Data - Security

To ensure that you don't return more data than you should, read the docs for [Tutorial - Response Model - Return Type](../tutorial/response-model.md){.internal-link target=_blank}.

## Documentation Tags - OpenAPI

from dirty_equals import IsDict
from fastapi.testclient import TestClient

from docs_src.request_files.tutorial002 import app

client = TestClient(app)


def test_post_form_no_body():
    response = client.post("/files/")
    assert response.status_code == 422, response.text
    assert response.json() == IsDict(
        {
            "detail": [
                {
                    "type": "missing",