Как вы обрабатываете данные формы и загрузку файлов?

Question

Accepted Answer

FastAPI обрабатывает HTML **данные формы** (`Form`) и **загрузку файлов** (`File`/`UploadFile`) — отличающиеся от JSON-тел, так как они используют разные типы контента (`multipart/form-data`). Оба объявляются со специальными типами параметров.

## Поля формы

```python
from fastapi import Form

@app.post("/login")
def login(username: str = Form(), password: str = Form()):   # form fields, not JSON
    # data comes as application/x-www-form-urlencoded or multipart/form-data
    return {"username": username}
```

Используйте `Form()` для получения полей HTML-формы (например, форма входа). Примечание: маршрут может использовать либо JSON-тело, **либо** данные формы, но не оба одновременно, так как это разные типы контента. (Требует установки `python-multipart`.)

## Загрузка файлов

```python
from fastapi import File, UploadFile

@app.post("/upload")
async def upload(file: UploadFile):                  # a single file
    contents = await file.read()                      # read the file's bytes
    file.filename                                      # original name
    file.content_type                                  # MIME type
    # save it:
    with open(f"uploads/{file.filename}", "wb") as f:
        f.write(contents)
    return {"filename": file.filename, "size": len(contents)}
```

`UploadFile` — рекомендуемый тип — это файл со спулингом (большие файлы идут на диск, не в памяти полностью), с асинхронными методами (`read`, `write`, `seek`) и метаданными. Используйте его вместо сырых `bytes` для всего, кроме крошечных файлов.

## Несколько файлов и форма + файл вместе

```python
@app.post("/upload-many")
async def upload_many(files: list[UploadFile]):       # multiple files
    return [f.filename for f in files]

@app.post("/profile")
async def profile(name: str = Form(), avatar: UploadFile = File()):
    # combine form fields AND a file upload in one multipart request
    ...
```

## Проверка загрузок (безопасность!)

```python
if file.content_type not in ["image/jpeg", "image/png"]:   # check type
    raise HTTPException(400, "Invalid file type")
# also: limit file SIZE, sanitize filenames, scan content — uploads are untrusted input
```

## Почему это важно

Обработка данных формы и загрузка файлов — частая, практическая необходимость — формы входа, загрузка фото профиля, подача документов и API обработки файлов — все это требует данной функциональности, и это работает иначе, чем JSON-тела, которые FastAPI использует по умолчанию.

Понимание `Form()` для полей формы и особенно **`UploadFile`** для загрузок (рекомендуемый подход, так как он спулит большие файлы на диск, а не загружает всё в память — важно для обработки больших файлов без истощения ОЗУ) необходимо для этих функций.

Единственно важна и **ответственность за безопасность**, которая сопровождает загрузки: так как загруженные файлы — это недоверенные входные данные, проверка их типа и размера, санитизация имён файлов и осторожность в том, как вы их сохраняете/раздаёте, необходима для предотвращения уязвимостей.

Знание того, как получать поля формы, обрабатывать единичные и множественные загрузки файлов, комбинировать формы с файлами и безопасно проверять загрузки — это практическое знание для создания реальных API, которые принимают содержимое, отправленное пользователем.