【FastAPI 學習筆記 EP.23】Form Data 表單欄位

什麼是 Form Data?

Form Data 是 HTML <form> 標籤的原生傳送格式，使用 application/x-www-form-urlencoded 或 multipart/form-data 編碼，讓客戶端以欄位鍵值對的形式傳送文字資料。

Form 基礎語法

1. 將路由函式的參數預設值設為 Form(...)，FastAPI 便會從請求的表單資料中解析該欄位；Form(...) 代表必填，Form(None) 代表選填。
2. Form Data 與 JSON Body 互斥——同一個路由無法同時接收 JSON Body（透過 Pydantic model 或 Body() 宣告）與 Form Data，因為兩者使用不同的 Content-Type，瀏覽器無法在同一個請求中混用。
3. 可在同一個路由中宣告多個 Form 欄位，FastAPI 會分別從請求的表單資料中解析每個欄位。
4. Form 欄位可與 UploadFile 同時出現在同一個路由，因為兩者都使用 multipart/form-data 格式，FastAPI 能一次解析文字欄位與上傳的檔案。

from fastapi import FastAPI, File, Form, UploadFile

app = FastAPI()

# 基本登入表單：兩個必填的文字欄位
@app.post("/login/")
def login(username: str = Form(...), password: str = Form(...)):
    return {"username": username, "message": "登入成功"}

# 註冊表單：必填與選填欄位並存
@app.post("/register/")
def register(
    username: str = Form(...),
    email: str = Form(...),
    bio: str | None = Form(None),   # 選填欄位
):
    return {"username": username, "email": email, "bio": bio}

# 同時接收文字欄位與上傳檔案
@app.post("/profile/")
async def update_profile(
    username: str = Form(...),
    avatar: UploadFile | None = File(None),  # 明確告知 FastAPI 此為檔案欄位
):
    avatar_name = None 
    if avatar and avatar.filename:
        content = await avatar.read()
        avatar_name = avatar.filename
        await avatar.close()

    return {"username": username, "avatar": avatar_name}