Files
clean-architecture-backend-…/docs/manual/06-errors.md
T
DongHyeonka bbe944bd3c fix!: 재리뷰가 찾은 결함과 색인에서 빠졌던 발견 5건을 고친다
문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가
Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다.
@SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히
prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고,
GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로
나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역
발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다.

방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이
기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록,
@SystemInvoked bean은 기동 실패, complete 단계 실패는
IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도
SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도
행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도
내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제
지표(redis.lane.*) 기준으로 고쳤다.

위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이
브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류
디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어
파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은
기동을 막는다. httpclient failure-injection lane의 main 단계 중복
실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다.

검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci
integrationCheck performanceCheck, :performanceCheck, :releaseCheck
(-PgitRevision), verify-compose-profile-contracts(18 lane) 통과.
첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event
id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절
BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호
첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드
IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은
static·의존 없음이어야 한다.
2026-11-03 23:29:35 +09:00

4.5 KiB

06. 오류 모델

핵심

실패마다 먼저 클라이언트 탓인가 서버 탓인가를 정한다. 클라이언트 탓이면 안정된 오류 코드를 가진 예외를 던지고, 서버 탓이면 코드 없이 던진다. 어느 쪽이든 기능 코드는 던지기만 하고, 전송별 핸들러 하나가 wire 모양으로 바꾼다.

domain    XInvariantException(Reason)          ← 코드 없음. domain-core는 shared-contract를 못 본다
   │  유스케이스가 잡아서 감싼다
application XRejectedException implements ApiErrorCarrier → XErrorCode.X_INVALID (VALIDATION, 400)
            XNotFoundException implements ApiErrorCarrier → XErrorCode.X_NOT_FOUND (NOT_FOUND, 404)
   │  던진다
web       GlobalExceptionHandler: ApiErrorCarrier → errorCode() → status + Envelope{error{code, category, retryable}}
gRPC/GraphQL/WebSocket: 같은 ApiErrorCarrier를 자기 status 모양으로

정본: src/shared-contract/src/main/java/dev/caskeleton/shared/error/ApiErrorCarrier.java, ApiErrorCode.java, OperationalError.java, docs/registries/error-codes.yaml, wire 모양은 docs/web/http-contract.md 1절(null 필드는 내보내지 않는다).

판단: 오류 코드를 어디에 두나

  • 고르는 기준: 같은 유스케이스를 여는 전송이 둘 이상이 될 수 있는가.
  • 기본값: application 기능 패키지의 XErrorCode implements ApiErrorCode enum + 예외가 ApiErrorCarrier 구현. 전송마다 핸들러를 만들 필요가 없다. 생성 명령 출력이 이 모양이다 (<F>ErrorCode, <F>NotFoundException, <F>RejectedException).
  • 예외: 한 전송에서만 의미가 있는 실패(HTTP 헤더 형식 등)는 그 전송 adapter에 둔다. sample은 기능 코드를 web 패키지(PortfolioErrorCode, DomainExceptionHandler)에 두는데, 한 leaf 수직 샘플이라 가능한 모양이다. 따라 하지 않는다.

판단: 어떤 예외 타입으로 던지나

상황 던질 것 결과
도메인 불변식 위반 domain XInvariantException(Reason) → 유스케이스가 XRejectedException으로 감쌈 400 기능 코드
찾는 것이 없음 / 남의 것 XNotFoundException(carrier) 404. 남의 것도 404로 존재를 숨긴다(07장)
상태 충돌(이미 있음, 버전 불일치) 기능 carrier(Category.CONFLICT, 409) 409
요청 파라미터 형식 오류(경로 id 문법 등) IllegalArgumentException 400 BAD_PARAMETER
서버 조립·설정 오류, 있을 수 없는 상태 IllegalStateException 500, 로그 남음
DB·외부 의존 실패 adapter가 shared-contract carrier(PersistenceFailureException, DependencyFailureException)로 분류표대로(04·05장)
  • IllegalArgumentException을 "서버 조립이 틀렸다"에 쓰지 않는다. web은 그것을 400으로 바꾸고 WARN 한 줄만 남긴다(GlobalExceptionHandler). 서버 결함이 클라이언트 오류 통계에 섞여 경보가 울리지 않는다 (리뷰 01-04). 서버 쪽 잘못은 IllegalStateException(500, 로그)이다.
  • 메시지는 로그용이다. 클라이언트에는 코드와 category별 고정 문구(ClientErrorMessages)만 간다. 메시지에 SQLState·내부 경로·토큰을 넣어도 클라이언트에 새지 않지만, 로그 정책은 지킨다.

판단: retryable을 무엇으로

  • 기본값: false. 기능 오류 대부분은 같은 요청을 다시 보내도 결과가 같다.
  • 예외: 시간이 지나면 성공할 수 있고 다시 보내도 안전한 경우만 true(일시적 의존 실패, IDEMPOTENT_IN_FLIGHT). true인 코드는 runbook 링크가 필요하다(registry 규칙).

코드 등록

  • 템플릿 운영 코드: OperationalError + docs/registries/error-codes.yaml을 같은 변경에서 고친다. ErrorCodeRegistryMappingTest(app-bootstrap)가 status 일치를 검사한다.
  • 서비스 기능 코드: 그 registry에 넣지 않는다(registry 머리말 "Product/fork ApiErrorCode enums own local registries"). 서비스 자기 registry를 만들고 같은 모양의 대조 테스트를 둔다. 예: src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/error/PortfolioErrorCodeRegistryMappingTest.java.

지금 이해하면 되는 것

  • 클라이언트 탓 = carrier 예외 + 기능 코드. 서버 탓 = IllegalStateException.
  • 기능 코드는 application에 두고, 전송 핸들러는 기능을 모른다.
  • retryable=true는 다시 보내도 안전할 때만.