Cum gestionezi datele formularului și încărcările de fișiere?

Question

Accepted Answer

FastAPI gestionează datele formularului HTML **form data** (`Form`) și **încărcările de fișiere** (`File`/`UploadFile`) — distincte de corpurile JSON, deoarece utilizează tipuri de conținut diferite (`multipart/form-data`). Ambele sunt declarate cu tipuri de parametri speciali.

## Câmpuri de formular

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

Folosește `Form()` pentru a primi câmpuri de formular HTML (de ex. un formular de conectare). Notă: o rută poate folosi fie un corp JSON **fie** date de formular, nu amândouă, deoarece sunt tipuri de conținut diferite. (Necesită `python-multipart` instalat.)

## Încărcări de fișiere

```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` este tipul recomandat — este un fișier spooled (fișierele mari merg pe disc, nu toți în memorie), cu metode asincrone (`read`, `write`, `seek`) și metadate. Folosește-l în loc de raw `bytes` pentru orice altceva decât fișiere minuscule.

## Fișiere multiple și formular + fișier împreună

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

## Validează încărcările (securitate!)

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

## De ce conteaza

Gestionarea datelor formularului și a încărcărilor de fișiere este o nevoie practică și comună — formularele de conectare, încărcări de imagini de profil, trimiteri de documente și API-uri de prelucrare a fișierelor necesită toate această funcționalitate, și funcționează diferit de corpurile JSON pe care FastAPI le folosește în mod implicit.

Înțelegerea `Form()` pentru câmpurile de formular și mai ales **`UploadFile`** pentru încărcări (abordarea recomandată, deoarece spoolează fișiere mari pe disc în loc să le încarce pe toate în memorie — important pentru gestionarea fișierelor mari fără a epuiza RAM-ul) este necesară pentru aceste funcționalități.

La fel de important este **responsabilitatea de securitate** care vine cu încărcările: deoarece fișierele încărcate sunt intrări neîncredibile, validarea tipului și mărimii lor, dezinfectarea numelor de fișiere și atenția la modul în care le stochezi/servi este esențial pentru a evita vulnerabilitățile.

Cunoașterea modului de a primi câmpuri de formular, de a gestiona încărcări de fișiere unice și multiple, de a combina formulare cu fișiere și de a valida încărcările în siguranță este cunoștințe practice pentru construirea API-urilor din lumea reală care acceptă conținut trimis de utilizatori.