Was ist multipart/form-data Content-Type? File Uploads, Beispiele

Was ist multipart/form-data?

multipart/form-data ist ein HTTP-Request-Content-Type zur Übermittlung von Form-Daten, die Files oder binären Inhalt neben Text-Feldern enthalten. Im Gegensatz zu application/x-www-form-urlencoded (die Default-Form-Encoding für Nur-Text-Felder) sendet multipart/form-data jedes Form-Feld als separaten "Part" im Request-Body, mit eigenen Headers und Inhalt. Diese Struktur ist essentiell für File-Uploads — die Binär-Bytes des Files können nicht sicher als key=value-Paar URL-encoded werden.

Das Format ist in RFC 7578 definiert. Browser nutzen es automatisch, wenn ein HTML-Form enctype="multipart/form-data" hat und ein <input type="file">-Element enthält.

Wie multipart/form-data funktioniert

Der Content-Type-Header enthält einen Boundary — einen zufällig generierten String, der jeden Part im Request-Body trennt:

POST /api/upload HTTP/1.1
Host: api.example.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Length: 554

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="username"

alice
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="avatar"; filename="photo.jpg"
Content-Type: image/jpeg

[binary JPEG bytes here]
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Jeder Part wird durch -- + Boundary-String eingeleitet. Jeder Part hat seinen eigenen Content-Disposition-Header und optionalen Content-Type.

multipart/form-data vs application/x-www-form-urlencoded

Wann multipart/form-data nutzen

• File-Uploads. Der ursprüngliche Use Case.
• Gemischte Text + File Forms.
• Mehrere Files in einem Request.
• Form-Submission mit Non-ASCII-Text.

multipart/form-data aus Code senden

JavaScript (Browser fetch + FormData)

const fd = new FormData();
fd.append('username', 'alice');
fd.append('avatar', fileInput.files[0]);

fetch('/api/upload', {
  method: 'POST',
  body: fd  // Browser setzt Content-Type mit Boundary automatisch
});

Wichtig: setzen Sie Content-Type NICHT manuell beim FormData-Senden — der Browser muss die Boundary selbst hinzufügen.

curl

curl -X POST https://api.example.com/upload \
  -F "username=alice" \
  -F "avatar=@/path/to/photo.jpg"

Python (requests)

import requests
files = {'avatar': open('photo.jpg', 'rb')}
data = {'username': 'alice'}
requests.post('https://api.example.com/upload', files=files, data=data)

Server-seitiges Parsing

• Express + Multer.
• Django. request.FILES['avatar']
• Flask. request.files['avatar']
• FastAPI. def upload(file: UploadFile)
• Spring Boot. @RequestParam MultipartFile
• Rails. params[:avatar]

Multipart-Upload-Limits und Fallstricke

• Server-Body-Size-Limits. NGINX-Default 1 MB; AWS API Gateway 10 MB; Cloudflare 100 MB Pro.
• Memory-Pressure bei Uploads. Streaming-Parser nutzen.
• Boundary-Kollisionen. Theoretisch möglich, extrem selten.
• CSRF bei Uploads. File-Upload-Endpoints brauchen denselben CSRF-Schutz wie andere state-ändernde Endpoints.
• File-Type-Validation. Vertrauen Sie nicht dem Client-Content-Type. Validieren basierend auf tatsächlichem File-Inhalt (Magic Bytes).

Performance-Überlegungen

• Vermeiden Sie große Files durch Ihren API-Server zu senden. Signed S3/Cloud-Storage-Upload-URLs nutzen.
• Chunked / resumable Uploads. Für sehr große Files Protokolle wie tus.io oder AWS S3 multipart upload.
• HTTP/2. Hilft bei Multi-File-Uploads.

Häufige Fehler

• 413 Payload Too Large.
• 400 Bad Request — fehlende Boundary.
• 500 — Multipart-Parser-Exception.
• Leerer File empfangen. Client nutzte FormData aber setzte Content-Type manuell.

Multipart-Uploads at Scale testen

• File-Größen variieren.
• Echten File-Content nutzen.
• Boundary-Cases testen. Knapp unter und über Server-Max-Upload-Limit.
• Multi-Region.
• Konkurrierende Uploads.

FAQ: multipart/form-data

Warum ist die Boundary im Content-Type-Header?

Der Server muss die Boundary kennen, um den Body zu parsen. Er kann sie nicht aus dem Body selbst ableiten.

Kann ich multipart/form-data ohne Files nutzen?

Ja. Es funktioniert auch für Nur-Text-Felder. Aber für Nur-Text-Forms ist application/x-www-form-urlencoded oder JSON effizienter.

Was ist der Unterschied zwischen multipart/form-data und multipart/mixed?

Beide sind multipart, aber multipart/form-data ist spezifisch für HTML-Form-Submissions. multipart/mixed ist generischer (genutzt in E-Mail-Attachments, MIME-Messages).

Wie sende ich JSON + ein File zusammen?

Zwei Patterns: (1) ein Part ist text/JSON, ein anderer ist das File; (2) das File als base64 in JSON einbetten (~33% Overhead).

Warum schlägt mein Upload fehl, wenn ich Content-Type manuell setze?

Weil Sie die Boundary nicht inkludiert haben. Lassen Sie Ihren HTTP-Client den Header automatisch setzen.

Was ist die maximale File-Größe für multipart-Uploads?

Hängt vom Server-Config ab. NGINX-Default 1 MB. AWS API Gateway Hard-Cap 10 MB. Für größere Files signed S3-URLs oder chunked Uploads (tus.io).

Multipart-Upload-Endpoints mit LoadFocus testen

Wenn Sie File-Upload-APIs load-testen, läuft LoadFocus JMeter- und k6-Scripts, die realistische Multipart-Payloads aus 25+ Cloud-Regionen mit bis zu 12.500 VUs senden können. Registrieren bei loadfocus.com/signup — keine Kreditkarte — und führen Sie Ihren ersten Multipart-Upload-Test in unter 5 Minuten aus.