Làm thế nào để xử lý lỗi và raise HTTP exception?

Question

Accepted Answer

FastAPI xử lý lỗi bằng cách **raise exception** mà nó chuyển thành các HTTP response đúng đắn. `HTTPException` bao quát phần lớn trường hợp; exception handler tùy chỉnh cho phép bạn kiểm soát định dạng lỗi toàn cục.

## Raise HTTPException

```python
from fastapi import HTTPException

@app.get("/items/{id}")
def get_item(id: int):
    item = db.get(id)
    if not item:
        raise HTTPException(status_code=404, detail="Item not found")   # → response JSON 404
    if not item.is_public:
        raise HTTPException(status_code=403, detail="Forbidden")
    return item
```

`raise HTTPException(status_code=..., detail=...)` là cách idiomatic để trả về một lỗi — FastAPI tạo ra một response JSON `{"detail": "..."}` với status đã cho. `detail` có thể là bất kỳ giá trị nào serialize được sang JSON (chuỗi, dict, list).

## Lỗi validation là tự động (422)

```text
Khi dữ liệu request fail Pydantic validation, FastAPI TỰ ĐỘNG trả về một 422
với một danh sách có cấu trúc chính xác những field nào sai — bạn không viết gì.
```

## Exception handler tùy chỉnh (định dạng toàn cục)

```python
from fastapi import Request
from fastapi.responses import JSONResponse

class ItemNotFound(Exception):
    def __init__(self, item_id: int): self.item_id = item_id

@app.exception_handler(ItemNotFound)         # xử lý một kiểu exception tùy chỉnh toàn cục
def handle_not_found(request: Request, exc: ItemNotFound):
    return JSONResponse(status_code=404, content={"error": f"Item {exc.item_id} not found"})

@app.get("/items/{id}")
def get(id: int):
    raise ItemNotFound(id)        # raise exception domain của bạn; handler định dạng nó
```

Exception handler tùy chỉnh cho phép bạn ánh xạ exception (domain) của riêng bạn thành response, tập trung hóa việc định dạng lỗi và giữ code handler sạch sẽ.

## Ghi đè handler mặc định

```python
from fastapi.exceptions import RequestValidationError

@app.exception_handler(RequestValidationError)   # tùy chỉnh định dạng lỗi-validation 422
def validation_handler(request, exc):
    return JSONResponse(status_code=422, content={"errors": exc.errors()})
```

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

Xử lý lỗi đúng đắn là thiết yếu để xây dựng API đáng tin cậy, chuyên nghiệp, và cách tiếp cận của FastAPI sạch sẽ và nhất quán. `HTTPException` idiomatic khiến dễ trả về các response lỗi đúng đắn với status code và thông báo thích hợp — cơ bản cho bất kỳ endpoint nào có thể fail (không tìm thấy, bị cấm, trạng thái sai).

Cũng có giá trị tương đương là việc **lỗi validation được xử lý tự động** (lỗi Pydantic tạo ra response 422 có cấu trúc mà bạn không viết code nào), và **exception handler tùy chỉnh** cho phép bạn ánh xạ exception domain của riêng bạn thành response và thực thi một định dạng lỗi nhất quán trên toàn API — cải thiện cả khả năng bảo trì (logic lỗi tập trung) lẫn trải nghiệm client (hình dạng lỗi dự đoán được).

Hiểu `HTTPException`, lỗi validation tự động, và handler tùy chỉnh bao quát phổ thực tế của việc xử lý lỗi, biến đây thành kiến thức quan trọng để xây dựng API bền vững.