Wie handhabst du Formulardaten und Datei-Uploads?

Question

Accepted Answer

FastAPI behandelt **HTML-Formulardaten** (`Form`) und **Datei-Uploads** (`File`/`UploadFile`) — unterschiedlich von JSON-Body, da sie verschiedene Content-Types verwenden (`multipart/form-data`). Beide werden mit speziellen Parametertypen deklariert.

## Formularfelder

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

Verwende `Form()`, um HTML-Formularfelder zu empfangen (z.B. ein Anmeldeformular). Hinweis: Eine Route kann entweder einen JSON-Body **oder** Formulardaten verwenden, aber nicht beides, da es sich um verschiedene Content-Types handelt. (Erfordert `python-multipart` installiert.)

## Datei-Uploads

```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` ist der empfohlene Typ — es ist eine spooled-Datei (große Dateien gehen auf die Festplatte, nicht alles in den Arbeitsspeicher), mit async-Methoden (`read`, `write`, `seek`) und Metadaten. Verwende es statt rohes `bytes` für alles außer winzigen Dateien.

## Mehrere Dateien und Formular + Datei zusammen

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

## Validiere Uploads (Sicherheit!)

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

## Warum es wichtig ist

Formulardaten und Datei-Uploads zu behandeln ist ein häufiges, praktisches Bedürfnis — Anmeldeformulare, Profilbilduploads, Dokumenteneinreichungen und Dateiverarbeitungs-APIs benötigen dies alle, und es funktioniert anders als die JSON-Bodies, die FastAPI standardmäßig verwendet.

Das Verständnis von `Form()` für Formularfelder und besonders **`UploadFile`** für Uploads (der empfohlene Ansatz, da große Dateien auf der Festplatte gepuffert werden, statt alles in den Arbeitsspeicher zu laden — wichtig für die Handhabung großer Dateien ohne RAM-Erschöpfung) ist für diese Funktionen notwendig.

Gleich wichtig ist die **Sicherheitsverantwortung**, die mit Uploads einhergeht: Da hochgeladene Dateien nicht vertrauenswürdige Eingaben sind, sind das Validieren ihres Typs und ihrer Größe, das Bereinigen von Dateinamen und Vorsicht, wie du sie speicherst/bereitstellst, wesentlich um Schwachstellen zu vermeiden.

Zu wissen, wie man Formularfelder empfängt, einzelne und mehrere Datei-Uploads handhabt, Formulare mit Dateien kombiniert und Uploads sicher validiert, ist praktisches Wissen zum Erstellen echter APIs, die von Benutzern eingereichte Inhalte akzeptieren.