백엔드 기초집: Python FastAPILESSON 08

예외 처리와 일관된 오류 응답

난이도초급

예상 시간35분

선수지식이전 강의

8강. 예외 처리와 일관된 오류 응답

1. 이번 강의에서 해결할 문제

없는 기록, 중복 데이터, 요청 검증 실패가 서로 다른 모양으로 응답되면 프론트엔드의 오류 처리가 복잡해집니다. 오류 코드를 포함한 공통 형식을 정의합니다.

2. 학습 목표

3. 핵심 개념

예외는 함수의 정상 반환값과 실패 흐름을 분리합니다. 경로 함수마다 JSONResponse를 직접 만들기보다 도메인 예외를 올리고 한곳에서 {error:{code,message}}로 변환하면 일관성이 생깁니다. 예상하지 못한 500 오류는 서버 로그에 원인을 남기되 응답에는 stack trace를 포함하지 않습니다.

4. 단계별 코드 예시

파일 경로: game-ranking-api/app/errors.py

app/errors.py
class RecordNotFoundError(Exception):
    def __init__(self, record_id: int) -> None:
        self.record_id = record_id

파일 경로: game-ranking-api/app/main.py

app/main.py
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

from app.errors import RecordNotFoundError

app = FastAPI(title="Game Ranking API")


@app.exception_handler(RecordNotFoundError)
async def record_not_found_handler(
    request: Request, exc: RecordNotFoundError
) -> JSONResponse:
    return JSONResponse(
        status_code=404,
        content={"error": {"code": "record_not_found", "message": f"기록 {exc.record_id}을 찾을 수 없습니다"}},
    )


@app.get("/records/{record_id}")
def get_record(record_id: int) -> dict[str, int]:
    if record_id != 1:
        raise RecordNotFoundError(record_id)
    return {"id": 1}

실행 위치: game-ranking-api/

python -m uvicorn app.main:app --reload
Invoke-RestMethod http://127.0.0.1:8000/records/999 -SkipHttpErrorCheck

5. 코드가 동작하는 이유

등록한 exception handler가 해당 타입의 예외를 가로채 404 JSON으로 바꿉니다. endpoint는 HTTP 표현을 반복하지 않고 “기록이 없음”이라는 도메인 사실만 알립니다. request는 필요하면 경로와 추적 정보를 로그에 남기는 데 사용할 수 있습니다.

6. 자주 하는 실수와 해결법

7. 직접 실습

8. 이해 점검 질문 3개

9. 핵심 요약

MINI QUIZ