오류를 처리하고 HTTP 예외를 어떻게 발생시킵니까?

Question

Accepted Answer

FastAPI는 적절한 HTTP 응답으로 변환되는 **예외를 발생시켜** 오류를 처리합니다. `HTTPException`이 대부분의 경우를 다루며, 커스텀 예외 핸들러로 오류 포맷팅을 전역적으로 제어할 수 있습니다.

## 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")   # → 404 JSON 응답
    if not item.is_public:
        raise HTTPException(status_code=403, detail="Forbidden")
    return item
```

`raise HTTPException(status_code=..., detail=...)`는 오류를 반환하는 관용적인 방법입니다. FastAPI는 주어진 상태와 함께 JSON 응답 `{"detail": "..."}`를 생성합니다. `detail`은 JSON 직렬화 가능한 모든 값(문자열, dict, list)이 될 수 있습니다.

## validation 오류는 자동입니다 (422)

```text
요청 데이터가 Pydantic validation에 실패하면, FastAPI가 자동으로 422를 반환하며
정확히 어떤 필드가 잘못되었는지 구조화된 목록을 제공합니다 — 작성할 코드가 없습니다.
```

## 커스텀 예외 핸들러 (전역 포맷팅)

```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)         # 커스텀 예외 타입을 전역적으로 처리
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)        # 도메인 예외를 발생시키면; 핸들러가 포맷팅함
```

커스텀 예외 핸들러는 자체(도메인) 예외를 응답에 매핑하여, 오류 포맷팅을 중앙화하고 핸들러 코드를 깔끔하게 유지합니다.

## 기본 핸들러 재정의

```python
from fastapi.exceptions import RequestValidationError

@app.exception_handler(RequestValidationError)   # 422 validation 오류 형식 커스터마이즈
def validation_handler(request, exc):
    return JSONResponse(status_code=422, content={"errors": exc.errors()})
```

## 왜 중요한가

적절한 오류 처리는 신뢰할 수 있고 전문적인 API를 구축하는 데 필수적이며, FastAPI의 접근 방식은 깔끔하고 일관됩니다.

관용적인 `HTTPException`은 적절한 상태 코드와 메시지로 올바른 오류 응답을 쉽게 반환하게 합니다. 실패할 수 있는 모든 엔드포인트(찾을 수 없음, 금지됨, 잘못된 상태)에 근본적입니다.

마찬가지로 가치 있는 것은 **validation 오류가 자동으로 처리된다는 점**(Pydantic 실패가 코드 없이 구조화된 422 응답을 생성)과, **커스텀 예외 핸들러**로 자체 도메인 예외를 응답에 매핑하고 전체 API에서 일관된 오류 형식을 강제할 수 있다는 점입니다. 유지보수성(중앙화된 오류 로직)과 클라이언트 경험(예측 가능한 오류 형태) 모두를 향상시킵니다.

`HTTPException`, 자동 validation 오류, 커스텀 핸들러를 이해하는 것은 오류 처리의 실용적 범위를 다루며, 견고한 API를 구축하기 위한 중요한 지식이 됩니다.