Jak obsługujesz dane formularza i przesyłanie plików?

Question

Accepted Answer

FastAPI obsługuje dane formularza HTML (`Form`) i przesyłanie plików (`File`/`UploadFile`) — różniące się od treści JSON, ponieważ używają różnych typów zawartości (`multipart/form-data`). Oba są deklarowane ze specjalnymi typami parametrów.

## Pola formularza

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

Użyj `Form()` do odbierania pól formularza HTML (np. formularz logowania). Uwaga: trasa może używać **albo** treści JSON **albo** danych formularza, ale nie obu naraz, ponieważ to różne typy zawartości. (Wymaga zainstalowanego `python-multipart`.)

## Przesyłanie plików

```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` to zalecany typ — jest to plik ze spoolem (duże pliki trafiają na dysk, a nie wszystkie do pamięci), z metodami asynchronicznymi (`read`, `write`, `seek`) i metadanymi. Używaj go zamiast surowych `bytes` dla czegoś więcej niż małych plików.

## Wiele plików i formularz + plik razem

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

## Walidacja przesyłanych plików (bezpieczeństwo!)

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

## Dlaczego to ważne

Obsługa danych formularza i przesyłania plików to powszechna, praktyczna potrzeba — formularze logowania, przesyłanie zdjęć profilowych, przesyłanie dokumentów i interfejsy API przetwarzające pliki wszystko to wymagają, i działa inaczej niż treści JSON, które FastAPI domyślnie używa.

Zrozumienie `Form()` dla pól formularza i zwłaszcza **`UploadFile`** dla przesyłek (zalecane podejście, ponieważ spooluje duże pliki na dysk, a nie ładuje wszystko do pamięci — ważne dla obsługi dużych plików bez wyczerpywania RAM) jest niezbędne dla tych funkcji.

Również ważna jest **odpowiedzialność za bezpieczeństwo**, która wiąże się z przesyłkami: ponieważ przesłane pliki to niezaufane dane wejściowe, walidacja ich typu i rozmiaru, czyszczenie nazw plików i ostrożność w sposobie ich przechowywania/serwowania jest istotna, aby uniknąć luk w zabezpieczeniach.

Wiedzenie, jak odbierać pola formularza, obsługiwać pojedyncze i wiele przesyłek plików, łączyć formularze z plikami i bezpiecznie walidować przesyłki, to praktyczna wiedza do budowania rzeczywistych interfejsów API, które akceptują zawartość przesłaną przez użytkownika.