Bagaimana Anda menangani data formulir dan unggahan file?

Question

Accepted Answer

FastAPI menangani **data formulir** HTML (`Form`) dan **unggahan file** (`File`/`UploadFile`) — berbeda dari badan JSON, karena menggunakan tipe konten yang berbeda (`multipart/form-data`). Keduanya dideklarasikan dengan tipe parameter khusus.

## Kolom formulir

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

Gunakan `Form()` untuk menerima kolom formulir HTML (misalnya formulir login). Catatan: rute dapat menggunakan badan JSON **atau** data formulir, tetapi tidak keduanya, karena merupakan tipe konten yang berbeda. (Memerlukan `python-multipart` yang diinstal.)

## Unggahan 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` adalah tipe yang direkomendasikan — ini adalah file dengan spool (file besar masuk ke disk, bukan semuanya di memori), dengan metode async (`read`, `write`, `seek`) dan metadata. Gunakan ini daripada `bytes` mentah untuk apa pun selain file kecil.

## Beberapa file dan formulir + file bersama-sama

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

## Validasi unggahan (keamanan!)

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

## Mengapa ini penting

Menangani data formulir dan unggahan file adalah kebutuhan umum dan praktis — formulir login, unggahan foto profil, pengiriman dokumen, dan API pemrosesan file semuanya memerlukannya, dan cara kerjanya berbeda dari badan JSON yang digunakan FastAPI secara default.

Memahami `Form()` untuk kolom formulir dan terutama **`UploadFile`** untuk unggahan (pendekatan yang direkomendasikan, karena menggabungkan file besar ke disk daripada memuat semuanya ke memori — penting untuk menangani file besar tanpa menghabiskan RAM) diperlukan untuk fitur-fitur ini.

Sama pentingnya adalah **tanggung jawab keamanan** yang menyertai unggahan: karena file yang diunggah adalah input yang tidak dipercaya, memvalidasi tipe dan ukurannya, mendesinfeksi nama file, dan berhati-hati tentang cara Anda menyimpan/melayaninya sangat penting untuk menghindari kerentanan.

Mengetahui cara menerima kolom formulir, menangani unggahan file tunggal dan ganda, menggabungkan formulir dengan file, dan memvalidasi unggahan dengan aman adalah pengetahuan praktis untuk membangun API dunia nyata yang menerima konten yang dikirimkan pengguna.