คุณจัดการ form data และการอัปโหลดไฟล์ได้อย่างไร?

Question

Accepted Answer

FastAPI จัดการ **form data** ของ HTML (`Form`) และ **การอัปโหลดไฟล์** (`File`/`UploadFile`) — ซึ่งแตกต่างจาก JSON bodies เพราะใช้ content types ที่ต่างกัน (`multipart/form-data`) ทั้งสองอย่างถูกประกาศด้วยชนิดพารามิเตอร์พิเศษ

## form fields

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

ใช้ `Form()` เพื่อรับ HTML form fields (เช่น login form) หมายเหตุ: route หนึ่งใช้ได้ทั้ง JSON body **หรือ** form data อย่างใดอย่างหนึ่ง ไม่ใช่ทั้งสอง เพราะเป็น content types ที่ต่างกัน (ต้องติดตั้ง `python-multipart`)

## การอัปโหลดไฟล์

```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` เป็นชนิดที่แนะนำ — มันเป็น spooled file (ไฟล์ขนาดใหญ่จะไปลง disk ไม่ได้อยู่ใน memory ทั้งหมด) พร้อม async methods (`read`, `write`, `seek`) และ metadata ใช้มันแทน raw `bytes` สำหรับอะไรที่ไม่ใช่ไฟล์เล็กจิ๋ว

## หลายไฟล์ และ form + file พร้อมกัน

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

## ตรวจสอบการอัปโหลด (ความปลอดภัย!)

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

## ทำไมจึงสำคัญ

การจัดการ form data และการอัปโหลดไฟล์เป็นความต้องการที่พบบ่อยและใช้จริง — login forms, การอัปโหลดรูปโปรไฟล์, การส่งเอกสาร และ API ประมวลผลไฟล์ ล้วนต้องการมัน และมันทำงานต่างจาก JSON bodies ที่ FastAPI ใช้โดยปริยาย

การเข้าใจ `Form()` สำหรับ form fields และโดยเฉพาะ **`UploadFile`** สำหรับการอัปโหลด (แนวทางที่แนะนำ เพราะมัน spool ไฟล์ขนาดใหญ่ลง disk แทนที่จะโหลดทุกอย่างเข้า memory — สำคัญสำหรับการจัดการไฟล์ใหญ่โดยไม่ทำให้ RAM หมด) เป็นสิ่งจำเป็นสำหรับฟีเจอร์เหล่านี้

ที่สำคัญเท่ากันคือ **ความรับผิดชอบด้านความปลอดภัย** ที่มาพร้อมการอัปโหลด: เนื่องจากไฟล์ที่อัปโหลดเป็น input ที่ไม่น่าไว้วางใจ การตรวจสอบชนิดและขนาดของมัน, การ sanitize ชื่อไฟล์ และการระมัดระวังวิธีจัดเก็บ/ให้บริการเป็นสิ่งจำเป็นเพื่อหลีกเลี่ยงช่องโหว่

การรู้วิธีรับ form fields, จัดการการอัปโหลดไฟล์เดียวและหลายไฟล์, รวม forms กับ files และตรวจสอบการอัปโหลดอย่างปลอดภัย เป็นความรู้ในทางปฏิบัติสำหรับการสร้าง API ในโลกจริงที่รับเนื้อหาที่ผู้ใช้ส่งมา