Hogyan kezeled a formaadatokat és fájlfeltöltéseket?

Question

Accepted Answer

A FastAPI kezeli a HTML **formaadatokat** (`Form`) és a **fájlfeltöltéseket** (`File`/`UploadFile`) — amelyek különböznek a JSON törzstől, mivel más tartalomtípusokat használnak (`multipart/form-data`). Mindkettő speciális paramétertípusokkal van deklarálva.

## Formamezők

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

A `Form()` segítségével fogadj HTML formaadatokat (pl. bejelentkezési forma). Megjegyzés: egy útvonal vagy JSON törzset, vagy formaadatokat használhat, de nem mindkettőt egyszerre, mivel különböző tartalomtípusokról van szó. (A `python-multipart` telepítése szükséges.)

## Fájlfeltöltések

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

Az `UploadFile` az ajánlott típus — egy spooled fájl (nagy fájlok lemezre kerülnek, nem teljesen a memóriában), aszinkron metódusokkal (`read`, `write`, `seek`) és metaadatokkal. Használd helyette a nyers `bytes` helyett bármilyen, csak nem apró fájlok esetén.

## Több fájl és forma + fájl együtt

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

## Feltöltések validálása (biztonsági!)

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

## Miért fontos

A formaadatok és fájlfeltöltések kezelése gyakori, gyakorlati igény — bejelentkezési formák, profilkép-feltöltések, dokumentumbejelentések és fájlfeldolgozó API-k mind szükségletik, és a JSON törzstől eltérően működik, amelyet a FastAPI alapértelmezésben használ.

A `Form()` formaadatokhoz és különösen az **`UploadFile`** feltöltésekhez (az ajánlott megközelítés, mivel nagy fájlokat lemezsporolásnak teszi, nem pedig mindent betölt a memóriába — fontos nagy fájlok kezeléséhez a RAM kimerülésének elkerüléséhez) szükséges ennek a funkcionalitásnak a megértése.

Egyformán fontos a **biztonsági felelősség**, amely feltöltésekkel jár: mivel a feltöltött fájlok nem megbízható bemenetek, típusuk és méretük validálása, fájlneveik szanitálása és körültekintő tárolása/kiszolgálása elengedhetetlen a biztonsági rések elkerüléséhez.

A formaadatok fogadásának, az egyes és több fájlfeltöltés kezelésének, a formák és fájlok kombinálásának, valamint a feltöltések biztonságos validálásának ismerete praktikus tudás a felhasználó által beküldött tartalmakat elfogadó, valós világbeli API-k építéséhez.