【FastAPI 學習筆記 EP.22】檔案上傳 (File Upload)

▌什麼是 UploadFile？

▌UploadFile 基礎語法

1. 安裝依賴套件：pip install python-multipart，FastAPI 需要此套件解析 multipart/form-data 格式。
2. 將路由函式的參數型別宣告為 UploadFile，即可取得 filename（原始檔名）與 content_type 屬性。
3. 使用 await file.read() 可讀取整個檔案的 bytes 內容；若要逐塊處理大型檔案以節省記憶體，建議搭配 while 迴圈重複呼叫 await file.read(size)，直到回傳空 bytes 為止，即可達成串流處理。
4. 若需同時上傳多個檔案，將型別宣告為 list[UploadFile] = File(...)，前端以相同欄位名稱送出多個檔案即可（例如 HTML 中使用 <input type="file" name="files" multiple>）。
5. 請求結束後 FastAPI 會自動關閉 UploadFile 的資源，但若在背景任務或長時間操作中繼續使用檔案物件，建議手動呼叫 await file.close()，並搭配 try/finally 確保一定執行。

from fastapi import FastAPI, File, UploadFile

app = FastAPI()

@app.post("/upload/")
async def upload_file(file: UploadFile):
    content = b""
    try:
        # 一次性讀取整個檔案（適合小型檔案）
        content = await file.read()
    finally:
        await file.close()

    return {
        "filename": file.filename,
        "content_type": file.content_type,
        "size_bytes": len(content),
    }

@app.post("/upload-multiple/")
async def upload_multiple(files: list[UploadFile] = File(...)):
    result = []
    for file in files:
        content = b""
        try:
            content = await file.read()
        finally:
            await file.close()
        result.append({
            "filename": file.filename,
            "size_bytes": len(content),
        })
    return result