Bagaimana anda mengendalikan data borang dan muat naik fail?

Question

Accepted Answer

FastAPI mengendalikan **data borang** HTML (`Form`) dan **muat naik fail** (`File`/`UploadFile`) — berbeza daripada badan JSON, kerana ia menggunakan jenis kandungan (content type) yang berlainan (`multipart/form-data`). Kedua-duanya diisytiharkan dengan jenis parameter khas.

## Medan borang

```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 medan borang HTML (cth. borang log masuk). Nota: satu laluan boleh menggunakan sama ada badan JSON **atau** data borang, bukan kedua-duanya, kerana ia jenis kandungan yang berlainan. (Memerlukan `python-multipart` dipasang.)

## Muat naik fail

```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` ialah jenis yang disyorkan — ia adalah fail bergulung (spooled file) (fail besar pergi ke cakera, bukan semuanya dalam ingatan), dengan kaedah async (`read`, `write`, `seek`) dan metadata. Gunakannya berbanding `bytes` mentah untuk apa-apa kecuali fail yang sangat kecil.

## Pelbagai fail dan borang + fail bersama

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

## Sahkan muat naik (keselamatan!)

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

Mengendalikan data borang dan muat naik fail ialah keperluan biasa dan praktikal — borang log masuk, muat naik gambar profil, penyerahan dokumen, dan API pemprosesan fail semuanya memerlukannya, dan ia berfungsi secara berbeza daripada badan JSON yang FastAPI gunakan secara lalai.

Memahami `Form()` untuk medan borang dan terutamanya **`UploadFile`** untuk muat naik (pendekatan yang disyorkan, kerana ia menggulung fail besar ke cakera dan bukannya memuatkan segalanya ke dalam ingatan — penting untuk mengendalikan fail besar tanpa menghabiskan RAM) adalah perlu untuk ciri-ciri ini.

Sama pentingnya ialah **tanggungjawab keselamatan** yang datang dengan muat naik: kerana fail yang dimuat naik ialah input yang tidak dipercayai, mengesahkan jenis dan saiznya, membersihkan nama fail, dan berhati-hati cara anda menyimpan/menyajikannya adalah penting untuk mengelakkan kerentanan.

Mengetahui cara menerima medan borang, mengendalikan muat naik fail tunggal dan berbilang, menggabungkan borang dengan fail, dan mengesahkan muat naik dengan selamat ialah pengetahuan praktikal untuk membina API dunia sebenar yang menerima kandungan yang diserahkan oleh pengguna.