Files
clean-architecture-backend-…/docs/manual/06-errors.md
T
DongHyeonka ab5982e955 refactor(repo)!: 샘플 모듈과 그 참조를 지운다
문제: src/sample-portfolio(311파일)와 src/Dockerfile.sample이 빌드 8곳,
registry, PR job, spotbugs 제외, 매뉴얼·leaf 문서 수십 곳에 얽혀 있다.
매뉴얼과 생성 명령이 예시를 맡게 된 뒤로 샘플은 유지 비용만 남았고,
문서 일부는 이미 없는 태스크(sampleOffTest)와 ArchUnit 규칙을 가리킨다.

고른 방법: 소유자 결정(2026-11-07)대로 샘플을 폴더째 지우고 역할은
옮기지 않는다. 샘플을 가리키던 것도 같은 변경에서 지운다.
- 빌드: registry 행, 루트 build.gradle의 샘플 태스크·의존·단계
  (sampleWebContractCheck, :sample-portfolio:*, strict lane 단계),
  app-bootstrap architectureTestRuntimeOnly, spotbugs 제외 3곳
- CI: ci-quality-gates.yml의 sample-portfolio job과 release-gate 칸
- 테스트: SampleRuntimeDefaultsContractTest, Dockerfile.sample 비교 테스트,
  ArchUnit 규칙의 죽은 sample 패키지 제외. build-logic 테스트와
  application-core 테스트의 가짜 이름은 example-app으로 바꾼다
- 문서: 매뉴얼 예시를 실제 코드(durable operation, identifier,
  ErrorCodeRegistryMappingTest)로 바꾸고, 템플릿에 예가 없는 기법
  (유일 제약 → 같은 409)은 규칙과 확인 방법만 적는다. 결정 색인의
  샘플 전용 행은 "샘플과 함께 사라짐"으로 표시한다
버린 대안: 설계서 권장안(OpenAPI 스냅숏·웹 계약을 옮긴 뒤 삭제)은
소유자가 고르지 않았다.

위험·한계:
- 샘플 안에만 있던 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC
  전파, 요청당 SQL 수 단언)가 함께 사라진다. 소유자가 남기라 하면
  총괄이 따로 맡긴다.
- APP_CACHE_REDIS_ENABLED는 샘플이 읽지 않는 키라(설계서 가정과 다름)
  지우지 않고 src/README.md 문장만 고쳤다. 제거 기한 2026-11-30은 그대로.
- docs/capability-status.md 「제거된 코드」 표와 docs/work/evidence.md의
  샘플 경로는 이력이라 두었다.

검증(desktop, 트리 0525e14e, ~/t1-layout-logs/):
- ./gradlew :ci --warning-mode=fail rc=0 (502 executed, 83 from cache)
- :verifyStrictLaneStages --dry-run rc=0
- :app-bootstrap:documentContractTest rc=0
- -p build-logic check rc=0
- :verifyDependencyLocks rc=0
- python3 scripts/check-work-docs.py, 상대 링크 검사 rc=0

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.2
BREAKING CHANGE: src/sample-portfolio, src/Dockerfile.sample, 샘플 태스크와 job이 없어진다. 샘플을 고쳐 쓰던 파생 서비스는 병합 때 수정 대 삭제 충돌이 난다. docs/upgrade/2026-11-maturity-review.md B-49.
2026-11-07 12:21:03 +09:00

4.3 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에 둔다.

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

상황 던질 것 결과
도메인 불변식 위반 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). 서버 결함이 클라이언트 오류 통계에 섞여 경보가 울리지 않는다. 서버 쪽 잘못은 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를 만들고 같은 모양의 대조 테스트를 둔다. 모양은 위 ErrorCodeRegistryMappingTest(src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ErrorCodeRegistryMappingTest.java)다.

지금 이해하면 되는 것

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