Kako rokovati s podatki obrazcev in nalaganjem datotek?

Question

Accepted Answer

FastAPI rokovati s podatki HTML **obrazca** (`Form`) in **nalaganjem datotek** (`File`/`UploadFile`) — različni od JSON telesa, ker uporabljajo drugačne vrste vsebine (`multipart/form-data`). Oba se deklarirata s posebnimi vrstami parametrov.

## Polja obrazca

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

Uporabite `Form()` za prejemanje polj HTML obrazca (npr. prijavni obrazec). Opomba: pot lahko uporabi ali JSON telo **ali** podatke obrazca, ne oboje, ker so drugačne vrste vsebine. (Zahteva nameščen `python-multipart`.)

## Nalaganje datotek

```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 priporočeni tip — je razporejeni dokument (velike datoteke gredo na disk, ne vse v pomnilnik), s sinhronimi metodami (`read`, `write`, `seek`) in metapodatki. Uporabite ga namesto surovega `bytes` za vse razen manjših datotek.

## Več datotek in obrazec + datoteka skupaj

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

## Preverjanje nalaganj (varnost!)

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

## Zakaj je to važno

Rokovanje s podatki obrazcev in nalaganjem datotek je pogosta, praktična potreba — prijavni obrazci, nalaganje fotografij profila, pošiljanje dokumentov in API-ji za obdelavo datotek to zahtevajo, in deluje drugače kot JSON telesa, ki jih FastAPI privzeto uporablja.

Razumevanje `Form()` za polja obrazca in zlasti **`UploadFile`** za nalaganja (priporočeni pristop, ker razporedi velike datoteke na disk, namesto da bi naložil vse v pomnilnik — važno za obdelavo velikih datotek brez izčrpavanja RAM-a) je potrebno za te funkcionalnosti.

Enako pomembna je **odgovornost za varnost**, ki jo prinaša nalaganje: ker so naložene datoteke nezaupljiv vhod, je preverjanje njihovega tipa in velikosti, čiščenje imen datotek in pazljivo upravljanje z njihovim shranjevanjem/nudjenjem bistveno za preprečevanje ranljivosti.

Znanje, kako prejemati polja obrazca, rokovati z enkratnim in več nalaganjem datotek, kombinirati obrazce z datotekami in varno preverjati nalaganja, je praktično znanje za gradnjo resničnih API-jev, ki sprejemajo vsebino, ki jo pošljejo uporabniki.