Jak zpracováváte data formuláře a nahrávání souborů?

Question

Accepted Answer

FastAPI zpracovává **data formuláře HTML** (`Form`) a **nahrávání souborů** (`File`/`UploadFile`) — odlišné od těl JSON, protože používají různé typy obsahu (`multipart/form-data`). Obě jsou deklarovány se speciálními typy parametrů.

## Pole formuláře

```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}
```

Použijte `Form()` k přijetí polí formuláře HTML (např. přihlašovací formulář). Poznámka: trasa může používat buď tělo JSON **nebo** data formuláře, ne obojí, protože jde o různé typy obsahu. (Vyžaduje instalaci `python-multipart`.)

## Nahrávání souborů

```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` je doporučený typ — je to spooled soubor (velké soubory jdou na disk, ne vše do paměti), s async metodami (`read`, `write`, `seek`) a metadaty. Používejte jej místo surových `bytes` pro všechno kromě malých souborů.

## Více souborů a formulář + soubor dohromady

```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
    ...
```

## Validujte nahrávky (bezpečnost!)

```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
```

## Proč je to důležité

Zpracování dat formuláře a nahrávání souborů je běžná, praktická potřeba — přihlašovací formuláře, nahrávání profilových obrázků, odevzdávání dokumentů a API na zpracování souborů to všechno vyžadují, a funguje to jinak než těla JSON, která FastAPI používá ve výchozím nastavení.

Pochopení `Form()` pro pole formuláře a zejména **`UploadFile`** pro nahrávky (doporučený přístup, protože spooluje velké soubory na disk místo načítání všeho do paměti — důležité pro zpracování velkých souborů bez vyčerpání RAM) je nezbytné pro tyto funkce.

Rovněž důležitá je **odpovědnost za bezpečnost**, která přichází s nahrávkami: protože nahrávané soubory jsou nedůvěryhodný vstup, validace jejich typu a velikosti, sanitizace názvů souborů a péče o to, jak je ukládáte/obsluhujete, je nezbytná, aby se předešlo zranitelnostem.

Znalost toho, jak přijímat pole formuláře, zpracovávat jednoduché a více nahrávání souborů, kombinovat formuláře se soubory a bezpečně validovat nahrávky, je praktická znalost pro vytváření skutečných API, která přijímají obsah odeslaný uživatelem.