Come gestisci i dati dei moduli e gli upload di file?

Question

Accepted Answer

FastAPI gestisce i **dati dei moduli HTML** (`Form`) e gli **upload di file** (`File`/`UploadFile`) — distinti dai corpi JSON, poiché utilizzano tipi di contenuto diversi (`multipart/form-data`). Entrambi sono dichiarati con tipi di parametro speciali.

## Campi del modulo

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

Usa `Form()` per ricevere campi di moduli HTML (ad es. un modulo di accesso). Nota: un percorso può utilizzare **o** un corpo JSON **o** dati del modulo, non entrambi, poiché sono tipi di contenuto diversi. (Richiede `python-multipart` installato.)

## Upload di file

```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` è il tipo consigliato — è un file con spooling (i file grandi vanno su disco, non tutti in memoria), con metodi asincroni (`read`, `write`, `seek`) e metadati. Usalo al posto di `bytes` grezzi per qualsiasi cosa tranne file minuscoli.

## Più file e modulo + file insieme

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

## Convalida degli upload (sicurezza!)

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

## Perché è importante

La gestione dei dati dei moduli e degli upload di file è una necessità comune e pratica — moduli di accesso, upload di foto del profilo, invio di documenti e API di elaborazione dei file richiedono tutto questo, e funziona diversamente dai corpi JSON che FastAPI utilizza per impostazione predefinita.

Comprendere `Form()` per i campi del modulo e soprattutto **`UploadFile`** per gli upload (l'approccio consigliato, poiché esegue lo spooling dei file grandi su disco anziché caricare tutto in memoria — importante per gestire file grandi senza esaurire la RAM) è necessario per queste funzionalità.

Equalmente importante è la **responsabilità di sicurezza** che deriva dagli upload: poiché i file caricati sono input non affidabili, convalidare il loro tipo e la loro dimensione, sanificare i nomi dei file e fare attenzione a come li archivi/li servi è essenziale per evitare vulnerabilità.

Sapere come ricevere campi del modulo, gestire upload di file singoli e multipli, combinare moduli con file e convalidare gli upload in modo sicuro è una conoscenza pratica per la creazione di API nel mondo reale che accettano contenuti inviati dagli utenti.