Files
clean-architecture-backend-…/docs/manual/06-errors.md
T
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.

고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
  :composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
  이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
  boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
  project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
  gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
  config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
  (getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
  훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
  rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
  src/를 붙인다. notification API surface의 application-notification 소스
  루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
  건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
  폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
  registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
  써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
  env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
  verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
  check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
  operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
  다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
  capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
  docs/upgrade/2026-11-relayout.md를 더한다.

위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.

검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.

BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
2026-11-11 22:15:42 +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/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ErrorCodeRegistryMappingTest.java)다.

지금 이해하면 되는 것

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