FastAPI — 타입이 곧 계약이다 · 오류 응답도 버전이 있는 API다 · 이론

오류 응답도 버전이 있는 API다의 설계 원리

한 줄 요약

업무 예외와 내부 오류를 구분하고 일관된 문제 응답을 제공합니다.

흐름 지도: 한 줄 요약 · 왜 이게 필요했나 · 어떻게 동작하나 · 계약을 읽고 실패를 예측하는 워크시트

왜 이게 필요했나

클라이언트는 오류가 나면 detail 문자열을 정규식으로 읽고 있었다. 어느 날 문장이 바뀌자 재고 부족도 결제 재시도로 처리됐다. 다른 경로에서는 예외 문자열이 그대로 공개되어 SQL과 내부 경로가 새어 나갔다. 오류는 성공 응답 못지않게 명시적인 계약이 필요하다.

어떻게 동작하나

업무 오류에는 missing, conflict, invalid라는 안정된 code를 붙인다. code를 HTTP 상태와 공개 문장으로 변환하되 원래 예외 메시지를 공개 본문에 복사하지 않는다. 요청 id는 길이와 문자 집합을 제한하고 본문과 응답 헤더에 같은 값을 넣는다. 예상한 업무 오류와 예상하지 못한 RuntimeError 모두 실제 TestClient 요청으로 확인한다.

업무 예외 → code → 상태·공개 메시지내부 예외 → 고정 500 → 세부 내용 숨김검증한 요청 id ─────────→ 헤더와 본문

계약을 읽고 실패를 예측하는 워크시트

다음은 구현을 통째로 외우는 답안이 아니라 단계별 코드 리뷰입니다. 각 변경 조각은 의도적으로 계약을 깨뜨립니다. 변경 후에도 정상 사례가 통과할 수 있다는 점에 주의하세요. 실행 전에 어느 입력·예외·상태를 관측하면 차이가 드러날지 예상하고, 구현 후에는 그 예상과 결과를 비교합니다.

1. 업무 예외에 code를 남긴다

DomainError(code, message)는 Exception 하위 클래스이며 .code에 code를 보관합니다. str(예외)는 message입니다.

판단의 근거: 기계가 판단할 code와 사람이 보는 내부 메시지를 분리합니다.

리뷰할 잘못된 변경 조각:

self.code = "invalid"

이 조각이 들어간 함수의 공개 계약과 비교해 보세요. 성공 사례 하나로는 구분되지 않는다면 거절되어야 할 입력이나 실패 이후의 상태를 관측 대상으로 선택합니다.

2. code를 상태로 매핑한다

status_for(code)는 missing=404, conflict=409, invalid=422, 그 외=500입니다.

판단의 근거: 알 수 없는 code를 성공으로 취급하지 않습니다.

리뷰할 잘못된 변경 조각:

.get(code, 200)

3. 공개 문장을 고정한다

public_message(code)는 missing='Resource not found', conflict='State conflict', invalid='Invalid request', 그 외='Internal error'입니다.

판단의 근거: 예외 문자열에 DB 주소나 내부 경로가 들어 있어도 공개하지 않습니다.

리뷰할 잘못된 변경 조각:

"invalid":"Internal error"

4. 요청 id를 제한한다

request_id(value)는 ASCII 영문·숫자·밑줄·하이픈으로만 이루어진 1~32자 문자열이면 그대로, 아니면 'untracked'입니다.

판단의 근거: 임의 헤더를 반사하지 않도록 길이와 문자 집합을 함께 제한합니다.

리뷰할 잘못된 변경 조각:

{1,64}

5. 문제 본문을 만든다

problem(code, rid)는 type='urn:labhub:problem:'+code, title와 detail=public_message(code), status=status_for(code), request_id=request_id(rid)만 가진 딕셔너리입니다.

판단의 근거: 본문과 HTTP 상태가 서로 다르면 클라이언트가 어느 값을 믿을지 결정할 수 없습니다.

리뷰할 잘못된 변경 조각:

"status":500

6. 응답 형식을 일관되게 만든다

response_for(code, rid)는 problem을 본문으로, status_for를 상태로, application/problem+json을 media_type으로, X-Request-ID를 정규화한 rid로 둔 JSONResponse입니다.

판단의 근거: 단순 딕셔너리 반환은 오류도 200으로 만들 수 있습니다.

리뷰할 잘못된 변경 조각:

media_type="application/json"

7. 업무 예외 핸들러를 연결한다

install_handlers(app)는 DomainError 핸들러를 등록합니다. 헤더 X-Request-ID를 읽고 exc.code에 대해 response_for를 반환합니다. exc의 message는 응답에 넣지 않습니다.

판단의 근거: 예외를 잡는 위치를 흩어 놓지 말고 앱의 공통 경계에 둡니다.

리뷰할 잘못된 변경 조각:

response_for("invalid", request.headers.get("x-request-id"))

8. 예상하지 못한 오류도 숨긴다

create_app()은 핸들러를 설치하고 GET /fail/{code}에서 DomainError(code, 내부문장)를 냅니다. 단 code=boom이면 RuntimeError를 냅니다. RuntimeError 핸들러는 code=internal인 고정 500 문제 응답을 반환합니다.

판단의 근거: 테스트에서 예외 재전파를 끄고 실제 500 응답의 바이트를 확인합니다.

리뷰할 잘못된 변경 조각:

response_for("invalid", request.headers.get("x-request-id"))

현장에서 만나는 모습

이 실습의 문제 응답은 type·title·status·detail·request_id를 갖는 교육용 계약이다. 범용 국제화와 전체 표준 적합성을 주장하지 않는다. request id는 추적에 쓰는 문자열이지 인증 수단이 아니며, 운영 로그에도 비밀값을 그대로 기록해서는 안 된다.

다음 실습에서 할 것

여덟 단계가 하나의 실행 가능한 결과물로 이어집니다. 업무 예외에 code를 남긴다 → code를 상태로 매핑한다 → 공개 문장을 고정한다 → 요청 id를 제한한다 → 문제 본문을 만든다 → 응답 형식을 일관되게 만든다 → 업무 예외 핸들러를 연결한다 → 예상하지 못한 오류도 숨긴다.

각 단계는 함수나 파일이 존재한다는 사실이 아니라 실제 반환값·예외·상태 변화를 검사합니다. 정답을 본 뒤에는 일부러 경계 비교나 정리 코드를 바꾸어 어떤 시험이 실패하는지 확인하세요. 앞선 시험이 다음 단계에서도 유지되는 이유를 설명하고, 이 실습이 보장하지 않는 운영 조건을 한 가지 적어 보세요.