FastAPI에서 예외 처리 및 커스텀 오류 정의 방법

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

웹 개발

대상자

FastAPI를 사용하는 개발자, API 설계 및 구현에 관심 있는 중급 이상 개발자

핵심 요약

• HTTPException 사용: 표준 오류 처리 시 HTTPException을 통해 404 Not Found 같은 HTTP 상태 코드를 전달 (예: raise HTTPException(status_code=404, detail="Item not found"))
• 전역 예외 핸들러 구현: @app.exception_handler(ValueError)로 모든 ValueError를 처리하여 400 Bad Request 응답으로 변환
• 커스텀 예외 정의: PaymentFailedError처럼 비즈니스 로직에 맞는 예외 클래스 정의 및 402 Payment Required 응답 처리 (예: status_code=402)

섹션별 세부 요약

1. `HTTPException` 사용 예시

• HTTPException은 FastAPI 내장 도구로, HTTP 상태 코드와 사용자 친화적 메시지를 함께 전달
• 예시 코드: raise HTTPException(status_code=404, detail="Item not found")
• item_id가 0인 경우 404 Not Found 응답을 반환

2. 전역 예외 핸들러 구현

• @app.exception_handler(ValueError)로 모든 ValueError를 한 번에 처리
• 예: divide 경로에서 0으로 나누기 시 발생하는 ValueError를 400 Bad Request로 변환
• JSONResponse로 구조화된 JSON 오류 메시지 전달

3. 커스텀 예외 정의 및 처리

• PaymentFailedError처럼 비즈니스 논리에 맞는 커스텀 예외 클래스 정의 (예: class PaymentFailedError(Exception):)
• @app.exception_handler(PaymentFailedError)로 402 Payment Required 응답 설정
• /pay 경로에서 PaymentFailedError 발생 시 "Card declined by bank" 메시지 전달

결론

• 구조화된 예외 처리는 API의 안정성과 개발자 친화성을 높임
• HTTPException, 전역 핸들러, 커스텀 예외를 결합하여 비즈니스 논리와 맞는 오류 코드 (예: 402, 429)를 사용해 API를 설계해야 함
• 예시: PaymentFailedError와 402 Payment Required 응답을 통해 실제 결제 시나리오에 대응 가능