Làm thế nào để xử lý form data và upload file?

Question

Accepted Answer

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 (`multipart/form-data`). Cả hai được khai báo với các kiểu tham số đặc biệt.

## Trường form

```python
from 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`.)

## Upload file

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

## Nhiều file và form + file cùng nhau

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

## Validate upload (bảo mật!)

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

## Tại sao điều này quan trọng

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.