Files
clean-architecture-backend-…/docs/manual/06-errors.md
T
DongHyeonka 1400dc1506 feat!: 남은 리뷰 발견을 고치고 개발 매뉴얼과 기능 생성 명령을 더한다
문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지
크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의
500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본
(TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR
테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로
만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져
객체 저장소 lane이 돌지 않았다.

방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은
결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD,
S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한).
MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자·
mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고,
scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과
왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와
결정은 리뷰 README 14절에 있다.

위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서
H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC·
WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체,
샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개
(composition:durable-operation, adapter:inbound:messaging)와 새
마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1,
grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면
실패한다(runbook에 확인 쿼리).

검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함
전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절
BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션
기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가,
샘플 Idempotency-Key 오류 코드 변경.
2026-11-03 19:52:06 +09:00

68 lines
4.4 KiB
Markdown

# 06. 오류 모델
## 핵심
실패마다 먼저 **클라이언트 탓인가 서버 탓인가**를 정한다. 클라이언트 탓이면 안정된 오류 코드를 가진
예외를 던지고, 서버 탓이면 코드 없이 던진다. 어느 쪽이든 기능 코드는 던지기만 하고, 전송별 핸들러
하나가 wire 모양으로 바꾼다.
```text
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으로
바꿔서 서버 결함이 클라이언트 오류로 숨는다(리뷰 01-04).
- 메시지는 로그용이다. 클라이언트에는 코드와 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`는 다시 보내도 안전할 때만.