Làm thế nào để nhận một JSON request body?

Question

Accepted Answer

Để nhận một JSON request body trong FastAPI, bạn khai báo một tham số function có kiểu là một **Pydantic model**. FastAPI đọc body, parse JSON, validate nó theo model, và trao cho bạn một đối tượng có kiểu — tự động.

## Pattern

```python
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    description: str | None = None      # field tùy chọn

@app.post("/items")
def create_item(item: Item):             # `item: Item` → đọc & validate JSON body
    # `item` ở đây là một đối tượng Item đã được validate đầy đủ
    return {"name": item.name, "total": item.price * 1.1}
```

```json
// request body mà client gửi:
{ "name": "Phone", "price": 999.0 }
```

Khai báo `item: Item` báo cho FastAPI đọc request body dưới dạng JSON, parse nó thành một `Item`, và **validate** nó — function của bạn nhận được một đối tượng hợp lệ, có kiểu. Input sai bị từ chối tự động:

```json
// POST { "name": "Phone" }  (thiếu price) → 422 tự động:
{ "detail": [{ "loc": ["body", "price"], "msg": "field required" }] }
```

## Body + path + query cùng nhau

```python
@app.put("/items/{item_id}")
def update(item_id: int, item: Item, notify: bool = False):
    # item_id = path param, item = JSON body (Pydantic model), notify = query param
    # FastAPI phân biệt chúng theo kiểu/vị trí tự động
```

FastAPI định tuyến tham số một cách thông minh: một placeholder trong path → path param, một Pydantic model → request body, một tham số kiểu đơn giản → query param.

## Nhiều tham số body / cập nhật một phần

```python
@app.patch("/items/{id}")
def patch(id: int, item: ItemUpdate):       # dùng model với tất cả field tùy chọn cho PATCH
    update_data = item.model_dump(exclude_unset=True)   # chỉ các field client đã gửi
```

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

Nhận và validate request body là thiết yếu — gần như mọi API tạo hoặc cập nhật dữ liệu đều cần, và FastAPI làm điều này cực kỳ gọn gàng: khai báo một tham số Pydantic-model cho bạn parse JSON tự động, **validation** đầy đủ (với lỗi 422 rõ ràng theo field), và một đối tượng có kiểu, loại bỏ việc parse và validate thủ công nhàm chán, dễ lỗi mà các framework khác đòi hỏi.

Validation cũng là một lợi ích **bảo mật/độ bền vững** then chốt — input dị dạng bị từ chối trước khi đến logic của bạn.

Hiểu cách định nghĩa một body model, cách FastAPI tự động phân biệt body với path/query parameter, và các pattern như `exclude_unset` cho cập nhật một phần là kiến thức cơ bản hằng ngày để xây dựng bất kỳ endpoint ghi nào.