문제: docs/manual 본문 19줄이 "리뷰 02-01 결정", "1라운드 06-01·06-03",
"리뷰 README 13.2, 09-02", "(05-01, 04-01, 06-01)", "sample P30 결정"처럼
지난 리뷰 번호만으로 이유를 댄다. 그 리뷰를 모르는 독자는 따라갈 수
없고, docs-writing.md 4절 6단계가 금지한다. 16줄은 --history 검사가
찾았고, 3줄은 걷어낸 뒤 grep으로 다시 읽어 찾았다.
고른 방법: 문장의 뜻은 두고 괄호만 바꾼다.
- 문장이 이미 내용을 말하는 곳(6줄)은 괄호를 지운다
- 지난 일이 근거인 곳은 날짜와 일어난 일로 바꾼다. 예: "2026-11-01
소유자 결정", "2026-11-01부터. 전에는 비어 있으면 검증을 건너뛰었다"
- README 제목 "1라운드 수정으로 생긴 패턴 (리뷰 README 13절)"은
"리뷰 뒤 첫 수정으로 생긴 패턴"으로 바꾼다. 이 제목을 가리키는 링크는
repo에 없다
걷어낸 번호와 원래 괄호, 원래 리뷰 문서와 발견 내용은
docs/work/evidence.md 8절에 표로 더했다(2026-11-06 표와 같은 칸).
버린 대안: 리뷰 문서로 링크 걸기. 본문이 다시 이력을 가리킨다.
위험·한계: 날짜와 "전에는" 문장은 1101 README 13절·15절과 영역 문서의
색인 문장에서 옮겼다. 코드로 다시 확인하지는 않았다. evidence.md 9절
T4-1 행("16줄은 고치지 않음")은 그때의 기록이라 고치지 않았다.
검증(desktop worktree, 이 커밋과 같은 트리 8ff82a67):
- python3 scripts/check-work-docs.py --history docs/manual
lines with history IDs: 0, rc=0
- python3 scripts/check-work-docs.py rc=0(분량, 본문 이력 0, 링크)
- python3 scripts/check-work-docs.py --links docs/manual docs/work
링크 113개, 깨진 것 0
- ./gradlew :app-bootstrap:documentContractTest rc=0, 22개 클래스
66건 통과, 실패·skip 0. docs/manual과 docs/work를 읽는 테스트는 없다
(src의 Java·Gradle에서 파일 이름·폴더 경로 grep, 주석 2곳만 걸림)
- grep -e 리뷰 -e 라운드 -e 결정 docs/manual/*.md로 남은 줄을 읽었다.
모두 날짜와 내용이 있는 문장이다
4.5 KiB
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 ApiErrorCodeenum + 예외가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). 서버 결함이 클라이언트 오류 통계에 섞여 경보가 울리지 않는다. 서버 쪽 잘못은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는 다시 보내도 안전할 때만.