FastAPI xử lý form data HTML (Form) và upload file (File/UploadFile) — khác với JSON body, vì chúng dùng các content type khác nhau (). Cả hai được khai báo với các kiểu tham số đặc biệt.
FastAPI xử lý form data HTML (Form) và upload file (File/UploadFile) — khác với JSON body, vì chúng dùng các content type khác nhau (). Cả hai được khai báo với các kiểu tham số đặc biệt.
multipart/form-datafrom fastapi import Form
@app.post("/login")
def login(username: str = Form(), password: str = Form()): # trường form, không phải JSON
# dữ liệu đến dạng application/x-www-form-urlencoded hoặc multipart/form-data
return {"username": username}
Dùng Form() để nhận các trường form HTML (ví dụ một form đăng nhập). Lưu ý: một route có thể dùng hoặc JSON body hoặc form data, không cả hai, vì chúng là các content type khác nhau. (Yêu cầu cài python-multipart.)
from fastapi import File, UploadFile
@app.post("/upload")
async def upload(file: UploadFile): # một file đơn
contents = await file.read() # đọc bytes của file
file.filename # tên gốc
file.content_type # kiểu MIME
# lưu nó:
with open(f"uploads/{file.filename}", "wb") as f:
f.write(contents)
return {"filename": file.filename, "size": len(contents)}
UploadFile là kiểu được khuyến nghị — nó là một spooled file (file lớn ghi xuống đĩa, không phải tất cả trong bộ nhớ), với các method async (read, write, seek) và metadata. Dùng nó thay vì bytes thô cho bất cứ thứ gì ngoài file rất nhỏ.
@app.post("/upload-many")
async def upload_many(files: list[UploadFile]): # nhiều file
return [f.filename for f in files]
@app.post("/profile")
async def profile(name: str = Form(), avatar: UploadFile = File()):
# kết hợp trường form VÀ upload file trong một request multipart
...
if file.content_type not in ["image/jpeg", "image/png"]: # kiểm tra kiểu
raise HTTPException(400, "Invalid file type")
# cũng: giới hạn KÍCH THƯỚC file, làm sạch tên file, quét nội dung — upload là input không tin cậy
Xử lý form data và upload file là một nhu cầu phổ biến, thực tiễn — form đăng nhập, upload ảnh đại diện, nộp tài liệu, và API xử lý file đều cần nó, và nó hoạt động khác với JSON body mà FastAPI dùng mặc định.
Hiểu Form() cho trường form và đặc biệt UploadFile cho upload (cách tiếp cận được khuyến nghị, vì nó spool file lớn xuống đĩa thay vì nạp tất cả vào bộ nhớ — quan trọng để xử lý file lớn mà không cạn RAM) là cần thiết cho các tính năng này.
Cũng quan trọng tương đương là trách nhiệm bảo mật đi kèm upload: vì file được upload là input không tin cậy, validate kiểu và kích thước của chúng, làm sạch tên file, và cẩn thận cách bạn lưu/phục vụ chúng là thiết yếu để tránh lỗ hổng.
Biết cách nhận trường form, xử lý upload một và nhiều file, kết hợp form với file, và validate upload an toàn là kiến thức thực tiễn để xây dựng API thực tế chấp nhận nội dung do người dùng gửi.