Kako rukovaš podatcima iz formi i učitavanjem datoteka?

Question

Accepted Answer

FastAPI rukuje HTML **podacima iz formi** (`Form`) i **učitavanjem datoteka** (`File`/`UploadFile`) — što je različito od JSON tijela, jer koriste različite vrste sadržaja (`multipart/form-data`). Oboje se deklarira sa posebnim vrstama parametara.

## Polja iz formi

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

Koristi `Form()` za primanje HTML polja iz formi (npr. login forma). Napomena: ruta može koristiti ili JSON tijelo **ili** podatke iz forme, ali ne oboje, jer su to različite vrste sadržaja. (Zahtijeva instaliran `python-multipart`.)

## Učitavanje datoteka

```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 preporučeni tip — to je privremena datoteka (velike datoteke idu na disk, ne sve u memoriji), sa async metodama (`read`, `write`, `seek`) i metapodacima. Koristi je umjesto raw `bytes` za sve osim minijaturnih datoteka.

## Više datoteka i forma + datoteka zajedno

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

## Validacija učitavanja (sigurnost!)

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

## Zašto je važno

Rukovanje podacima iz formi i učitavanjem datoteka je čest, praktičan zahtjev — login forme, učitavanje profilne slike, slanje dokumenata i API-ji za obradu datoteka sve to zahtijevaju, a funkcionira drugačije od JSON tijela koja FastAPI koristi kao zadanu opciju.

Razumijevanje `Form()` za polja iz formi i posebno **`UploadFile`** za učitavanja (preporučeni pristup, jer privremeno sprema velike datoteke na disk umjesto da učitava sve u memoriju — važno za rukovanje velikim datotekama bez iscrpljivanja RAM-a) je neophodno za te mogućnosti.

Jednako je važna **odgovornost za sigurnost** koja dolazi sa učitavanjem: budući da su učitane datoteke nepouzdani ulaz, validacija njihove vrste i veličine, čišćenje imena datoteka i oprez kako ih pohranjiš/posluživaš je bitno kako bi se izbjegla ranjivost.

Znanje kako primiti polja iz formi, rukovati sa jednošću i višestrukošću učitavanja datoteka, kombinirati forme sa datotekama i sigurno validirati učitavanja je praktično znanje za gradnju stvarnih API-ja koji prihvaćaju sadržaj koji je korisnik poslao.