response_model dùng để làm gì?

Question

Accepted Answer

Tham số **`response_model`** khai báo hình dạng response của một endpoint. FastAPI dùng nó để **validate, lọc và serialize** dữ liệu trả về — và để tài liệu hóa response trong tài liệu API. Nhiệm vụ quan trọng nhất của nó: đảm bảo bạn chỉ phơi bày những field dự định (ví dụ không bao giờ rò rỉ password).

## Vấn đề: rò rỉ các field nhạy cảm

```python
class User(BaseModel):
    name: str
    email: str
    password: str        # ⚠️ KHÔNG BAO GIỜ nên có trong response!

@app.get("/users/{id}")
def get_user(id: int) -> User:
    return db.get_user(id)   # trả về đối tượng đầy đủ sẽ phơi bày password
```

## Giải pháp: một response model riêng

```python
class UserOut(BaseModel):    # hình dạng công khai AN TOÀN — không có password
    name: str
    email: str

@app.get("/users/{id}", response_model=UserOut)
def get_user(id: int):
    return db.get_user(id)   # trả về một user đầy đủ, nhưng FastAPI LỌC nó còn UserOut
# response → { "name": "...", "email": "..." }  — password bị loại bỏ tự động
```

Với `response_model=UserOut`, FastAPI lấy bất cứ thứ gì bạn trả về và **lọc nó xuống** chỉ còn các field được khai báo trong `UserOut` — vì vậy password (và bất kỳ field thừa nào khác) bị loại khỏi response, dù bạn đã trả về đối tượng đầy đủ.

## response_model làm gì

```text
✓ LỌC output chỉ còn các field được khai báo (then chốt để ẩn dữ liệu nhạy cảm)
✓ VALIDATE rằng response của bạn khớp schema được khai báo (bắt lỗi)
✓ SERIALIZE dữ liệu thành JSON đúng cách
✓ TÀI LIỆU HÓA hình dạng response trong tài liệu OpenAPI/Swagger
```

## Cách hiện đại thay thế: annotation kiểu trả về

```python
@app.get("/users/{id}")
def get_user(id: int) -> UserOut:    # kiểu trả về -> hoạt động như response_model
    return db.get_user(id)
# response_model_exclude_unset=True → bỏ qua các field không được set rõ ràng
```

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

`response_model` quan trọng cho cả **bảo mật** lẫn thiết kế API sạch sẽ.

Vai trò then chốt nhất của nó là ngăn rò rỉ dữ liệu vô tình — bằng cách khai báo chính xác những field nào response nên chứa, FastAPI lọc ra mọi thứ khác (như password hash, cờ nội bộ, hay token) ngay cả khi code của bạn trả về một đối tượng database đầy đủ, loại bỏ một lỗ hổng phổ biến và nghiêm trọng.

Ngoài ra, nó validate response theo schema khai báo (bắt lỗi khi bạn trả về sai hình dạng), đảm bảo serialize đúng, và tài liệu hóa response trong tài liệu API tự sinh.

Pattern dùng model input và output riêng biệt (với `response_model` kiểm soát những gì được phơi bày) là một best practice cho API an toàn, được định nghĩa rõ ràng, khiến đây là kiến thức quan trọng cho bất kỳ endpoint nào trả về dữ liệu.