docs(agents)!: leaf 지역 규칙 문서를 같은 폴더 AGENTS.md로 옮긴다
leaf·family 지역 규칙은 지금 src/**/CLAUDE.md에만 있어서 Claude Code 밖의 에이전트는 이 규칙을 정본 이름으로 찾지 못한다. 소유자가 2026-11-07에 루트와 하위 폴더 모두 AGENTS.md를 정본으로 정했다 (design-docs harness/01-harness-design.md 13절 Q1·Q2). - 28개 파일을 git mv로 같은 폴더 AGENTS.md로 옮기고, 그 자리 CLAUDE.md에는 `@AGENTS.md` 한 줄만 둔다. 이 세션에서 src/domain-core 파일을 열자 CLAUDE.md의 가져오기가 펼쳐져 AGENTS.md 본문이 함께 읽히는 것을 확인했다. 그래서 Claude Code는 지금처럼 그 폴더를 만질 때 규칙을 읽는다. - 버린 대안: 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않는다), CLAUDE.md 그대로 두기(다른 에이전트가 못 찾는다). - 살아 있는 문서와 테스트 코드의 leaf 규칙 경로를 새 이름으로 바꿨다. 기록 문서(evidence, upgrade, design, history, reviews, adr)는 쓴 때의 경로를 그대로 둔다. - link-check workflow(lychee)는 src/**/CLAUDE.md만 본다. 내용이 AGENTS.md로 가면 상대 링크가 검사 밖으로 나가므로, PR마다 도는 check-docs.py에 살아 있는 문서 전체의 상대 링크 검사를 더했다. workflow는 CI 재편 몫이라 고치지 않았다. - check-work-docs.py의 이력 ID 검사도 src/**/AGENTS.md를 본다. 위험: git은 이 커밋을 "CLAUDE.md 수정 + AGENTS.md 추가"로 본다(같은 이름의 새 파일이 생겨 이름 바꾸기로 잡히지 않는다). 옛 이력은 `git log -- <폴더>/CLAUDE.md`로 본다. 코드 주석의 "CLAUDE.md"는 가져오기를 거쳐 같은 문서에 닿으므로 운영 코드는 고치지 않았다. 검증: python3 scripts/check-docs.py, python3 scripts/check-work-docs.py, python3 -m unittest discover -s scripts/tests 모두 rc=0. 링크 검사 시험은 검사 조건을 끈 사본에서 7건 중 3건이 실패했다. BREAKING CHANGE: 파생 서비스의 leaf 규칙 문서 이름이 AGENTS.md로 바뀐다. 동기화 뒤 각 leaf의 CLAUDE.md는 `@AGENTS.md` 한 줄이다.
This commit is contained in:
@@ -84,7 +84,7 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src
|
||||
|
||||
| 하려는 일 | 시작할 곳 |
|
||||
| --- | --- |
|
||||
| 이 저장소에서 일하기(새 기능, 개선, 조사, 문서, 운영, 일 나누기) | 작업 매뉴얼 [docs/work/README.md](docs/work/README.md). 지도는 [CLAUDE.md](CLAUDE.md) |
|
||||
| 이 저장소에서 일하기(새 기능, 개선, 조사, 문서, 운영, 일 나누기) | 작업 매뉴얼 [docs/work/README.md](docs/work/README.md). 지도는 [AGENTS.md](AGENTS.md) |
|
||||
| 새 업무 기능 만들기 | 개발 매뉴얼 [docs/manual/README.md](docs/manual/README.md)와 생성 명령 `scripts/new-feature.sh` |
|
||||
| 계약 확인하기(HTTP, 오류 코드, env 키, 메트릭, 헤더) | [docs/web/http-contract.md](docs/web/http-contract.md), `docs/registries/` |
|
||||
| 기능 운영하기(설정, 장애 대응) | 영역 운영 문서(`docs/jpa/`, `docs/redis/` 등), 장애 코드별 런북 `docs/runbooks/` |
|
||||
@@ -92,7 +92,7 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src
|
||||
| 예전 설계·계획·리뷰 찾기 | 기록 `docs/design/`, `docs/history/`, `docs/reviews/`. 쓴 때의 글이고 지금 동작은 각 머리 블록의 「현재 정본」을 읽는다 |
|
||||
| 템플릿 변경을 파생 서비스에 받기 | `docs/upgrade/` |
|
||||
|
||||
각 모듈의 규칙과 설계 근거는 그 모듈 폴더의 `CLAUDE.md`와 README에 있다(예: [domain-core](src/domain-core/README.md), [app-bootstrap](src/app-bootstrap/README.md)).
|
||||
각 모듈의 규칙과 설계 근거는 그 모듈 폴더의 `AGENTS.md`와 README에 있다(예: [domain-core](src/domain-core/README.md), [app-bootstrap](src/app-bootstrap/README.md)).
|
||||
|
||||
## 검증
|
||||
|
||||
@@ -130,6 +130,6 @@ cd src
|
||||
## 규칙과 기여
|
||||
|
||||
- 규칙의 정본은 [AGENTS.md](AGENTS.md)다. 「Prime Directive」의 HARD-STOP 조건을 어기면 동작하더라도 병합하지 않는다.
|
||||
- 일을 시작할 때 읽는 지도는 [CLAUDE.md](CLAUDE.md)다. 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다.
|
||||
- 각 모듈의 지역 규칙은 가장 가까운 `src/**/CLAUDE.md`다.
|
||||
- 일을 시작할 때 읽는 지도는 [AGENTS.md](AGENTS.md)다. 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다.
|
||||
- 각 모듈의 지역 규칙은 가장 가까운 `src/**/AGENTS.md`다.
|
||||
- 커밋 정책과 메시지 형식은 [docs/work/README.md](docs/work/README.md) 「커밋」이다. PR은 [.github/pull_request_template.md](.github/pull_request_template.md) 양식을 채운다.
|
||||
|
||||
+1
-1
@@ -200,4 +200,4 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
|
||||
|
||||
- 실행되는 검증 스크립트는 문서가 아니다. `scripts/` 와 `.github/scripts/` 에 있다.
|
||||
- 모듈 레지스트리·Gradle 정책은 `src/config/architecture/modules.json` 과 `src/build.gradle` 이 소유한다.
|
||||
- 각 모듈의 지역 규칙은 해당 모듈의 `src/**/CLAUDE.md` 가 소유한다.
|
||||
- 각 모듈의 지역 규칙은 해당 모듈의 `src/**/AGENTS.md` 가 소유한다.
|
||||
|
||||
@@ -48,7 +48,7 @@ major의 증거가 모두 같은 커밋 SHA를 지니기를 요구한다. 그래
|
||||
H2는 두 번째 운영 대상이 아니다. 같은 위반에 다른 SQLSTATE를 보고하고, JSONB 연산자도, range 타입도, 동시 인덱스
|
||||
빌드도 없다. H2에서 통과한 실행은 코드가 컴파일되고 돈다는 증거일 뿐이다.
|
||||
|
||||
`SKIP LOCKED`는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 `CLAUDE.md`는 측정을 기록한다.
|
||||
`SKIP LOCKED`는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 `AGENTS.md`는 측정을 기록한다.
|
||||
H2 2.4.240은 `FOR UPDATE SKIP LOCKED`를 받고 잠긴 행을 정말로 건너뛴다. 그래서 outbox claim SQL이 두 vendor에서 같다. 이
|
||||
문서는 전에 H2에 그런 보장이 없다고 했다. 둘은 서로 다른 질문에 각각 맞았고, 그 구별이 요점이다. **측정한 버전에서 관찰한
|
||||
동작은 운영 보장이 아니고, PostgreSQL 계약 증거는 더욱 아니다.** 측정 덕분에 claim SQL에 vendor 분기가 필요 없고, 보장이
|
||||
|
||||
@@ -30,7 +30,7 @@ scripts/new-feature.sh Invoice --no-format # Gradle 없이 파일만 (뒤에
|
||||
| 입력 | 규칙 | 어디서 막나 |
|
||||
| --- | --- | --- |
|
||||
| 이름 | PascalCase, 영숫자 | 스크립트 |
|
||||
| 패키지 이름 | 이름을 소문자로(`purchaseorder`). Java 예약어이거나, 다섯 루트 중 어디든(어느 leaf든) 이미 있는 패키지 이름이면 거절 — 템플릿 패키지(`operation`, `lock`, `cache`…)가 모두 여기 걸린다. 목록은 `src/application-core/CLAUDE.md` 「Package ownership」 | 스크립트, `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES` |
|
||||
| 패키지 이름 | 이름을 소문자로(`purchaseorder`). Java 예약어이거나, 다섯 루트 중 어디든(어느 leaf든) 이미 있는 패키지 이름이면 거절 — 템플릿 패키지(`operation`, `lock`, `cache`…)가 모두 여기 걸린다. 목록은 `src/application-core/AGENTS.md` 「Package ownership」 | 스크립트, `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES` |
|
||||
| HTTP 경로 | lowerCamel 복수형. AIP-122 모양 | 스크립트, `ForbiddenApiArchitectureTest.CONTROLLER_REQUEST_MAPPINGS_FOLLOW_AIP122` |
|
||||
| 이미 있는 파일·패키지 | 덮어쓰지 않고 멈춘다 | 스크립트 |
|
||||
|
||||
|
||||
@@ -50,7 +50,7 @@
|
||||
- **기본값**: aggregate를 통째로 저장·로드하면 domain 소유 `XRepository`.
|
||||
- **예외**: 읽기 모양이 aggregate와 다르면 application 소유 `XQueryPort` + projection(record).
|
||||
`QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`가 반환 타입을 검사한다. lease·claim 같은 기술
|
||||
저장은 application 소유 `*StorePort`. 이름 규칙의 정본은 `src/application-core/CLAUDE.md`.
|
||||
저장은 application 소유 `*StorePort`. 이름 규칙의 정본은 `src/application-core/AGENTS.md`.
|
||||
|
||||
## 2단계 — application-core: 유스케이스와 포트
|
||||
|
||||
@@ -70,7 +70,7 @@ record, 오류 코드 enum과 carrier 예외. 예: `src/application-core/src/mai
|
||||
- **고르는 기준**: 결과를 커밋 뒤에 내보내야 하는가, 호출자와 독립적으로 커밋해야 하는가.
|
||||
- **기본값**: 쓰기 `tx.inWrite`, 읽기 `tx.inRead`.
|
||||
- **예외**: 커밋 확인 뒤 결과를 노출해야 하면 `inRootWrite`(바깥 트랜잭션이 있으면 거부). 감사·보상만
|
||||
`inNew`(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: `src/application-core/CLAUDE.md`
|
||||
`inNew`(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: `src/application-core/AGENTS.md`
|
||||
「Allowed transactional shapes」.
|
||||
|
||||
### 판단: 무엇을 반환하나
|
||||
|
||||
@@ -55,7 +55,7 @@
|
||||
- `<f>`는 템플릿 패키지 이름(`operation`, `outbox`, `lock`, `cache`, `secret`, `notification`…)과
|
||||
겹치지 않는다. 겹치면 upstream 템플릿을 받을 때 같은 패키지 트리에서 병합 충돌이 난다. 업무 코드를
|
||||
이름이 맞아 보이는 템플릿 패키지에 넣지도 않는다.
|
||||
- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/CLAUDE.md`
|
||||
- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/AGENTS.md`
|
||||
「Package ownership」이다.** 매뉴얼은 목록을 다시 적지 않는다. 생성 명령이 이름을 거절하고, 생성
|
||||
뒤에는 ArchUnit(`NamingConventionTest`의 package ownership 규칙 두 개)이 다시 막는다.
|
||||
- 이름 규칙은 같은 파일 「Naming convention」이 정본이다.
|
||||
|
||||
@@ -16,7 +16,7 @@
|
||||
DB 커밋 중 연결 끊김 ─────────────────────────────────────▶ 500 DB_COMPLETION_UNKNOWN (retryable=false)
|
||||
```
|
||||
|
||||
정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application-core/CLAUDE.md` 「Idempotency (KEYED)」
|
||||
정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application-core/AGENTS.md` 「Idempotency (KEYED)」
|
||||
(executor 구조), `docs/adr/ADR-JPA-003-completion-unknown.md`(커밋 결과 불명).
|
||||
|
||||
## 판단: 이 쓰기를 KEYED로 만드나
|
||||
|
||||
@@ -17,7 +17,7 @@ use case ── tx.inWrite ─┬─▶ repository.save(aggregate) ┐
|
||||
DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공하는 순간이 생긴다. outbox는 그 순간을
|
||||
없앤다. 대가는 **적어도 한 번** 전달이다 — 소비자는 event id로 중복을 걸러야 한다.
|
||||
|
||||
정본: `src/application-core/CLAUDE.md`(이벤트 타입 표), `docs/messaging/outbox-inbox.md`,
|
||||
정본: `src/application-core/AGENTS.md`(이벤트 타입 표), `docs/messaging/outbox-inbox.md`,
|
||||
`docs/messaging/delivery-guarantees.md`.
|
||||
|
||||
## 순서
|
||||
|
||||
@@ -5,8 +5,8 @@
|
||||
## 배치·이름
|
||||
|
||||
- [ ] 배치를 03장 기준표로 정했다(기본: 계층 leaf 안 `<feature>` 패키지).
|
||||
- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/CLAUDE.md` 「Package ownership」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다.
|
||||
- [ ] 이름이 `src/application-core/CLAUDE.md` 「Naming convention」을 따른다.
|
||||
- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다.
|
||||
- [ ] 이름이 `src/application-core/AGENTS.md` 「Naming convention」을 따른다.
|
||||
|
||||
## domain
|
||||
|
||||
|
||||
@@ -42,8 +42,8 @@
|
||||
| --- | --- |
|
||||
| 계층 경계·금지 규칙·테스트 작성 규칙 | `AGENTS.md`(작업 지도는 `CLAUDE.md`) |
|
||||
| leaf 목록·허용 의존 | `src/config/architecture/modules.json` |
|
||||
| 이름 규칙(유스케이스·포트·command·query) | `src/application-core/CLAUDE.md` 「Naming convention」. 기계 검사는 `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java`와 `ApplicationBoundaryArchitectureTest.java` |
|
||||
| 유스케이스 모양·트랜잭션 모양 | `src/application-core/CLAUDE.md` 「Canonical use case shape」「Allowed transactional shapes」 |
|
||||
| 이름 규칙(유스케이스·포트·command·query) | `src/application-core/AGENTS.md` 「Naming convention」. 기계 검사는 `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java`와 `ApplicationBoundaryArchitectureTest.java` |
|
||||
| 유스케이스 모양·트랜잭션 모양 | `src/application-core/AGENTS.md` 「Canonical use case shape」「Allowed transactional shapes」 |
|
||||
| HTTP wire 계약(Envelope·멱등성 응답) | `docs/web/http-contract.md` |
|
||||
| 운영 오류 코드 | `docs/registries/error-codes.yaml`, `src/shared-contract/src/main/java/dev/caskeleton/shared/error/OperationalError.java` |
|
||||
| 엔티티 매핑·마이그레이션 | `docs/jpa/entity-mapping-guide.md`, `docs/jpa/migration-guide.md`, `docs/jpa/transaction-guide.md` |
|
||||
|
||||
@@ -27,7 +27,7 @@
|
||||
> `modules.json`은 messaging leaf의 `gradle_path`와 허용 의존성을 관리하지만
|
||||
> `runtime_memberships` 필드는 없다. 실제 런타임 편입은 `app-bootstrap`의 Gradle 의존성과 starter /
|
||||
> auto-configuration 경로가 결정한다. 아래 등급은 "무엇이 증명되었는가"를 말하며 런타임 편입 여부와
|
||||
> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/CLAUDE.md`가 소유한다.
|
||||
> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/AGENTS.md`가 소유한다.
|
||||
|
||||
## 브로커 등급
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
파생 서비스가 `adapter:outbound:persistence-mongo`를 실제로 쓰려면 **자기 Mongo 어댑터 leaf**를 하나
|
||||
만든다. 이 leaf(이하 "플랫폼 leaf")는 client·template·정책·실패 분류를 주고, document·repository·
|
||||
mapper·port 구현은 서비스 leaf가 가진다. 플랫폼 leaf에는 예시 도메인을 production으로 넣지 않는다
|
||||
(`src/adapter/outbound/persistence-mongo/CLAUDE.md` "Forbidden").
|
||||
(`src/adapter/outbound/persistence-mongo/AGENTS.md` "Forbidden").
|
||||
|
||||
전체 흐름:
|
||||
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
# 업그레이드 안내 — 2026-11 Claude Code 작업 환경(하네스)
|
||||
|
||||
- 범위: 지침 파일 배치(leaf 규칙 문서 이름, 루트 `AGENTS.md`·`CLAUDE.md`), `.claude/`의 권한·훅·규칙·스킬·서브에이전트, 예측·실측 장부
|
||||
- 근거: 소유자 결정(2026-11-07), design-docs `harness/01-harness-design.md` 13절, `docs/work/reference/decisions.md` 「지침 배치」
|
||||
|
||||
## 1. 누가 읽나
|
||||
|
||||
이 템플릿을 받아 도메인을 채운 파생 서비스가 읽는다. 코드·설정·빌드의 동작은 바뀌지 않았다. 바뀐 것은 지침 파일의 자리와 Claude Code 세션 설정이다.
|
||||
|
||||
## 2. 바뀐 것과 할 일
|
||||
|
||||
| # | 바뀐 것 | 서비스가 할 일 |
|
||||
| --- | --- | --- |
|
||||
| 1 | leaf·family 지역 규칙 문서가 `src/**/CLAUDE.md`에서 같은 폴더 `src/**/AGENTS.md`로 옮겨 갔다. 그 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄이다 | 서비스가 leaf `CLAUDE.md`를 고쳤다면 merge에서 충돌이 난다. 고친 내용을 같은 폴더 `AGENTS.md`로 옮기고 `CLAUDE.md`는 한 줄로 둔다. 서비스가 새로 만든 leaf도 같은 모양으로 둔다. 서비스 문서·테스트가 `src/<leaf>/CLAUDE.md`의 내용을 읽으면 `AGENTS.md`로 바꾼다(`git grep -n 'CLAUDE\.md' -- docs src`) |
|
||||
+1
-1
@@ -31,7 +31,7 @@
|
||||
|
||||
1. 기준 커밋을 고정한다. `git rev-parse HEAD`를 산출물과 보고에 적는다.
|
||||
2. 이미 정한 것을 읽는다: [reference/decisions.md](reference/decisions.md), `docs/reviews/`에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다.
|
||||
3. 소유 leaf를 찾는다. registry의 `source_path`로 정하고, 가장 가까운 `src/**/CLAUDE.md`를 읽는다.
|
||||
3. 소유 leaf를 찾는다. registry의 `source_path`로 정하고, 가장 가까운 `src/**/AGENTS.md`를 읽는다.
|
||||
4. 스킬을 고른다. 정본은 `AGENTS.md` 「Superpowers Workflow」다. playbook에 작업별 스킬이 있다.
|
||||
5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다.
|
||||
6. 무거운 실행(Gradle, Docker, 테스트, 게이트)은 [operate.md](operate.md) 「실행 위치」대로 한다.
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
## 1. 언제 쓰나
|
||||
|
||||
- `docs/work/`, `docs/manual/`, 루트·leaf `CLAUDE.md`, 모듈 README, runbook, 안내 문서를 쓰거나 고칠 때.
|
||||
- `docs/work/`, `docs/manual/`, 루트·leaf `AGENTS.md`, 모듈 README, runbook, 안내 문서를 쓰거나 고칠 때.
|
||||
- 이것은 아니다.
|
||||
- 리뷰 문서 → [improve.md](improve.md)(리뷰 양식은 [reference/review-criteria.md](reference/review-criteria.md) 10절)
|
||||
- 설계서·ADR → [research-design.md](research-design.md)
|
||||
@@ -28,7 +28,7 @@
|
||||
## 4. 절차
|
||||
|
||||
1. 독자와 목적을 한 문장으로 쓴다: "<누가> 이 문서만 읽고 <무엇을> 끝낸다".
|
||||
2. 정본을 찾는다. 규칙이 이미 `AGENTS.md`, registry, leaf `CLAUDE.md`, `docs/web/http-contract.md`, `docs/registries/`에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다.
|
||||
2. 정본을 찾는다. 규칙이 이미 `AGENTS.md`, registry, leaf `AGENTS.md`, `docs/web/http-contract.md`, `docs/registries/`에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다.
|
||||
3. 위치를 정한다. 문서 위치 규칙은 `docs/README.md`다. 여러 repo나 소유자 운영에 걸친 내용은 이 repo가 아니라 design-docs에 둔다.
|
||||
4. 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다.
|
||||
5. 절차는 한 줄에 한 단계, 동사로 시작한다. 명령은 실제로 있는 것만 쓴다. 태스크 이름은 `src/build.gradle`이나 leaf `build.gradle`에서, 경로는 `ls`로 확인한다.
|
||||
|
||||
@@ -69,7 +69,7 @@
|
||||
### 4.3 리팩터링, 성능, 구조, 테스트 구조
|
||||
|
||||
- 리팩터링: 지킬 동작·타입·실패·진단을 "보존 조건"으로 적는다. 그 조건을 지키는 테스트가 지금 통과하는지 먼저 본다. 리팩터링과 동작 변경을 한 커밋에 섞지 않는다.
|
||||
- 복사본을 합칠 때: 정본 하나를 정하고 나머지를 지운다. 못 지우면 이유를 가까운 `CLAUDE.md`에 적고, 두 벌이 같은지 보는 대조 테스트를 둔다.
|
||||
- 복사본을 합칠 때: 정본 하나를 정하고 나머지를 지운다. 못 지우면 이유를 가까운 `AGENTS.md`에 적고, 두 벌이 같은지 보는 대조 테스트를 둔다.
|
||||
- 성능: 숫자 없이 시작하지 않는다. 기준선 측정 → 원인 좁히기 → 변경 하나 → 같은 조건으로 재측정 → 회귀 테스트로 고정. 조건은 review-criteria.md 「성능 측정」, 지난 기준선은 [evidence.md](evidence.md)다. 지난 숫자는 현재 커밋에서 다시 잰다.
|
||||
- 구조 변경: 설계서(`docs/design/`)와 계획서(`docs/history/plans/`)를 먼저 둔다. review-criteria.md 「leaf 변경 체크리스트」를 따른다. ArchUnit 규칙을 바꾸면 잡혀야 할 위반 fixture와 통과해야 할 허용 fixture를 둘 다 둔다.
|
||||
- 테스트 구조: 지금 테스트가 증명하는 것(이름, 단언, skip 수)을 적는다. 고친 뒤 지키려는 production 코드를 일부러 망가뜨려 테스트가 실패하는지(변이) 본다. 옮겼으면 lane별 테스트 수를 전후로 비교한다.
|
||||
|
||||
@@ -29,7 +29,7 @@
|
||||
## 4. 절차
|
||||
|
||||
1. `docs/manual/README.md`를 읽는다. 처음이면 01 → 02 → 03장을 읽는다.
|
||||
2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `<feature>` 패키지다. 이름이 템플릿 패키지(`src/application-core/CLAUDE.md` 「Package ownership」)와 겹치지 않는지 본다.
|
||||
2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `<feature>` 패키지다. 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않는지 본다.
|
||||
3. capability 모듈이면 `docs/manual/10-capabilities.md`와 `AGENTS.md` 「부가 기능(capability) 모듈 규칙」의 완료 기준 7개를 먼저 읽는다. 새 leaf가 생기면 [reference/review-criteria.md](reference/review-criteria.md) 「leaf 변경 체크리스트」를 따른다.
|
||||
4. 뼈대를 만든다: `scripts/new-feature.sh <FeatureName>`(`docs/manual/01-generator.md`). 이 명령은 끝에 Gradle `spotlessApply`를 돈다. 노트북에서는 `--no-format`으로 파일만 만들고, 포맷은 desktop에서 `./gradlew spotlessApply`로 한다([operate.md](operate.md) 「실행 위치」).
|
||||
5. `docs/manual/02-new-feature.md`의 순서대로 채운다: domain-core → application-core → outbound adapter → inbound adapter → app-bootstrap 조립. 안쪽부터 만들면 각 단계가 앞 단계만 보고 컴파일된다.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
이 repo의 리뷰에서 반복해서 나온 결함을 **모양**으로 묶은 목록이다. 리뷰를 시작하기 전에 훑어보고, 고칠 때는 「막는 기준」을 따른다. 리뷰 README의 「반복되는 원인」에 이 번호(A1~)를 붙인다. 패턴마다 근거가 된 지난 발견은 [evidence.md](../evidence.md) 「결함 패턴의 근거」에 있다.
|
||||
|
||||
계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 모듈 책임, 금지된 지름길)와 가장 가까운 `src/**/CLAUDE.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다.
|
||||
계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 모듈 책임, 금지된 지름길)와 가장 가까운 `src/**/AGENTS.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다.
|
||||
|
||||
## 패턴
|
||||
|
||||
@@ -121,7 +121,7 @@
|
||||
| 규칙을 일부러 다르게 둔 타입 | 그 타입의 Javadoc |
|
||||
| 정적 분석 제외 | 제외 항목 옆 이유(`src/config/spotbugs/exclude-test.xml` 등) |
|
||||
| 규칙의 예외 경로 | 이유를 요구하는 표시(`@SystemCaller(reason)`) |
|
||||
| 복사본을 남긴 이유 | 가까운 `CLAUDE.md`(예: `src/platforms/messaging/CLAUDE.md`) |
|
||||
| 복사본을 남긴 이유 | 가까운 `AGENTS.md`(예: `src/platforms/messaging/AGENTS.md`) |
|
||||
| 되돌리기 비싼 선택 | `docs/adr/ADR-<영역>-<번호>-<제목>.md` |
|
||||
|
||||
## 패턴을 더하는 법
|
||||
|
||||
@@ -101,7 +101,7 @@
|
||||
| # | 관점 | 볼 곳 | 이런 증거면 결함 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 코드 성숙도 | 바뀐 클래스와 호출자, 예외 경로 | 이름·Javadoc과 다른 동작, 항상 참·거짓인 조건 |
|
||||
| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `CLAUDE.md` | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import |
|
||||
| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `AGENTS.md` | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import |
|
||||
| 3 | 변경 용이성 | 기능 하나를 더하거나 뺄 때 고칠 파일, `scripts/new-feature.sh` 왕복 | 같은 규칙을 여러 곳에서 바꿔야 함 |
|
||||
| 4 | 인지 부하 | 따라 할 예시 수, 같은 질문에 답하는 문서 수 | 예시·규칙이 여러 갈래이고 고르는 기준이 없음 |
|
||||
| 5 | 위험 가시성 | 기본값, 설정 검증, 기동 rule, 프로필 허용 목록 | 위험이 기본값 뒤에 숨음, 레지스트리 `required`인데 코드는 빈 값 허용 |
|
||||
@@ -123,9 +123,9 @@
|
||||
| 21 | Guardrail 성숙도 | ArchUnit, `verifyStrictLaneStages`, 기동 rule, 정적 분석 단계 | 거짓으로 통과하는 게이트, 어떤 단계도 돌리지 않는 검사 |
|
||||
| 22 | 추상화 성숙도 | 포트·SPI가 보호하는 것 | adapter가 정책을 소유, 역할 없는 단계 |
|
||||
| 23 | 일관성 | 같은 역할의 이름·모양·규칙 | 같은 개념이 여러 벌 |
|
||||
| 24 | 네이밍·의미 | `src/application-core/CLAUDE.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 |
|
||||
| 24 | 네이밍·의미 | `src/application-core/AGENTS.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 |
|
||||
| 25 | 조직 확장성 | 파생 서비스가 upstream을 받을 때 겹치는 곳 | 기능 패키지가 템플릿 패키지와 섞임 |
|
||||
| 26 | Ownership | leaf마다 가까운 `CLAUDE.md`·README | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 |
|
||||
| 26 | Ownership | leaf마다 가까운 `AGENTS.md`·README | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 |
|
||||
| 27 | 삭제 가능성 | capability `runtimeOnly` 한 줄 제거 | 한 줄 지워도 흔적이 남음, bootstrap이 capability 이름을 앎 |
|
||||
| 28 | 회복 가능성 | runbook SQL, DEAD·park, ledger 회수 | 영구히 막히는 key, 복구가 행마다 수작업 |
|
||||
|
||||
@@ -199,7 +199,7 @@ RED가 증거가 되려면: 실패 메시지가 그 결함을 말한다. 머신
|
||||
- 모듈 구조는 디렉터리가 아니라 registry가 정한다. 폴더를 바꾸는 일은 registry를 바꾸는 일이다.
|
||||
- 문서는 leaf 목록·개수·leaf별 명령을 적지 않는다. leaf 명령은 registry의 `gradle_path`에서 만든다.
|
||||
- 새 업무 기능은 계층 leaf 안의 패키지가 기본이다(`docs/manual/03-placement.md`).
|
||||
- 템플릿 패키지 목록은 `src/application-core/CLAUDE.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다.
|
||||
- 템플릿 패키지 목록은 `src/application-core/AGENTS.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다.
|
||||
- capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다.
|
||||
- vendored family(`messaging:*`, 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `CLAUDE.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다.
|
||||
- source set은 runtime·classpath·외부 인프라·JVM 옵션·실행 비용 중 하나가 다를 때만 나눈다. 공유 테스트 코드는 `src/testFixtures/java`다(`docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`).
|
||||
@@ -212,7 +212,7 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼
|
||||
- [ ] leaf `build.gradle`: `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 하나
|
||||
- [ ] lockfile(`verifyDependencyLocks`가 통과하게 다시 만든다)
|
||||
- [ ] capability면 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄과 자기 `AutoConfiguration.imports`
|
||||
- [ ] leaf `CLAUDE.md`, capability면 README 세 가지(제공하는 것, 추가할 한 줄, 필요한 env 키)
|
||||
- [ ] leaf `AGENTS.md`, capability면 README 세 가지(제공하는 것, 추가할 한 줄, 필요한 env 키)
|
||||
- [ ] 템플릿 패키지를 더하거나 지우면 「Package ownership」 표
|
||||
- [ ] ArchUnit 규칙과 그 위반·허용 fixture
|
||||
- [ ] 지운 leaf를 가리키던 문서·workflow·주석(grep으로 찾는다)
|
||||
|
||||
@@ -26,7 +26,7 @@
|
||||
- `docs/reviews/`의 리뷰 README 「결정」 절과 영역 문서의 「Declined to judge」
|
||||
- `docs/adr/`(되돌리기 비싼 선택), `docs/design/`(설계서), `docs/history/plans/`(계획서)
|
||||
- `git log --oneline -- <경로>`와 커밋 본문의 "고른 방법과 버린 대안"
|
||||
- 가장 가까운 `src/**/CLAUDE.md`와 모듈 README
|
||||
- 가장 가까운 `src/**/AGENTS.md`와 모듈 README
|
||||
- 외부 선례: 쓰는 라이브러리의 공식 문서와 릴리스 노트(Spring Boot, Flyway, Hibernate 등), 같은 문제를 다룬 공개 저장소. 직접 쓴 글(1차)인지 정리한 글(2차)인지 표시한다.
|
||||
- 스킬: `superpowers:brainstorming`, 결정 기록은 `documentation-and-adrs`, 공식 문서 확인은 `source-driven-development`. 큰 판단은 `doubt-driven-development`로 반론을 세운다.
|
||||
|
||||
|
||||
+49
-2
@@ -61,7 +61,7 @@ from pathlib import Path
|
||||
REPO_ROOT = Path(__file__).resolve().parent.parent
|
||||
EXCEPTIONS_FILE = "scripts/check-docs-exceptions.txt"
|
||||
REGISTRY_FILE = "src/config/architecture/modules.json"
|
||||
CHECKS = ("language", "head", "reference", "number", "map", "readme")
|
||||
CHECKS = ("language", "head", "reference", "number", "map", "readme", "link")
|
||||
|
||||
# 기록: 본문은 쓴 때의 원문이다. 머리 블록만 고친다. 종류는 폴더가 정한다.
|
||||
RECORD_KINDS = [
|
||||
@@ -148,6 +148,10 @@ VERSION = re.compile(r"(?<![\w.§])v?\d+\.\d+\.\d+(?:[.-][A-Za-z][A-Za-z0-9]*)*(
|
||||
SPRING_BOOT_CELL = re.compile(r"^Spring Boot(?:\s+(?:BOM|버전))?$")
|
||||
CELL_MARKUP = re.compile(r"[*_`]")
|
||||
LINK_TEXT = re.compile(r"\[([^\]\n]*)\]\([^)\s]*\)")
|
||||
# 상대 링크: 살아 있는 문서의 `[글](경로)`가 이 트리의 파일·폴더를 가리킨다. lychee(link-check.yml)는 PR에서
|
||||
# 정해진 경로만 보고, 그 밖의 문서(`src/**/AGENTS.md`, `.claude/**`, 루트 `AGENTS.md`)의 상대 링크는 이 검사만 본다.
|
||||
LINK_TARGET = re.compile(r"\[[^\]\n]*\]\(([^)\s]+)\)")
|
||||
URL_SCHEME = re.compile(r"^[a-z][a-z0-9+.-]*:", re.I)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
@@ -367,6 +371,49 @@ def inline_spans(lines: list[str]) -> list[tuple[int, str]]:
|
||||
return spans
|
||||
|
||||
|
||||
def link_targets(lines: list[str]) -> list[tuple[int, str]]:
|
||||
"""(줄 번호, 상대 링크 대상) — 코드 블록·인라인 코드·「이력」 인용 블록 밖에서만."""
|
||||
targets, fence, history = [], None, False
|
||||
for number, line in enumerate(lines, start=1):
|
||||
match = FENCE.match(line)
|
||||
if fence:
|
||||
if match and match.group(1)[0] == fence[0] and len(match.group(1)) >= len(fence):
|
||||
fence = None
|
||||
continue
|
||||
if match:
|
||||
fence = match.group(1)
|
||||
continue
|
||||
quoted = line.lstrip().startswith(">")
|
||||
if quoted and HISTORY_QUOTE.match(line):
|
||||
history = True
|
||||
elif not quoted:
|
||||
history = False
|
||||
if history:
|
||||
continue
|
||||
for found in LINK_TARGET.finditer(INLINE.sub("", line)):
|
||||
target = found.group(1).split("#", 1)[0]
|
||||
if target and not URL_SCHEME.match(target):
|
||||
targets.append((number, target))
|
||||
return targets
|
||||
|
||||
|
||||
def check_link(root: Path, files: list[str]) -> list[Problem]:
|
||||
known = known_paths(root)
|
||||
problems = []
|
||||
for path in files:
|
||||
if not is_living(path):
|
||||
continue
|
||||
text = (root / path).read_text(encoding="utf-8")
|
||||
lines = body_lines(text)
|
||||
offset = len(text.split("\n")) - len(lines)
|
||||
for number, target in link_targets(lines):
|
||||
resolved = posixpath.normpath(posixpath.join(posixpath.dirname(path), target))
|
||||
if resolved.startswith("..") or not is_known(known, resolved):
|
||||
problems.append(Problem("link", path, target, f"없는 곳을 가리키는 상대 링크다: {target}",
|
||||
number + offset))
|
||||
return problems
|
||||
|
||||
|
||||
def registry_projects(root: Path) -> set[str]:
|
||||
registry = root / REGISTRY_FILE
|
||||
if not registry.is_file():
|
||||
@@ -634,7 +681,7 @@ def check_readme(root: Path, files: list[str]) -> list[Problem]:
|
||||
|
||||
|
||||
RUNNERS = {"language": check_language, "head": check_head, "reference": check_reference, "number": check_number,
|
||||
"map": check_map, "readme": check_readme}
|
||||
"map": check_map, "readme": check_readme, "link": check_link}
|
||||
|
||||
|
||||
def read_exceptions(text: str) -> list[str]:
|
||||
|
||||
@@ -9,7 +9,7 @@ to finish the job from those alone. Two things break that, and both are mechanic
|
||||
who does not know that review. History belongs in `docs/work/evidence.md`, and the two reference
|
||||
files that are indexes of history (`reference/decisions.md`, `reference/defect-patterns.md`).
|
||||
The same rule covers the other files a new session reads first: the rule book `AGENTS.md` and
|
||||
every `src/**/CLAUDE.md` (owner decision 2026-11-07). Module READMEs, design documents and
|
||||
every `src/**/AGENTS.md` (owner decision 2026-11-07). Module READMEs, design documents and
|
||||
`docs/reviews/**` keep their IDs, because a reader can follow them from inside the repository.
|
||||
2. Length. Each entry file has a line limit, and the entry path (map + README + one playbook) has a
|
||||
total limit, so a session reads the whole path instead of skimming it.
|
||||
@@ -196,11 +196,12 @@ def check_skeleton(errors: list[str]) -> None:
|
||||
|
||||
|
||||
def module_guides() -> list[Path]:
|
||||
"""Every src/**/CLAUDE.md, the local rule book of a leaf or a family, outside build output."""
|
||||
"""Every src/**/AGENTS.md, the local rule book of a leaf or a family, outside build output.
|
||||
The src/**/CLAUDE.md beside it is one line, `@AGENTS.md`, so Claude Code reads the same book."""
|
||||
skipped = {"build", ".gradle", "node_modules"}
|
||||
return sorted(
|
||||
path
|
||||
for path in (REPO_ROOT / "src").rglob("CLAUDE.md")
|
||||
for path in (REPO_ROOT / "src").rglob("AGENTS.md")
|
||||
if not skipped.intersection(path.relative_to(REPO_ROOT).parts)
|
||||
)
|
||||
|
||||
|
||||
@@ -439,6 +439,38 @@ class ReadmeTest(RepositoryTestCase):
|
||||
self.assertFailsWith(self.repo.run(("readme",)), "루트 README가 없다")
|
||||
|
||||
|
||||
class LinkTest(RepositoryTestCase):
|
||||
def errors_for(self, text: str, path: str = "src/app/AGENTS.md") -> list[str]:
|
||||
self.repo.write(path, KOREAN + text)
|
||||
return self.repo.run(("link",))
|
||||
|
||||
def test_a_relative_link_to_a_missing_file_fails(self) -> None:
|
||||
self.assertFailsWith(self.errors_for("[설계](README.md)를 본다.\n"), "없는 곳을 가리키는 상대 링크다: README.md")
|
||||
|
||||
def test_a_relative_link_to_a_tracked_file_passes(self) -> None:
|
||||
self.repo.write("src/app/README.md", KOREAN)
|
||||
self.assertEqual(self.errors_for("[설계](README.md#결정)를 본다.\n"), [])
|
||||
|
||||
def test_a_link_up_the_tree_resolves_from_the_document_folder(self) -> None:
|
||||
self.assertEqual(self.errors_for("[살아 있는 문서](../../docs/live.md)를 본다.\n"), [])
|
||||
|
||||
def test_a_link_out_of_the_repository_fails(self) -> None:
|
||||
self.assertFailsWith(self.errors_for("[밖](../../../outside.md)를 본다.\n"), "../../../outside.md")
|
||||
|
||||
def test_a_folder_left_empty_on_disk_fails(self) -> None:
|
||||
(self.repo.root / "src/app/moved").mkdir(parents=True)
|
||||
self.assertFailsWith(self.errors_for("[옮김](moved/)을 본다.\n"), "moved/")
|
||||
|
||||
def test_urls_anchors_code_and_history_quotes_are_skipped(self) -> None:
|
||||
text = ("[웹](https://example.com/x) [절](#절) `[코드](gone.md)`\n"
|
||||
"```text\n[블록](gone.md)\n```\n> 이력: [옛 문서](gone.md)는 지웠다.\n")
|
||||
self.assertEqual(self.errors_for(text), [])
|
||||
|
||||
def test_a_record_is_not_checked(self) -> None:
|
||||
self.repo.write("docs/design/2026-08-11-x-design.md", head() + "[옛](gone.md)\n")
|
||||
self.assertEqual(self.repo.run(("link",)), [])
|
||||
|
||||
|
||||
class CommandLineTest(unittest.TestCase):
|
||||
def test_an_unknown_check_is_a_usage_error(self) -> None:
|
||||
self.assertEqual(check_docs.main(["--only", "spelling"]), 2)
|
||||
|
||||
+1
-1
@@ -1,7 +1,7 @@
|
||||
# src — 빌드 스크립트 / 환경 변수 참조
|
||||
|
||||
`src/` 는 Gradle 멀티모듈 루트다. 모듈 경계·의존 방향 규칙은 루트 [CLAUDE.md](../CLAUDE.md)
|
||||
와 [AGENTS.md](../AGENTS.md), 모듈별 규칙은 각 모듈의 `CLAUDE.md` 가 SSOT이다.
|
||||
와 [AGENTS.md](../AGENTS.md), 모듈별 규칙은 각 모듈의 `AGENTS.md` 가 SSOT이다.
|
||||
|
||||
이 문서는 [build.gradle](build.gradle) 과 [.env.example](.env.example)(복사해 `.env` 로 씀) 의 코드 주석에서 덜어낸 **설정 항목 설명과
|
||||
결정 근거**를 모아둔 참조용 기록이다. 두 파일에는 짧은 기능 주석과 "자세한 내용은 README 참조"
|
||||
|
||||
@@ -0,0 +1,218 @@
|
||||
# adapter:inbound:graphql — inbound GraphQL 어댑터(골격 장치)
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-inbound-graphql`
|
||||
- Gradle 경로: `:adapter:inbound:graphql`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:graphql:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
Package root: `dev.caskeleton.adapter.inbound.graphql`.
|
||||
|
||||
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈
|
||||
규칙 SSOT).
|
||||
|
||||
## 플랫폼 모듈 = sub-package (Gradle 모듈 아님)
|
||||
|
||||
GraphQL 플랫폼 설계서는 Stable 16개 + Advanced 12개 "모듈"을 말하지만, 이 구현은 그 28개를 이
|
||||
leaf 안의 **bounded sub-package** 로 매핑한다(선례: httpclient leaf 가 366개 java 파일을 같은
|
||||
방식으로 담는다). GraphQL 표면은 하나의 인바운드 전송 경계이고, 그 내부 분할을 leaf 정체성
|
||||
SSOT(`src/config/architecture/modules.json`)까지 밀어올리지 않는다는 선택이다.
|
||||
|
||||
**이는 레지스트리가 닫혀 있어서가 아니다.** `modules.json` 은 확장 가능하며, 실제로 자매
|
||||
플랫폼인 messaging 은 **정반대 선택**을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 개수는
|
||||
`modules.json` 이 소유하며 여기서 되풀이하지 않는다 — 산문에 적힌 숫자는 leaf 가 하나 추가되는 순간
|
||||
낡는다. 즉 이 레포에는 두 패턴이 공존한다:
|
||||
|
||||
| | 방식 | 경계 강제 |
|
||||
| --- | --- | --- |
|
||||
| messaging | 레지스트리에 leaf 등록 | Gradle 의존 게이트 |
|
||||
| graphql | 단일 leaf 내 sub-package | 아래 ArchUnit 테스트 (전송 경계만) |
|
||||
|
||||
어느 쪽으로 통일할지는 **미결 아키텍처 결정**이다.
|
||||
|
||||
sub-package 사이의 경계(Stable↔Advanced 방향, 모듈 레코드)를 값으로 선언하던 `moduleboundary/`
|
||||
모델과 부팅 때마다 컨트롤러를 리플렉션으로 검사하던 `architecture/` 는 2026-09-25 에 삭제했다
|
||||
(`docs/capability-status.md` 제거 표). 지금 기계가 지키는 것은 전송 경계 두 가지뿐이다 —
|
||||
`GraphQlTransportBoundaryArchitectureTest`(ArchUnit, 이 leaf 패키지 대상):
|
||||
|
||||
- resolver(`@SchemaMapping` 계열·`@BatchMapping`) 시그니처는 전송 타입만 쓴다. 반환·인자 타입과
|
||||
그 제네릭 인자에 raw `Map`, persistence 매핑 타입(`@Entity`/`@Document`/`@Table` 등, 단순명
|
||||
매칭), domain·outbound adapter·JPA/Hibernate/Spring Data/JDBC/Mongo/AWS/gRPC/Kafka 타입이
|
||||
오면 실패한다.
|
||||
- raw `DataFetcher` 구현은 `scalar`·`schema`·`execution` 패키지에만 둔다.
|
||||
|
||||
두 규칙 모두 위반 fixture 로 실제로 잡히는지 같은 테스트가 확인한다. `graphqlStableTest` 의
|
||||
required-class 검사가 이 테스트가 조용히 사라지는 것을 막는다.
|
||||
|
||||
## 책임
|
||||
|
||||
- GraphQL 전송 인프라만: 최소 health 스키마(`skeleton.graphqls`) + `HealthGraphqlController`,
|
||||
프로토콜 에러 매핑(`error/GraphQlWireErrorMapper`). Spring for GraphQL 이 스키마와 컨트롤러를
|
||||
자동 합성/바인딩하도록 얹는 얇은 계층이다.
|
||||
- 그 위에 **GraphQL API 실행 플랫폼**(`...graphql` 하위 sub-package 군)이 스키마 계약·전송
|
||||
프로파일·실행 정책·비용 한계·DataLoader·페이지네이션·에러/보안 경계·관측을
|
||||
소유한다. 플랫폼은 여전히 **feature-agnostic** 이며 정책·계약·검증 기계만 제공한다.
|
||||
- feature-agnostic: `classpath:graphql/**` 스키마와 모든 `@Controller` `@QueryMapping`/
|
||||
`@MutationMapping` 을 generic 하게 합성한다. **WorkLog 등 구체 기능을 이름으로 알지 않는다.**
|
||||
- 있으면 켜진다: 서비스가 `app-bootstrap/build.gradle`에 `runtimeOnly project(':adapter:inbound:graphql')`
|
||||
한 줄로 고른다(기본 조립에는 없다). `APP_GRAPHQL_ENABLED=false`(`app.graphql.enabled`)만 끄며,
|
||||
그때 `GraphQlActivationEnvironmentPostProcessor`가 Spring GraphQL 자동 설정도 exclude 한다.
|
||||
실제 활성화 시 composition root 는 인증/인가·CORS 정책과 GraphiQL/introspection 운영 설정을 함께
|
||||
명시해야 한다.
|
||||
|
||||
## 오류 코드 소유
|
||||
|
||||
`docs/registries/error-codes.yaml`은 골격 전체의 `OperationalError` 정본이다. 전송 계층마다 다른 표현
|
||||
코드를 모두 받는 registry가 아니다. 그래서 GraphQL은 자기의 유한한 플랫폼 wire 코드 catalog를
|
||||
`GraphQlErrorCode`에 둔다.
|
||||
|
||||
- GraphQL 플랫폼 mapper는 `GraphQlErrorCode.platform(...)`을 써야 한다. 등록되지 않은 플랫폼 코드는 바로
|
||||
실패한다.
|
||||
- application·domain `ApiErrorCode` 값은 별도 namespace로 남고 `GraphQlErrorCode.of(...)`로 그대로 지나간다.
|
||||
GraphQL은 제품 오류의 이름을 바꾸면 안 된다. 이 길로 wire에 닿는 것은 등록된 `ApiErrorCode`뿐이다 —
|
||||
DataLoader의 키별 실패도 그것을 싣고, 자유 문자열을 싣지 않는다(소유자 결정 2026-09-25).
|
||||
- GraphQL이 가진 새 플랫폼 코드는 `GRAPHQL_` 접두어를 쓴다. 접두어 없는 기존 플랫폼 값은 얼려 둔 옛 wire
|
||||
계약이고 `legacyUnprefixedPlatformCodes()`가 하나씩 적는다.
|
||||
- 모델만 있는 capability 코드는 그 capability가 출하하는 요청 경로에 닿기 전까지 `platformCodes()`에
|
||||
더하지 않는다.
|
||||
|
||||
`GraphQlErrorCodeCatalogTest`가 출하하는 catalog 전체, 접두어 규칙, application·플랫폼 namespace 분리를
|
||||
고정한다.
|
||||
|
||||
## 허용
|
||||
|
||||
- `:application-core`, `:domain-core`, `:shared-contract`. `:application-core` 는 선언만이 아니라 실제
|
||||
의존이다 — object 인가의 **답하는 계약**(`dev.caskeleton.application.security.ObjectAccessPolicy`)이
|
||||
거기 살기 때문이다. 이 leaf 가 그 계약을 소유했다면 application 구현체가 인바운드 전송을 컴파일
|
||||
의존해야 했고, 그건 의존 방향이 뒤집힌다.
|
||||
- `spring-boot-starter-graphql` (Spring Boot BOM 관리 — 버전 명시 없음).
|
||||
- test scope 에 한해 `spring-boot-starter-web`(random-port 전송 테스트용),
|
||||
`spring-boot-starter-security`(HTTP 인증/CORS qualification 용),
|
||||
`io.micrometer:micrometer-core`(실제 `MeterRegistry` 로 metric label cardinality 를 **측정**).
|
||||
- `java-test-fixtures` — 계약 스위트·통합 fixture·in-memory 스텁은 `src/testFixtures/java` 가
|
||||
소유하고 production jar 에 들어가지 않는다.
|
||||
- test scope 에 한해 `archunit-junit5` — 전송 경계 규칙(`GraphQlTransportBoundaryArchitectureTest`).
|
||||
|
||||
**서버는 이 leaf 가 고르지 않는다.** production 파일 중 `org.springframework.web`·
|
||||
`org.springframework.http` 을 import 하는 것은 **하나도 없다**(servlet API 는 body 상한 필터만
|
||||
`compileOnly` 로 쓴다). 서버 선택은 composition root 의 결정이고, `gradle.lockfile` 이 이를
|
||||
고정한다(`spring-boot-starter-web`·`spring-webmvc`·`spring-webflux`·`tomcat-embed-*` 전부
|
||||
`testCompileClasspath,testRuntimeClasspath` 만). 템플릿은 servlet 단일 스택이라 실행
|
||||
프로파일(`execution-profile`)·reactive 런타임 감지·blocking bridge 는 2026-09-25 에 삭제했다.
|
||||
- `annotationProcessor` 로 `spring-boot-configuration-processor` — `GraphQlPlatformProperties` 가
|
||||
`@ConfigurationProperties` 이므로 `ca.spring-config` convention plugin이 주는 패리티
|
||||
게이트가 이 선언을 요구한다.
|
||||
|
||||
## 금지
|
||||
|
||||
- outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드
|
||||
포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit
|
||||
`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`, 일반 `..adapter.inbound..` 규칙이 이
|
||||
모듈을 자동 커버 — per-module 규칙 추가 불필요).
|
||||
- 프로덕션 feature 쿼리/뮤테이션을 스켈레톤에 두는 것 — health 표면만 (web 의
|
||||
`HealthcheckController` 와 동일 원칙). feature 스키마/컨트롤러/매퍼는 그 기능을 가진 서비스가 소유한다.
|
||||
- 모듈별 `yml` — 설정은 프레임워크 `spring.graphql.*` 로 composition-root `application.yml` 에 산다.
|
||||
|
||||
## 오류 대응 (`Category → ErrorType`)
|
||||
|
||||
모든 client 에러는 `error/GraphQlWireErrorMapper` 하나를 거친다 — 전송 interceptor, 실행 전
|
||||
pipeline(instrumentation), data fetcher resolver 세 곳이 같은 bean 을 받는다. 순서는 플랫폼 거부
|
||||
(예외가 구현한 `error/GraphQlPlatformRejection`) → 실패 자신이 `ApiErrorCarrier`면 그 `ApiErrorCode` → 등록된
|
||||
application 매핑(`GraphQlExceptionResolver`) → 원인 사슬의 첫 carrier → `IllegalArgumentException`·인자 binder의
|
||||
`BindException`=`BAD_PARAMETER`(2026-11-07 소유자 결정). 등록 매핑이 원인 사슬의 carrier보다 먼저라, 앱이 등록한
|
||||
실패는 하위 실패를 원인으로 들어도 등록한 코드로 답한다. 실패 자신이 carrier인 타입은 등록해도 쓰이지 않는다. 어디에도 안
|
||||
걸린 예외는 `INTERNAL_ERROR` 로 가려지고, 같은 executionId 로 ERROR 로그 한 줄이 남는다. client 문구는
|
||||
shared-contract `ClientErrorMessages`(Category 별 한국어 표), `retryable` 은 코드의 값이다. Category →
|
||||
wire category/`ErrorType` 표는 mapper 의 `RENDERINGS` 하나뿐이고 [README.md](README.md)에 옮겨 둔다.
|
||||
DataLoader 키 실패는 등록된 `ApiErrorCode` 만 싣는다(`GraphQlBatchLoadException`, 2026-09-25 소유자 결정).
|
||||
|
||||
## 향후 adopter 의 feature 기여 방법
|
||||
|
||||
- **스키마**: adopter feature 가 `src/main/resources/graphql/*.graphqls` 를 두면
|
||||
`classpath:graphql/**` 병합으로 합칠 수 있다.
|
||||
- **핸들러**: adopter 가 `@Controller` + `@QueryMapping`/`@MutationMapping` 빈을 등록하면 자동
|
||||
바인딩된다.
|
||||
- **도메인 예외 매핑**: adopter 는 자신의 `DataFetcherExceptionResolver` 를 추가하거나
|
||||
`ApiErrorCarrier` 를 사용해 안정적 코드로 매핑할 수 있다.
|
||||
|
||||
템플릿에는 feature GraphQL schema/controller/resolver 가 없다. 이 leaf 는
|
||||
health 스키마만 소유한다.
|
||||
|
||||
## 구현된 플랫폼 범위 — 등급으로 말한다
|
||||
|
||||
"구현됐다" 는 네 가지 서로 다른 사실을 한 단어로 덮는다. 그래서 capability 마다 아래 등급을
|
||||
쓰고, **현재 등급보다 높게 표현하지 않는다.**
|
||||
|
||||
| 등급 | 의미 |
|
||||
| --- | --- |
|
||||
| `modelled` | 정책·계약 객체가 있고 단위 테스트가 있다. 요청 경로에는 없다. |
|
||||
| `wired` | Spring 실행 경로에 연결돼 있고, 실제 endpoint 테스트가 그 사실을 증명한다. |
|
||||
| `integration-verified` | 실제 외부 시스템(datastore/broker) 과의 통합 증거가 있다. |
|
||||
| `production-verified` | 실부하·장애 시나리오 증거가 있다. |
|
||||
|
||||
| Capability | 등급 | 증거 |
|
||||
| --- | --- | --- |
|
||||
| 실행 파이프라인 / 인가 / cost 예산 | `wired` | `systemTest/runtime/GraphQlPlatformExecutionPathTest` (random-port, 거부 시 resolver 호출 0회) |
|
||||
| depth/complexity 제한 (`cost/`) | `wired` | 같은 테스트의 depth/alias/complexity 케이스 |
|
||||
| preparsed document cache (`execution/`) | `wired` | `GraphQlPreparsedDocumentAdapter` + 같은 테스트의 캐시 hit 케이스 |
|
||||
| 커스텀 scalar (`scalar/`) | `wired` | 같은 테스트의 scalar coercion 케이스 |
|
||||
| 요청 크기 (`http/`, body limit filter) | `wired` | `runtime/GraphQlPlatformWebInterceptorRequestBoundsTest`(auto-configured interceptor 로 byte·shape·extension 거부), `http/GraphQlRequestBoundsTest` |
|
||||
| 관측 tag cardinality (`observation/`) | `wired` | `runtime/GraphQlRequestObservationConventionAdapter` 가 Spring 의 `ExecutionRequestObservationConvention` 을 구현해 Boot 의 `GraphQlObservationAutoConfiguration` 이 이 컨벤션을 가져간다. `autoconfigure/GraphQlObservationWiringTest`(프레임워크가 실제로 해석), `runtime/GraphQlRequestObservationConventionAdapterTest`(실제 `MeterRegistry` 에 임의 이름 10,000개 → series 1개) |
|
||||
| object 인가 (`security/`) | `modelled` | 답하는 계약은 중립 `dev.caskeleton.application.security.ObjectAccessPolicy` 가 소유하고 이 leaf 는 `ApplicationObjectAuthorization` 매핑만 가진다. 실행 경로에 연결하는 configuration 은 없다 |
|
||||
| DataLoader/batching (`dataloader/`) | `wired` | `runtime/GraphQlBatchLoaderRegistrationTest` (실제 graphql-java 실행 + Spring `BatchLoaderRegistry`, 50 parent → 3 downstream 호출), `dataloader/GraphQlBatchContractTest` |
|
||||
| 요청 deadline (`maxExecutionTime`) | `wired` | `systemTest/runtime/GraphQlRequestDeadlineTest`(virtual thread: deadline 근처 `REQUEST_TIMEOUT`, 하위 필드 미실행), `GraphQlRequestDeadlineOnRequestThreadTest`(요청 스레드: 느린 resolver 가 끝난 뒤 응답 — 한계). 이미 도는 resolver 는 끊지 않는다(README 「요청 deadline」) |
|
||||
| per-parent fetch(N+1) 신호 | `wired` | `systemTest/runtime/GraphQlPerParentFetchTest`(일반 `@SchemaMapping` 자식 → WARN 1줄 + `graphql.per.parent.fetch`, registrar 자식 → 조용함). 거부하지 않는다 |
|
||||
| cursor 서명·connection (`pagination/`), fetch profile (`fetch/`) | 라이브러리 | 요청 경로에 없다. 서비스가 직접 호출한다 — README "라이브러리 API". `autoconfigure/GraphQlPolicyRequestPathTest` 가 auto-configuration 이 codec·key ring 을 만들지 않음을 고정 |
|
||||
| 실부하·장애 | 미달성 | 증거 없음 |
|
||||
|
||||
여전히 미구현인 것:
|
||||
|
||||
- feature GraphQL schema/resolver — 이 leaf 는 health 표면만 소유한다(변경 없음).
|
||||
- 실부하 성능/장애 시나리오 증거 — 없다. 시나리오 카탈로그와 릴리스 게이트(`release/`,
|
||||
`advanced/release/`)와 스키마 호환성 비교기(`compat/`)는 호출하는 곳이 없어 2026-09-25 에
|
||||
삭제했다.
|
||||
- 실제 datastore 통합 증거 — 없다.
|
||||
- `advanced/**`(SSE·RSocket·federation·incremental·HTTP GET·persisted operation·subscription
|
||||
replay 등)는 바인딩되지 않는 feature flag gate 뒤의 모델뿐이어서 2026-09-25 에 삭제했다
|
||||
(`docs/capability-status.md` 제거 표). 다시 필요하면 Spring GraphQL/graphql-java SPI 를 구현하는
|
||||
형태로 새로 만든다.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:inbound:graphql:test --console=plain
|
||||
./gradlew :adapter:inbound:graphql:graphqlTransportQualificationTest --console=plain
|
||||
```
|
||||
|
||||
테스트 레인:
|
||||
|
||||
```bash
|
||||
./gradlew :adapter:inbound:graphql:graphqlStableTest --console=plain # GraphQlTransportBoundaryArchitectureTest만, skip 금지
|
||||
./gradlew :adapter:inbound:graphql:systemTest --console=plain # 23 tests (실제 HTTP 서버)
|
||||
```
|
||||
|
||||
`graphqlStableTest` 는 `GraphQlTransportBoundaryArchitectureTest` 가 실행되지 않거나 skip 되면
|
||||
실패한다(`build.gradle` 의 strict lane `requires` + `rejectSkipped`). 같은 클래스는 `test` 에서도 돈다.
|
||||
|
||||
## 아티팩트 게이트
|
||||
|
||||
```bash
|
||||
./gradlew :adapter:inbound:graphql:test --tests '*GraphQlProductionClassesTest' --console=plain
|
||||
./gradlew :adapter:inbound:graphql:verifyGraphQlApiSurface --console=plain
|
||||
```
|
||||
|
||||
- `GraphQlProductionClassesTest` — production 클래스에 `testkit`/`InMemory`/`ForTests`/`Fixture`/
|
||||
`TestContext` 가 하나라도 있으면 실패한다(`test` 의 일부). 테스트용 request context 헬퍼(`testkit/GraphQlRequestContexts`)는
|
||||
`src/testFixtures/java` 가 소유한다.
|
||||
- `verifyGraphQlApiSurface` — `docs/architecture/graphql-api-surface.txt` 스냅샷과 실제 public
|
||||
타입 목록이 다르면 실패한다. 단일 jar 안에서 `public` 은 모든 adopter 에게 public 이므로,
|
||||
표면 증가는 리뷰 결정이지 빌드 부산물이 아니다. 승인 후:
|
||||
`./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange`.
|
||||
|
||||
- mutation 멱등성 — 저장소에 연결된 적 없는 `GraphQlMutationIdempotencyInterceptor`·context·
|
||||
fingerprint 와 `idempotencyKey` extension 허용을 2026-09-25 에 삭제했다. Stable 기본
|
||||
`GraphQlExtensionsPolicy` 는 어떤 extension key 도 허용하지 않는다. 요청 재생 멱등성이 필요하면
|
||||
application `IdempotencyExecutor` 를 use case 안에서 쓴다.
|
||||
@@ -1,218 +1 @@
|
||||
# adapter:inbound:graphql — inbound GraphQL 어댑터(골격 장치)
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-inbound-graphql`
|
||||
- Gradle 경로: `:adapter:inbound:graphql`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:graphql:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
Package root: `dev.caskeleton.adapter.inbound.graphql`.
|
||||
|
||||
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈
|
||||
규칙 SSOT).
|
||||
|
||||
## 플랫폼 모듈 = sub-package (Gradle 모듈 아님)
|
||||
|
||||
GraphQL 플랫폼 설계서는 Stable 16개 + Advanced 12개 "모듈"을 말하지만, 이 구현은 그 28개를 이
|
||||
leaf 안의 **bounded sub-package** 로 매핑한다(선례: httpclient leaf 가 366개 java 파일을 같은
|
||||
방식으로 담는다). GraphQL 표면은 하나의 인바운드 전송 경계이고, 그 내부 분할을 leaf 정체성
|
||||
SSOT(`src/config/architecture/modules.json`)까지 밀어올리지 않는다는 선택이다.
|
||||
|
||||
**이는 레지스트리가 닫혀 있어서가 아니다.** `modules.json` 은 확장 가능하며, 실제로 자매
|
||||
플랫폼인 messaging 은 **정반대 선택**을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 개수는
|
||||
`modules.json` 이 소유하며 여기서 되풀이하지 않는다 — 산문에 적힌 숫자는 leaf 가 하나 추가되는 순간
|
||||
낡는다. 즉 이 레포에는 두 패턴이 공존한다:
|
||||
|
||||
| | 방식 | 경계 강제 |
|
||||
| --- | --- | --- |
|
||||
| messaging | 레지스트리에 leaf 등록 | Gradle 의존 게이트 |
|
||||
| graphql | 단일 leaf 내 sub-package | 아래 ArchUnit 테스트 (전송 경계만) |
|
||||
|
||||
어느 쪽으로 통일할지는 **미결 아키텍처 결정**이다.
|
||||
|
||||
sub-package 사이의 경계(Stable↔Advanced 방향, 모듈 레코드)를 값으로 선언하던 `moduleboundary/`
|
||||
모델과 부팅 때마다 컨트롤러를 리플렉션으로 검사하던 `architecture/` 는 2026-09-25 에 삭제했다
|
||||
(`docs/capability-status.md` 제거 표). 지금 기계가 지키는 것은 전송 경계 두 가지뿐이다 —
|
||||
`GraphQlTransportBoundaryArchitectureTest`(ArchUnit, 이 leaf 패키지 대상):
|
||||
|
||||
- resolver(`@SchemaMapping` 계열·`@BatchMapping`) 시그니처는 전송 타입만 쓴다. 반환·인자 타입과
|
||||
그 제네릭 인자에 raw `Map`, persistence 매핑 타입(`@Entity`/`@Document`/`@Table` 등, 단순명
|
||||
매칭), domain·outbound adapter·JPA/Hibernate/Spring Data/JDBC/Mongo/AWS/gRPC/Kafka 타입이
|
||||
오면 실패한다.
|
||||
- raw `DataFetcher` 구현은 `scalar`·`schema`·`execution` 패키지에만 둔다.
|
||||
|
||||
두 규칙 모두 위반 fixture 로 실제로 잡히는지 같은 테스트가 확인한다. `graphqlStableTest` 의
|
||||
required-class 검사가 이 테스트가 조용히 사라지는 것을 막는다.
|
||||
|
||||
## 책임
|
||||
|
||||
- GraphQL 전송 인프라만: 최소 health 스키마(`skeleton.graphqls`) + `HealthGraphqlController`,
|
||||
프로토콜 에러 매핑(`error/GraphQlWireErrorMapper`). Spring for GraphQL 이 스키마와 컨트롤러를
|
||||
자동 합성/바인딩하도록 얹는 얇은 계층이다.
|
||||
- 그 위에 **GraphQL API 실행 플랫폼**(`...graphql` 하위 sub-package 군)이 스키마 계약·전송
|
||||
프로파일·실행 정책·비용 한계·DataLoader·페이지네이션·에러/보안 경계·관측을
|
||||
소유한다. 플랫폼은 여전히 **feature-agnostic** 이며 정책·계약·검증 기계만 제공한다.
|
||||
- feature-agnostic: `classpath:graphql/**` 스키마와 모든 `@Controller` `@QueryMapping`/
|
||||
`@MutationMapping` 을 generic 하게 합성한다. **WorkLog 등 구체 기능을 이름으로 알지 않는다.**
|
||||
- 있으면 켜진다: 서비스가 `app-bootstrap/build.gradle`에 `runtimeOnly project(':adapter:inbound:graphql')`
|
||||
한 줄로 고른다(기본 조립에는 없다). `APP_GRAPHQL_ENABLED=false`(`app.graphql.enabled`)만 끄며,
|
||||
그때 `GraphQlActivationEnvironmentPostProcessor`가 Spring GraphQL 자동 설정도 exclude 한다.
|
||||
실제 활성화 시 composition root 는 인증/인가·CORS 정책과 GraphiQL/introspection 운영 설정을 함께
|
||||
명시해야 한다.
|
||||
|
||||
## 오류 코드 소유
|
||||
|
||||
`docs/registries/error-codes.yaml`은 골격 전체의 `OperationalError` 정본이다. 전송 계층마다 다른 표현
|
||||
코드를 모두 받는 registry가 아니다. 그래서 GraphQL은 자기의 유한한 플랫폼 wire 코드 catalog를
|
||||
`GraphQlErrorCode`에 둔다.
|
||||
|
||||
- GraphQL 플랫폼 mapper는 `GraphQlErrorCode.platform(...)`을 써야 한다. 등록되지 않은 플랫폼 코드는 바로
|
||||
실패한다.
|
||||
- application·domain `ApiErrorCode` 값은 별도 namespace로 남고 `GraphQlErrorCode.of(...)`로 그대로 지나간다.
|
||||
GraphQL은 제품 오류의 이름을 바꾸면 안 된다. 이 길로 wire에 닿는 것은 등록된 `ApiErrorCode`뿐이다 —
|
||||
DataLoader의 키별 실패도 그것을 싣고, 자유 문자열을 싣지 않는다(소유자 결정 2026-09-25).
|
||||
- GraphQL이 가진 새 플랫폼 코드는 `GRAPHQL_` 접두어를 쓴다. 접두어 없는 기존 플랫폼 값은 얼려 둔 옛 wire
|
||||
계약이고 `legacyUnprefixedPlatformCodes()`가 하나씩 적는다.
|
||||
- 모델만 있는 capability 코드는 그 capability가 출하하는 요청 경로에 닿기 전까지 `platformCodes()`에
|
||||
더하지 않는다.
|
||||
|
||||
`GraphQlErrorCodeCatalogTest`가 출하하는 catalog 전체, 접두어 규칙, application·플랫폼 namespace 분리를
|
||||
고정한다.
|
||||
|
||||
## 허용
|
||||
|
||||
- `:application-core`, `:domain-core`, `:shared-contract`. `:application-core` 는 선언만이 아니라 실제
|
||||
의존이다 — object 인가의 **답하는 계약**(`dev.caskeleton.application.security.ObjectAccessPolicy`)이
|
||||
거기 살기 때문이다. 이 leaf 가 그 계약을 소유했다면 application 구현체가 인바운드 전송을 컴파일
|
||||
의존해야 했고, 그건 의존 방향이 뒤집힌다.
|
||||
- `spring-boot-starter-graphql` (Spring Boot BOM 관리 — 버전 명시 없음).
|
||||
- test scope 에 한해 `spring-boot-starter-web`(random-port 전송 테스트용),
|
||||
`spring-boot-starter-security`(HTTP 인증/CORS qualification 용),
|
||||
`io.micrometer:micrometer-core`(실제 `MeterRegistry` 로 metric label cardinality 를 **측정**).
|
||||
- `java-test-fixtures` — 계약 스위트·통합 fixture·in-memory 스텁은 `src/testFixtures/java` 가
|
||||
소유하고 production jar 에 들어가지 않는다.
|
||||
- test scope 에 한해 `archunit-junit5` — 전송 경계 규칙(`GraphQlTransportBoundaryArchitectureTest`).
|
||||
|
||||
**서버는 이 leaf 가 고르지 않는다.** production 파일 중 `org.springframework.web`·
|
||||
`org.springframework.http` 을 import 하는 것은 **하나도 없다**(servlet API 는 body 상한 필터만
|
||||
`compileOnly` 로 쓴다). 서버 선택은 composition root 의 결정이고, `gradle.lockfile` 이 이를
|
||||
고정한다(`spring-boot-starter-web`·`spring-webmvc`·`spring-webflux`·`tomcat-embed-*` 전부
|
||||
`testCompileClasspath,testRuntimeClasspath` 만). 템플릿은 servlet 단일 스택이라 실행
|
||||
프로파일(`execution-profile`)·reactive 런타임 감지·blocking bridge 는 2026-09-25 에 삭제했다.
|
||||
- `annotationProcessor` 로 `spring-boot-configuration-processor` — `GraphQlPlatformProperties` 가
|
||||
`@ConfigurationProperties` 이므로 `ca.spring-config` convention plugin이 주는 패리티
|
||||
게이트가 이 선언을 요구한다.
|
||||
|
||||
## 금지
|
||||
|
||||
- outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드
|
||||
포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit
|
||||
`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`, 일반 `..adapter.inbound..` 규칙이 이
|
||||
모듈을 자동 커버 — per-module 규칙 추가 불필요).
|
||||
- 프로덕션 feature 쿼리/뮤테이션을 스켈레톤에 두는 것 — health 표면만 (web 의
|
||||
`HealthcheckController` 와 동일 원칙). feature 스키마/컨트롤러/매퍼는 그 기능을 가진 서비스가 소유한다.
|
||||
- 모듈별 `yml` — 설정은 프레임워크 `spring.graphql.*` 로 composition-root `application.yml` 에 산다.
|
||||
|
||||
## 오류 대응 (`Category → ErrorType`)
|
||||
|
||||
모든 client 에러는 `error/GraphQlWireErrorMapper` 하나를 거친다 — 전송 interceptor, 실행 전
|
||||
pipeline(instrumentation), data fetcher resolver 세 곳이 같은 bean 을 받는다. 순서는 플랫폼 거부
|
||||
(예외가 구현한 `error/GraphQlPlatformRejection`) → 실패 자신이 `ApiErrorCarrier`면 그 `ApiErrorCode` → 등록된
|
||||
application 매핑(`GraphQlExceptionResolver`) → 원인 사슬의 첫 carrier → `IllegalArgumentException`·인자 binder의
|
||||
`BindException`=`BAD_PARAMETER`(2026-11-07 소유자 결정). 등록 매핑이 원인 사슬의 carrier보다 먼저라, 앱이 등록한
|
||||
실패는 하위 실패를 원인으로 들어도 등록한 코드로 답한다. 실패 자신이 carrier인 타입은 등록해도 쓰이지 않는다. 어디에도 안
|
||||
걸린 예외는 `INTERNAL_ERROR` 로 가려지고, 같은 executionId 로 ERROR 로그 한 줄이 남는다. client 문구는
|
||||
shared-contract `ClientErrorMessages`(Category 별 한국어 표), `retryable` 은 코드의 값이다. Category →
|
||||
wire category/`ErrorType` 표는 mapper 의 `RENDERINGS` 하나뿐이고 [README.md](README.md)에 옮겨 둔다.
|
||||
DataLoader 키 실패는 등록된 `ApiErrorCode` 만 싣는다(`GraphQlBatchLoadException`, 2026-09-25 소유자 결정).
|
||||
|
||||
## 향후 adopter 의 feature 기여 방법
|
||||
|
||||
- **스키마**: adopter feature 가 `src/main/resources/graphql/*.graphqls` 를 두면
|
||||
`classpath:graphql/**` 병합으로 합칠 수 있다.
|
||||
- **핸들러**: adopter 가 `@Controller` + `@QueryMapping`/`@MutationMapping` 빈을 등록하면 자동
|
||||
바인딩된다.
|
||||
- **도메인 예외 매핑**: adopter 는 자신의 `DataFetcherExceptionResolver` 를 추가하거나
|
||||
`ApiErrorCarrier` 를 사용해 안정적 코드로 매핑할 수 있다.
|
||||
|
||||
템플릿에는 feature GraphQL schema/controller/resolver 가 없다. 이 leaf 는
|
||||
health 스키마만 소유한다.
|
||||
|
||||
## 구현된 플랫폼 범위 — 등급으로 말한다
|
||||
|
||||
"구현됐다" 는 네 가지 서로 다른 사실을 한 단어로 덮는다. 그래서 capability 마다 아래 등급을
|
||||
쓰고, **현재 등급보다 높게 표현하지 않는다.**
|
||||
|
||||
| 등급 | 의미 |
|
||||
| --- | --- |
|
||||
| `modelled` | 정책·계약 객체가 있고 단위 테스트가 있다. 요청 경로에는 없다. |
|
||||
| `wired` | Spring 실행 경로에 연결돼 있고, 실제 endpoint 테스트가 그 사실을 증명한다. |
|
||||
| `integration-verified` | 실제 외부 시스템(datastore/broker) 과의 통합 증거가 있다. |
|
||||
| `production-verified` | 실부하·장애 시나리오 증거가 있다. |
|
||||
|
||||
| Capability | 등급 | 증거 |
|
||||
| --- | --- | --- |
|
||||
| 실행 파이프라인 / 인가 / cost 예산 | `wired` | `systemTest/runtime/GraphQlPlatformExecutionPathTest` (random-port, 거부 시 resolver 호출 0회) |
|
||||
| depth/complexity 제한 (`cost/`) | `wired` | 같은 테스트의 depth/alias/complexity 케이스 |
|
||||
| preparsed document cache (`execution/`) | `wired` | `GraphQlPreparsedDocumentAdapter` + 같은 테스트의 캐시 hit 케이스 |
|
||||
| 커스텀 scalar (`scalar/`) | `wired` | 같은 테스트의 scalar coercion 케이스 |
|
||||
| 요청 크기 (`http/`, body limit filter) | `wired` | `runtime/GraphQlPlatformWebInterceptorRequestBoundsTest`(auto-configured interceptor 로 byte·shape·extension 거부), `http/GraphQlRequestBoundsTest` |
|
||||
| 관측 tag cardinality (`observation/`) | `wired` | `runtime/GraphQlRequestObservationConventionAdapter` 가 Spring 의 `ExecutionRequestObservationConvention` 을 구현해 Boot 의 `GraphQlObservationAutoConfiguration` 이 이 컨벤션을 가져간다. `autoconfigure/GraphQlObservationWiringTest`(프레임워크가 실제로 해석), `runtime/GraphQlRequestObservationConventionAdapterTest`(실제 `MeterRegistry` 에 임의 이름 10,000개 → series 1개) |
|
||||
| object 인가 (`security/`) | `modelled` | 답하는 계약은 중립 `dev.caskeleton.application.security.ObjectAccessPolicy` 가 소유하고 이 leaf 는 `ApplicationObjectAuthorization` 매핑만 가진다. 실행 경로에 연결하는 configuration 은 없다 |
|
||||
| DataLoader/batching (`dataloader/`) | `wired` | `runtime/GraphQlBatchLoaderRegistrationTest` (실제 graphql-java 실행 + Spring `BatchLoaderRegistry`, 50 parent → 3 downstream 호출), `dataloader/GraphQlBatchContractTest` |
|
||||
| 요청 deadline (`maxExecutionTime`) | `wired` | `systemTest/runtime/GraphQlRequestDeadlineTest`(virtual thread: deadline 근처 `REQUEST_TIMEOUT`, 하위 필드 미실행), `GraphQlRequestDeadlineOnRequestThreadTest`(요청 스레드: 느린 resolver 가 끝난 뒤 응답 — 한계). 이미 도는 resolver 는 끊지 않는다(README 「요청 deadline」) |
|
||||
| per-parent fetch(N+1) 신호 | `wired` | `systemTest/runtime/GraphQlPerParentFetchTest`(일반 `@SchemaMapping` 자식 → WARN 1줄 + `graphql.per.parent.fetch`, registrar 자식 → 조용함). 거부하지 않는다 |
|
||||
| cursor 서명·connection (`pagination/`), fetch profile (`fetch/`) | 라이브러리 | 요청 경로에 없다. 서비스가 직접 호출한다 — README "라이브러리 API". `autoconfigure/GraphQlPolicyRequestPathTest` 가 auto-configuration 이 codec·key ring 을 만들지 않음을 고정 |
|
||||
| 실부하·장애 | 미달성 | 증거 없음 |
|
||||
|
||||
여전히 미구현인 것:
|
||||
|
||||
- feature GraphQL schema/resolver — 이 leaf 는 health 표면만 소유한다(변경 없음).
|
||||
- 실부하 성능/장애 시나리오 증거 — 없다. 시나리오 카탈로그와 릴리스 게이트(`release/`,
|
||||
`advanced/release/`)와 스키마 호환성 비교기(`compat/`)는 호출하는 곳이 없어 2026-09-25 에
|
||||
삭제했다.
|
||||
- 실제 datastore 통합 증거 — 없다.
|
||||
- `advanced/**`(SSE·RSocket·federation·incremental·HTTP GET·persisted operation·subscription
|
||||
replay 등)는 바인딩되지 않는 feature flag gate 뒤의 모델뿐이어서 2026-09-25 에 삭제했다
|
||||
(`docs/capability-status.md` 제거 표). 다시 필요하면 Spring GraphQL/graphql-java SPI 를 구현하는
|
||||
형태로 새로 만든다.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:inbound:graphql:test --console=plain
|
||||
./gradlew :adapter:inbound:graphql:graphqlTransportQualificationTest --console=plain
|
||||
```
|
||||
|
||||
테스트 레인:
|
||||
|
||||
```bash
|
||||
./gradlew :adapter:inbound:graphql:graphqlStableTest --console=plain # GraphQlTransportBoundaryArchitectureTest만, skip 금지
|
||||
./gradlew :adapter:inbound:graphql:systemTest --console=plain # 23 tests (실제 HTTP 서버)
|
||||
```
|
||||
|
||||
`graphqlStableTest` 는 `GraphQlTransportBoundaryArchitectureTest` 가 실행되지 않거나 skip 되면
|
||||
실패한다(`build.gradle` 의 strict lane `requires` + `rejectSkipped`). 같은 클래스는 `test` 에서도 돈다.
|
||||
|
||||
## 아티팩트 게이트
|
||||
|
||||
```bash
|
||||
./gradlew :adapter:inbound:graphql:test --tests '*GraphQlProductionClassesTest' --console=plain
|
||||
./gradlew :adapter:inbound:graphql:verifyGraphQlApiSurface --console=plain
|
||||
```
|
||||
|
||||
- `GraphQlProductionClassesTest` — production 클래스에 `testkit`/`InMemory`/`ForTests`/`Fixture`/
|
||||
`TestContext` 가 하나라도 있으면 실패한다(`test` 의 일부). 테스트용 request context 헬퍼(`testkit/GraphQlRequestContexts`)는
|
||||
`src/testFixtures/java` 가 소유한다.
|
||||
- `verifyGraphQlApiSurface` — `docs/architecture/graphql-api-surface.txt` 스냅샷과 실제 public
|
||||
타입 목록이 다르면 실패한다. 단일 jar 안에서 `public` 은 모든 adopter 에게 public 이므로,
|
||||
표면 증가는 리뷰 결정이지 빌드 부산물이 아니다. 승인 후:
|
||||
`./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange`.
|
||||
|
||||
- mutation 멱등성 — 저장소에 연결된 적 없는 `GraphQlMutationIdempotencyInterceptor`·context·
|
||||
fingerprint 와 `idempotencyKey` extension 허용을 2026-09-25 에 삭제했다. Stable 기본
|
||||
`GraphQlExtensionsPolicy` 는 어떤 extension key 도 허용하지 않는다. 요청 재생 멱등성이 필요하면
|
||||
application `IdempotencyExecutor` 를 use case 안에서 쓴다.
|
||||
@AGENTS.md
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
`dev.caskeleton.adapter.inbound.graphql`.
|
||||
|
||||
허용/금지 의존, 모듈 규칙, 설정 knob, 테스트 명령 같은 **모듈 규칙**은
|
||||
[CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를
|
||||
[AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를
|
||||
모아둔 참조용 기록이다.
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,115 @@
|
||||
# adapter:inbound:grpc — inbound gRPC 어댑터(골격 장치)
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-inbound-grpc`
|
||||
- Gradle 경로: `:adapter:inbound:grpc`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:grpc:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
Package root: `dev.caskeleton.adapter.inbound.grpc`.
|
||||
|
||||
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈
|
||||
규칙 SSOT).
|
||||
|
||||
## 책임
|
||||
|
||||
- gRPC 전송 인프라만: 서버 수명주기(`GrpcServerRunner`), 타입드 설정(`GrpcServerSettings`),
|
||||
feature 인증 정책 경계, 프로토콜 에러 매핑(`GrpcStatusMapper` +
|
||||
`GrpcExceptionHandlingInterceptor`), 그리고 `.proto` 없이도 부팅하는 최소 표면(standard
|
||||
health, 명시적으로 켠 경우에만 reflection).
|
||||
- feature-agnostic: 모든 `io.grpc.BindableService` 빈을 generic 하게 등록하며 구체 기능을
|
||||
이름으로 알지 않는다.
|
||||
|
||||
## 허용
|
||||
|
||||
- `:application-core`, `:domain-core`, `:shared-contract`.
|
||||
- `io.grpc:*` (grpc-netty-shaded / grpc-protobuf / grpc-stub / grpc-services),
|
||||
`spring-boot-starter`, `spring-boot-starter-validation`.
|
||||
|
||||
## 금지
|
||||
|
||||
- outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드
|
||||
포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit
|
||||
`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`).
|
||||
- 이 스켈레톤 모듈에서의 `com.google.protobuf` 플러그인 / `.proto` — 향후 도입하는 스키마와
|
||||
서비스는 consuming feature 모듈이 소유한다.
|
||||
- 프로덕션 feature RPC 를 스켈레톤에 두는 것 — health/reflection 표면만 (web 의
|
||||
`HealthcheckController` 와 동일 원칙).
|
||||
|
||||
## 설정 손잡이 (`app.grpc.server.*`)
|
||||
|
||||
타입드 `@ConfigurationProperties` 만 두고, 값은 composition-root `application.yml` 에 산다
|
||||
(모듈별 `yml` 없음). prefix가 `app.grpc`가 아니라 `.server`까지인 이유: 바인딩이
|
||||
`ignoreUnknownFields = false`라서, 부모 prefix를 쓰면 벤더 starter의 `app.grpc.platform.*`
|
||||
키가 들어오는 순간 기동이 실패한다(`GrpcSafeActivationTest`).
|
||||
|
||||
| key | default | 의미 |
|
||||
|---|---|---|
|
||||
| `enabled` | `true` | 모듈이 있으면 켜진다. `false`면 관련 빈과 listener가 생기지 않는다 |
|
||||
| `port` | `9090` | 바인딩 TCP 포트. `0` 이면 ephemeral 포트(테스트) |
|
||||
| `bindAddress` | `127.0.0.1` | P1 insecure listener 바인드. loopback 주소만 허용한다 |
|
||||
| `allowInsecureLocal` | `false` | local plaintext 위험을 명시적으로 승인하는 개발용 override |
|
||||
| `reflectionEnabled` | `false` | v1 server reflection 노출을 독립적으로 opt-in 한다 |
|
||||
| `shutdownGraceSeconds` | `5` | graceful shutdown 전체 예산(초, 0 이상). drain 대기를 포함한다 |
|
||||
| `shutdownDrainSeconds` | `2` | health NOT_SERVING 뒤 listener 를 열어 둔 채 기다리는 초. `shutdownGraceSeconds` 이하 |
|
||||
| `maxInboundMessageBytes` | `1048576` | 요청 메시지 상한. 넘으면 `RESOURCE_EXHAUSTED` (플랫폼 `GrpcTransportLimits`와 같은 값) |
|
||||
| `maxInboundMetadataBytes` | `8192` | 호출당 metadata 상한 (플랫폼과 같은 값) |
|
||||
| `maxConcurrentCallsPerConnection` | `100` | 연결당 동시 호출(HTTP/2 stream) 상한. 넘친 호출은 클라이언트에서 기다린다 |
|
||||
| `executorMaxPoolSize` | `32` | feature 호출을 실행하는 고정 스레드 수 (플랫폼 executor 기본값) |
|
||||
| `executorQueueCapacity` | `256` | 스레드를 기다릴 수 있는 호출 수(1..10000). 넘친 호출은 즉시 `RESOURCE_EXHAUSTED` |
|
||||
| `defaultDeadline` | `10s` | deadline 없는(또는 더 긴) feature 호출의 서버 deadline. 넘으면 `DEADLINE_EXCEEDED` |
|
||||
| `keepAliveTime` / `keepAliveTimeout` | `30s` / `10s` | 서버 keep-alive ping 간격 / 응답 대기 (플랫폼 `GrpcServerProfile.stable`) |
|
||||
| `permitKeepAliveTime` | `30s` | 클라이언트 ping 최소 간격. `keepAliveTime` 이하 |
|
||||
| `maxConnectionAge` / `maxConnectionAgeGrace` | `30m` / `30s` | 연결 수명과 GOAWAY 뒤 유예 |
|
||||
|
||||
한도 값의 근거·플랫폼과의 대응·포화 동작은 [README.md](README.md) 「서버 한도」 절이 소유한다.
|
||||
`port`는 0..65535 범위여야 한다. 현재 transport credential은 plaintext뿐이므로
|
||||
`enabled=true`는 `allowInsecureLocal=true`와 실제 loopback `bindAddress`가 함께 없으면
|
||||
configuration binding/startup 단계에서 실패한다.
|
||||
|
||||
## 이 capability 채택하기
|
||||
|
||||
gRPC도 **빌드 조립에서 고르는 것**이다. 기본 bootJar에는 이 leaf가 없다.
|
||||
|
||||
1. 쓰는 조립에 `:adapter:inbound:grpc`를 더하고 `config/architecture/modules.json`에 맞는 허용 의존
|
||||
edge를 더한다.
|
||||
2. 설정은 capability 루트로 등록한다. 출하하는 `@ConfigurationPropertiesScan`에
|
||||
`dev.caskeleton.adapter.inbound.grpc`를 더하지 않는다.
|
||||
3. 기능의 `BindableService`와 정확히 하나의 `GrpcAuthenticationPolicy`를 준다.
|
||||
4. 승격 전에 `./gradlew :adapter:inbound:grpc:test :conditionalTransportQualification`을 돌린다.
|
||||
5. 고른 런타임 계약에 대한 조립 소유의 설정·env registry 항목이 생기기 전에는 운영 채택이 끝난 것이 아니다.
|
||||
|
||||
**지금 전송의 한계:** P1 서버는 평문이고 일부러 loopback bind만 허용한다. 그래서 같은 프로세스나 같은
|
||||
Pod sidecar 통신에만 맞다. 보통 Kubernetes Service를 위해 `0.0.0.0`에 bind할 수 없고, 다른 Pod의 트래픽을
|
||||
받을 수 없으며, 클러스터를 향한 gRPC endpoint로 내세우면 안 된다. 클러스터에 노출하려면 미뤄 둔 TLS/mTLS
|
||||
credential 경로와 따로 검증한 loopback 아닌 bind가 필요하다.
|
||||
|
||||
## Feature 기여 방법
|
||||
|
||||
현재 저장소에는 feature RPC가 없다. 향후 feature를 도입할
|
||||
때는 `.proto`/generated stub/`BindableService`를 해당 feature가 소유하고, 서비스 빈과 정확히 한
|
||||
개의 caller-supplied `GrpcAuthenticationPolicy` 빈을 함께 제공한다. 정책이 없거나 여러 개면
|
||||
listener 시작이 실패한다. 정책은 `Optional<Principal> authenticate(Metadata)`이고, 돌려준
|
||||
호출자는 gRPC `Context`에 담겨 handler가 `GrpcAuthenticatedCaller.current()`로 읽는다. 정책이
|
||||
빈 값·`null`을 반환하거나 예외를 던진 요청은 feature handler에 닿지
|
||||
않고 안정적인 `UNAUTHENTICATED` status/code/category로 종료된다. 정책 예외는 예외 타입과 메서드
|
||||
이름만 WARN으로 남긴다(메시지는 자격 증명을 담을 수 있어 남기지 않는다).
|
||||
|
||||
## P1 증거와 한계
|
||||
|
||||
- `GrpcSafeActivationTest`: 기본 비활성, 관련 빈 부재, 설정 검증, feature 인증 정책 필수 조건.
|
||||
- `GrpcP1BoundaryWireTest`: 실제 loopback ephemeral Netty unary service의 auth 성공/실패,
|
||||
reflection-off, handler/listener/observer/raw-status 오류 sanitization과 sentinel redaction.
|
||||
서버 한도(메시지 크기, 기본 deadline, 연결당 동시 호출, executor 포화)도 같은 wire 에서 검증한다.
|
||||
|
||||
이 증거는 local insecure unary qualification일 뿐 production-ready 근거가 아니다. TLS/mTLS,
|
||||
external bind, 메서드별 deadline, streaming/backpressure, generated protobuf 호환성은 P2로 남아 있다.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:inbound:grpc:test
|
||||
```
|
||||
@@ -1,115 +1 @@
|
||||
# adapter:inbound:grpc — inbound gRPC 어댑터(골격 장치)
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-inbound-grpc`
|
||||
- Gradle 경로: `:adapter:inbound:grpc`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:grpc:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
Package root: `dev.caskeleton.adapter.inbound.grpc`.
|
||||
|
||||
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈
|
||||
규칙 SSOT).
|
||||
|
||||
## 책임
|
||||
|
||||
- gRPC 전송 인프라만: 서버 수명주기(`GrpcServerRunner`), 타입드 설정(`GrpcServerSettings`),
|
||||
feature 인증 정책 경계, 프로토콜 에러 매핑(`GrpcStatusMapper` +
|
||||
`GrpcExceptionHandlingInterceptor`), 그리고 `.proto` 없이도 부팅하는 최소 표면(standard
|
||||
health, 명시적으로 켠 경우에만 reflection).
|
||||
- feature-agnostic: 모든 `io.grpc.BindableService` 빈을 generic 하게 등록하며 구체 기능을
|
||||
이름으로 알지 않는다.
|
||||
|
||||
## 허용
|
||||
|
||||
- `:application-core`, `:domain-core`, `:shared-contract`.
|
||||
- `io.grpc:*` (grpc-netty-shaded / grpc-protobuf / grpc-stub / grpc-services),
|
||||
`spring-boot-starter`, `spring-boot-starter-validation`.
|
||||
|
||||
## 금지
|
||||
|
||||
- outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드
|
||||
포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit
|
||||
`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`).
|
||||
- 이 스켈레톤 모듈에서의 `com.google.protobuf` 플러그인 / `.proto` — 향후 도입하는 스키마와
|
||||
서비스는 consuming feature 모듈이 소유한다.
|
||||
- 프로덕션 feature RPC 를 스켈레톤에 두는 것 — health/reflection 표면만 (web 의
|
||||
`HealthcheckController` 와 동일 원칙).
|
||||
|
||||
## 설정 손잡이 (`app.grpc.server.*`)
|
||||
|
||||
타입드 `@ConfigurationProperties` 만 두고, 값은 composition-root `application.yml` 에 산다
|
||||
(모듈별 `yml` 없음). prefix가 `app.grpc`가 아니라 `.server`까지인 이유: 바인딩이
|
||||
`ignoreUnknownFields = false`라서, 부모 prefix를 쓰면 벤더 starter의 `app.grpc.platform.*`
|
||||
키가 들어오는 순간 기동이 실패한다(`GrpcSafeActivationTest`).
|
||||
|
||||
| key | default | 의미 |
|
||||
|---|---|---|
|
||||
| `enabled` | `true` | 모듈이 있으면 켜진다. `false`면 관련 빈과 listener가 생기지 않는다 |
|
||||
| `port` | `9090` | 바인딩 TCP 포트. `0` 이면 ephemeral 포트(테스트) |
|
||||
| `bindAddress` | `127.0.0.1` | P1 insecure listener 바인드. loopback 주소만 허용한다 |
|
||||
| `allowInsecureLocal` | `false` | local plaintext 위험을 명시적으로 승인하는 개발용 override |
|
||||
| `reflectionEnabled` | `false` | v1 server reflection 노출을 독립적으로 opt-in 한다 |
|
||||
| `shutdownGraceSeconds` | `5` | graceful shutdown 전체 예산(초, 0 이상). drain 대기를 포함한다 |
|
||||
| `shutdownDrainSeconds` | `2` | health NOT_SERVING 뒤 listener 를 열어 둔 채 기다리는 초. `shutdownGraceSeconds` 이하 |
|
||||
| `maxInboundMessageBytes` | `1048576` | 요청 메시지 상한. 넘으면 `RESOURCE_EXHAUSTED` (플랫폼 `GrpcTransportLimits`와 같은 값) |
|
||||
| `maxInboundMetadataBytes` | `8192` | 호출당 metadata 상한 (플랫폼과 같은 값) |
|
||||
| `maxConcurrentCallsPerConnection` | `100` | 연결당 동시 호출(HTTP/2 stream) 상한. 넘친 호출은 클라이언트에서 기다린다 |
|
||||
| `executorMaxPoolSize` | `32` | feature 호출을 실행하는 고정 스레드 수 (플랫폼 executor 기본값) |
|
||||
| `executorQueueCapacity` | `256` | 스레드를 기다릴 수 있는 호출 수(1..10000). 넘친 호출은 즉시 `RESOURCE_EXHAUSTED` |
|
||||
| `defaultDeadline` | `10s` | deadline 없는(또는 더 긴) feature 호출의 서버 deadline. 넘으면 `DEADLINE_EXCEEDED` |
|
||||
| `keepAliveTime` / `keepAliveTimeout` | `30s` / `10s` | 서버 keep-alive ping 간격 / 응답 대기 (플랫폼 `GrpcServerProfile.stable`) |
|
||||
| `permitKeepAliveTime` | `30s` | 클라이언트 ping 최소 간격. `keepAliveTime` 이하 |
|
||||
| `maxConnectionAge` / `maxConnectionAgeGrace` | `30m` / `30s` | 연결 수명과 GOAWAY 뒤 유예 |
|
||||
|
||||
한도 값의 근거·플랫폼과의 대응·포화 동작은 [README.md](README.md) 「서버 한도」 절이 소유한다.
|
||||
`port`는 0..65535 범위여야 한다. 현재 transport credential은 plaintext뿐이므로
|
||||
`enabled=true`는 `allowInsecureLocal=true`와 실제 loopback `bindAddress`가 함께 없으면
|
||||
configuration binding/startup 단계에서 실패한다.
|
||||
|
||||
## 이 capability 채택하기
|
||||
|
||||
gRPC도 **빌드 조립에서 고르는 것**이다. 기본 bootJar에는 이 leaf가 없다.
|
||||
|
||||
1. 쓰는 조립에 `:adapter:inbound:grpc`를 더하고 `config/architecture/modules.json`에 맞는 허용 의존
|
||||
edge를 더한다.
|
||||
2. 설정은 capability 루트로 등록한다. 출하하는 `@ConfigurationPropertiesScan`에
|
||||
`dev.caskeleton.adapter.inbound.grpc`를 더하지 않는다.
|
||||
3. 기능의 `BindableService`와 정확히 하나의 `GrpcAuthenticationPolicy`를 준다.
|
||||
4. 승격 전에 `./gradlew :adapter:inbound:grpc:test :conditionalTransportQualification`을 돌린다.
|
||||
5. 고른 런타임 계약에 대한 조립 소유의 설정·env registry 항목이 생기기 전에는 운영 채택이 끝난 것이 아니다.
|
||||
|
||||
**지금 전송의 한계:** P1 서버는 평문이고 일부러 loopback bind만 허용한다. 그래서 같은 프로세스나 같은
|
||||
Pod sidecar 통신에만 맞다. 보통 Kubernetes Service를 위해 `0.0.0.0`에 bind할 수 없고, 다른 Pod의 트래픽을
|
||||
받을 수 없으며, 클러스터를 향한 gRPC endpoint로 내세우면 안 된다. 클러스터에 노출하려면 미뤄 둔 TLS/mTLS
|
||||
credential 경로와 따로 검증한 loopback 아닌 bind가 필요하다.
|
||||
|
||||
## Feature 기여 방법
|
||||
|
||||
현재 저장소에는 feature RPC가 없다. 향후 feature를 도입할
|
||||
때는 `.proto`/generated stub/`BindableService`를 해당 feature가 소유하고, 서비스 빈과 정확히 한
|
||||
개의 caller-supplied `GrpcAuthenticationPolicy` 빈을 함께 제공한다. 정책이 없거나 여러 개면
|
||||
listener 시작이 실패한다. 정책은 `Optional<Principal> authenticate(Metadata)`이고, 돌려준
|
||||
호출자는 gRPC `Context`에 담겨 handler가 `GrpcAuthenticatedCaller.current()`로 읽는다. 정책이
|
||||
빈 값·`null`을 반환하거나 예외를 던진 요청은 feature handler에 닿지
|
||||
않고 안정적인 `UNAUTHENTICATED` status/code/category로 종료된다. 정책 예외는 예외 타입과 메서드
|
||||
이름만 WARN으로 남긴다(메시지는 자격 증명을 담을 수 있어 남기지 않는다).
|
||||
|
||||
## P1 증거와 한계
|
||||
|
||||
- `GrpcSafeActivationTest`: 기본 비활성, 관련 빈 부재, 설정 검증, feature 인증 정책 필수 조건.
|
||||
- `GrpcP1BoundaryWireTest`: 실제 loopback ephemeral Netty unary service의 auth 성공/실패,
|
||||
reflection-off, handler/listener/observer/raw-status 오류 sanitization과 sentinel redaction.
|
||||
서버 한도(메시지 크기, 기본 deadline, 연결당 동시 호출, executor 포화)도 같은 wire 에서 검증한다.
|
||||
|
||||
이 증거는 local insecure unary qualification일 뿐 production-ready 근거가 아니다. TLS/mTLS,
|
||||
external bind, 메서드별 deadline, streaming/backpressure, generated protobuf 호환성은 P2로 남아 있다.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:inbound:grpc:test
|
||||
```
|
||||
@AGENTS.md
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
`dev.caskeleton.adapter.inbound.grpc`.
|
||||
|
||||
허용/금지 의존, 모듈 규칙, 설정 knob, 테스트 명령 같은 **모듈 규칙**은
|
||||
[CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를
|
||||
[AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를
|
||||
모아둔 참조용 기록이다.
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
# adapter:inbound:messaging
|
||||
|
||||
- 모듈 ID `adapter-inbound-messaging`, Gradle 경로 `:adapter:inbound:messaging`. registry 정본:
|
||||
`src/config/architecture/modules.json`.
|
||||
- 책임: 들여온 메시징 플랫폼의 애플리케이션 소비 쪽이다 — 플랫폼이 애플리케이션에서 받아야 하는
|
||||
inbox 부품(애플리케이션 DataSource 위의 `JdbcInboxRepository`, 그 `PlatformTransactionManager` 위의
|
||||
`TransactionRunner`, 자기 Flyway stream `MessagingInboxSchemaStream`인 inbox migration)과 애플리케이션의
|
||||
`MessageHandler` 구현들이다. 핸들러 하나는 전달 하나를 유스케이스 호출 하나로 바꾼다. 핸들러는 그 밖에
|
||||
아무것도 등록하지 않는다: 플랫폼이 그 `destination()`과 `schemaVersions()`가 선언한 것을 decode한다.
|
||||
- 경계: 핸들러에 업무 규칙을 두지 않는다(HARD-STOP 4). 영속 엔티티나 repository가 없다. broker SDK 타입이
|
||||
없다. 허용 edge는 registry 항목에서만 온다.
|
||||
- 쓰기 유스케이스를 부르는 핸들러는 `@SystemCaller(reason = ...)`이고 `@SystemInvoked` 유스케이스를 직접
|
||||
만든다. 유스케이스는 bean이 아니고, 사용자 전송 계층은 핸들러를 부르지 않는다
|
||||
(`docs/manual/09-outbox-events.md` 「소비 — 이벤트를 받는 쪽」 순서 4단계,
|
||||
`docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」,
|
||||
`ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`, `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`,
|
||||
`USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`). 핸들러는 프로젝트 타입(`MessageHandler<T>`)만 구현하고,
|
||||
`Runnable`이나 프로젝트 밖의 다른 타입은 구현하지 않는다(`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`).
|
||||
- 시험: 자동 구성과 inbox 동작을 보는 시험. `./gradlew :adapter:inbound:messaging:check`.
|
||||
실제 Kafka + PostgreSQL 재전달 lane은 `messagingInboxRedeliveryIntegrationTest`다(`:integrationCheck`).
|
||||
- 좌표: group `dev.caskeleton.adapter.inbound`, jar `adapter-inbound-messaging`. 지우지 않는다 — 기본
|
||||
group이면 Gradle에게 이 프로젝트와 `:adapter:outbound:messaging`은 같은 모듈이 된다.
|
||||
- 설계와 버린 대안: `README.md`.
|
||||
@@ -1,23 +1 @@
|
||||
# adapter:inbound:messaging
|
||||
|
||||
- 모듈 ID `adapter-inbound-messaging`, Gradle 경로 `:adapter:inbound:messaging`. registry 정본:
|
||||
`src/config/architecture/modules.json`.
|
||||
- 책임: 들여온 메시징 플랫폼의 애플리케이션 소비 쪽이다 — 플랫폼이 애플리케이션에서 받아야 하는
|
||||
inbox 부품(애플리케이션 DataSource 위의 `JdbcInboxRepository`, 그 `PlatformTransactionManager` 위의
|
||||
`TransactionRunner`, 자기 Flyway stream `MessagingInboxSchemaStream`인 inbox migration)과 애플리케이션의
|
||||
`MessageHandler` 구현들이다. 핸들러 하나는 전달 하나를 유스케이스 호출 하나로 바꾼다. 핸들러는 그 밖에
|
||||
아무것도 등록하지 않는다: 플랫폼이 그 `destination()`과 `schemaVersions()`가 선언한 것을 decode한다.
|
||||
- 경계: 핸들러에 업무 규칙을 두지 않는다(HARD-STOP 4). 영속 엔티티나 repository가 없다. broker SDK 타입이
|
||||
없다. 허용 edge는 registry 항목에서만 온다.
|
||||
- 쓰기 유스케이스를 부르는 핸들러는 `@SystemCaller(reason = ...)`이고 `@SystemInvoked` 유스케이스를 직접
|
||||
만든다. 유스케이스는 bean이 아니고, 사용자 전송 계층은 핸들러를 부르지 않는다
|
||||
(`docs/manual/09-outbox-events.md` 「소비 — 이벤트를 받는 쪽」 순서 4단계,
|
||||
`docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」,
|
||||
`ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`, `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`,
|
||||
`USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`). 핸들러는 프로젝트 타입(`MessageHandler<T>`)만 구현하고,
|
||||
`Runnable`이나 프로젝트 밖의 다른 타입은 구현하지 않는다(`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`).
|
||||
- 시험: 자동 구성과 inbox 동작을 보는 시험. `./gradlew :adapter:inbound:messaging:check`.
|
||||
실제 Kafka + PostgreSQL 재전달 lane은 `messagingInboxRedeliveryIntegrationTest`다(`:integrationCheck`).
|
||||
- 좌표: group `dev.caskeleton.adapter.inbound`, jar `adapter-inbound-messaging`. 지우지 않는다 — 기본
|
||||
group이면 Gradle에게 이 프로젝트와 `:adapter:outbound:messaging`은 같은 모듈이 된다.
|
||||
- 설계와 버린 대안: `README.md`.
|
||||
@AGENTS.md
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
# adapter:inbound:web-advanced — 골라 쓰는 web 라이브러리
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-inbound-web-advanced`
|
||||
- Gradle 경로: `:adapter:inbound:web-advanced`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web-advanced:test --console=plain`
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.inbound.web.advanced`. 무엇을 주는지, 서비스가 더하는 한 줄,
|
||||
설정은 [README.md](README.md)에 있다.
|
||||
|
||||
## 책임
|
||||
|
||||
- servlet 운영 경로가 닿지 않는 web 라이브러리 코드: streaming, virtual thread admission, JSON Patch /
|
||||
Merge Patch, CBOR·XML codec, OpenAPI 3.2 생성기와 breaking change 정책, URI·method 정책, versioning,
|
||||
operation·budget·contract catalog, security context bridge, 멱등 응답 codec, route 목록.
|
||||
- 스위치가 있는 MVC capability 셋(virtual thread, NDJSON, JSON sequence). 각각 이 leaf의
|
||||
`AutoConfiguration.imports`에 적힌 `@AutoConfiguration`이고 기본은 꺼져 있다.
|
||||
|
||||
## 규칙
|
||||
|
||||
- 어떤 기본 조립에도 없다. `app-bootstrap` main은 이 leaf에 의존하지 않는다.
|
||||
`app-bootstrap`은 저장소 전체 ArchUnit import가 이 leaf를 읽도록 `testRuntimeOnly`로만 받는다.
|
||||
- `adapter:inbound:web`(`core` 어휘)에 의존하고, 그 반대는 없다.
|
||||
- component scan에 걸리는 stereotype이 없다. 쓰는 애플리케이션은 어댑터 패키지를 scan할 수 있다
|
||||
(서비스가 `dev.caskeleton.adapter.inbound.web`을 scan할 수 있다). 그래서 여기 둔 `@Configuration`이나
|
||||
`@Component`는 스위치가 무엇을 말하든 만들어진다. 스위치가 있는 배선은 `@AutoConfiguration` + imports
|
||||
한 줄이다. import되는 도우미는 stereotype을 달지 않는다(`MvcStreamingSupportConfiguration`).
|
||||
- 아무 코드도 읽지 않는 설정, 시험만 부르는 `main`의 gate·증거 타입을 두지 않는다 — 릴리스 gate와
|
||||
OpenAPI 승격 보고서를 바로 그 이유로 지웠다(`docs/capability-status.md`).
|
||||
- 기능마다 세대 하나. 운영 web 경로가 이미 다른 방식으로 하는 일을 여기서 다시 구현하지 않는다:
|
||||
forwarded header(`server.forward-headers-strategy`), CORS·CSRF(`CorsSettings`/`SecurityConfig`), cache
|
||||
header(`CacheControlFilter`), JSON mapper(Boot의 `JsonMapper`), OpenAPI 손질(`OpenApiContractConfig`).
|
||||
그 중복과 WebFlux `functional` 패키지는 2026-09-25에 지웠다(`docs/capability-status.md`).
|
||||
- `adapter:inbound:web`의 inbound 어댑터 규칙이 그대로 적용된다: repository 접근 없음, 업무 규칙 없음,
|
||||
`application-core`·`domain-core`로 새는 DTO 없음.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:inbound:web-advanced:check --console=plain
|
||||
./gradlew :adapter:inbound:web-advanced:webAdvancedTest --console=plain
|
||||
```
|
||||
@@ -1,45 +1 @@
|
||||
# adapter:inbound:web-advanced — 골라 쓰는 web 라이브러리
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-inbound-web-advanced`
|
||||
- Gradle 경로: `:adapter:inbound:web-advanced`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web-advanced:test --console=plain`
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.inbound.web.advanced`. 무엇을 주는지, 서비스가 더하는 한 줄,
|
||||
설정은 [README.md](README.md)에 있다.
|
||||
|
||||
## 책임
|
||||
|
||||
- servlet 운영 경로가 닿지 않는 web 라이브러리 코드: streaming, virtual thread admission, JSON Patch /
|
||||
Merge Patch, CBOR·XML codec, OpenAPI 3.2 생성기와 breaking change 정책, URI·method 정책, versioning,
|
||||
operation·budget·contract catalog, security context bridge, 멱등 응답 codec, route 목록.
|
||||
- 스위치가 있는 MVC capability 셋(virtual thread, NDJSON, JSON sequence). 각각 이 leaf의
|
||||
`AutoConfiguration.imports`에 적힌 `@AutoConfiguration`이고 기본은 꺼져 있다.
|
||||
|
||||
## 규칙
|
||||
|
||||
- 어떤 기본 조립에도 없다. `app-bootstrap` main은 이 leaf에 의존하지 않는다.
|
||||
`app-bootstrap`은 저장소 전체 ArchUnit import가 이 leaf를 읽도록 `testRuntimeOnly`로만 받는다.
|
||||
- `adapter:inbound:web`(`core` 어휘)에 의존하고, 그 반대는 없다.
|
||||
- component scan에 걸리는 stereotype이 없다. 쓰는 애플리케이션은 어댑터 패키지를 scan할 수 있다
|
||||
(서비스가 `dev.caskeleton.adapter.inbound.web`을 scan할 수 있다). 그래서 여기 둔 `@Configuration`이나
|
||||
`@Component`는 스위치가 무엇을 말하든 만들어진다. 스위치가 있는 배선은 `@AutoConfiguration` + imports
|
||||
한 줄이다. import되는 도우미는 stereotype을 달지 않는다(`MvcStreamingSupportConfiguration`).
|
||||
- 아무 코드도 읽지 않는 설정, 시험만 부르는 `main`의 gate·증거 타입을 두지 않는다 — 릴리스 gate와
|
||||
OpenAPI 승격 보고서를 바로 그 이유로 지웠다(`docs/capability-status.md`).
|
||||
- 기능마다 세대 하나. 운영 web 경로가 이미 다른 방식으로 하는 일을 여기서 다시 구현하지 않는다:
|
||||
forwarded header(`server.forward-headers-strategy`), CORS·CSRF(`CorsSettings`/`SecurityConfig`), cache
|
||||
header(`CacheControlFilter`), JSON mapper(Boot의 `JsonMapper`), OpenAPI 손질(`OpenApiContractConfig`).
|
||||
그 중복과 WebFlux `functional` 패키지는 2026-09-25에 지웠다(`docs/capability-status.md`).
|
||||
- `adapter:inbound:web`의 inbound 어댑터 규칙이 그대로 적용된다: repository 접근 없음, 업무 규칙 없음,
|
||||
`application-core`·`domain-core`로 새는 DTO 없음.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:inbound:web-advanced:check --console=plain
|
||||
./gradlew :adapter:inbound:web-advanced:webAdvancedTest --console=plain
|
||||
```
|
||||
@AGENTS.md
|
||||
|
||||
@@ -0,0 +1,172 @@
|
||||
# adapter:inbound:web — inbound HTTP 어댑터
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-inbound-web`
|
||||
- Gradle 경로: `:adapter:inbound:web`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.inbound.web`.
|
||||
|
||||
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT).
|
||||
|
||||
## 책임
|
||||
|
||||
- HTTP controller.
|
||||
- 요청·응답 DTO.
|
||||
- 요청 DTO를 application command로 바꾸기.
|
||||
- 인증, 검증, 오류 대응, filter, web·보안 설정.
|
||||
- 애플리케이션이 가진 `CorrelationIdPort`로 내놓는, 걸러 낸 요청 correlation 문맥.
|
||||
- `shared-contract`로 Swagger 의존을 새게 하지 않으면서 `ApiError.details`를 `type: object`로 두는,
|
||||
전송 계층이 가진 OpenAPI 손질.
|
||||
|
||||
모든 서비스가 이 leaf를 싣는다. 그래서 servlet 운영 경로가 닿는 것만 담는다: 그 `AutoConfiguration.imports`
|
||||
루트(`WebAdapterAutoConfiguration`은 envelope, filter, health, rate-limit bean을 import한다.
|
||||
`WebSecurityAutoConfiguration`은 JWT chain을 import하므로, 자기 보안 방식을 가진 애플리케이션은 그 루트만
|
||||
뺀다. `WebMethodSecurityAutoConfiguration`은 method security와 권한 포트를 import하고 chain을 바꿔도 남는다.
|
||||
이 leaf를 scan하는 쪽은 없다), 그리고 `app-bootstrap`, `web-fileserver`, `composition:fileserver-platform`이
|
||||
이름을 대는 타입과 그것이 전이로 참조하는 것. 운영 경로가 닿지 않는 라이브러리 코드(streaming, virtual
|
||||
thread, patch, codec, OpenAPI 3.2, URI·method 정책, versioning, operation, budget, contract, security context
|
||||
bridge, `JsonIdempotentResponseCodec`, route 목록)는 골라 쓰는 leaf `adapter:inbound:web-advanced`에 있다.
|
||||
운영 경로에서 아무도 쓰지 않는 새 타입은 여기가 아니라 거기에 둔다. 이 leaf는 그 leaf에 의존하지 않는다
|
||||
(Gradle registry + ArchUnit `WEB-ARCH-ADV`).
|
||||
|
||||
## 허용
|
||||
|
||||
- `:application-core`
|
||||
- `:domain-core`
|
||||
- `:shared-contract`
|
||||
- `:adapter:outbound:support` — `StrictSettingsBinder`만. `app.security`(`SecuritySettings`, 인증 모드 포함)는
|
||||
모든 모듈이 쓰는 엄격한 binder 하나로 바인딩한다(2026-11-01부터). ArchUnit inbound·outbound 규칙은 그
|
||||
leaf에서 이 클래스만 허용한다.
|
||||
- Spring Web·Security·Validation 의존성.
|
||||
|
||||
## 금지
|
||||
|
||||
- `adapter:outbound:persistence-jpa`나 다른 `adapter:outbound:*` 타입에 직접 의존하기.
|
||||
- controller에서 repository나 JPA 엔티티에 직접 접근하기.
|
||||
- controller, filter, config, mapper, settings 코드 안의 핵심 업무 규칙.
|
||||
- DTO가 application이나 domain으로 새는 것.
|
||||
|
||||
## 경계 검증과 mapper 계약
|
||||
|
||||
`feature-boundary-validation-mapping-contract`(설계 기록)가 이 계층 경계의 동작을 정한다. 저장소 단위
|
||||
가드레일(ArchUnit + Jackson 설정 + handler)은 정적 위반만 잡는다. 아래 계약은 참조 구현이 따라야 할 런타임
|
||||
패턴도 정한다.
|
||||
|
||||
- **B1 — 요청 경계의 Jackson 정책.** `spring.jackson.deserialization`이 `fail-on-unknown-properties`,
|
||||
`fail-on-null-for-primitives`, `fail-on-ignored-properties`를 `true`로, `read-unknown-enum-values-as-null`을
|
||||
`false`로 고정한다. 클래스 수준 `@JsonIgnoreProperties(ignoreUnknown = true)`로 DTO마다 이것을 되돌리지
|
||||
**않는다** — ArchUnit 규칙 `REQUEST_DTOS_DO_NOT_SILENCE_UNKNOWN_FIELDS`가 막는다. 요청 record에는
|
||||
wrapper 타입(`Integer`, `Long`, `Boolean`, `Optional<T>`)을 써서 JSON `null`이 primitive `0`이 되지 못하게
|
||||
한다.
|
||||
- **B2 — PATCH 뜻.** RFC 7396 `application/merge-patch+json`(`null = 삭제`)을 쓰지 않는다. PATCH endpoint는
|
||||
*없음*(바꾸지 않음), *명시한 null*(필드 비움), *값*(바꿈)을 구별해야 한다. 요청 record에
|
||||
`org.openapitools:jackson-databind-nullable`(`JsonNullable<T>`)이나 `Optional<T>` wrapper를 쓴다.
|
||||
- **B3 — mapper 안의 실패.** record 정규 생성자의 `IllegalArgumentException`, MapStruct가 생성한 NPE, ACL
|
||||
정규화 실패 등은 `MappingException`을 던져 대응시킨다. 전역 handler가 그것을 `MAPPING_FAILED`(HTTP 400)로
|
||||
보내고, `BAD_PARAMETER`나 `INTERNAL_ERROR`로 보내지 않는다. mapper가 아닌 호출자의 평범한
|
||||
`IllegalArgumentException`은 계속 `BAD_PARAMETER`다.
|
||||
- **B4 — 검증 층.** 클래스 수준 Bean Validation 제약은 *문법* 층(요청 DTO)에 속한다. 도메인 불변식은
|
||||
`application-core` / `domain-core`에 속한다. 문법이 실패하면 `@GroupSequence(...)`로 불변식 평가를 건너뛴다.
|
||||
`@Valid` cascade 깊이는 3 이하로 둔다.
|
||||
- **B5 — 다형 역직렬화.** `ObjectMapper.enableDefaultTyping()` / `activateDefaultTyping()`을 부르거나
|
||||
`LaissezFaireSubTypeValidator`를 참조하는 것은 CVE-2019-14379 RCE의 입구이고 ArchUnit이 막는다
|
||||
(`NO_JACKSON_LAISSEZ_FAIRE_SUBTYPE_VALIDATOR`, `NO_JACKSON_ENABLE_DEFAULT_TYPING_CALL`). sealed `Command`
|
||||
타입은 `@JsonTypeInfo(use = NAME)` + `@JsonSubTypes`나 `BasicPolymorphicTypeValidator` 허용 목록을 쓴다.
|
||||
- **B6 — virtual thread 문맥 전파.** `spring.threads.virtual.enabled=true`이면 `InheritableThreadLocal`을 쓰지
|
||||
않는다(ArchUnit 규칙 `NO_INHERITABLE_THREAD_LOCAL`). filter와 interceptor는 SLF4J 2.0+ MDC나
|
||||
`RequestContextHolder`로 `requestId` / `traceId`를 전파한다.
|
||||
- **B7 — outbound ACL mapper 범위.** outbound HTTP·메시징 어댑터의 응답은 `application-core`나 `domain-core`에
|
||||
닿기 전에 ACL mapper(정규화, 가리기, 공개 필드 고르기)를 거친다 — inbound와 같은 경계 계약이다. 외부 응답
|
||||
원본 타입은 `domain-core`로 새면 안 된다.
|
||||
- **B8 — bulk endpoint의 부분 성공.** envelope `success = true`는 모든 항목이 성공했을 때뿐이다. 일부가
|
||||
실패하면 `success = false` + `error.code = BATCH_PARTIAL_FAILURE` + `error.details[]`(항목별 배열)로
|
||||
답한다 — 단일 항목 endpoint와 모양이 다르다. 모양이 다르다는 것을 OpenAPI spec에 적는다.
|
||||
|
||||
이 모듈을 쓰는 모듈의 도메인 `@RestControllerAdvice`에는 `@Order(Ordered.HIGHEST_PRECEDENCE)`를 단다(또는
|
||||
다른 방법으로 이 모듈의 기본 `GlobalExceptionHandler`보다 앞에 둔다). 그렇지 않으면 기본 handler의
|
||||
catch-all `@ExceptionHandler(Exception.class)`가 도메인 예외를 `INTERNAL_ERROR`로 만든다.
|
||||
|
||||
기본 운영 handler(`error/GlobalExceptionHandler`), 오류 코드 계약
|
||||
(`dev.caskeleton.shared.error.ApiErrorCode` + `OperationalError`), `error/ErrorResponseFactory`,
|
||||
`envelope/EnvelopeBodyAdvice`는 이제 운영 모듈(`adapter:inbound:web` / `shared-contract`)에 있어서, 돌아가는
|
||||
애플리케이션이 그것을 준다. 기능 전용 예외 handler와 오류 코드는 그 기능을 가진 모듈에 둔다(`docs/manual/06-errors.md`).
|
||||
|
||||
## schema·직렬화 계약
|
||||
|
||||
`feature-schema-serialization-contract`(설계 기록)가 wire 계약의 *응답을 만드는* 쪽을 정한다 — 위 B1
|
||||
*요청을 받는* 정책의 짝이다. 역직렬화 스위치(B1)와 null·빈 값·없음 세 상태(`Patch<T>` + `JsonNullable`,
|
||||
B2)가 이미 inbound 쪽을 덮고, 아래 규칙이 outbound 쪽을 덮는다. Jackson 속성은 `app-bootstrap`의
|
||||
`application.yml`(`spring.jackson.deserialization.*`, `spring.jackson.datatype.*`)에 있다. ArchUnit과 실제
|
||||
설정 시험도 `app-bootstrap`에 있다(`JacksonSerializationPolicyTest`, `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`).
|
||||
|
||||
- **S1 — 날짜·시간·시간대.** `WRITE_DATES_AS_TIMESTAMPS=false`로 고정하므로 `java.time` 값은
|
||||
`JavaTimeModule`을 거쳐 ISO-8601 문자열로 직렬화한다(`OffsetDateTime` → `"...Z"`, `LocalDate` →
|
||||
`"YYYY-MM-DD"`). 숫자 epoch나 `[y,m,d,...]` 배열이 되지 않는다. 서버 시간대는 **UTC**다: 시각은 `Z`
|
||||
offset을 가진 `OffsetDateTime`/`Instant`로 낸다. 날짜만 있는 달력 필드에만 `LocalDate`를 쓴다. 시간대
|
||||
없는 `LocalDateTime`을 응답 DTO에 넣지 **않는다** — offset 없이 직렬화되어 계약을 깬다.
|
||||
- **S2 — 돈·BigDecimal.** 도메인이 따로 적지 않으면 기본 scale 2, 반올림 `HALF_UP`이다(KRW/JPY는 scale 0과
|
||||
schema 메모). 값은 지수 표기로 직렬화되지 않는다 — 설정 키로 고정하지 않고 `JacksonSerializationPolicyTest`가
|
||||
큰 값과 끝자리 0을 단언한다. API마다 JSON 표현을 **하나** 고르고 OpenAPI schema에 적는다: 공개·금융
|
||||
endpoint는 **string**(`@JsonSerialize(using = ToStringSerializer.class)`. 클라이언트가 파싱하고 정밀도를
|
||||
잃지 않는다), 내부 서비스 사이 endpoint는 **number + plain**. 기본값에 기대지 않는다 — endpoint를 설계할
|
||||
때 정한다.
|
||||
- **S3 — `new BigDecimal(double)`은 금지다.** `double`/`float` 생성자는 이진 부동소수점 오차를 담는다
|
||||
(`new BigDecimal(0.1)` ≠ `0.1`). `String`(`new BigDecimal("0.1")`)이나 `BigDecimal.valueOf(double)`로
|
||||
만든다. ArchUnit 규칙 `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`가 강제한다.
|
||||
- **S4 — enum과 null·빈 값·없음.** 요청 쪽의 모르는 enum → `VALIDATION_FAILED`(B1
|
||||
`read-unknown-enum-values-as-null=false`). 옛 값은 명시한 어댑터로 대응시키고 소리 없는 대체값을 쓰지
|
||||
않는다. 없음·명시한 null·값의 구별은 inbound web mapper(Controller DTO → Command)가 가지고 `Patch<T>`(B2)로
|
||||
나타낸다. `domain-core`와 `application-core`는 이미 풀린 세 상태를 받고 wire 타입은 받지 않는다.
|
||||
- **S5 — 이 브랜치의 범위 밖.** OpenAPI drift 강제는 검증 suite / api-contract-baseline의 몫이다. 지운
|
||||
필드 재사용 금지 도구(`x-removed-fields` 대 markdown catalog)는 `needs-confirmation`이다. outbox·event용
|
||||
Avro Schema Registry와 응답 필드 이름 바꾸기·versioning(`feature-api-compatibility-deprecation-contract`)은
|
||||
다른 브랜치다.
|
||||
|
||||
## 업무 규칙 검증 계약
|
||||
|
||||
`feature-business-rule-validation-contract`(설계 기록)는 **어떤 규칙을 어느 경계에서 검증하는지** 정해서,
|
||||
「검증」이 controller DTO나 DB 제약 하나로 뭉개지지 않게 한다. 위 경계·대응 계약 위에 놓이고, ArchUnit과
|
||||
계약 시험이 강제한다(새 런타임 장치가 아니다).
|
||||
|
||||
| 층 | 소유 | 검증하는 것 | `error.category` | 강제하는 곳 |
|
||||
|---|---|---|---|---|
|
||||
| 문법·모양 | `adapter:inbound:web` 요청 DTO(`@Valid` / `jakarta.validation`) | 요청 모양, 타입, 필수 필드 | `VALIDATION` | ArchUnit 규칙 `VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY` |
|
||||
| 유스케이스 정책 | `application-core` | 인가, aggregate를 가로지르는 정책, 상태 전제 조건 | `AUTHZ` / `CONFLICT` | `BusinessRuleValidationContractTest` |
|
||||
| 도메인 불변식 | `domain-core` 모델·값 객체 **생성자** | 업무 불변식(예: end ≥ start) | `CONFLICT` / `VALIDATION` | 도메인 단위 시험(예: `PeriodTest`) — 생성자가 유일하고 바뀌지 않는 생성 경로다 |
|
||||
| 영속 무결성 | `adapter:outbound:persistence-jpa`(번역기는 `feature-persistence-failure-baseline`의 것) | unique / FK / check / serialization | `DATA_INTEGRITY` / `CONFLICT` | `BusinessRuleValidationContractTest` + 누출 시험 |
|
||||
|
||||
- **C1 — 검증 애너테이션은 web 경계에 머문다.** `jakarta.validation`(`@NotNull`, `@Valid`, …)은
|
||||
`adapter:inbound:web`에만 나와야 한다. `domain-core`와 `application-core`는 불변식과 정책을 평범한 Java로
|
||||
나타낸다. Bean Validation 애너테이션이 `..domain..`이나 `..application..`으로 새면 ArchUnit 규칙
|
||||
`VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY`가 빌드를 실패시킨다.
|
||||
- **C2 — 업무 불변식은 도메인에 있고 우회할 수 없다.** 불변식은 값 객체·엔티티 **생성자**(유일한 생성
|
||||
경로)에서 강제하고 타입을 불변으로 둔다. 그래서 어떤 application service나 영속 경로도 불변식을 어긴
|
||||
인스턴스를 내줄 수 없다. DB 제약은 뒷받침일 뿐 유일한 검사가 아니다(금지: 「불변식을 DB 제약으로만
|
||||
지키기」).
|
||||
- **C3 / C7 — 영속 무결성은 새는 것 없이 운영 오류로 대응한다.** unique·FK·check·serialization 실패는
|
||||
**클라이언트에게 안전한 메시지만** 가진 `DATA_INTEGRITY` / `CONFLICT`로 대응한다. SQL 원문, 제약·index
|
||||
이름, SQLState 코드, 예외 클래스, stack frame은 `error.message`나 `error.details`에 닿으면 안 된다. 기본
|
||||
`GlobalExceptionHandler` catch-all이 이미 메시지를 불투명한 공용 메시지(`ClientErrorMessages.OPAQUE`)로
|
||||
바꾸고 details를 `null`로 낸다. category가 맞는 대응(23505 → `CONFLICT/DB_UNIQUE_VIOLATION`, …)은
|
||||
`feature-persistence-failure-baseline`의 영속 어댑터 번역기가 가진다.
|
||||
- **C8 — 중복 검증에는 정본 소유자가 있어야 한다.** UX나 성능을 위해 같은 규칙을 다른 층에서 미리 검사할 수
|
||||
있다(예: DB unique 제약을 따라 하는 application 사전 검사). 단 그 규칙의 **정본 소유자**를 코드 주석이나
|
||||
관련 `AGENTS.md`에 적어야 한다. 소유자를 적지 않은 중복 검증기는 리뷰에서 실패다(소리 없이 서로 어긋날
|
||||
위험). 자동 규칙이 아니라 절차 게이트(PR 리뷰)다 — 소유자 표지 애너테이션이 정당해질 때까지
|
||||
`needs-confirmation`이다.
|
||||
|
||||
이 브랜치의 범위 밖(참조만 하고 여기서 다시 구현하지 않는다): SQLState → 코드 9행 표와
|
||||
`DataAccessException` 번역기(`feature-persistence-failure-baseline`), Jackson B1/B2 요청 경계 스위치와 mapper
|
||||
표지 예외(`feature-boundary-validation-mapping-contract`), envelope, `Category` enum, `OperationalError` 코드
|
||||
(`feature-operational-error-observability-foundation`).
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:inbound:web:test --console=plain
|
||||
```
|
||||
@@ -1,172 +1 @@
|
||||
# adapter:inbound:web — inbound HTTP 어댑터
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-inbound-web`
|
||||
- Gradle 경로: `:adapter:inbound:web`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.inbound.web`.
|
||||
|
||||
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT).
|
||||
|
||||
## 책임
|
||||
|
||||
- HTTP controller.
|
||||
- 요청·응답 DTO.
|
||||
- 요청 DTO를 application command로 바꾸기.
|
||||
- 인증, 검증, 오류 대응, filter, web·보안 설정.
|
||||
- 애플리케이션이 가진 `CorrelationIdPort`로 내놓는, 걸러 낸 요청 correlation 문맥.
|
||||
- `shared-contract`로 Swagger 의존을 새게 하지 않으면서 `ApiError.details`를 `type: object`로 두는,
|
||||
전송 계층이 가진 OpenAPI 손질.
|
||||
|
||||
모든 서비스가 이 leaf를 싣는다. 그래서 servlet 운영 경로가 닿는 것만 담는다: 그 `AutoConfiguration.imports`
|
||||
루트(`WebAdapterAutoConfiguration`은 envelope, filter, health, rate-limit bean을 import한다.
|
||||
`WebSecurityAutoConfiguration`은 JWT chain을 import하므로, 자기 보안 방식을 가진 애플리케이션은 그 루트만
|
||||
뺀다. `WebMethodSecurityAutoConfiguration`은 method security와 권한 포트를 import하고 chain을 바꿔도 남는다.
|
||||
이 leaf를 scan하는 쪽은 없다), 그리고 `app-bootstrap`, `web-fileserver`, `composition:fileserver-platform`이
|
||||
이름을 대는 타입과 그것이 전이로 참조하는 것. 운영 경로가 닿지 않는 라이브러리 코드(streaming, virtual
|
||||
thread, patch, codec, OpenAPI 3.2, URI·method 정책, versioning, operation, budget, contract, security context
|
||||
bridge, `JsonIdempotentResponseCodec`, route 목록)는 골라 쓰는 leaf `adapter:inbound:web-advanced`에 있다.
|
||||
운영 경로에서 아무도 쓰지 않는 새 타입은 여기가 아니라 거기에 둔다. 이 leaf는 그 leaf에 의존하지 않는다
|
||||
(Gradle registry + ArchUnit `WEB-ARCH-ADV`).
|
||||
|
||||
## 허용
|
||||
|
||||
- `:application-core`
|
||||
- `:domain-core`
|
||||
- `:shared-contract`
|
||||
- `:adapter:outbound:support` — `StrictSettingsBinder`만. `app.security`(`SecuritySettings`, 인증 모드 포함)는
|
||||
모든 모듈이 쓰는 엄격한 binder 하나로 바인딩한다(2026-11-01부터). ArchUnit inbound·outbound 규칙은 그
|
||||
leaf에서 이 클래스만 허용한다.
|
||||
- Spring Web·Security·Validation 의존성.
|
||||
|
||||
## 금지
|
||||
|
||||
- `adapter:outbound:persistence-jpa`나 다른 `adapter:outbound:*` 타입에 직접 의존하기.
|
||||
- controller에서 repository나 JPA 엔티티에 직접 접근하기.
|
||||
- controller, filter, config, mapper, settings 코드 안의 핵심 업무 규칙.
|
||||
- DTO가 application이나 domain으로 새는 것.
|
||||
|
||||
## 경계 검증과 mapper 계약
|
||||
|
||||
`feature-boundary-validation-mapping-contract`(설계 기록)가 이 계층 경계의 동작을 정한다. 저장소 단위
|
||||
가드레일(ArchUnit + Jackson 설정 + handler)은 정적 위반만 잡는다. 아래 계약은 참조 구현이 따라야 할 런타임
|
||||
패턴도 정한다.
|
||||
|
||||
- **B1 — 요청 경계의 Jackson 정책.** `spring.jackson.deserialization`이 `fail-on-unknown-properties`,
|
||||
`fail-on-null-for-primitives`, `fail-on-ignored-properties`를 `true`로, `read-unknown-enum-values-as-null`을
|
||||
`false`로 고정한다. 클래스 수준 `@JsonIgnoreProperties(ignoreUnknown = true)`로 DTO마다 이것을 되돌리지
|
||||
**않는다** — ArchUnit 규칙 `REQUEST_DTOS_DO_NOT_SILENCE_UNKNOWN_FIELDS`가 막는다. 요청 record에는
|
||||
wrapper 타입(`Integer`, `Long`, `Boolean`, `Optional<T>`)을 써서 JSON `null`이 primitive `0`이 되지 못하게
|
||||
한다.
|
||||
- **B2 — PATCH 뜻.** RFC 7396 `application/merge-patch+json`(`null = 삭제`)을 쓰지 않는다. PATCH endpoint는
|
||||
*없음*(바꾸지 않음), *명시한 null*(필드 비움), *값*(바꿈)을 구별해야 한다. 요청 record에
|
||||
`org.openapitools:jackson-databind-nullable`(`JsonNullable<T>`)이나 `Optional<T>` wrapper를 쓴다.
|
||||
- **B3 — mapper 안의 실패.** record 정규 생성자의 `IllegalArgumentException`, MapStruct가 생성한 NPE, ACL
|
||||
정규화 실패 등은 `MappingException`을 던져 대응시킨다. 전역 handler가 그것을 `MAPPING_FAILED`(HTTP 400)로
|
||||
보내고, `BAD_PARAMETER`나 `INTERNAL_ERROR`로 보내지 않는다. mapper가 아닌 호출자의 평범한
|
||||
`IllegalArgumentException`은 계속 `BAD_PARAMETER`다.
|
||||
- **B4 — 검증 층.** 클래스 수준 Bean Validation 제약은 *문법* 층(요청 DTO)에 속한다. 도메인 불변식은
|
||||
`application-core` / `domain-core`에 속한다. 문법이 실패하면 `@GroupSequence(...)`로 불변식 평가를 건너뛴다.
|
||||
`@Valid` cascade 깊이는 3 이하로 둔다.
|
||||
- **B5 — 다형 역직렬화.** `ObjectMapper.enableDefaultTyping()` / `activateDefaultTyping()`을 부르거나
|
||||
`LaissezFaireSubTypeValidator`를 참조하는 것은 CVE-2019-14379 RCE의 입구이고 ArchUnit이 막는다
|
||||
(`NO_JACKSON_LAISSEZ_FAIRE_SUBTYPE_VALIDATOR`, `NO_JACKSON_ENABLE_DEFAULT_TYPING_CALL`). sealed `Command`
|
||||
타입은 `@JsonTypeInfo(use = NAME)` + `@JsonSubTypes`나 `BasicPolymorphicTypeValidator` 허용 목록을 쓴다.
|
||||
- **B6 — virtual thread 문맥 전파.** `spring.threads.virtual.enabled=true`이면 `InheritableThreadLocal`을 쓰지
|
||||
않는다(ArchUnit 규칙 `NO_INHERITABLE_THREAD_LOCAL`). filter와 interceptor는 SLF4J 2.0+ MDC나
|
||||
`RequestContextHolder`로 `requestId` / `traceId`를 전파한다.
|
||||
- **B7 — outbound ACL mapper 범위.** outbound HTTP·메시징 어댑터의 응답은 `application-core`나 `domain-core`에
|
||||
닿기 전에 ACL mapper(정규화, 가리기, 공개 필드 고르기)를 거친다 — inbound와 같은 경계 계약이다. 외부 응답
|
||||
원본 타입은 `domain-core`로 새면 안 된다.
|
||||
- **B8 — bulk endpoint의 부분 성공.** envelope `success = true`는 모든 항목이 성공했을 때뿐이다. 일부가
|
||||
실패하면 `success = false` + `error.code = BATCH_PARTIAL_FAILURE` + `error.details[]`(항목별 배열)로
|
||||
답한다 — 단일 항목 endpoint와 모양이 다르다. 모양이 다르다는 것을 OpenAPI spec에 적는다.
|
||||
|
||||
이 모듈을 쓰는 모듈의 도메인 `@RestControllerAdvice`에는 `@Order(Ordered.HIGHEST_PRECEDENCE)`를 단다(또는
|
||||
다른 방법으로 이 모듈의 기본 `GlobalExceptionHandler`보다 앞에 둔다). 그렇지 않으면 기본 handler의
|
||||
catch-all `@ExceptionHandler(Exception.class)`가 도메인 예외를 `INTERNAL_ERROR`로 만든다.
|
||||
|
||||
기본 운영 handler(`error/GlobalExceptionHandler`), 오류 코드 계약
|
||||
(`dev.caskeleton.shared.error.ApiErrorCode` + `OperationalError`), `error/ErrorResponseFactory`,
|
||||
`envelope/EnvelopeBodyAdvice`는 이제 운영 모듈(`adapter:inbound:web` / `shared-contract`)에 있어서, 돌아가는
|
||||
애플리케이션이 그것을 준다. 기능 전용 예외 handler와 오류 코드는 그 기능을 가진 모듈에 둔다(`docs/manual/06-errors.md`).
|
||||
|
||||
## schema·직렬화 계약
|
||||
|
||||
`feature-schema-serialization-contract`(설계 기록)가 wire 계약의 *응답을 만드는* 쪽을 정한다 — 위 B1
|
||||
*요청을 받는* 정책의 짝이다. 역직렬화 스위치(B1)와 null·빈 값·없음 세 상태(`Patch<T>` + `JsonNullable`,
|
||||
B2)가 이미 inbound 쪽을 덮고, 아래 규칙이 outbound 쪽을 덮는다. Jackson 속성은 `app-bootstrap`의
|
||||
`application.yml`(`spring.jackson.deserialization.*`, `spring.jackson.datatype.*`)에 있다. ArchUnit과 실제
|
||||
설정 시험도 `app-bootstrap`에 있다(`JacksonSerializationPolicyTest`, `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`).
|
||||
|
||||
- **S1 — 날짜·시간·시간대.** `WRITE_DATES_AS_TIMESTAMPS=false`로 고정하므로 `java.time` 값은
|
||||
`JavaTimeModule`을 거쳐 ISO-8601 문자열로 직렬화한다(`OffsetDateTime` → `"...Z"`, `LocalDate` →
|
||||
`"YYYY-MM-DD"`). 숫자 epoch나 `[y,m,d,...]` 배열이 되지 않는다. 서버 시간대는 **UTC**다: 시각은 `Z`
|
||||
offset을 가진 `OffsetDateTime`/`Instant`로 낸다. 날짜만 있는 달력 필드에만 `LocalDate`를 쓴다. 시간대
|
||||
없는 `LocalDateTime`을 응답 DTO에 넣지 **않는다** — offset 없이 직렬화되어 계약을 깬다.
|
||||
- **S2 — 돈·BigDecimal.** 도메인이 따로 적지 않으면 기본 scale 2, 반올림 `HALF_UP`이다(KRW/JPY는 scale 0과
|
||||
schema 메모). 값은 지수 표기로 직렬화되지 않는다 — 설정 키로 고정하지 않고 `JacksonSerializationPolicyTest`가
|
||||
큰 값과 끝자리 0을 단언한다. API마다 JSON 표현을 **하나** 고르고 OpenAPI schema에 적는다: 공개·금융
|
||||
endpoint는 **string**(`@JsonSerialize(using = ToStringSerializer.class)`. 클라이언트가 파싱하고 정밀도를
|
||||
잃지 않는다), 내부 서비스 사이 endpoint는 **number + plain**. 기본값에 기대지 않는다 — endpoint를 설계할
|
||||
때 정한다.
|
||||
- **S3 — `new BigDecimal(double)`은 금지다.** `double`/`float` 생성자는 이진 부동소수점 오차를 담는다
|
||||
(`new BigDecimal(0.1)` ≠ `0.1`). `String`(`new BigDecimal("0.1")`)이나 `BigDecimal.valueOf(double)`로
|
||||
만든다. ArchUnit 규칙 `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`가 강제한다.
|
||||
- **S4 — enum과 null·빈 값·없음.** 요청 쪽의 모르는 enum → `VALIDATION_FAILED`(B1
|
||||
`read-unknown-enum-values-as-null=false`). 옛 값은 명시한 어댑터로 대응시키고 소리 없는 대체값을 쓰지
|
||||
않는다. 없음·명시한 null·값의 구별은 inbound web mapper(Controller DTO → Command)가 가지고 `Patch<T>`(B2)로
|
||||
나타낸다. `domain-core`와 `application-core`는 이미 풀린 세 상태를 받고 wire 타입은 받지 않는다.
|
||||
- **S5 — 이 브랜치의 범위 밖.** OpenAPI drift 강제는 검증 suite / api-contract-baseline의 몫이다. 지운
|
||||
필드 재사용 금지 도구(`x-removed-fields` 대 markdown catalog)는 `needs-confirmation`이다. outbox·event용
|
||||
Avro Schema Registry와 응답 필드 이름 바꾸기·versioning(`feature-api-compatibility-deprecation-contract`)은
|
||||
다른 브랜치다.
|
||||
|
||||
## 업무 규칙 검증 계약
|
||||
|
||||
`feature-business-rule-validation-contract`(설계 기록)는 **어떤 규칙을 어느 경계에서 검증하는지** 정해서,
|
||||
「검증」이 controller DTO나 DB 제약 하나로 뭉개지지 않게 한다. 위 경계·대응 계약 위에 놓이고, ArchUnit과
|
||||
계약 시험이 강제한다(새 런타임 장치가 아니다).
|
||||
|
||||
| 층 | 소유 | 검증하는 것 | `error.category` | 강제하는 곳 |
|
||||
|---|---|---|---|---|
|
||||
| 문법·모양 | `adapter:inbound:web` 요청 DTO(`@Valid` / `jakarta.validation`) | 요청 모양, 타입, 필수 필드 | `VALIDATION` | ArchUnit 규칙 `VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY` |
|
||||
| 유스케이스 정책 | `application-core` | 인가, aggregate를 가로지르는 정책, 상태 전제 조건 | `AUTHZ` / `CONFLICT` | `BusinessRuleValidationContractTest` |
|
||||
| 도메인 불변식 | `domain-core` 모델·값 객체 **생성자** | 업무 불변식(예: end ≥ start) | `CONFLICT` / `VALIDATION` | 도메인 단위 시험(예: `PeriodTest`) — 생성자가 유일하고 바뀌지 않는 생성 경로다 |
|
||||
| 영속 무결성 | `adapter:outbound:persistence-jpa`(번역기는 `feature-persistence-failure-baseline`의 것) | unique / FK / check / serialization | `DATA_INTEGRITY` / `CONFLICT` | `BusinessRuleValidationContractTest` + 누출 시험 |
|
||||
|
||||
- **C1 — 검증 애너테이션은 web 경계에 머문다.** `jakarta.validation`(`@NotNull`, `@Valid`, …)은
|
||||
`adapter:inbound:web`에만 나와야 한다. `domain-core`와 `application-core`는 불변식과 정책을 평범한 Java로
|
||||
나타낸다. Bean Validation 애너테이션이 `..domain..`이나 `..application..`으로 새면 ArchUnit 규칙
|
||||
`VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY`가 빌드를 실패시킨다.
|
||||
- **C2 — 업무 불변식은 도메인에 있고 우회할 수 없다.** 불변식은 값 객체·엔티티 **생성자**(유일한 생성
|
||||
경로)에서 강제하고 타입을 불변으로 둔다. 그래서 어떤 application service나 영속 경로도 불변식을 어긴
|
||||
인스턴스를 내줄 수 없다. DB 제약은 뒷받침일 뿐 유일한 검사가 아니다(금지: 「불변식을 DB 제약으로만
|
||||
지키기」).
|
||||
- **C3 / C7 — 영속 무결성은 새는 것 없이 운영 오류로 대응한다.** unique·FK·check·serialization 실패는
|
||||
**클라이언트에게 안전한 메시지만** 가진 `DATA_INTEGRITY` / `CONFLICT`로 대응한다. SQL 원문, 제약·index
|
||||
이름, SQLState 코드, 예외 클래스, stack frame은 `error.message`나 `error.details`에 닿으면 안 된다. 기본
|
||||
`GlobalExceptionHandler` catch-all이 이미 메시지를 불투명한 공용 메시지(`ClientErrorMessages.OPAQUE`)로
|
||||
바꾸고 details를 `null`로 낸다. category가 맞는 대응(23505 → `CONFLICT/DB_UNIQUE_VIOLATION`, …)은
|
||||
`feature-persistence-failure-baseline`의 영속 어댑터 번역기가 가진다.
|
||||
- **C8 — 중복 검증에는 정본 소유자가 있어야 한다.** UX나 성능을 위해 같은 규칙을 다른 층에서 미리 검사할 수
|
||||
있다(예: DB unique 제약을 따라 하는 application 사전 검사). 단 그 규칙의 **정본 소유자**를 코드 주석이나
|
||||
관련 `CLAUDE.md`에 적어야 한다. 소유자를 적지 않은 중복 검증기는 리뷰에서 실패다(소리 없이 서로 어긋날
|
||||
위험). 자동 규칙이 아니라 절차 게이트(PR 리뷰)다 — 소유자 표지 애너테이션이 정당해질 때까지
|
||||
`needs-confirmation`이다.
|
||||
|
||||
이 브랜치의 범위 밖(참조만 하고 여기서 다시 구현하지 않는다): SQLState → 코드 9행 표와
|
||||
`DataAccessException` 번역기(`feature-persistence-failure-baseline`), Jackson B1/B2 요청 경계 스위치와 mapper
|
||||
표지 예외(`feature-boundary-validation-mapping-contract`), envelope, `Category` enum, `OperationalError` 코드
|
||||
(`feature-operational-error-observability-foundation`).
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:inbound:web:test --console=plain
|
||||
```
|
||||
@AGENTS.md
|
||||
|
||||
@@ -9,7 +9,7 @@ route inventory)는 opt-in leaf `adapter:inbound:web-advanced` 에 있다
|
||||
([README](../web-advanced/README.md)).
|
||||
|
||||
허용/금지 의존, 경계 계약(B1~B8), 스키마/직렬화 계약(S1~S5), 비즈니스 규칙 검증 계약(C1~C8),
|
||||
테스트 명령 같은 **모듈 규칙**은 [CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서
|
||||
테스트 명령 같은 **모듈 규칙**은 [AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서
|
||||
덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할
|
||||
때 본다. 아래 설명은 별도 추적 ID를 몰라도 읽히도록 결정의 배경과 트레이드오프를 문장으로
|
||||
풀어 둔다.
|
||||
@@ -197,7 +197,7 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML
|
||||
|
||||
- **D5: RFC 7807 `ProblemDetail` 표현은 거부**하고 자체 `Envelope` 형식을 쓴다.
|
||||
- **운영/전송/보안 예외만** 처리한다. 도메인 예외는 소비 모듈의 별도 `@RestControllerAdvice` 가 처리하고
|
||||
Spring 이 두 advice 를 합성(compose)한다(CLAUDE.md 의 `@Order(HIGHEST_PRECEDENCE)` 규칙 참조).
|
||||
Spring 이 두 advice 를 합성(compose)한다(AGENTS.md 의 `@Order(HIGHEST_PRECEDENCE)` 규칙 참조).
|
||||
- **클라이언트 메시지는 allowlist다.** 예외 메시지, validation interpolated message, rejected
|
||||
request value, raw request URL은
|
||||
`error.message`/`details`에 넣지 않는다. `error.message`는 항상 shared-contract
|
||||
|
||||
@@ -0,0 +1,120 @@
|
||||
# adapter:inbound:websocket — 고를 때만 켜는 WebSocket·STOMP 경계
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-inbound-websocket`
|
||||
- Gradle 경로: `:adapter:inbound:websocket`
|
||||
- 이 모듈만 시험: `./gradlew :adapter:inbound:websocket:test --console=plain`
|
||||
- 실행 기준: Java 21. Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.inbound.websocket`.
|
||||
|
||||
## 책임
|
||||
|
||||
이 leaf에는 **서로 다른 범위 둘**이 있고, 배포되는 기능 하나로 읽으면 안 된다.
|
||||
|
||||
1. **골라 쓰는 STOMP·SockJS 채널** — `stomp/**`가 Spring 전송 설정, 타입 있는 `app.websocket.*` 설정,
|
||||
handshake principal·origin 검사, destination 정책, 정해진 클라이언트 안전 STOMP `ERROR` 대응, 할 수 있는
|
||||
만큼만 하는(best-effort) 프로세스 안 이벤트 projection을 가진다.
|
||||
2. **servlet handler 라이브러리** — `servlet/`, `outbound/`, `budget/`과 id record 둘
|
||||
`core/WebSocketConnectionId`, `protocol/WebSocketMessageId`. 설정 키도 Spring 설정도 없다: 서비스 자신의
|
||||
어댑터 leaf가 `PlatformWebSocketHandler`를 만들고 등록한다. README 「라이브러리 API」가 진입점과 배선을
|
||||
적는다.
|
||||
|
||||
이 leaf는 command 중복을 걸러 내지 않고 저장소 SPI를 가지지 않는다. 예전 `idempotency/` 패키지(command
|
||||
원장, `WebSocketActorReference`, `WebSocketEndpointName`)는 2026-09-25에 지웠다. 많아야 한 번 돌아야 하는
|
||||
command는 그 유스케이스 안에서 애플리케이션 `IdempotencyExecutor`를 거친다. 범위(scope)는 다시 연결해도
|
||||
살아남는 값(endpoint + actor + 클라이언트 자신의 message id)이고, connection id가 아니다.
|
||||
|
||||
이 모듈은 출하하는 런타임 조립 둘 어디에도 없다. 등록되고 시험된다고 두 범위 중 어느 것도 켜지지 않는다.
|
||||
|
||||
## 허용
|
||||
|
||||
- `@DomainEvent` 표지를 위한 `:domain-core` 등록 의존.
|
||||
- 저장소 BOM이 관리하는 Spring Boot WebSocket·validation starter.
|
||||
- 시험에서만: 내장 Tomcat·Jetty·SockJS·STOMP 클라이언트와 Testcontainers(Nginx lane).
|
||||
|
||||
## 금지
|
||||
|
||||
- 어떤 `adapter:outbound:*` 모듈에든 직접 의존하기.
|
||||
- repository, Spring Data, 영속 엔티티, 업무 정책 접근.
|
||||
- `@DomainEvent` payload를 그대로 보내기, 리플렉션 기반 이벤트 직렬화.
|
||||
- 켜져 있을 때 wildcard·빈 handshake origin.
|
||||
- 익명 handshake, 아무 topic 구독, 클라이언트가 broker destination으로 보내기.
|
||||
- 이 골격 leaf 안의 운영 기능 `@MessageMapping`.
|
||||
- 모듈 안의 YAML 파일. 속성 값은 조립 루트가 가진다.
|
||||
- 이 leaf의 어떤 코드도 하지 않는 동작을 위한 설정 키·flag·catalog. handler가 강제하지 않는 한계는
|
||||
`WebSocketConnectionBudget`의 필드가 아니다.
|
||||
- reactive(WebFlux) WebSocket 코드: 템플릿은 servlet만 쓴다.
|
||||
|
||||
## 타입 있는 설정 (`app.websocket.*`)
|
||||
|
||||
속성 트리 하나와 운영자 env 접두어 하나가 있다: `app.websocket.*` ↔ `APP_WEBSOCKET_*`. STOMP 채널만
|
||||
설정한다. 기본 bootJar에는 이 leaf가 없으니, 이 값은 이 leaf를 채택한 조립에서만 뜻이 있다.
|
||||
|
||||
| 속성 | env | 기본값·역할 |
|
||||
| --- | --- | --- |
|
||||
| `app.websocket.enabled` | `APP_WEBSOCKET_ENABLED` | `true`. `false`이면 STOMP·SockJS 채널을 끈다 |
|
||||
| `app.websocket.endpoint` | `APP_WEBSOCKET_ENDPOINT` | `/ws` |
|
||||
| `app.websocket.allowed-origins` | `APP_WEBSOCKET_ALLOWED_ORIGINS` | `http://localhost:3000`. 명시한 origin만 |
|
||||
| `app.websocket.broadcast-destination` | `APP_WEBSOCKET_BROADCAST_DESTINATION` | `/topic/events` |
|
||||
| `app.websocket.channel-queue-capacity` | `APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY` | `10000`. STOMP 채널마다(클라이언트 inbound, 클라이언트 outbound, broker) 거절하기 전에 쌓아 두는 메시지 수 |
|
||||
| `app.websocket.message-size-limit` | `APP_WEBSOCKET_MESSAGE_SIZE_LIMIT` | `64KB`(Spring 기본값을 이제 명시한다) |
|
||||
| `app.websocket.send-buffer-size-limit` | `APP_WEBSOCKET_SEND_BUFFER_SIZE_LIMIT` | `512KB`(Spring 기본값을 이제 명시한다) |
|
||||
| `app.websocket.send-time-limit` | `APP_WEBSOCKET_SEND_TIME_LIMIT` | `10s`(Spring 기본값을 이제 명시한다) |
|
||||
| `app.websocket.time-to-first-message` | `APP_WEBSOCKET_TIME_TO_FIRST_MESSAGE` | `60s`(Spring 기본값을 이제 명시한다) |
|
||||
| `app.websocket.max-connections` | `APP_WEBSOCKET_MAX_CONNECTIONS` | `1000`. 노드마다 STOMP 세션 수. 그다음 것은 1013으로 닫는다 |
|
||||
|
||||
`WebSocketSettings`는 `@Validated`다. 켜진 상태의 잘못된 설정은 context 기동을 실패시킨다.
|
||||
|
||||
## 이 capability 채택하기
|
||||
|
||||
WebSocket은 기본 bootJar 안에 잠든 기능이 아니라 **빌드 조립에서 고르는 것**이다.
|
||||
|
||||
1. 쓰는 조립의 의존성에 `:adapter:inbound:websocket`을 더하고 `config/architecture/modules.json`에 맞는 허용
|
||||
edge를 더한다.
|
||||
2. 설정 등록은 capability 루트에 둔다. 출하하는 `@ConfigurationPropertiesScan`에
|
||||
`dev.caskeleton.adapter.inbound.websocket`을 다시 더하지 않는다.
|
||||
3. STOMP·SockJS 채널은 이 leaf 자신의 `AutoConfiguration.imports`가 등록하고, leaf가 servlet classpath에
|
||||
있으면 언제나 켜진다. wildcard가 아닌 origin 허용 목록을 정하고, 끄려면 `app.websocket.enabled=false`로
|
||||
한다.
|
||||
4. handler 라이브러리는 README 「라이브러리 API」를 따른다. handler는 bean이어야 한다. 그래야 그
|
||||
`SmartLifecycle` 멈춤(열린 모든 연결에 1001)이 web 서버가 멈추기 전에 돈다.
|
||||
5. 조립을 승격하기 전에 leaf lane과 저장소 conditional-transport 묶음을 돌린다:
|
||||
`./gradlew :adapter:inbound:websocket:test :adapter:inbound:websocket:systemTest :conditionalTransportQualification`.
|
||||
|
||||
## inbound 정책 (STOMP)
|
||||
|
||||
- HTTP upgrade에는 이미 비어 있지 않은 `Principal`이 있어야 한다. 어댑터는 credential을 직접 인증하지 않는다.
|
||||
- STOMP `SUBSCRIBE`는 설정한 broadcast destination에만 허용한다.
|
||||
- 인증된 `SEND`는 `/app/**` 아래에만 허용한다.
|
||||
- 클라이언트가 `/topic/**`나 다른 destination으로 보내는 `SEND`는 거절한다.
|
||||
- 클라이언트에게 보이는 처리 실패는 모두 빈 payload와 정해진 `message` `WEBSOCKET_REQUEST_REJECTED`를 가진
|
||||
ERROR frame이 된다. 그 `error-code` header는 cause chain에서 처음 나오는 `ApiErrorCarrier`가 실은
|
||||
`ApiErrorCode`(`IllegalArgumentException` 뒤에 있어도), `IllegalArgumentException`이면 `BAD_PARAMETER`, 그
|
||||
밖에는 `WEBSOCKET_REQUEST_REJECTED`다.
|
||||
|
||||
## 이벤트 projection 계약
|
||||
|
||||
나중의 기능이 정확히 하나의 `@DomainEvent` 클래스에 대해 `LiveEventProjector<T>` bean을 기여할 수 있다.
|
||||
broadcaster는 projector가 정확히 하나 맞을 때만 보낸다. projector가 없거나 둘 이상이거나, projection이
|
||||
실패하거나, 이벤트 타입이 잘못됐거나, 필드가 null이거나, map이 한계를 넘으면 버린다. wire envelope에는
|
||||
`type`, 한계 있는 문자열 `fields`, `occurredAt`만 있다. broker 채널은 자기 한계 있는 executor를 가지므로,
|
||||
simple broker가 구독자에게 퍼뜨리는 일은 도메인 이벤트를 발행한 스레드에서 돌지 않는다. broker queue가 차면
|
||||
이벤트를 버린다(best-effort, R1).
|
||||
|
||||
템플릿에는 WebSocket 이벤트를 발행하거나 projector를 기여하는 기능이 없다.
|
||||
|
||||
## 증거와 한계
|
||||
|
||||
| lane | 증명하는 것 |
|
||||
| --- | --- |
|
||||
| `test` | STOMP 설정·정책, queue·writer·budget, handler 크기와 넘침 종료 |
|
||||
| `systemTest` | 실제 Tomcat: STOMP 경계(`WebSocketBoundaryQualificationTest`), handler 런타임과 남용 계약, context를 닫으면 1001을 보냄 |
|
||||
| `websocketJettyTest` | Jetty에서 handler 런타임 계약 |
|
||||
| `websocketNginxTest` | 실제 Nginx 뒤의 upgrade·forwarding(Docker 필요. 없으면 실패한다) |
|
||||
| `websocketTransportQualificationTest` | STOMP 경계 시험을 건너뛰지 않고 실행 |
|
||||
|
||||
simple broker는 로컬·단일 프로세스·best-effort R1 증거일 뿐이다. broker relay, 여러 노드·durable 전달,
|
||||
롤백에 안전한 발행, replay·resume은 주지 않는다.
|
||||
@@ -1,120 +1 @@
|
||||
# adapter:inbound:websocket — 고를 때만 켜는 WebSocket·STOMP 경계
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-inbound-websocket`
|
||||
- Gradle 경로: `:adapter:inbound:websocket`
|
||||
- 이 모듈만 시험: `./gradlew :adapter:inbound:websocket:test --console=plain`
|
||||
- 실행 기준: Java 21. Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.inbound.websocket`.
|
||||
|
||||
## 책임
|
||||
|
||||
이 leaf에는 **서로 다른 범위 둘**이 있고, 배포되는 기능 하나로 읽으면 안 된다.
|
||||
|
||||
1. **골라 쓰는 STOMP·SockJS 채널** — `stomp/**`가 Spring 전송 설정, 타입 있는 `app.websocket.*` 설정,
|
||||
handshake principal·origin 검사, destination 정책, 정해진 클라이언트 안전 STOMP `ERROR` 대응, 할 수 있는
|
||||
만큼만 하는(best-effort) 프로세스 안 이벤트 projection을 가진다.
|
||||
2. **servlet handler 라이브러리** — `servlet/`, `outbound/`, `budget/`과 id record 둘
|
||||
`core/WebSocketConnectionId`, `protocol/WebSocketMessageId`. 설정 키도 Spring 설정도 없다: 서비스 자신의
|
||||
어댑터 leaf가 `PlatformWebSocketHandler`를 만들고 등록한다. README 「라이브러리 API」가 진입점과 배선을
|
||||
적는다.
|
||||
|
||||
이 leaf는 command 중복을 걸러 내지 않고 저장소 SPI를 가지지 않는다. 예전 `idempotency/` 패키지(command
|
||||
원장, `WebSocketActorReference`, `WebSocketEndpointName`)는 2026-09-25에 지웠다. 많아야 한 번 돌아야 하는
|
||||
command는 그 유스케이스 안에서 애플리케이션 `IdempotencyExecutor`를 거친다. 범위(scope)는 다시 연결해도
|
||||
살아남는 값(endpoint + actor + 클라이언트 자신의 message id)이고, connection id가 아니다.
|
||||
|
||||
이 모듈은 출하하는 런타임 조립 둘 어디에도 없다. 등록되고 시험된다고 두 범위 중 어느 것도 켜지지 않는다.
|
||||
|
||||
## 허용
|
||||
|
||||
- `@DomainEvent` 표지를 위한 `:domain-core` 등록 의존.
|
||||
- 저장소 BOM이 관리하는 Spring Boot WebSocket·validation starter.
|
||||
- 시험에서만: 내장 Tomcat·Jetty·SockJS·STOMP 클라이언트와 Testcontainers(Nginx lane).
|
||||
|
||||
## 금지
|
||||
|
||||
- 어떤 `adapter:outbound:*` 모듈에든 직접 의존하기.
|
||||
- repository, Spring Data, 영속 엔티티, 업무 정책 접근.
|
||||
- `@DomainEvent` payload를 그대로 보내기, 리플렉션 기반 이벤트 직렬화.
|
||||
- 켜져 있을 때 wildcard·빈 handshake origin.
|
||||
- 익명 handshake, 아무 topic 구독, 클라이언트가 broker destination으로 보내기.
|
||||
- 이 골격 leaf 안의 운영 기능 `@MessageMapping`.
|
||||
- 모듈 안의 YAML 파일. 속성 값은 조립 루트가 가진다.
|
||||
- 이 leaf의 어떤 코드도 하지 않는 동작을 위한 설정 키·flag·catalog. handler가 강제하지 않는 한계는
|
||||
`WebSocketConnectionBudget`의 필드가 아니다.
|
||||
- reactive(WebFlux) WebSocket 코드: 템플릿은 servlet만 쓴다.
|
||||
|
||||
## 타입 있는 설정 (`app.websocket.*`)
|
||||
|
||||
속성 트리 하나와 운영자 env 접두어 하나가 있다: `app.websocket.*` ↔ `APP_WEBSOCKET_*`. STOMP 채널만
|
||||
설정한다. 기본 bootJar에는 이 leaf가 없으니, 이 값은 이 leaf를 채택한 조립에서만 뜻이 있다.
|
||||
|
||||
| 속성 | env | 기본값·역할 |
|
||||
| --- | --- | --- |
|
||||
| `app.websocket.enabled` | `APP_WEBSOCKET_ENABLED` | `true`. `false`이면 STOMP·SockJS 채널을 끈다 |
|
||||
| `app.websocket.endpoint` | `APP_WEBSOCKET_ENDPOINT` | `/ws` |
|
||||
| `app.websocket.allowed-origins` | `APP_WEBSOCKET_ALLOWED_ORIGINS` | `http://localhost:3000`. 명시한 origin만 |
|
||||
| `app.websocket.broadcast-destination` | `APP_WEBSOCKET_BROADCAST_DESTINATION` | `/topic/events` |
|
||||
| `app.websocket.channel-queue-capacity` | `APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY` | `10000`. STOMP 채널마다(클라이언트 inbound, 클라이언트 outbound, broker) 거절하기 전에 쌓아 두는 메시지 수 |
|
||||
| `app.websocket.message-size-limit` | `APP_WEBSOCKET_MESSAGE_SIZE_LIMIT` | `64KB`(Spring 기본값을 이제 명시한다) |
|
||||
| `app.websocket.send-buffer-size-limit` | `APP_WEBSOCKET_SEND_BUFFER_SIZE_LIMIT` | `512KB`(Spring 기본값을 이제 명시한다) |
|
||||
| `app.websocket.send-time-limit` | `APP_WEBSOCKET_SEND_TIME_LIMIT` | `10s`(Spring 기본값을 이제 명시한다) |
|
||||
| `app.websocket.time-to-first-message` | `APP_WEBSOCKET_TIME_TO_FIRST_MESSAGE` | `60s`(Spring 기본값을 이제 명시한다) |
|
||||
| `app.websocket.max-connections` | `APP_WEBSOCKET_MAX_CONNECTIONS` | `1000`. 노드마다 STOMP 세션 수. 그다음 것은 1013으로 닫는다 |
|
||||
|
||||
`WebSocketSettings`는 `@Validated`다. 켜진 상태의 잘못된 설정은 context 기동을 실패시킨다.
|
||||
|
||||
## 이 capability 채택하기
|
||||
|
||||
WebSocket은 기본 bootJar 안에 잠든 기능이 아니라 **빌드 조립에서 고르는 것**이다.
|
||||
|
||||
1. 쓰는 조립의 의존성에 `:adapter:inbound:websocket`을 더하고 `config/architecture/modules.json`에 맞는 허용
|
||||
edge를 더한다.
|
||||
2. 설정 등록은 capability 루트에 둔다. 출하하는 `@ConfigurationPropertiesScan`에
|
||||
`dev.caskeleton.adapter.inbound.websocket`을 다시 더하지 않는다.
|
||||
3. STOMP·SockJS 채널은 이 leaf 자신의 `AutoConfiguration.imports`가 등록하고, leaf가 servlet classpath에
|
||||
있으면 언제나 켜진다. wildcard가 아닌 origin 허용 목록을 정하고, 끄려면 `app.websocket.enabled=false`로
|
||||
한다.
|
||||
4. handler 라이브러리는 README 「라이브러리 API」를 따른다. handler는 bean이어야 한다. 그래야 그
|
||||
`SmartLifecycle` 멈춤(열린 모든 연결에 1001)이 web 서버가 멈추기 전에 돈다.
|
||||
5. 조립을 승격하기 전에 leaf lane과 저장소 conditional-transport 묶음을 돌린다:
|
||||
`./gradlew :adapter:inbound:websocket:test :adapter:inbound:websocket:systemTest :conditionalTransportQualification`.
|
||||
|
||||
## inbound 정책 (STOMP)
|
||||
|
||||
- HTTP upgrade에는 이미 비어 있지 않은 `Principal`이 있어야 한다. 어댑터는 credential을 직접 인증하지 않는다.
|
||||
- STOMP `SUBSCRIBE`는 설정한 broadcast destination에만 허용한다.
|
||||
- 인증된 `SEND`는 `/app/**` 아래에만 허용한다.
|
||||
- 클라이언트가 `/topic/**`나 다른 destination으로 보내는 `SEND`는 거절한다.
|
||||
- 클라이언트에게 보이는 처리 실패는 모두 빈 payload와 정해진 `message` `WEBSOCKET_REQUEST_REJECTED`를 가진
|
||||
ERROR frame이 된다. 그 `error-code` header는 cause chain에서 처음 나오는 `ApiErrorCarrier`가 실은
|
||||
`ApiErrorCode`(`IllegalArgumentException` 뒤에 있어도), `IllegalArgumentException`이면 `BAD_PARAMETER`, 그
|
||||
밖에는 `WEBSOCKET_REQUEST_REJECTED`다.
|
||||
|
||||
## 이벤트 projection 계약
|
||||
|
||||
나중의 기능이 정확히 하나의 `@DomainEvent` 클래스에 대해 `LiveEventProjector<T>` bean을 기여할 수 있다.
|
||||
broadcaster는 projector가 정확히 하나 맞을 때만 보낸다. projector가 없거나 둘 이상이거나, projection이
|
||||
실패하거나, 이벤트 타입이 잘못됐거나, 필드가 null이거나, map이 한계를 넘으면 버린다. wire envelope에는
|
||||
`type`, 한계 있는 문자열 `fields`, `occurredAt`만 있다. broker 채널은 자기 한계 있는 executor를 가지므로,
|
||||
simple broker가 구독자에게 퍼뜨리는 일은 도메인 이벤트를 발행한 스레드에서 돌지 않는다. broker queue가 차면
|
||||
이벤트를 버린다(best-effort, R1).
|
||||
|
||||
템플릿에는 WebSocket 이벤트를 발행하거나 projector를 기여하는 기능이 없다.
|
||||
|
||||
## 증거와 한계
|
||||
|
||||
| lane | 증명하는 것 |
|
||||
| --- | --- |
|
||||
| `test` | STOMP 설정·정책, queue·writer·budget, handler 크기와 넘침 종료 |
|
||||
| `systemTest` | 실제 Tomcat: STOMP 경계(`WebSocketBoundaryQualificationTest`), handler 런타임과 남용 계약, context를 닫으면 1001을 보냄 |
|
||||
| `websocketJettyTest` | Jetty에서 handler 런타임 계약 |
|
||||
| `websocketNginxTest` | 실제 Nginx 뒤의 upgrade·forwarding(Docker 필요. 없으면 실패한다) |
|
||||
| `websocketTransportQualificationTest` | STOMP 경계 시험을 건너뛰지 않고 실행 |
|
||||
|
||||
simple broker는 로컬·단일 프로세스·best-effort R1 증거일 뿐이다. broker relay, 여러 노드·durable 전달,
|
||||
롤백에 안전한 발행, replay·resume은 주지 않는다.
|
||||
@AGENTS.md
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# adapter-inbound-websocket
|
||||
|
||||
모듈 규칙(허용 의존, 설정 키, 테스트 명령)은 [CLAUDE.md](CLAUDE.md)가 SSOT다. 이 문서는 무엇을
|
||||
모듈 규칙(허용 의존, 설정 키, 테스트 명령)은 [AGENTS.md](AGENTS.md)가 SSOT다. 이 문서는 무엇을
|
||||
제공하는지, 어떻게 붙이는지, 왜 이런 모양인지를 적는다.
|
||||
|
||||
이 leaf는 두 가지를 제공한다. 서로 참조하지 않는다.
|
||||
|
||||
@@ -0,0 +1,180 @@
|
||||
# adapter:outbound:cache-redis — cache와 Redis 어댑터
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-cache-redis`
|
||||
- Gradle 경로: `:adapter:outbound:cache-redis`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:cache-redis:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.cache`.
|
||||
|
||||
## 책임
|
||||
|
||||
- `application-core`의 semantic cache 포트를 구현하고, Redis 개념을 core에 드러내지 않는다.
|
||||
- 정해진 물리 키, digest, codec·envelope, program catalog, 타입 있는 Redis 원자 창구, runtime client 연결,
|
||||
capability별 실패 뜻을 가진다.
|
||||
- semantic cache 포트(`CacheRegionPort`) 뒤에서 절대 soft·hard 만료, 쓰기 조건, 키 무효화 표지를 구현한다. TTL
|
||||
jitter도 stampede 보호도 없다. single-flight는 호출자의 몫이다. revision 순서는 포트의
|
||||
`CacheSourceRevisionOrder`다. Lua 사본은 `CacheRegionContract`(application-core testFixtures)가 그 순서에
|
||||
맞추고, `RedisCacheRegionContractTest`와 `LiveRedisCacheRegionContractTest`가 그 계약을 상속한다.
|
||||
- provider 중립 `EdgeRateLimitPort`를 전용 조율 Redis 설정, 연결·admission, 전용 키, 버전 있는 원자 program으로
|
||||
구현한다.
|
||||
- 쓰는 쪽이 semantic 포트로 옮기는 동안 옛 cache router를 떼어 둔다.
|
||||
- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다.
|
||||
- semantic 어댑터가 쓰는 공용 topology client, 연결 lifecycle, `SemanticRedisCommands` 여덟 개, 조건부 Redis
|
||||
runtime 조립은 `:adapter:outbound:redis-runtime`에 의존한다.
|
||||
- 범용 typed SDK는 따로 둔 라이브러리 leaf `:adapter:outbound:redis-sdk`에 둔다(그 `README.md`를 본다). 이
|
||||
leaf는 시험을 포함해 어떤 설정에서도 그것에 의존하지 않는다. SDK의 시험과 lane은 그 leaf에 있다.
|
||||
|
||||
## Redis 런타임과 골라 쓰는 typed SDK (`…cache.redis.runtime`, `…cache.redis.sdk`)
|
||||
|
||||
등록된 leaf 둘, 패키지 둘, 방향 하나: SDK는 runtime 위에 서고, runtime은 SDK를 모른다(runtime 안의
|
||||
`RedisRuntimePackageBoundaryTest`가 그 방향을 지킨다).
|
||||
|
||||
- `:adapter:outbound:redis-runtime`은 운영 기반이다: `RedisRuntimeSettings` 바인딩, credential 해석, topology
|
||||
client, runtime 자신의 lane(`RedisConnectionKind.REGULAR`, `SCRIPT`)을 가진 `RedisRuntimeOwner`,
|
||||
`SemanticRedisCommands`(이 leaf와 health contributor가 보내는 명령 여덟 개), health. `cache-redis`가 이 leaf에
|
||||
의존한다.
|
||||
- `:adapter:outbound:redis-sdk`는 골라 쓰는 범용 typed API를 가진다: `RedisCommandGateway`(`SemanticRedisCommands`를
|
||||
상속), 명령 catalog·정책, operation 예산, 명령 guard, raw·admin surface, programmability, extension — 그리고
|
||||
자기 lane(`RedisSdkLane`: blocking, transaction, admin)과 admin 계정. 서비스가 그것을
|
||||
`RedisLaneContribution`/`RedisAccountContribution` bean으로 runtime에 기여한다(`RedisSdkComposition`).
|
||||
`cache-redis`는 운영에서도 시험에서도 그것에 의존하지 **않는다**.
|
||||
- 이 leaf의 semantic cache·멱등성·rate-limit·lease 어댑터는 runtime의 `SemanticRedisCommands`를 자기의 닫힌
|
||||
semantic program(`RegisteredLuaScript`)으로 보낸다. `CommandPolicyGuard`를 지나지 않고,
|
||||
`redis-command-policy.yml`이 그것을 다루지 않는다.
|
||||
- 정확성을 위해 어떤 role에 Redis가 필요한지는 이 leaf의 `RedisCorrectnessRoleSelectors`가 정하고,
|
||||
`META-INF/spring.factories`에 runtime의 `RedisCorrectnessRequirement`로 등록한다.
|
||||
|
||||
`docs/design/2026-08-07-redis-wrapper-typed-api-design.md`가 설명하는 typed SDK는 출하하는 semantic Redis 어댑터의
|
||||
일부가 아니라 골라 쓰는 라이브러리로 남는다. 전달 상태와 맞춘 이력은
|
||||
`docs/history/plans/2026-08-07-redis-wrapper-typed-api-status.md`에 있다.
|
||||
|
||||
- `sdk.api..`는 공개 계약이다. Spring, Lettuce, Micrometer, SDK 구현 패키지를 import하지 않는다. Reactor는
|
||||
`sdk.api.reactive` 안에만 둔다.
|
||||
- `sdk.lettuce..`가 계약을 구현한다. `sdk.config`는 속성, capability probe, 허가 정본을 가진다.
|
||||
- `:adapter:outbound:redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml`이 골라 쓰는 typed SDK의 명령
|
||||
정책 정본이다. 거기 분류되지 않은 typed SDK 명령은 거절한다. 이 leaf의 semantic capability 어댑터를 위한 정책
|
||||
파일이 아니다.
|
||||
- `sdk.lettuce.operations`가 타입 있는 operation을 구현한다. 거기 있는 모든 것은 Lettuce에 닿는 유일한 이음매인
|
||||
`RedisCommandGateway`를 거치고, 모든 호출은 돌기 전에 `CommandPolicyGuard`의 허가를 받는다. operation에서
|
||||
driver를 직접 부르지 않는다.
|
||||
- `sdk.cluster`는 client 쪽 slot 계산과 cluster 관찰을 가진다. `sdk.api`에만 의존하고 Lettuce를 import하지
|
||||
않는다: slot을 명령을 만들기 전에 계산하므로 `CommandPolicyGuard`가 서버 redirect로 알게 되기 전에 cross-slot
|
||||
요청을 거절할 수 있다.
|
||||
- `sdk.programmability`는 트랜잭션, 등록된 Lua script, 배포된 function 호출을 가진다. 호출 때 script 본문을 받지
|
||||
않는다: catalog가 `EVAL`을 막고 `RedisScriptRegistry` digest의 `EVALSHA`만 닿을 수 있다. `FUNCTION LOAD`는
|
||||
애플리케이션이 아니라 admin plane이다.
|
||||
- 트랜잭션은 `WATCH`/`MULTI`/`EXEC`이고 **절대** 롤백하지 않는다. `TransactionResult`는 「실행됨」이나 「감시한
|
||||
키가 바뀌어서 아무것도 돌지 않음」만 알리고, 이 패키지의 어떤 타입도 다른 뜻을 비치는 말을 주지 않는다.
|
||||
줄 세운 명령은 `QueuedReply`를 돌려주고, 커밋 전에 읽으면 던진다. 그 창 안에서 서버는 `+QUEUED`만 답했기
|
||||
때문이다. 줄 세운 명령도 보통 명령과 같은 `CommandPolicyGuard` 허가를 지난다 — 트랜잭션은 guard를 피하는 길이
|
||||
아니다 — 그리고 창은 던진 callback을 포함해 모든 출구에서 닫는다. `MULTI` 상태로 버려진 연결은 다음 호출자의
|
||||
명령을 소리 없이 줄 세우기 때문이다. queue는 일부러 쓰기 전용이다: 창 안의 읽기로는 분기할 수 없으니,
|
||||
트랜잭션이 기대는 읽기는 그 앞에서 `WATCH` 아래에 둔다.
|
||||
- `sdk.raw`는 승인된 raw 명령 gateway다. catalog가 `RAW_ONLY`로 표시했고 *그리고* 배포가 그 명령에
|
||||
`ApprovedRawCommand`를 등록했을 때만 닿을 수 있다. 보내기 전에 인자에서 키를 다시 파싱해 namespace를 검사한다.
|
||||
명령 이름을 문자열로 받는 메서드를 여기 더하지 않는다.
|
||||
- `sdk.admin`은 읽기 전용 진단 plane이다. 자기 gateway(admin ACL 계정, 자기 연결)를 받고, catalog가 `ADMIN_ONLY`이자
|
||||
읽기 전용으로 분류하지 않은 명령은 모두 거절하며, slow log나 client 목록이 인자·상대 주소·연결 이름을 싣지
|
||||
않게 응답을 걸러 낸다.
|
||||
- `sdk.extensions.*`는 Redis 8 모듈(JSON, Search, Time Series, Probabilistic)을 담는다. 모든 bean은
|
||||
`ifSupported(...)`로 만든다 — capability probe가 정하고, catalog 최소값은 앞 걸러내기일 뿐이다 — 그리고 모두
|
||||
`ExtensionCommandRunner`로 명령을 만들어 guard가 그 키를 본다. Search는 이것을 보여 주는 예외다: index는 키가
|
||||
아니라서 그 이름은 `LettuceRedisSearchOperations`가 직접 namespace를 붙인다.
|
||||
- `RedisSdkModuleBoundaryTest`(`redis-sdk` 안)가 `redis-sdk` 소스 루트를 scan해 내부 패키지 그래프, driver 가두기,
|
||||
아무 문자열 명령 surface 없음, 설계한 모듈 목록을 강제한다.
|
||||
- 설계를 다시 보지 않고 바꾸면 안 되는 결정: 한계 없는 `entries`, `members`, `rangeAll`, `keys` 없음. 선택 사항인
|
||||
R2 허가·예산 없음. 아무 명령 문자열을 받는 overload 없음. timeout 뒤 멱등이 아닌 쓰기의 자동 재시도 없음.
|
||||
metric이나 trace tag에 실제 키 없음.
|
||||
|
||||
## 경계
|
||||
|
||||
- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다.
|
||||
- inbound 전송, 영속 엔티티·repository, bootstrap, 샘플 의존이 없다.
|
||||
- cache 어댑터는 업무상 신선도, 자격, 도메인 대체 규칙을 정하지 않는다.
|
||||
- Redis 물리 TTL은 인코딩한 hard 만료와 같아야 한다. 미래·손상 schema가 보통 miss로 뭉개지면 안 된다.
|
||||
- application·domain 코드는 raw Redis 키, 명령, Lua·Function 이름, SDK 객체, topology, 연결 타입을 받으면 안 된다.
|
||||
- cache의 fail-open 동작을 session, 멱등성, 엄격한 quota, lease, fencing에 다시 쓰면 안 된다.
|
||||
- rate-limit 조립은 `app.cache.redis`, 그 연결, 외부 client 모드, 실패하면 열리는 뜻을 다시 쓰면 안 된다. v1은
|
||||
조율 role이고 실패하면 닫히는 것뿐이다.
|
||||
- standalone runtime·cache 서비스 lane은 R1 증거일 뿐이다. Sentinel·Cluster, TLS·ACL, 영속·재시작, eviction, 장애
|
||||
증거는 R2를 위해 따로 필요하다.
|
||||
|
||||
## 테스트
|
||||
|
||||
이 모듈만 보는 시험은 semantic 어댑터를 `testFixtures(project(':adapter:outbound:redis-runtime'))`의
|
||||
`InMemorySemanticRedisCommands`에 대고 돌린다. `SemanticRedisCommands`의 유일한 fake이고, `StubRedisRuntimeClient`를
|
||||
거쳐 쓴다. R1·R2 승격에는 따로 실제 Redis 서비스 lane이 필요하다. 그 lane을 골랐으면 소리 없이 건너뛰면 안 된다.
|
||||
|
||||
실제 서버 lane이 둘 있다. `redisContainerContractTest`(integration category, `integrationCheck`에만 있다 — 이 leaf의
|
||||
`mainCheck`에도 있었을 때는 main push마다 두 번 돌았다)는 Testcontainers로 자기 Redis를 띄운다 —
|
||||
`config/testing/container-images.properties`의 `redis` image이고 `compose/redis/acl/lane-fixture-accounts.acl`을
|
||||
읽어 들인다 — 그리고 `LiveRedisCacheRegionContractTest`, `LiveRedisDistributedLeaseContractTest`,
|
||||
`LiveRedisIdempotencyStoreContractTest`(메모리 fake도 통과하는 `application-core` 포트 계약),
|
||||
`LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`를 돌린다. 건너뛰기가 있으면 실패한다
|
||||
(2026-11-01부터). 멱등성 계약은 2026-11-03까지 명시할 때만 도는 topology lane에만 있었다. 그래서 Lua 상태 기계의
|
||||
낡은 handle, 갱신 거절, 재시도 경우가 어느 게이트에서도 실제 서버에 닿지 않았다. `RedisTestContainer`는 그 lane이
|
||||
ACL 파일을 이름으로 댈 때만 서버를 띄운다.
|
||||
|
||||
`redisTopologyTest`는 외부 topology lane이고 `ca.redis-topology-lane`으로 선언한다. 이 leaf는 `standalone`과
|
||||
`cluster`(`LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`)를 선언한다. `redis-runtime`과
|
||||
`redis-sdk`는 자기 클래스에 대해 자기 lane을 선언한다. 고를 때만 돌고 실패하면 닫힌다: 모드는 `standalone`,
|
||||
`sentinel`, `cluster`, `tls` 중 이 leaf가 선언한 것이어야 하고, endpoint 속성이 있어야 하며(`sentinel`은
|
||||
`redis.topology.master`가, `tls`는 `redis.topology.trust-material`이 더 필요하다), 시험을 하나도 찾지 못하거나
|
||||
돌리지 않은 실행은 실패하고(그것은 이 leaf가 아니라 규약이 가진다), leaf가 `redisTopologyLane`에 적은 클래스가
|
||||
실제로 돌았어야 하며, 건너뛴 시험은 실행한 것으로 세지 않고 실행을 실패시킨다. `tls`는 배포 모드가 아니라
|
||||
lane이다 — 모양은 standalone이고 태스크가 그렇게 대응시킨다. 검증하는 것이 전송이기 때문이다.
|
||||
|
||||
예전 검사 둘은 없어졌다. 시험 소스에서 글자 그대로 `@Tag("redis-topology")`를 찾는 scan은
|
||||
`failOnNoDiscoveredTests`가 이미 내는 실패의 메시지를 낫게 할 뿐이었고, 같은 글을 담은 주석으로도 만족됐다. 손으로
|
||||
관리하던 모드별 실행 수 하한(20/20/24/4)은 경우를 더하거나 뺄 때마다 고쳐야 했고, 그것이 잡는 「덮는 범위가
|
||||
줄었다」는 런타임·배포·데이터·보안·컴파일 실패가 아니다.
|
||||
|
||||
## 조립
|
||||
|
||||
`RedisRuntimeAutoConfiguration`은 이제 `:adapter:outbound:redis-runtime`의 것이다. Redis 설정과 공용 runtime 기반이
|
||||
생기는 유일한 곳이고, `app.redis.enabled`(env `APP_REDIS_ENABLED`, 기본 `true` — 모듈이 있으면 켜진다)가 true인
|
||||
동안에만 있다. topology client, 연결 owner, health contributor를 만든다. 이 leaf의 `RedisCapabilityConfig`(자기
|
||||
`AutoConfiguration.imports`)가 그 runtime 위에 semantic 포트를 조립한다.
|
||||
|
||||
골라 쓰는 `:adapter:outbound:redis-sdk`는 출하하는 애플리케이션이 자동으로 조립하지 않는다. 그
|
||||
`RedisStartupProbe`는 라이브러리 API이고 숨은 운영 guard가 아니다. 특히 `APP_REDIS_ACKNOWLEDGED_WRITE_LOSS_ACCEPTED`
|
||||
스위치는 없다: 그 거래를 받아들이는 것은 운영 호출자가 없는 공개 설정이 아니라 probe를 부르는 곳의 명시한 인자여야
|
||||
한다.
|
||||
|
||||
모든 capability는 `CapabilityKeyspace`를 거쳐 `app.redis.namespace`의 namespace 하나 —
|
||||
`{environment}:{service}:{domain}` — 아래에 키를 만든다. capability에 자기 접두어 token을 주지 않는다: capability 넷이
|
||||
각자 자유 문자열 둘을 이어 붙였더니 키 모양이 넷이 됐고, 배포의 ACL pattern은 그중 어느 것과도 맞지 않았다.
|
||||
|
||||
lane은 서로 다른 계정으로 인증한다. `RedisLane.account()`가 lane의 `RedisAccount`를 이름으로 대고, topology factory는
|
||||
*설정한* 계정마다 client를 하나 만든다 — 그래서 계정이 하나인 배포는 여전히 client 하나와 event loop 하나만 가진다.
|
||||
`SCRIPT` lane이 그것이 있는 이유다: `SCRIPT LOAD`와 `EVALSHA`는 advanced 계정의 것이라서, cache 항목을 읽는 계정은
|
||||
script를 실행할 수 없다.
|
||||
|
||||
cache의 조건부 쓰기는 같은 계정이지만 자기 lane `CacheScriptLane.CACHE_SCRIPT`에서 돈다
|
||||
(`app.capabilities.cache.maximum-script-connections`, `RedisCacheConfig`가 `RedisLaneContribution`으로 기여한다).
|
||||
`SCRIPT`로 되돌리지 않는다: 그 lane은 멱등성·rate-limit·lease의 예산이고, 부하를 받는 cache가 그것을 가져가면
|
||||
안 된다(2026-11-03에 정함). lane마다 기다림, 거절, 재연결은 `redis-runtime`의 meter(`RedisLaneMetrics`, `redis.lane.*`,
|
||||
tag `lane`)이다. 그래서 cache가 `SCRIPT`를 쓰지 않는지는 짐작이 아니라 조회로 안다. `DEGRADED` health 순서는
|
||||
`redis-runtime`과 함께 나가고, 그 leaf가 상태를 알린다(`config/module-defaults/redis-runtime.yml`).
|
||||
|
||||
Cluster 트랜잭션은 노드 하나에서 돈다. 그래서 SDK의 `RedisTransactionRunner`는 감시한 키(또는 명시한
|
||||
`RedisSlotTag`)에서 routing 키를 끌어내고, 그 slot을 가진 노드에서 키의 주인에 고정된 `RedisSdkLane.TRANSACTION`을
|
||||
빌린다. route된 lease는 pool에 두지 않는다: pool에 둔 연결은 앞 호출자의 노드에 고정되어 있다.
|
||||
|
||||
설정 바인딩은 capability 기준 4(접두어 하나, `StrictSettingsBinder`)의 기록된 예외다(2026-11-03에 정함):
|
||||
`app.redis.*`는 `redis-runtime`이 setter와 `validate()`로 바인딩한다. 그 leaf는 프로젝트 의존이 없어서
|
||||
`StrictSettingsBinder`(support)에 닿을 수 없기 때문이다. `app.capabilities.*`(cache, lease, rate-limit provider)는 이
|
||||
leaf가 공용 capability 선택 루트 아래에서 엄격하게 바인딩한다. `app.rate-limit.*`은 이 leaf가 읽기만 하는 HTTP
|
||||
경계의 스위치다. 키 이름을 바꾸면 동작 이득 없이 모든 배포의 환경이 깨지니 세 트리를 그대로 둔다. 새 Redis 설정은
|
||||
그중 하나에 넣고, 네 번째 트리를 만들지 않는다.
|
||||
|
||||
`RedisRuntimeSettings`에는 클래스 수준 `@ConfigurationProperties`를 달면 안 된다: `RedisRuntimeAutoConfiguration`이
|
||||
그것을 바인딩하므로 `APP_REDIS_ENABLED=false`이면 Redis 설정을 하나도 바인딩하지 않는다. 이 패키지에 닿는
|
||||
properties scan은 그래도 그것을 바인딩하게 된다(bootstrap의 `@ConfigurationPropertiesScan`은
|
||||
`dev.caskeleton.bootstrap.*` 패키지만 적는다). role 선택자(cache 바인딩, session 인증 모드, 멱등성·lease·rate-limit
|
||||
provider)는 어떤 capability를 조립할지 고른다. 그중 어느 것도 Redis를 켜지 않고, 전역 스위치가 꺼져 있으면 이
|
||||
모듈은 bean을 하나도 기여하지 않는다.
|
||||
@@ -1,180 +1 @@
|
||||
# adapter:outbound:cache-redis — cache와 Redis 어댑터
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-cache-redis`
|
||||
- Gradle 경로: `:adapter:outbound:cache-redis`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:cache-redis:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.cache`.
|
||||
|
||||
## 책임
|
||||
|
||||
- `application-core`의 semantic cache 포트를 구현하고, Redis 개념을 core에 드러내지 않는다.
|
||||
- 정해진 물리 키, digest, codec·envelope, program catalog, 타입 있는 Redis 원자 창구, runtime client 연결,
|
||||
capability별 실패 뜻을 가진다.
|
||||
- semantic cache 포트(`CacheRegionPort`) 뒤에서 절대 soft·hard 만료, 쓰기 조건, 키 무효화 표지를 구현한다. TTL
|
||||
jitter도 stampede 보호도 없다. single-flight는 호출자의 몫이다. revision 순서는 포트의
|
||||
`CacheSourceRevisionOrder`다. Lua 사본은 `CacheRegionContract`(application-core testFixtures)가 그 순서에
|
||||
맞추고, `RedisCacheRegionContractTest`와 `LiveRedisCacheRegionContractTest`가 그 계약을 상속한다.
|
||||
- provider 중립 `EdgeRateLimitPort`를 전용 조율 Redis 설정, 연결·admission, 전용 키, 버전 있는 원자 program으로
|
||||
구현한다.
|
||||
- 쓰는 쪽이 semantic 포트로 옮기는 동안 옛 cache router를 떼어 둔다.
|
||||
- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다.
|
||||
- semantic 어댑터가 쓰는 공용 topology client, 연결 lifecycle, `SemanticRedisCommands` 여덟 개, 조건부 Redis
|
||||
runtime 조립은 `:adapter:outbound:redis-runtime`에 의존한다.
|
||||
- 범용 typed SDK는 따로 둔 라이브러리 leaf `:adapter:outbound:redis-sdk`에 둔다(그 `README.md`를 본다). 이
|
||||
leaf는 시험을 포함해 어떤 설정에서도 그것에 의존하지 않는다. SDK의 시험과 lane은 그 leaf에 있다.
|
||||
|
||||
## Redis 런타임과 골라 쓰는 typed SDK (`…cache.redis.runtime`, `…cache.redis.sdk`)
|
||||
|
||||
등록된 leaf 둘, 패키지 둘, 방향 하나: SDK는 runtime 위에 서고, runtime은 SDK를 모른다(runtime 안의
|
||||
`RedisRuntimePackageBoundaryTest`가 그 방향을 지킨다).
|
||||
|
||||
- `:adapter:outbound:redis-runtime`은 운영 기반이다: `RedisRuntimeSettings` 바인딩, credential 해석, topology
|
||||
client, runtime 자신의 lane(`RedisConnectionKind.REGULAR`, `SCRIPT`)을 가진 `RedisRuntimeOwner`,
|
||||
`SemanticRedisCommands`(이 leaf와 health contributor가 보내는 명령 여덟 개), health. `cache-redis`가 이 leaf에
|
||||
의존한다.
|
||||
- `:adapter:outbound:redis-sdk`는 골라 쓰는 범용 typed API를 가진다: `RedisCommandGateway`(`SemanticRedisCommands`를
|
||||
상속), 명령 catalog·정책, operation 예산, 명령 guard, raw·admin surface, programmability, extension — 그리고
|
||||
자기 lane(`RedisSdkLane`: blocking, transaction, admin)과 admin 계정. 서비스가 그것을
|
||||
`RedisLaneContribution`/`RedisAccountContribution` bean으로 runtime에 기여한다(`RedisSdkComposition`).
|
||||
`cache-redis`는 운영에서도 시험에서도 그것에 의존하지 **않는다**.
|
||||
- 이 leaf의 semantic cache·멱등성·rate-limit·lease 어댑터는 runtime의 `SemanticRedisCommands`를 자기의 닫힌
|
||||
semantic program(`RegisteredLuaScript`)으로 보낸다. `CommandPolicyGuard`를 지나지 않고,
|
||||
`redis-command-policy.yml`이 그것을 다루지 않는다.
|
||||
- 정확성을 위해 어떤 role에 Redis가 필요한지는 이 leaf의 `RedisCorrectnessRoleSelectors`가 정하고,
|
||||
`META-INF/spring.factories`에 runtime의 `RedisCorrectnessRequirement`로 등록한다.
|
||||
|
||||
`docs/design/2026-08-07-redis-wrapper-typed-api-design.md`가 설명하는 typed SDK는 출하하는 semantic Redis 어댑터의
|
||||
일부가 아니라 골라 쓰는 라이브러리로 남는다. 전달 상태와 맞춘 이력은
|
||||
`docs/history/plans/2026-08-07-redis-wrapper-typed-api-status.md`에 있다.
|
||||
|
||||
- `sdk.api..`는 공개 계약이다. Spring, Lettuce, Micrometer, SDK 구현 패키지를 import하지 않는다. Reactor는
|
||||
`sdk.api.reactive` 안에만 둔다.
|
||||
- `sdk.lettuce..`가 계약을 구현한다. `sdk.config`는 속성, capability probe, 허가 정본을 가진다.
|
||||
- `:adapter:outbound:redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml`이 골라 쓰는 typed SDK의 명령
|
||||
정책 정본이다. 거기 분류되지 않은 typed SDK 명령은 거절한다. 이 leaf의 semantic capability 어댑터를 위한 정책
|
||||
파일이 아니다.
|
||||
- `sdk.lettuce.operations`가 타입 있는 operation을 구현한다. 거기 있는 모든 것은 Lettuce에 닿는 유일한 이음매인
|
||||
`RedisCommandGateway`를 거치고, 모든 호출은 돌기 전에 `CommandPolicyGuard`의 허가를 받는다. operation에서
|
||||
driver를 직접 부르지 않는다.
|
||||
- `sdk.cluster`는 client 쪽 slot 계산과 cluster 관찰을 가진다. `sdk.api`에만 의존하고 Lettuce를 import하지
|
||||
않는다: slot을 명령을 만들기 전에 계산하므로 `CommandPolicyGuard`가 서버 redirect로 알게 되기 전에 cross-slot
|
||||
요청을 거절할 수 있다.
|
||||
- `sdk.programmability`는 트랜잭션, 등록된 Lua script, 배포된 function 호출을 가진다. 호출 때 script 본문을 받지
|
||||
않는다: catalog가 `EVAL`을 막고 `RedisScriptRegistry` digest의 `EVALSHA`만 닿을 수 있다. `FUNCTION LOAD`는
|
||||
애플리케이션이 아니라 admin plane이다.
|
||||
- 트랜잭션은 `WATCH`/`MULTI`/`EXEC`이고 **절대** 롤백하지 않는다. `TransactionResult`는 「실행됨」이나 「감시한
|
||||
키가 바뀌어서 아무것도 돌지 않음」만 알리고, 이 패키지의 어떤 타입도 다른 뜻을 비치는 말을 주지 않는다.
|
||||
줄 세운 명령은 `QueuedReply`를 돌려주고, 커밋 전에 읽으면 던진다. 그 창 안에서 서버는 `+QUEUED`만 답했기
|
||||
때문이다. 줄 세운 명령도 보통 명령과 같은 `CommandPolicyGuard` 허가를 지난다 — 트랜잭션은 guard를 피하는 길이
|
||||
아니다 — 그리고 창은 던진 callback을 포함해 모든 출구에서 닫는다. `MULTI` 상태로 버려진 연결은 다음 호출자의
|
||||
명령을 소리 없이 줄 세우기 때문이다. queue는 일부러 쓰기 전용이다: 창 안의 읽기로는 분기할 수 없으니,
|
||||
트랜잭션이 기대는 읽기는 그 앞에서 `WATCH` 아래에 둔다.
|
||||
- `sdk.raw`는 승인된 raw 명령 gateway다. catalog가 `RAW_ONLY`로 표시했고 *그리고* 배포가 그 명령에
|
||||
`ApprovedRawCommand`를 등록했을 때만 닿을 수 있다. 보내기 전에 인자에서 키를 다시 파싱해 namespace를 검사한다.
|
||||
명령 이름을 문자열로 받는 메서드를 여기 더하지 않는다.
|
||||
- `sdk.admin`은 읽기 전용 진단 plane이다. 자기 gateway(admin ACL 계정, 자기 연결)를 받고, catalog가 `ADMIN_ONLY`이자
|
||||
읽기 전용으로 분류하지 않은 명령은 모두 거절하며, slow log나 client 목록이 인자·상대 주소·연결 이름을 싣지
|
||||
않게 응답을 걸러 낸다.
|
||||
- `sdk.extensions.*`는 Redis 8 모듈(JSON, Search, Time Series, Probabilistic)을 담는다. 모든 bean은
|
||||
`ifSupported(...)`로 만든다 — capability probe가 정하고, catalog 최소값은 앞 걸러내기일 뿐이다 — 그리고 모두
|
||||
`ExtensionCommandRunner`로 명령을 만들어 guard가 그 키를 본다. Search는 이것을 보여 주는 예외다: index는 키가
|
||||
아니라서 그 이름은 `LettuceRedisSearchOperations`가 직접 namespace를 붙인다.
|
||||
- `RedisSdkModuleBoundaryTest`(`redis-sdk` 안)가 `redis-sdk` 소스 루트를 scan해 내부 패키지 그래프, driver 가두기,
|
||||
아무 문자열 명령 surface 없음, 설계한 모듈 목록을 강제한다.
|
||||
- 설계를 다시 보지 않고 바꾸면 안 되는 결정: 한계 없는 `entries`, `members`, `rangeAll`, `keys` 없음. 선택 사항인
|
||||
R2 허가·예산 없음. 아무 명령 문자열을 받는 overload 없음. timeout 뒤 멱등이 아닌 쓰기의 자동 재시도 없음.
|
||||
metric이나 trace tag에 실제 키 없음.
|
||||
|
||||
## 경계
|
||||
|
||||
- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다.
|
||||
- inbound 전송, 영속 엔티티·repository, bootstrap, 샘플 의존이 없다.
|
||||
- cache 어댑터는 업무상 신선도, 자격, 도메인 대체 규칙을 정하지 않는다.
|
||||
- Redis 물리 TTL은 인코딩한 hard 만료와 같아야 한다. 미래·손상 schema가 보통 miss로 뭉개지면 안 된다.
|
||||
- application·domain 코드는 raw Redis 키, 명령, Lua·Function 이름, SDK 객체, topology, 연결 타입을 받으면 안 된다.
|
||||
- cache의 fail-open 동작을 session, 멱등성, 엄격한 quota, lease, fencing에 다시 쓰면 안 된다.
|
||||
- rate-limit 조립은 `app.cache.redis`, 그 연결, 외부 client 모드, 실패하면 열리는 뜻을 다시 쓰면 안 된다. v1은
|
||||
조율 role이고 실패하면 닫히는 것뿐이다.
|
||||
- standalone runtime·cache 서비스 lane은 R1 증거일 뿐이다. Sentinel·Cluster, TLS·ACL, 영속·재시작, eviction, 장애
|
||||
증거는 R2를 위해 따로 필요하다.
|
||||
|
||||
## 테스트
|
||||
|
||||
이 모듈만 보는 시험은 semantic 어댑터를 `testFixtures(project(':adapter:outbound:redis-runtime'))`의
|
||||
`InMemorySemanticRedisCommands`에 대고 돌린다. `SemanticRedisCommands`의 유일한 fake이고, `StubRedisRuntimeClient`를
|
||||
거쳐 쓴다. R1·R2 승격에는 따로 실제 Redis 서비스 lane이 필요하다. 그 lane을 골랐으면 소리 없이 건너뛰면 안 된다.
|
||||
|
||||
실제 서버 lane이 둘 있다. `redisContainerContractTest`(integration category, `integrationCheck`에만 있다 — 이 leaf의
|
||||
`mainCheck`에도 있었을 때는 main push마다 두 번 돌았다)는 Testcontainers로 자기 Redis를 띄운다 —
|
||||
`config/testing/container-images.properties`의 `redis` image이고 `compose/redis/acl/lane-fixture-accounts.acl`을
|
||||
읽어 들인다 — 그리고 `LiveRedisCacheRegionContractTest`, `LiveRedisDistributedLeaseContractTest`,
|
||||
`LiveRedisIdempotencyStoreContractTest`(메모리 fake도 통과하는 `application-core` 포트 계약),
|
||||
`LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`를 돌린다. 건너뛰기가 있으면 실패한다
|
||||
(2026-11-01부터). 멱등성 계약은 2026-11-03까지 명시할 때만 도는 topology lane에만 있었다. 그래서 Lua 상태 기계의
|
||||
낡은 handle, 갱신 거절, 재시도 경우가 어느 게이트에서도 실제 서버에 닿지 않았다. `RedisTestContainer`는 그 lane이
|
||||
ACL 파일을 이름으로 댈 때만 서버를 띄운다.
|
||||
|
||||
`redisTopologyTest`는 외부 topology lane이고 `ca.redis-topology-lane`으로 선언한다. 이 leaf는 `standalone`과
|
||||
`cluster`(`LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`)를 선언한다. `redis-runtime`과
|
||||
`redis-sdk`는 자기 클래스에 대해 자기 lane을 선언한다. 고를 때만 돌고 실패하면 닫힌다: 모드는 `standalone`,
|
||||
`sentinel`, `cluster`, `tls` 중 이 leaf가 선언한 것이어야 하고, endpoint 속성이 있어야 하며(`sentinel`은
|
||||
`redis.topology.master`가, `tls`는 `redis.topology.trust-material`이 더 필요하다), 시험을 하나도 찾지 못하거나
|
||||
돌리지 않은 실행은 실패하고(그것은 이 leaf가 아니라 규약이 가진다), leaf가 `redisTopologyLane`에 적은 클래스가
|
||||
실제로 돌았어야 하며, 건너뛴 시험은 실행한 것으로 세지 않고 실행을 실패시킨다. `tls`는 배포 모드가 아니라
|
||||
lane이다 — 모양은 standalone이고 태스크가 그렇게 대응시킨다. 검증하는 것이 전송이기 때문이다.
|
||||
|
||||
예전 검사 둘은 없어졌다. 시험 소스에서 글자 그대로 `@Tag("redis-topology")`를 찾는 scan은
|
||||
`failOnNoDiscoveredTests`가 이미 내는 실패의 메시지를 낫게 할 뿐이었고, 같은 글을 담은 주석으로도 만족됐다. 손으로
|
||||
관리하던 모드별 실행 수 하한(20/20/24/4)은 경우를 더하거나 뺄 때마다 고쳐야 했고, 그것이 잡는 「덮는 범위가
|
||||
줄었다」는 런타임·배포·데이터·보안·컴파일 실패가 아니다.
|
||||
|
||||
## 조립
|
||||
|
||||
`RedisRuntimeAutoConfiguration`은 이제 `:adapter:outbound:redis-runtime`의 것이다. Redis 설정과 공용 runtime 기반이
|
||||
생기는 유일한 곳이고, `app.redis.enabled`(env `APP_REDIS_ENABLED`, 기본 `true` — 모듈이 있으면 켜진다)가 true인
|
||||
동안에만 있다. topology client, 연결 owner, health contributor를 만든다. 이 leaf의 `RedisCapabilityConfig`(자기
|
||||
`AutoConfiguration.imports`)가 그 runtime 위에 semantic 포트를 조립한다.
|
||||
|
||||
골라 쓰는 `:adapter:outbound:redis-sdk`는 출하하는 애플리케이션이 자동으로 조립하지 않는다. 그
|
||||
`RedisStartupProbe`는 라이브러리 API이고 숨은 운영 guard가 아니다. 특히 `APP_REDIS_ACKNOWLEDGED_WRITE_LOSS_ACCEPTED`
|
||||
스위치는 없다: 그 거래를 받아들이는 것은 운영 호출자가 없는 공개 설정이 아니라 probe를 부르는 곳의 명시한 인자여야
|
||||
한다.
|
||||
|
||||
모든 capability는 `CapabilityKeyspace`를 거쳐 `app.redis.namespace`의 namespace 하나 —
|
||||
`{environment}:{service}:{domain}` — 아래에 키를 만든다. capability에 자기 접두어 token을 주지 않는다: capability 넷이
|
||||
각자 자유 문자열 둘을 이어 붙였더니 키 모양이 넷이 됐고, 배포의 ACL pattern은 그중 어느 것과도 맞지 않았다.
|
||||
|
||||
lane은 서로 다른 계정으로 인증한다. `RedisLane.account()`가 lane의 `RedisAccount`를 이름으로 대고, topology factory는
|
||||
*설정한* 계정마다 client를 하나 만든다 — 그래서 계정이 하나인 배포는 여전히 client 하나와 event loop 하나만 가진다.
|
||||
`SCRIPT` lane이 그것이 있는 이유다: `SCRIPT LOAD`와 `EVALSHA`는 advanced 계정의 것이라서, cache 항목을 읽는 계정은
|
||||
script를 실행할 수 없다.
|
||||
|
||||
cache의 조건부 쓰기는 같은 계정이지만 자기 lane `CacheScriptLane.CACHE_SCRIPT`에서 돈다
|
||||
(`app.capabilities.cache.maximum-script-connections`, `RedisCacheConfig`가 `RedisLaneContribution`으로 기여한다).
|
||||
`SCRIPT`로 되돌리지 않는다: 그 lane은 멱등성·rate-limit·lease의 예산이고, 부하를 받는 cache가 그것을 가져가면
|
||||
안 된다(2026-11-03에 정함). lane마다 기다림, 거절, 재연결은 `redis-runtime`의 meter(`RedisLaneMetrics`, `redis.lane.*`,
|
||||
tag `lane`)이다. 그래서 cache가 `SCRIPT`를 쓰지 않는지는 짐작이 아니라 조회로 안다. `DEGRADED` health 순서는
|
||||
`redis-runtime`과 함께 나가고, 그 leaf가 상태를 알린다(`config/module-defaults/redis-runtime.yml`).
|
||||
|
||||
Cluster 트랜잭션은 노드 하나에서 돈다. 그래서 SDK의 `RedisTransactionRunner`는 감시한 키(또는 명시한
|
||||
`RedisSlotTag`)에서 routing 키를 끌어내고, 그 slot을 가진 노드에서 키의 주인에 고정된 `RedisSdkLane.TRANSACTION`을
|
||||
빌린다. route된 lease는 pool에 두지 않는다: pool에 둔 연결은 앞 호출자의 노드에 고정되어 있다.
|
||||
|
||||
설정 바인딩은 capability 기준 4(접두어 하나, `StrictSettingsBinder`)의 기록된 예외다(2026-11-03에 정함):
|
||||
`app.redis.*`는 `redis-runtime`이 setter와 `validate()`로 바인딩한다. 그 leaf는 프로젝트 의존이 없어서
|
||||
`StrictSettingsBinder`(support)에 닿을 수 없기 때문이다. `app.capabilities.*`(cache, lease, rate-limit provider)는 이
|
||||
leaf가 공용 capability 선택 루트 아래에서 엄격하게 바인딩한다. `app.rate-limit.*`은 이 leaf가 읽기만 하는 HTTP
|
||||
경계의 스위치다. 키 이름을 바꾸면 동작 이득 없이 모든 배포의 환경이 깨지니 세 트리를 그대로 둔다. 새 Redis 설정은
|
||||
그중 하나에 넣고, 네 번째 트리를 만들지 않는다.
|
||||
|
||||
`RedisRuntimeSettings`에는 클래스 수준 `@ConfigurationProperties`를 달면 안 된다: `RedisRuntimeAutoConfiguration`이
|
||||
그것을 바인딩하므로 `APP_REDIS_ENABLED=false`이면 Redis 설정을 하나도 바인딩하지 않는다. 이 패키지에 닿는
|
||||
properties scan은 그래도 그것을 바인딩하게 된다(bootstrap의 `@ConfigurationPropertiesScan`은
|
||||
`dev.caskeleton.bootstrap.*` 패키지만 적는다). role 선택자(cache 바인딩, session 인증 모드, 멱등성·lease·rate-limit
|
||||
provider)는 어떤 capability를 조립할지 고른다. 그중 어느 것도 Redis를 켜지 않고, 전역 스위치가 꺼져 있으면 이
|
||||
모듈은 bean을 하나도 기여하지 않는다.
|
||||
@AGENTS.md
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
# adapter:outbound:fileserver — 모듈 규칙
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-fileserver`
|
||||
- Gradle 경로: `:adapter:outbound:fileserver`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:fileserver:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.fileserver.platform`. HTTP 파일 서버 플랫폼의 driven
|
||||
(outbound) 어댑터다: `application-fileserver` 포트(내용 저장, 검증, 식별자, 감사, metric)를 구현한다.
|
||||
설계 근거는 [README.md](README.md)에 있다.
|
||||
|
||||
## 책임
|
||||
|
||||
- `application-fileserver` 포트 뒤의 로컬 파일 시스템 내용 저장, 검증, 식별자, 감사, metric.
|
||||
- `app.fileserver-platform.*`(기본 꺼짐)으로만 켠다. 이 leaf의 `AutoConfiguration.imports`에 등록한
|
||||
`platform.autoconfigure.FileserverCapabilityAutoConfiguration`에서 켜진다.
|
||||
- 자세한 전송·보안·운영 계약은 `docs/fileserver/` 아래에 있다. 인증된 동작은
|
||||
`docs/fileserver/support-matrix.md`가 적는다.
|
||||
|
||||
## 허용
|
||||
|
||||
- 프로젝트 의존: 정본은 `src/config/architecture/modules.json`의 `adapter-outbound-fileserver` 항목이고
|
||||
`src/build.gradle`이 강제한다. `:domain-core`는 없다.
|
||||
- 외부 런타임: JDK 파일 시스템, `spring-boot-autoconfigure`, `micrometer-core`, `slf4j-api`.
|
||||
|
||||
## 금지
|
||||
|
||||
- inbound 어댑터, 영속, `app-bootstrap`(ArchUnit `OUTBOUND_ADAPTERS_*` 규칙 묶음).
|
||||
- 파일 시스템·stream·프레임워크·provider 타입을 application 포트 너머로 새게 하기.
|
||||
- `docs/fileserver/support-matrix.md`가 적지 않은 플랫폼 기능을 구현됐다고 내세우기.
|
||||
- 줄 안에 완전한 이름으로 쓴 타입 참조, 파일 하나에 공개 최상위 타입 둘 이상.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:outbound:fileserver:check
|
||||
```
|
||||
@@ -1,41 +1 @@
|
||||
# adapter:outbound:fileserver — 모듈 규칙
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-fileserver`
|
||||
- Gradle 경로: `:adapter:outbound:fileserver`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:fileserver:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.fileserver.platform`. HTTP 파일 서버 플랫폼의 driven
|
||||
(outbound) 어댑터다: `application-fileserver` 포트(내용 저장, 검증, 식별자, 감사, metric)를 구현한다.
|
||||
설계 근거는 [README.md](README.md)에 있다.
|
||||
|
||||
## 책임
|
||||
|
||||
- `application-fileserver` 포트 뒤의 로컬 파일 시스템 내용 저장, 검증, 식별자, 감사, metric.
|
||||
- `app.fileserver-platform.*`(기본 꺼짐)으로만 켠다. 이 leaf의 `AutoConfiguration.imports`에 등록한
|
||||
`platform.autoconfigure.FileserverCapabilityAutoConfiguration`에서 켜진다.
|
||||
- 자세한 전송·보안·운영 계약은 `docs/fileserver/` 아래에 있다. 인증된 동작은
|
||||
`docs/fileserver/support-matrix.md`가 적는다.
|
||||
|
||||
## 허용
|
||||
|
||||
- 프로젝트 의존: 정본은 `src/config/architecture/modules.json`의 `adapter-outbound-fileserver` 항목이고
|
||||
`src/build.gradle`이 강제한다. `:domain-core`는 없다.
|
||||
- 외부 런타임: JDK 파일 시스템, `spring-boot-autoconfigure`, `micrometer-core`, `slf4j-api`.
|
||||
|
||||
## 금지
|
||||
|
||||
- inbound 어댑터, 영속, `app-bootstrap`(ArchUnit `OUTBOUND_ADAPTERS_*` 규칙 묶음).
|
||||
- 파일 시스템·stream·프레임워크·provider 타입을 application 포트 너머로 새게 하기.
|
||||
- `docs/fileserver/support-matrix.md`가 적지 않은 플랫폼 기능을 구현됐다고 내세우기.
|
||||
- 줄 안에 완전한 이름으로 쓴 타입 참조, 파일 하나에 공개 최상위 타입 둘 이상.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:outbound:fileserver:check
|
||||
```
|
||||
@AGENTS.md
|
||||
|
||||
@@ -5,7 +5,7 @@ HTTP 파일 서버 플랫폼의 outbound(driven) 어댑터다. 패키지 루트:
|
||||
시스템 내용 저장, 업로드 검증, 식별자, 감사, metric.
|
||||
|
||||
허용·금지 운영 의존 정책은 `src/config/architecture/modules.json`의 `adapter-outbound-fileserver` 항목이
|
||||
가진다. 루트 Gradle 검증이 그 registry를 읽는다. 모듈 규칙은 [CLAUDE.md](CLAUDE.md)에 있다.
|
||||
가진다. 루트 Gradle 검증이 그 registry를 읽는다. 모듈 규칙은 [AGENTS.md](AGENTS.md)에 있다.
|
||||
|
||||
전송·보안·설정·운영 계약은 `docs/fileserver/`에 있다. 이 파일 서버 플랫폼과 Object Storage 중 무엇을
|
||||
고를지에 대한 저장소 단위 선택은
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
# adapter:outbound:httpclient — HTTP client 플랫폼
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-httpclient`
|
||||
- Gradle 경로: `:adapter:outbound:httpclient`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:httpclient:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.httpclient`.
|
||||
|
||||
## 설계 정본
|
||||
|
||||
구현은 `docs/design/2026-08-08-httpclient-platform-design.md`를 따른다. 설계는 Gradle 모듈 19개를 따로 두는
|
||||
것을 전제한다. 이 저장소의 실패하면 닫히는 registry가 그 배치보다 앞서므로, 그 모듈들은 여기서 **패키지**다.
|
||||
그 대응과 그 밖에 일부러 바꾼 것은 모두 `docs/httpclient/repository-adaptation.md`에 적혀 있다. 타입을 다른
|
||||
패키지로 옮기기 전에 그것을 읽는다.
|
||||
|
||||
## 책임
|
||||
|
||||
- 공개 호출 surface를 가진다: H1 typed service client(기본), H2 generic exchange, H3 dynamic target. H4 native
|
||||
engine 접근은 `apache`, `jdk`, `http3` 안에 머문다.
|
||||
- blocking만: 호출은 `RestClient`를 거쳐 호출자의 (virtual) 스레드에서 돈다. reactive stack(`WebClient`,
|
||||
Reactor Netty)은 2026-09-25 소유자 결정으로 지웠다. 다시 들이지 않는다.
|
||||
- Named Client Profile, runtime generation, transport SPI, deadline, 증거 기반 재시도, resilience, 인증, TLS,
|
||||
SSRF 방어, streaming lifecycle, 관측을 가진다.
|
||||
- 외부 HTTP 호출을 application·domain 포트 뒤에 맞춘다.
|
||||
- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다.
|
||||
|
||||
## 패키지 경계
|
||||
|
||||
`HttpClientModuleBoundaryTest`와 `PublicApiArchitectureTest`가 설계의 모듈 표를 강제한다:
|
||||
|
||||
- `api`는 플랫폼 안의 다른 어떤 것에도, Spring·Apache·Jetty·Resilience4j 타입에도 의존하지 않는다.
|
||||
- `profile`은 공개적으로 `api`에만 의존한다.
|
||||
- transport 패키지는 gateway로 거슬러 닿지 않는다.
|
||||
- `resilience`는 transport에 의존하지 않는다 — 재시도 자격은 transport와 무관하다.
|
||||
- 운영 패키지는 다시 쓰는 testkit에 의존하지 않는다. testkit은 Gradle `testFixtures`
|
||||
(`src/testFixtures/java`)에 있고, 보통 시험, integration·performance lane, JMH가 명시적으로 쓴다. 그 의존은
|
||||
test-fixture·test 설정에 머물러서 운영 코드는 여전히 닿지 못한다. 경계 규칙이 import하는 「운영 클래스」의
|
||||
유일한 정의는 `PlatformClasses`다.
|
||||
- Stable 코드는 `http3`를 참조하지 않는다.
|
||||
- 어떤 클래스도 `org.springframework.web.service.registry`나 `RestTemplate`를 쓰지 않는다.
|
||||
|
||||
## 경계
|
||||
|
||||
- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다.
|
||||
- inbound controller·DTO, 영속, bootstrap, 샘플 의존이 없다.
|
||||
- 재시도와 circuit breaker 코드는 기술적 resilience다. 업무 보상과 유스케이스 순서는 application·domain 계층에
|
||||
남는다.
|
||||
- application·domain 코드는 이 모듈의 gateway, operation descriptor, URI 타입, Spring HTTP 타입, engine client,
|
||||
재시도 타입, wire DTO를 import하면 안 된다. 그 방향은 `config/architecture/modules.json`의 저장소 단위 Gradle
|
||||
의존 게이트가 강제한다. 이 leaf의 ArchUnit 규칙은 leaf 안의 경계만 다룬다.
|
||||
- 보통 호출은 등록된 profile과 profile 기준 template을 쓴다. 절대 URL은 H3만 쓴다.
|
||||
- 조립은 `dev.caskeleton.adapter.outbound.httpclient.autoconfigure` 아래에서 capability가 가진다: profile 바인딩,
|
||||
기동 검증, transport 등록, service gateway, dynamic target, actuator endpoint가 이 leaf에 있고 Boot 자동 구성
|
||||
metadata로 나간다. `HttpClientPlatformAutoConfiguration`은 `app.httpclient.enabled=true`일 때만 켜진다.
|
||||
스위치가 꺼져 있으면 capability에는 bean이 하나도 없다 — 빈 registry가 아니라 아무것도 없다.
|
||||
- `app-bootstrap`은 운영 코드에서 HTTP client 구현이나 자동 구성 클래스를 import하면 안 된다. 빌드에 넣을지는
|
||||
이 런타임 켜기 스위치와 따로 정한다.
|
||||
|
||||
## 테스트
|
||||
|
||||
기본 lane: `./gradlew :adapter:outbound:httpclient:test`. 추가 lane은 모두 실패하면 닫힌다:
|
||||
|
||||
| lane | 용도 |
|
||||
|---|---|
|
||||
| `httpClientStableContractTest` | Apache와 JDK에 걸친 semantic 계약 하나 |
|
||||
| `httpClientSecurityTest` | SSRF 표, credential 걷어내기, tag cardinality |
|
||||
| `httpClientFailureInjectionTest` | Toxiproxy 장애. **Docker가 필요하고 없으면 실패한다** |
|
||||
| `httpClientPerformanceTest` | pool, streaming, 재시도, 교체의 자원 한계 |
|
||||
| `spring62ApiSurfaceScan` | Spring 6.2 API surface 가두기 |
|
||||
| `spring70CompatibilityTest` | 저장소 기준 버전 위의 계약 suite |
|
||||
| `jmh` | 호출당 부담 benchmark |
|
||||
|
||||
고른 lane은 소리 없이 건너뛰지 않는다: 장애 lane은 Docker가 없으면 던지고, 계약 lane은 transport 선택이
|
||||
비었거나 모르는 것이면 던지고, performance lane은 실행마다 모든 한계를 단언한다 — 빌드가
|
||||
`performance.assertions.enabled`에 `true` 아닌 값을 넣거나 그 시험 하나가 건너뛰어지면 strict lane 규약이
|
||||
실패시킨다.
|
||||
|
||||
transport 포트(`BlockingTransportProvider`)에는 test fixtures에 추상 계약 하나
|
||||
`testkit/BlockingTransportProviderContract`가 있다. engine은 실제 socket 위에서 그것을 통과하고
|
||||
(`StableTransportProviderContractTest`, 계약 lane, 고른 transport마다 한 번), gateway 시험이 딛고 서는 각본
|
||||
fake는 기본 lane에서 그것을 통과한다(`ScriptedTransportContractTest`). 새 transport나 `ScriptedTransport`의
|
||||
변경은 사본이 아니라 같은 클래스를 상속한다(AGENTS.md 규칙 6).
|
||||
@@ -1,86 +1 @@
|
||||
# adapter:outbound:httpclient — HTTP client 플랫폼
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-httpclient`
|
||||
- Gradle 경로: `:adapter:outbound:httpclient`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:httpclient:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.httpclient`.
|
||||
|
||||
## 설계 정본
|
||||
|
||||
구현은 `docs/design/2026-08-08-httpclient-platform-design.md`를 따른다. 설계는 Gradle 모듈 19개를 따로 두는
|
||||
것을 전제한다. 이 저장소의 실패하면 닫히는 registry가 그 배치보다 앞서므로, 그 모듈들은 여기서 **패키지**다.
|
||||
그 대응과 그 밖에 일부러 바꾼 것은 모두 `docs/httpclient/repository-adaptation.md`에 적혀 있다. 타입을 다른
|
||||
패키지로 옮기기 전에 그것을 읽는다.
|
||||
|
||||
## 책임
|
||||
|
||||
- 공개 호출 surface를 가진다: H1 typed service client(기본), H2 generic exchange, H3 dynamic target. H4 native
|
||||
engine 접근은 `apache`, `jdk`, `http3` 안에 머문다.
|
||||
- blocking만: 호출은 `RestClient`를 거쳐 호출자의 (virtual) 스레드에서 돈다. reactive stack(`WebClient`,
|
||||
Reactor Netty)은 2026-09-25 소유자 결정으로 지웠다. 다시 들이지 않는다.
|
||||
- Named Client Profile, runtime generation, transport SPI, deadline, 증거 기반 재시도, resilience, 인증, TLS,
|
||||
SSRF 방어, streaming lifecycle, 관측을 가진다.
|
||||
- 외부 HTTP 호출을 application·domain 포트 뒤에 맞춘다.
|
||||
- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다.
|
||||
|
||||
## 패키지 경계
|
||||
|
||||
`HttpClientModuleBoundaryTest`와 `PublicApiArchitectureTest`가 설계의 모듈 표를 강제한다:
|
||||
|
||||
- `api`는 플랫폼 안의 다른 어떤 것에도, Spring·Apache·Jetty·Resilience4j 타입에도 의존하지 않는다.
|
||||
- `profile`은 공개적으로 `api`에만 의존한다.
|
||||
- transport 패키지는 gateway로 거슬러 닿지 않는다.
|
||||
- `resilience`는 transport에 의존하지 않는다 — 재시도 자격은 transport와 무관하다.
|
||||
- 운영 패키지는 다시 쓰는 testkit에 의존하지 않는다. testkit은 Gradle `testFixtures`
|
||||
(`src/testFixtures/java`)에 있고, 보통 시험, integration·performance lane, JMH가 명시적으로 쓴다. 그 의존은
|
||||
test-fixture·test 설정에 머물러서 운영 코드는 여전히 닿지 못한다. 경계 규칙이 import하는 「운영 클래스」의
|
||||
유일한 정의는 `PlatformClasses`다.
|
||||
- Stable 코드는 `http3`를 참조하지 않는다.
|
||||
- 어떤 클래스도 `org.springframework.web.service.registry`나 `RestTemplate`를 쓰지 않는다.
|
||||
|
||||
## 경계
|
||||
|
||||
- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다.
|
||||
- inbound controller·DTO, 영속, bootstrap, 샘플 의존이 없다.
|
||||
- 재시도와 circuit breaker 코드는 기술적 resilience다. 업무 보상과 유스케이스 순서는 application·domain 계층에
|
||||
남는다.
|
||||
- application·domain 코드는 이 모듈의 gateway, operation descriptor, URI 타입, Spring HTTP 타입, engine client,
|
||||
재시도 타입, wire DTO를 import하면 안 된다. 그 방향은 `config/architecture/modules.json`의 저장소 단위 Gradle
|
||||
의존 게이트가 강제한다. 이 leaf의 ArchUnit 규칙은 leaf 안의 경계만 다룬다.
|
||||
- 보통 호출은 등록된 profile과 profile 기준 template을 쓴다. 절대 URL은 H3만 쓴다.
|
||||
- 조립은 `dev.caskeleton.adapter.outbound.httpclient.autoconfigure` 아래에서 capability가 가진다: profile 바인딩,
|
||||
기동 검증, transport 등록, service gateway, dynamic target, actuator endpoint가 이 leaf에 있고 Boot 자동 구성
|
||||
metadata로 나간다. `HttpClientPlatformAutoConfiguration`은 `app.httpclient.enabled=true`일 때만 켜진다.
|
||||
스위치가 꺼져 있으면 capability에는 bean이 하나도 없다 — 빈 registry가 아니라 아무것도 없다.
|
||||
- `app-bootstrap`은 운영 코드에서 HTTP client 구현이나 자동 구성 클래스를 import하면 안 된다. 빌드에 넣을지는
|
||||
이 런타임 켜기 스위치와 따로 정한다.
|
||||
|
||||
## 테스트
|
||||
|
||||
기본 lane: `./gradlew :adapter:outbound:httpclient:test`. 추가 lane은 모두 실패하면 닫힌다:
|
||||
|
||||
| lane | 용도 |
|
||||
|---|---|
|
||||
| `httpClientStableContractTest` | Apache와 JDK에 걸친 semantic 계약 하나 |
|
||||
| `httpClientSecurityTest` | SSRF 표, credential 걷어내기, tag cardinality |
|
||||
| `httpClientFailureInjectionTest` | Toxiproxy 장애. **Docker가 필요하고 없으면 실패한다** |
|
||||
| `httpClientPerformanceTest` | pool, streaming, 재시도, 교체의 자원 한계 |
|
||||
| `spring62ApiSurfaceScan` | Spring 6.2 API surface 가두기 |
|
||||
| `spring70CompatibilityTest` | 저장소 기준 버전 위의 계약 suite |
|
||||
| `jmh` | 호출당 부담 benchmark |
|
||||
|
||||
고른 lane은 소리 없이 건너뛰지 않는다: 장애 lane은 Docker가 없으면 던지고, 계약 lane은 transport 선택이
|
||||
비었거나 모르는 것이면 던지고, performance lane은 실행마다 모든 한계를 단언한다 — 빌드가
|
||||
`performance.assertions.enabled`에 `true` 아닌 값을 넣거나 그 시험 하나가 건너뛰어지면 strict lane 규약이
|
||||
실패시킨다.
|
||||
|
||||
transport 포트(`BlockingTransportProvider`)에는 test fixtures에 추상 계약 하나
|
||||
`testkit/BlockingTransportProviderContract`가 있다. engine은 실제 socket 위에서 그것을 통과하고
|
||||
(`StableTransportProviderContractTest`, 계약 lane, 고른 transport마다 한 번), gateway 시험이 딛고 서는 각본
|
||||
fake는 기본 lane에서 그것을 통과한다(`ScriptedTransportContractTest`). 새 transport나 `ScriptedTransport`의
|
||||
변경은 사본이 아니라 같은 클래스를 상속한다(AGENTS.md 규칙 6).
|
||||
@AGENTS.md
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
# adapter:outbound:identifier — IO 없는 기반 capability 어댑터
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-identifier`
|
||||
- Gradle 경로: `:adapter:outbound:identifier`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:identifier:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.identifier`.
|
||||
|
||||
예전에 코드 주석에 두던 설계 결정(알고리즘 정본, salt 출처, 빌드 선택)은 [README.md](README.md)에 있다.
|
||||
|
||||
## 책임
|
||||
|
||||
- `HmacUserPrincipalPseudonymizer` — `UserPrincipalPseudonymizerPort` 구현(UTF-8 principal의 HMAC-SHA-256,
|
||||
소문자 hex).
|
||||
- `UuidV7DurableOperationIdFactory` — `DurableOperationIdFactory` 구현(`uuid-creator`로 만든 UUIDv7).
|
||||
operation id는 제출 이벤트의 id이기도 하고, 메시징 플랫폼의 message id는 UUIDv7만 받는다.
|
||||
`composition:durable-operation`이 배선한다.
|
||||
- leaf 이름은 「identifier」다. 범용 시계·난수 출처는 여기 없다. Gradle 경로와 쓰는 쪽이 이 이름을 쓰니
|
||||
이름을 그대로 둔다(README).
|
||||
- 배선은 이 leaf가 아니라 `composition/service-runtime`(`PseudonymizationConfig`)이다.
|
||||
|
||||
## 허용
|
||||
|
||||
[build.gradle](build.gradle)에 선언한다. registry 항목이 정본이다.
|
||||
|
||||
- `:application-core` — 두 클래스가 구현하는 포트.
|
||||
- `:shared-contract`, `HmacSha256`만. 가명은 principal의 hex HMAC이다.
|
||||
`HmacUserPrincipalPseudonymizerVectorTest`가 그것을 JVM 밖에서 계산한 벡터에 고정한다. 릴리스 전후에 쓴
|
||||
로그를 이 값으로 잇기 때문이다.
|
||||
- `:domain-core` — 기능의 서버 지정 id 어댑터가 여기서 그 도메인 `*IdFactory` 포트를 구현한다(registry
|
||||
edge `adapter:outbound:identifier -> domain-core`, `docs/manual/02-new-feature.md`).
|
||||
- `com.github.f4b6a3:uuid-creator`(`libs.uuid.creator`) — `UuidV7DurableOperationIdFactory`의 UUIDv7.
|
||||
|
||||
## 금지
|
||||
|
||||
- 영속·web 기술(JPA/Hibernate/Spring Data/Spring Web) — ArchUnit
|
||||
`IDENTIFIER_ADAPTER_DOES_NOT_DEPEND_ON_OTHER_ADAPTERS_OR_BOOTSTRAP`와 registry 방향 게이트가 막는다.
|
||||
- inbound 어댑터, 영속 어댑터, 다른 outbound leaf, `app-bootstrap`.
|
||||
- 외부 IO(HTTP / 메시징 / cache / DB) — 그것은 IO를 하는 outbound 어댑터 leaf에 둔다.
|
||||
|
||||
## 테스트
|
||||
|
||||
Spring context 없는 순수 단위 시험: `HmacUserPrincipalPseudonymizerTest`(RFC 4231 known-answer 벡터 포함),
|
||||
`HmacUserPrincipalPseudonymizerVectorTest`, `UuidV7DurableOperationIdFactoryTest`.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:outbound:identifier:test --console=plain
|
||||
```
|
||||
@@ -1,53 +1 @@
|
||||
# adapter:outbound:identifier — IO 없는 기반 capability 어댑터
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-identifier`
|
||||
- Gradle 경로: `:adapter:outbound:identifier`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:identifier:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.identifier`.
|
||||
|
||||
예전에 코드 주석에 두던 설계 결정(알고리즘 정본, salt 출처, 빌드 선택)은 [README.md](README.md)에 있다.
|
||||
|
||||
## 책임
|
||||
|
||||
- `HmacUserPrincipalPseudonymizer` — `UserPrincipalPseudonymizerPort` 구현(UTF-8 principal의 HMAC-SHA-256,
|
||||
소문자 hex).
|
||||
- `UuidV7DurableOperationIdFactory` — `DurableOperationIdFactory` 구현(`uuid-creator`로 만든 UUIDv7).
|
||||
operation id는 제출 이벤트의 id이기도 하고, 메시징 플랫폼의 message id는 UUIDv7만 받는다.
|
||||
`composition:durable-operation`이 배선한다.
|
||||
- leaf 이름은 「identifier」다. 범용 시계·난수 출처는 여기 없다. Gradle 경로와 쓰는 쪽이 이 이름을 쓰니
|
||||
이름을 그대로 둔다(README).
|
||||
- 배선은 이 leaf가 아니라 `composition/service-runtime`(`PseudonymizationConfig`)이다.
|
||||
|
||||
## 허용
|
||||
|
||||
[build.gradle](build.gradle)에 선언한다. registry 항목이 정본이다.
|
||||
|
||||
- `:application-core` — 두 클래스가 구현하는 포트.
|
||||
- `:shared-contract`, `HmacSha256`만. 가명은 principal의 hex HMAC이다.
|
||||
`HmacUserPrincipalPseudonymizerVectorTest`가 그것을 JVM 밖에서 계산한 벡터에 고정한다. 릴리스 전후에 쓴
|
||||
로그를 이 값으로 잇기 때문이다.
|
||||
- `:domain-core` — 기능의 서버 지정 id 어댑터가 여기서 그 도메인 `*IdFactory` 포트를 구현한다(registry
|
||||
edge `adapter:outbound:identifier -> domain-core`, `docs/manual/02-new-feature.md`).
|
||||
- `com.github.f4b6a3:uuid-creator`(`libs.uuid.creator`) — `UuidV7DurableOperationIdFactory`의 UUIDv7.
|
||||
|
||||
## 금지
|
||||
|
||||
- 영속·web 기술(JPA/Hibernate/Spring Data/Spring Web) — ArchUnit
|
||||
`IDENTIFIER_ADAPTER_DOES_NOT_DEPEND_ON_OTHER_ADAPTERS_OR_BOOTSTRAP`와 registry 방향 게이트가 막는다.
|
||||
- inbound 어댑터, 영속 어댑터, 다른 outbound leaf, `app-bootstrap`.
|
||||
- 외부 IO(HTTP / 메시징 / cache / DB) — 그것은 IO를 하는 outbound 어댑터 leaf에 둔다.
|
||||
|
||||
## 테스트
|
||||
|
||||
Spring context 없는 순수 단위 시험: `HmacUserPrincipalPseudonymizerTest`(RFC 4231 known-answer 벡터 포함),
|
||||
`HmacUserPrincipalPseudonymizerVectorTest`, `UuidV7DurableOperationIdFactoryTest`.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:outbound:identifier:test --console=plain
|
||||
```
|
||||
@AGENTS.md
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
이 leaf의 main 코드는 `HmacUserPrincipalPseudonymizer`와 `UuidV7DurableOperationIdFactory` 두 클래스다. 패키지 루트:
|
||||
`dev.caskeleton.adapter.outbound.identifier`.
|
||||
|
||||
허용·금지 의존과 테스트 명령 같은 **모듈 규칙**은 [CLAUDE.md](CLAUDE.md)가 기준이다. 이 문서는
|
||||
허용·금지 의존과 테스트 명령 같은 **모듈 규칙**은 [AGENTS.md](AGENTS.md)가 기준이다. 이 문서는
|
||||
설계 결정의 근거를 모은다.
|
||||
|
||||
## 이름과 내용이 다른 이유 (review 05-21)
|
||||
@@ -49,7 +49,7 @@ Spring 어노테이션이 없다. bean은
|
||||
|
||||
의존은 넷이다: `:application-core`(두 클래스가 구현하는 port), `:shared-contract`(`HmacSha256`),
|
||||
`:domain-core`(기능의 `*IdFactory` 구현 자리), `uuid-creator`(UUIDv7). 목록과 이유는
|
||||
[CLAUDE.md](CLAUDE.md) Allowed 절이 기준이다.
|
||||
[AGENTS.md](AGENTS.md) Allowed 절이 기준이다.
|
||||
|
||||
`:application-core`를 `implementation`으로 받는다. 이 leaf의 public 타입 시그니처에
|
||||
application-core 타입이 드러나지만, 조립하는 쪽이 application-core를 이미 classpath에 갖고 있다.
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
# adapter:outbound:messaging-kafka
|
||||
|
||||
- 모듈 ID `adapter-outbound-messaging-kafka`, Gradle 경로 `:adapter:outbound:messaging-kafka`.
|
||||
registry 정본: `src/config/architecture/modules.json`.
|
||||
- 책임: Kafka 발행 capability를 `runtimeOnly` 한 줄로 만든다. 운영 코드가 없다:
|
||||
`adapter:outbound:messaging`(애플리케이션의 bridge)과 `messaging:messaging-spring-boot-starter-kafka`(들여온
|
||||
플랫폼과 그 Kafka 전송)를 묶고, 모듈 기본값 `config/module-defaults/messaging.yml`을 싣는다.
|
||||
- 경계: 여기 코드를 더하지 않는다. 발행 규칙은 bridge(`adapter:outbound:messaging`)에, Kafka 규칙은 들여온
|
||||
제품(`src/platforms/messaging/AGENTS.md`)에 속한다. 여기 클래스를 두면 세 번째 자리가 생긴다. 허용 edge는
|
||||
registry 항목에서만 온다.
|
||||
- 시험: 켜기 시험(`./gradlew :adapter:outbound:messaging-kafka:test`)과 실제 Kafka lane
|
||||
`messagingKafkaRelayIntegrationTest`(relay → bridge → broker record 바이트, `:integrationCheck`).
|
||||
- 설계: `README.md`.
|
||||
@@ -1,13 +1 @@
|
||||
# adapter:outbound:messaging-kafka
|
||||
|
||||
- 모듈 ID `adapter-outbound-messaging-kafka`, Gradle 경로 `:adapter:outbound:messaging-kafka`.
|
||||
registry 정본: `src/config/architecture/modules.json`.
|
||||
- 책임: Kafka 발행 capability를 `runtimeOnly` 한 줄로 만든다. 운영 코드가 없다:
|
||||
`adapter:outbound:messaging`(애플리케이션의 bridge)과 `messaging:messaging-spring-boot-starter-kafka`(들여온
|
||||
플랫폼과 그 Kafka 전송)를 묶고, 모듈 기본값 `config/module-defaults/messaging.yml`을 싣는다.
|
||||
- 경계: 여기 코드를 더하지 않는다. 발행 규칙은 bridge(`adapter:outbound:messaging`)에, Kafka 규칙은 들여온
|
||||
제품(`src/platforms/messaging/CLAUDE.md`)에 속한다. 여기 클래스를 두면 세 번째 자리가 생긴다. 허용 edge는
|
||||
registry 항목에서만 온다.
|
||||
- 시험: 켜기 시험(`./gradlew :adapter:outbound:messaging-kafka:test`)과 실제 Kafka lane
|
||||
`messagingKafkaRelayIntegrationTest`(relay → bridge → broker record 바이트, `:integrationCheck`).
|
||||
- 설계: `README.md`.
|
||||
@AGENTS.md
|
||||
|
||||
@@ -0,0 +1,46 @@
|
||||
# adapter:outbound:messaging — 메시징 어댑터
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-messaging`
|
||||
- Gradle 경로: `:adapter:outbound:messaging`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:messaging:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.messaging`.
|
||||
|
||||
## 책임
|
||||
|
||||
- application·domain 포트 뒤에서 outbound 메시지 발행과 broker 연동을 구현한다.
|
||||
- broker 설정, 꺼짐·안전 실패 기술 모드, outbox 발행 연결을 가진다.
|
||||
- 조건 없이 하나만 있는 `Slf4jOutboxRelayFailureReportAdapter` bean으로 `OutboxRelayFailureReport`를 구조화해
|
||||
남긴다.
|
||||
- 공용 기술 관심사는 `adapter:outbound:support`를 다시 쓴다.
|
||||
|
||||
## 경계
|
||||
|
||||
- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다.
|
||||
- inbound DTO·controller, 영속 repository·엔티티, bootstrap, 샘플 의존이 없다.
|
||||
- 정해진 플랫폼 bridge는 `messaging-core-api`(`schema` 패키지도 담는다)에만 의존할 수 있다.
|
||||
`platformbridge/` 아래에서 `messaging-runtime-core`, 전송 SPI 구현, broker SDK 타입을 import하지 않는다.
|
||||
- 발행 경로는 하나다: `OutboxMessagePublishAdapter` → `IntegrationEventPublishPort` → 플랫폼 bridge. 옛
|
||||
`KafkaSender` / `MessageBroker` R0 이음매와 실패해도 열리는(fail-open) `MessagePublisher`는 정해진 outbox와
|
||||
함께 지웠다(2026-09-28). 두 번째 경로를 다시 들이지 않는다.
|
||||
- 정해진 producer identity는 명시한 `app.messaging.producer-id`다. `spring.application.name`, host, pod,
|
||||
프로세스 identity에서 끌어내지 않는다. 모듈이 켜져 있는데 bridge가 없으면 기동을 거절한다 — relay가 발행할
|
||||
길이 없다.
|
||||
- 템플릿의 `IntegrationEventEncoderPort`(`JsonIntegrationEventEncoder`)는 여기가 아니라
|
||||
`adapter:outbound:support`에 있다: 유스케이스는 append하기 전에 인코딩하는데, 이 모듈을 싣지 않는 조립도
|
||||
있다. R1 contract·binding 컴파일러와 JSON Schema envelope 인코더는 2026-09-25에 지웠다
|
||||
(`docs/capability-status.md`).
|
||||
- 주 classpath에 JSON Schema 엔진(NetworkNT)이 없다. 증거 manifest schema 검사와 capability card 검사
|
||||
(`release/`)는 이 leaf의 시험(`evidence/`)이다. snakeyaml은 시험에서만 쓴다(소유자 결정 2026-09-25).
|
||||
- 유스케이스 순서나 업무 라우팅 정책을 broker 어댑터 안에 숨기지 않는다.
|
||||
- `OutboxMessagePublishAdapter`는 위임만 하고 의존성 로그를 내지 않는다. 확정된 FAILED/DEAD 전이가 정해진
|
||||
ERROR 하나를 가진다.
|
||||
|
||||
## 테스트
|
||||
|
||||
가짜 정해진 publisher로 단위·계약 시험을 쓴다. 이 모듈만 보는 시험은 실제 네트워크나 broker를 쓰지 않는다.
|
||||
설정이 바뀌면 settings record에 바인딩·검증 시험을 더한다.
|
||||
@@ -1,46 +1 @@
|
||||
# adapter:outbound:messaging — 메시징 어댑터
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-messaging`
|
||||
- Gradle 경로: `:adapter:outbound:messaging`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:messaging:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.messaging`.
|
||||
|
||||
## 책임
|
||||
|
||||
- application·domain 포트 뒤에서 outbound 메시지 발행과 broker 연동을 구현한다.
|
||||
- broker 설정, 꺼짐·안전 실패 기술 모드, outbox 발행 연결을 가진다.
|
||||
- 조건 없이 하나만 있는 `Slf4jOutboxRelayFailureReportAdapter` bean으로 `OutboxRelayFailureReport`를 구조화해
|
||||
남긴다.
|
||||
- 공용 기술 관심사는 `adapter:outbound:support`를 다시 쓴다.
|
||||
|
||||
## 경계
|
||||
|
||||
- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다.
|
||||
- inbound DTO·controller, 영속 repository·엔티티, bootstrap, 샘플 의존이 없다.
|
||||
- 정해진 플랫폼 bridge는 `messaging-core-api`(`schema` 패키지도 담는다)에만 의존할 수 있다.
|
||||
`platformbridge/` 아래에서 `messaging-runtime-core`, 전송 SPI 구현, broker SDK 타입을 import하지 않는다.
|
||||
- 발행 경로는 하나다: `OutboxMessagePublishAdapter` → `IntegrationEventPublishPort` → 플랫폼 bridge. 옛
|
||||
`KafkaSender` / `MessageBroker` R0 이음매와 실패해도 열리는(fail-open) `MessagePublisher`는 정해진 outbox와
|
||||
함께 지웠다(2026-09-28). 두 번째 경로를 다시 들이지 않는다.
|
||||
- 정해진 producer identity는 명시한 `app.messaging.producer-id`다. `spring.application.name`, host, pod,
|
||||
프로세스 identity에서 끌어내지 않는다. 모듈이 켜져 있는데 bridge가 없으면 기동을 거절한다 — relay가 발행할
|
||||
길이 없다.
|
||||
- 템플릿의 `IntegrationEventEncoderPort`(`JsonIntegrationEventEncoder`)는 여기가 아니라
|
||||
`adapter:outbound:support`에 있다: 유스케이스는 append하기 전에 인코딩하는데, 이 모듈을 싣지 않는 조립도
|
||||
있다. R1 contract·binding 컴파일러와 JSON Schema envelope 인코더는 2026-09-25에 지웠다
|
||||
(`docs/capability-status.md`).
|
||||
- 주 classpath에 JSON Schema 엔진(NetworkNT)이 없다. 증거 manifest schema 검사와 capability card 검사
|
||||
(`release/`)는 이 leaf의 시험(`evidence/`)이다. snakeyaml은 시험에서만 쓴다(소유자 결정 2026-09-25).
|
||||
- 유스케이스 순서나 업무 라우팅 정책을 broker 어댑터 안에 숨기지 않는다.
|
||||
- `OutboxMessagePublishAdapter`는 위임만 하고 의존성 로그를 내지 않는다. 확정된 FAILED/DEAD 전이가 정해진
|
||||
ERROR 하나를 가진다.
|
||||
|
||||
## 테스트
|
||||
|
||||
가짜 정해진 publisher로 단위·계약 시험을 쓴다. 이 모듈만 보는 시험은 실제 네트워크나 broker를 쓰지 않는다.
|
||||
설정이 바뀌면 settings record에 바인딩·검증 시험을 더한다.
|
||||
@AGENTS.md
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
adapter로 구조화한다.
|
||||
|
||||
허용/금지 의존 정책은 `src/config/architecture/modules.json`과 이 모듈의
|
||||
[CLAUDE.md](CLAUDE.md)가 소유한다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔
|
||||
[AGENTS.md](AGENTS.md)가 소유한다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔
|
||||
참조용 기록이다.
|
||||
|
||||
## 모듈 개요
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
# adapter:outbound:notification — 알림 어댑터
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-notification`
|
||||
- Gradle 경로: `:adapter:outbound:notification`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:notification:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.notification`.
|
||||
|
||||
## 책임
|
||||
|
||||
- 지금의 raw 알림 router·provider 이음매는 리뷰를 거친 정해진 전환(cutover)이 지울 때까지 `R0 legacy` 호환
|
||||
기준선으로만 지킨다.
|
||||
- 앞으로의 provider 프로토콜은 애플리케이션이 가진 포트 뒤에서 구현하고, SDK·전송·bootstrap·영속 타입을
|
||||
새게 하지 않는다.
|
||||
- provider 설정, 기술적 대체 장치, provider 연결을 가진다. 모드, 자격, 재시도·대체 판단, 업무 실패의 뜻은
|
||||
애플리케이션 정책이 가진다.
|
||||
- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다.
|
||||
|
||||
## 지금의 R0 동결
|
||||
|
||||
- `RoutingNotifier`가 `(Channel, providerId)` 위에서 route 목록으로 퍼뜨린다.
|
||||
- `FailOpenNotificationProvider`가 전역 fail-open 규칙 하나를 적용한다.
|
||||
- `google-email`/`GoogleEmailClient`와 `slack-webhook`/`SlackClient`는 fake로만 쓰는 확장 이음매다. 운영 연동이나
|
||||
검증된 provider card가 아니다.
|
||||
- 커밋해 둔 provider 선택 키는 router의 `routes` + provider `enabled` 문법과 어긋나 있다. 정해진 그래프가
|
||||
대신할 때까지 그 어긋남을 지키고 적어 둔다. 옛 키를 소리 없이 다르게 해석하지 않는다.
|
||||
- 기능·애플리케이션 운영 소비자가 없고, 실제 provider·durable·수신 확인·보안·부하·교체 증거가 없다.
|
||||
- 지울 옛 코드의 정확한 목록은 [README.md](README.md)에 있다. 정해진 대체물을 만드는 동안 그 클래스에 동작을
|
||||
더하지 않는다.
|
||||
|
||||
## 경계
|
||||
|
||||
- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다.
|
||||
- inbound DTO·controller, 영속, bootstrap, 샘플 의존이 없다.
|
||||
- provider 선택은 설정한 채널로 보낼 수 있지만 업무 자격 규칙을 담으면 안 된다.
|
||||
- 줄 안에 완전한 이름으로 쓴 타입 참조가 없다. `adapter:outbound:fileserver`는 이미 이것을 금지했고 이 leaf는
|
||||
아니었다. 그래서 같은 구문이 한 capability에서는 결함이고 다음 capability에서는 평범한 문체였다. 플랫폼 자동
|
||||
구성에 그런 것이 스물두 개 쌓여 있었다.
|
||||
`dev.caskeleton.application.notification.platform.dispatch.ReconciliationJobStorePort jobs`처럼 쓴 매개변수는
|
||||
import 블록이 읽기 쉽게 보여 주려고 있는 바로 그 leaf 사이 edge를 import 블록에서 숨긴다.
|
||||
|
||||
## 테스트
|
||||
|
||||
provider·client fake와 계약 시험을 쓴다. 실제 webhook이나 email 네트워크 호출이 없다. 설정을 바꾸면
|
||||
바인딩·검증 시험을 더한다.
|
||||
@@ -1,49 +1 @@
|
||||
# adapter:outbound:notification — 알림 어댑터
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-notification`
|
||||
- Gradle 경로: `:adapter:outbound:notification`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:notification:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.notification`.
|
||||
|
||||
## 책임
|
||||
|
||||
- 지금의 raw 알림 router·provider 이음매는 리뷰를 거친 정해진 전환(cutover)이 지울 때까지 `R0 legacy` 호환
|
||||
기준선으로만 지킨다.
|
||||
- 앞으로의 provider 프로토콜은 애플리케이션이 가진 포트 뒤에서 구현하고, SDK·전송·bootstrap·영속 타입을
|
||||
새게 하지 않는다.
|
||||
- provider 설정, 기술적 대체 장치, provider 연결을 가진다. 모드, 자격, 재시도·대체 판단, 업무 실패의 뜻은
|
||||
애플리케이션 정책이 가진다.
|
||||
- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다.
|
||||
|
||||
## 지금의 R0 동결
|
||||
|
||||
- `RoutingNotifier`가 `(Channel, providerId)` 위에서 route 목록으로 퍼뜨린다.
|
||||
- `FailOpenNotificationProvider`가 전역 fail-open 규칙 하나를 적용한다.
|
||||
- `google-email`/`GoogleEmailClient`와 `slack-webhook`/`SlackClient`는 fake로만 쓰는 확장 이음매다. 운영 연동이나
|
||||
검증된 provider card가 아니다.
|
||||
- 커밋해 둔 provider 선택 키는 router의 `routes` + provider `enabled` 문법과 어긋나 있다. 정해진 그래프가
|
||||
대신할 때까지 그 어긋남을 지키고 적어 둔다. 옛 키를 소리 없이 다르게 해석하지 않는다.
|
||||
- 기능·애플리케이션 운영 소비자가 없고, 실제 provider·durable·수신 확인·보안·부하·교체 증거가 없다.
|
||||
- 지울 옛 코드의 정확한 목록은 [README.md](README.md)에 있다. 정해진 대체물을 만드는 동안 그 클래스에 동작을
|
||||
더하지 않는다.
|
||||
|
||||
## 경계
|
||||
|
||||
- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다.
|
||||
- inbound DTO·controller, 영속, bootstrap, 샘플 의존이 없다.
|
||||
- provider 선택은 설정한 채널로 보낼 수 있지만 업무 자격 규칙을 담으면 안 된다.
|
||||
- 줄 안에 완전한 이름으로 쓴 타입 참조가 없다. `adapter:outbound:fileserver`는 이미 이것을 금지했고 이 leaf는
|
||||
아니었다. 그래서 같은 구문이 한 capability에서는 결함이고 다음 capability에서는 평범한 문체였다. 플랫폼 자동
|
||||
구성에 그런 것이 스물두 개 쌓여 있었다.
|
||||
`dev.caskeleton.application.notification.platform.dispatch.ReconciliationJobStorePort jobs`처럼 쓴 매개변수는
|
||||
import 블록이 읽기 쉽게 보여 주려고 있는 바로 그 leaf 사이 edge를 import 블록에서 숨긴다.
|
||||
|
||||
## 테스트
|
||||
|
||||
provider·client fake와 계약 시험을 쓴다. 실제 webhook이나 email 네트워크 호출이 없다. 설정을 바꾸면
|
||||
바인딩·검증 시험을 더한다.
|
||||
@AGENTS.md
|
||||
|
||||
@@ -0,0 +1,48 @@
|
||||
# adapter:outbound:objectstorage — 모듈 규칙
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-objectstorage`
|
||||
- Gradle 경로: `:adapter:outbound:objectstorage`
|
||||
- 이 모듈만 시험: `./gradlew :adapter:outbound:objectstorage:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.objectstorage`. 설계 근거와 사실대로 적은 준비 상태는
|
||||
[README.md](README.md)와 `docs/registries/object-storage-readiness.yaml`에 있다.
|
||||
|
||||
## 책임
|
||||
|
||||
- application-core의 semantic object 게시·읽기·폐기·operation 해석 포트를 provider 중립의 한계 있는 streaming과
|
||||
엄격한 durable 제어 레코드 뒤에서 구현한다.
|
||||
- 기본 꺼짐인 `app.object-storage` 설정을, 고른 자원을 만들기 전에 정확하고 바뀌지 않는
|
||||
provider·destination·route·policy 바인딩으로 컴파일한다.
|
||||
- R1 전용 개발 provider로 `filesystem-local-dev`를 준다.
|
||||
- scanner 유지보수 조립은 따로 둔다. 지원하지 않는 capability는 bean을 기여하지 않는다. purge·direct-grant·
|
||||
multipart 포트는 없다.
|
||||
|
||||
## 허용
|
||||
|
||||
- 프로젝트 의존은 `src/config/architecture/modules.json`의 `adapter-outbound-objectstorage` 항목이 허용한 것뿐이다.
|
||||
지금은 application-core, shared-contract, application-objectstorage, 그리고 등록된 support edge
|
||||
(`adapter:outbound:support`: 모든 local-dev 파일 접근이 거치는 descriptor 기반 `SecureFileAccess`/
|
||||
`SecureDirectoryWalk`, 그리고 `StrictSettingsBinder` — `app.object-storage` 트리는 환경 변수까지 엄격하게
|
||||
바인딩한다. capability 규칙 4)다.
|
||||
- provider SDK·설정 타입은 이 leaf 안에 머문다.
|
||||
- provider 기여는 부작용 없이 지원 내용을 설명할 수 있고, 정확히 골라진 뒤에만 자원을 만들 수 있다.
|
||||
|
||||
## 금지
|
||||
|
||||
- inbound 어댑터, 이웃 outbound 어댑터, 영속, app-bootstrap 의존.
|
||||
- provider 키·경로·locator·SDK 타입·Spring 타입·제어 레코드 타입이 application-core로 새는 것.
|
||||
- 기본 provider·destination·namespace, 운영에서 local-dev, capability가 꺼져 있을 때 기동 중 변경.
|
||||
- 보통 라우팅 타입이 scanner 유지보수 포트를 구현하기.
|
||||
- `docs/registries/object-storage-readiness.yaml`의 정확한 행보다 높은 주장.
|
||||
- 새 semantic operation을 옛 호출자 키 기반 덮어쓰기 뜻으로 되돌려 맞추기.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:outbound:objectstorage:check --console=plain
|
||||
```
|
||||
@@ -1,48 +1 @@
|
||||
# adapter:outbound:objectstorage — 모듈 규칙
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-objectstorage`
|
||||
- Gradle 경로: `:adapter:outbound:objectstorage`
|
||||
- 이 모듈만 시험: `./gradlew :adapter:outbound:objectstorage:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.objectstorage`. 설계 근거와 사실대로 적은 준비 상태는
|
||||
[README.md](README.md)와 `docs/registries/object-storage-readiness.yaml`에 있다.
|
||||
|
||||
## 책임
|
||||
|
||||
- application-core의 semantic object 게시·읽기·폐기·operation 해석 포트를 provider 중립의 한계 있는 streaming과
|
||||
엄격한 durable 제어 레코드 뒤에서 구현한다.
|
||||
- 기본 꺼짐인 `app.object-storage` 설정을, 고른 자원을 만들기 전에 정확하고 바뀌지 않는
|
||||
provider·destination·route·policy 바인딩으로 컴파일한다.
|
||||
- R1 전용 개발 provider로 `filesystem-local-dev`를 준다.
|
||||
- scanner 유지보수 조립은 따로 둔다. 지원하지 않는 capability는 bean을 기여하지 않는다. purge·direct-grant·
|
||||
multipart 포트는 없다.
|
||||
|
||||
## 허용
|
||||
|
||||
- 프로젝트 의존은 `src/config/architecture/modules.json`의 `adapter-outbound-objectstorage` 항목이 허용한 것뿐이다.
|
||||
지금은 application-core, shared-contract, application-objectstorage, 그리고 등록된 support edge
|
||||
(`adapter:outbound:support`: 모든 local-dev 파일 접근이 거치는 descriptor 기반 `SecureFileAccess`/
|
||||
`SecureDirectoryWalk`, 그리고 `StrictSettingsBinder` — `app.object-storage` 트리는 환경 변수까지 엄격하게
|
||||
바인딩한다. capability 규칙 4)다.
|
||||
- provider SDK·설정 타입은 이 leaf 안에 머문다.
|
||||
- provider 기여는 부작용 없이 지원 내용을 설명할 수 있고, 정확히 골라진 뒤에만 자원을 만들 수 있다.
|
||||
|
||||
## 금지
|
||||
|
||||
- inbound 어댑터, 이웃 outbound 어댑터, 영속, app-bootstrap 의존.
|
||||
- provider 키·경로·locator·SDK 타입·Spring 타입·제어 레코드 타입이 application-core로 새는 것.
|
||||
- 기본 provider·destination·namespace, 운영에서 local-dev, capability가 꺼져 있을 때 기동 중 변경.
|
||||
- 보통 라우팅 타입이 scanner 유지보수 포트를 구현하기.
|
||||
- `docs/registries/object-storage-readiness.yaml`의 정확한 행보다 높은 주장.
|
||||
- 새 semantic operation을 옛 호출자 키 기반 덮어쓰기 뜻으로 되돌려 맞추기.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:outbound:objectstorage:check --console=plain
|
||||
```
|
||||
@AGENTS.md
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
`dev.caskeleton.application.objectstorage`의 semantic 계약을 구현하고, provider 키·경로·SDK 타입·제어
|
||||
레코드를 애플리케이션 경계 뒤에 둔다.
|
||||
|
||||
허용 운영 의존은 `src/config/architecture/modules.json`이 가진다. 모듈 규칙은 [CLAUDE.md](CLAUDE.md), 전체
|
||||
허용 운영 의존은 `src/config/architecture/modules.json`이 가진다. 모듈 규칙은 [AGENTS.md](AGENTS.md), 전체
|
||||
설계는 `docs/design/2026-07-28-objectstorage-production-capability-design.md`, 정확한 증거 주장은
|
||||
`docs/registries/object-storage-readiness.yaml`에 있다.
|
||||
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
# persistence-fileserver
|
||||
|
||||
파일 서버 capability의 관계형 영속이다: 엔티티, Spring Data repository, `application-fileserver` 포트를 구현하는
|
||||
store 어댑터. 루트 `AGENTS.md`와 `adapter/outbound/persistence-jpa/AGENTS.md`도 그대로 적용된다. 이 파일은 이
|
||||
leaf에만 있는 것을 더한다.
|
||||
|
||||
## 패키지
|
||||
|
||||
- `entity/` — JPA 행만. 모든 엔티티는 `AssignedIdEntity`를 상속한다.
|
||||
- `repository/` — Spring Data 인터페이스와 그것이 돌리는 SQL 글(`CleanupClaimSql`).
|
||||
- 패키지 루트 — store 어댑터(`Jpa*`), `FileEntityMapper`, 그것들을 bean으로 등록하는 `@Configuration`
|
||||
클래스.
|
||||
|
||||
`persistence-notification`도 같은 규칙(`platform.entity`, `platform.repository`, 어댑터는 `platform`)을
|
||||
따르므로 두 capability leaf를 같은 방식으로 읽는다.
|
||||
|
||||
## 규칙
|
||||
|
||||
- **트랜잭션.** store는 트랜잭션을 열지 않는다. 모든 쓰기는 `CallerTransaction.require("<store> <operation>")`로
|
||||
시작한다. 그래서 `TransactionPort.inWrite`를 잊은 유스케이스는 문장마다 커밋하지 않고 실패한다.
|
||||
- **새 행.** id를 insert 전에 정하므로 엔티티가 새것인지 스스로 말해야 한다: `AssignedIdEntity`
|
||||
(`Persistable<UUID>`)를 상속한다. 그렇지 않으면 `save`가 merge한다 — insert마다 SELECT가 앞서고, 이미 있는 id로
|
||||
하는 두 번째 insert가 primary key에서 실패하지 않고 행을 덮어쓴다. 새 `@Version` 열은 primitive `long`으로 둬도
|
||||
된다. 새것인지는 version이 아니라 `Persistable`이 정한다.
|
||||
- **여기에 정책을 두지 않는다.** 재시도 예산, lease 길이 같은 판단은 `application-fileserver`의 것이고 포트
|
||||
인자로 온다. claim token 같은 fence는 어댑터 필드가 아니라 포트 타입(`CleanupItem.claimToken`)에 실려 다닌다.
|
||||
- **claim.** queue claim은 문장 하나다: CTE + `FOR UPDATE SKIP LOCKED` + `RETURNING`(`CleanupClaimSql`). 마무리
|
||||
처리는 claim token을 맞춰 보고, 낡은 worker이면 0행을 update한다.
|
||||
|
||||
## migration
|
||||
|
||||
- `src/main/resources/db/migration/jpa/fileserver/V*.sql`. capability 자신의 Flyway stream
|
||||
(`flyway_jpa_fileserver_history`)으로 적용한다.
|
||||
- 적용한 파일은 고치지 않는다. 새 버전과 그 hash를 불변 목록에 더한다. `persistence-jpa`의
|
||||
`AppliedMigrationImmutabilityTest`가 이 파일들을 있는 자리에서 고정한다.
|
||||
|
||||
## 테스트
|
||||
|
||||
- `src/test` — container 없는 이 leaf 자신의 시험. 돌리기:
|
||||
`./gradlew :adapter:outbound:persistence-fileserver:test --console=plain`.
|
||||
- `FileserverStoreCallerTransactionTest` — 모든 store의 보호된 쓰기는 호출자 트랜잭션이 없으면 repository에
|
||||
닿기 전에 거절한다(위 트랜잭션 규칙, 쓰기마다 경우 하나. Spring Data repository는 mock이다).
|
||||
- `FileserverPersistenceActivationTest` — scan은 `app.fileserver-platform.enabled` 뒤에서 이 패키지만 덮고,
|
||||
JPA 루트 자동 구성보다 먼저 돈다.
|
||||
- `repository.CleanupClaimSqlTest` — claim 글이 문장 하나 모양을 지킨다(claim 규칙). 잠금 자체는
|
||||
`PostgreSqlFileserverReclamationIntegrationTest`가 PostgreSQL에서 본다.
|
||||
- `entity.AssignedIdEntityTest` — H2 위의 Hibernate에서 `Persistable`로 새것인지 정한다.
|
||||
새 store 쓰기는 보호 시험에 자기 경우를 더한다. 새 자동 구성은 켜기 시험에 자기 줄을 더한다.
|
||||
- 포트 계약은 `application-fileserver` testFixtures에 있다(`*PortContract`, 그리고 테이블 하나를 같이 쓰는 quota
|
||||
포트 셋의 `FileQuotaLedgerContract`). 메모리 fake와 PostgreSQL 시험이 모두 그것을 상속한다. 이 leaf가 구현하는
|
||||
포트는 모두 계약이 있다(`docs/testing/TESTING_STRATEGY.md` 9.3절). 2026-11-03에 더한 일곱 개의 PostgreSQL
|
||||
쪽은 `jpa-contract` tag를 달고 persistence-jpa의 `jpaPlatformContractTest` lane에서
|
||||
`FileserverPostgreSqlStack` 위에 돈다. 경우마다 그 시계를 옮긴다.
|
||||
- 실제 PostgreSQL 시험은 아직 `persistence-jpa`의 `postgresqlIntegrationTest` source set에 있다. 그 source set이
|
||||
container와 Flyway 배선을 가지고, JPA readiness card(`persistence-jpa/release/readiness-cards.yaml`,
|
||||
`JpaReadinessRegistryTest`가 검사)가 그 시험을 그 leaf의 태스크로 이름 댄다 — 옮기려면 card의 태스크와
|
||||
selector도 함께 옮겨야 한다: `postgresqlFileserverMigrationIntegrationTest`,
|
||||
`postgresqlFileserverMetadataIntegrationTest`, `postgresqlFileserverReclamationIntegrationTest`
|
||||
(`./gradlew :adapter:outbound:persistence-jpa:<lane> --console=plain`).
|
||||
@@ -1,59 +1 @@
|
||||
# persistence-fileserver
|
||||
|
||||
파일 서버 capability의 관계형 영속이다: 엔티티, Spring Data repository, `application-fileserver` 포트를 구현하는
|
||||
store 어댑터. 루트 `AGENTS.md`와 `adapter/outbound/persistence-jpa/CLAUDE.md`도 그대로 적용된다. 이 파일은 이
|
||||
leaf에만 있는 것을 더한다.
|
||||
|
||||
## 패키지
|
||||
|
||||
- `entity/` — JPA 행만. 모든 엔티티는 `AssignedIdEntity`를 상속한다.
|
||||
- `repository/` — Spring Data 인터페이스와 그것이 돌리는 SQL 글(`CleanupClaimSql`).
|
||||
- 패키지 루트 — store 어댑터(`Jpa*`), `FileEntityMapper`, 그것들을 bean으로 등록하는 `@Configuration`
|
||||
클래스.
|
||||
|
||||
`persistence-notification`도 같은 규칙(`platform.entity`, `platform.repository`, 어댑터는 `platform`)을
|
||||
따르므로 두 capability leaf를 같은 방식으로 읽는다.
|
||||
|
||||
## 규칙
|
||||
|
||||
- **트랜잭션.** store는 트랜잭션을 열지 않는다. 모든 쓰기는 `CallerTransaction.require("<store> <operation>")`로
|
||||
시작한다. 그래서 `TransactionPort.inWrite`를 잊은 유스케이스는 문장마다 커밋하지 않고 실패한다.
|
||||
- **새 행.** id를 insert 전에 정하므로 엔티티가 새것인지 스스로 말해야 한다: `AssignedIdEntity`
|
||||
(`Persistable<UUID>`)를 상속한다. 그렇지 않으면 `save`가 merge한다 — insert마다 SELECT가 앞서고, 이미 있는 id로
|
||||
하는 두 번째 insert가 primary key에서 실패하지 않고 행을 덮어쓴다. 새 `@Version` 열은 primitive `long`으로 둬도
|
||||
된다. 새것인지는 version이 아니라 `Persistable`이 정한다.
|
||||
- **여기에 정책을 두지 않는다.** 재시도 예산, lease 길이 같은 판단은 `application-fileserver`의 것이고 포트
|
||||
인자로 온다. claim token 같은 fence는 어댑터 필드가 아니라 포트 타입(`CleanupItem.claimToken`)에 실려 다닌다.
|
||||
- **claim.** queue claim은 문장 하나다: CTE + `FOR UPDATE SKIP LOCKED` + `RETURNING`(`CleanupClaimSql`). 마무리
|
||||
처리는 claim token을 맞춰 보고, 낡은 worker이면 0행을 update한다.
|
||||
|
||||
## migration
|
||||
|
||||
- `src/main/resources/db/migration/jpa/fileserver/V*.sql`. capability 자신의 Flyway stream
|
||||
(`flyway_jpa_fileserver_history`)으로 적용한다.
|
||||
- 적용한 파일은 고치지 않는다. 새 버전과 그 hash를 불변 목록에 더한다. `persistence-jpa`의
|
||||
`AppliedMigrationImmutabilityTest`가 이 파일들을 있는 자리에서 고정한다.
|
||||
|
||||
## 테스트
|
||||
|
||||
- `src/test` — container 없는 이 leaf 자신의 시험. 돌리기:
|
||||
`./gradlew :adapter:outbound:persistence-fileserver:test --console=plain`.
|
||||
- `FileserverStoreCallerTransactionTest` — 모든 store의 보호된 쓰기는 호출자 트랜잭션이 없으면 repository에
|
||||
닿기 전에 거절한다(위 트랜잭션 규칙, 쓰기마다 경우 하나. Spring Data repository는 mock이다).
|
||||
- `FileserverPersistenceActivationTest` — scan은 `app.fileserver-platform.enabled` 뒤에서 이 패키지만 덮고,
|
||||
JPA 루트 자동 구성보다 먼저 돈다.
|
||||
- `repository.CleanupClaimSqlTest` — claim 글이 문장 하나 모양을 지킨다(claim 규칙). 잠금 자체는
|
||||
`PostgreSqlFileserverReclamationIntegrationTest`가 PostgreSQL에서 본다.
|
||||
- `entity.AssignedIdEntityTest` — H2 위의 Hibernate에서 `Persistable`로 새것인지 정한다.
|
||||
새 store 쓰기는 보호 시험에 자기 경우를 더한다. 새 자동 구성은 켜기 시험에 자기 줄을 더한다.
|
||||
- 포트 계약은 `application-fileserver` testFixtures에 있다(`*PortContract`, 그리고 테이블 하나를 같이 쓰는 quota
|
||||
포트 셋의 `FileQuotaLedgerContract`). 메모리 fake와 PostgreSQL 시험이 모두 그것을 상속한다. 이 leaf가 구현하는
|
||||
포트는 모두 계약이 있다(`docs/testing/TESTING_STRATEGY.md` 9.3절). 2026-11-03에 더한 일곱 개의 PostgreSQL
|
||||
쪽은 `jpa-contract` tag를 달고 persistence-jpa의 `jpaPlatformContractTest` lane에서
|
||||
`FileserverPostgreSqlStack` 위에 돈다. 경우마다 그 시계를 옮긴다.
|
||||
- 실제 PostgreSQL 시험은 아직 `persistence-jpa`의 `postgresqlIntegrationTest` source set에 있다. 그 source set이
|
||||
container와 Flyway 배선을 가지고, JPA readiness card(`persistence-jpa/release/readiness-cards.yaml`,
|
||||
`JpaReadinessRegistryTest`가 검사)가 그 시험을 그 leaf의 태스크로 이름 댄다 — 옮기려면 card의 태스크와
|
||||
selector도 함께 옮겨야 한다: `postgresqlFileserverMigrationIntegrationTest`,
|
||||
`postgresqlFileserverMetadataIntegrationTest`, `postgresqlFileserverReclamationIntegrationTest`
|
||||
(`./gradlew :adapter:outbound:persistence-jpa:<lane> --console=plain`).
|
||||
@AGENTS.md
|
||||
|
||||
@@ -0,0 +1,357 @@
|
||||
# adapter:outbound:persistence-jpa — JPA·PostgreSQL 영속 어댑터
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-persistence-jpa`
|
||||
- Gradle 경로: `:adapter:outbound:persistence-jpa`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:persistence-jpa:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.persistence`.
|
||||
|
||||
예전에 코드 주석으로 두던 설계 결정(트랜잭션 template, 감사 값 잡기, 실패 번역 SPI, 멱등성·outbox 동시성, 분산
|
||||
lock TTL)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙과 계약 표의 정본으로 남는다.
|
||||
|
||||
이 모듈은 RDBMS·JPA 구현 기반이다. MongoDB, Redis, DynamoDB나 다른 NoSQL 저장소를 위한 저장소 중립 core가 아니다.
|
||||
앞으로의 NoSQL 영속 어댑터는 application·domain 포트를 직접 구현하고 이 모듈에 의존하면 안 된다.
|
||||
|
||||
## JPA 관계형 영속 플랫폼
|
||||
|
||||
`docs/design/2026-08-11-jpa-persistence-platform-design.md`의 플랫폼을 여기 구현했다. 설계는 그것을 Stable 라이브러리
|
||||
모듈 18개로 모델링한다. 이 저장소의 실패하면 닫히는 registry가 그 배치보다 앞서므로, 그 모듈들은 이 leaf의
|
||||
**패키지**이고 `docs/jpa/repository-adaptation.md`가 그 대응을 적는다. 타입을 다른 패키지로 옮기기 전에 그것을 읽는다.
|
||||
|
||||
| 플랫폼 패키지 | 가지는 것 |
|
||||
|---|---|
|
||||
| `autoconfigure` | package-private Boot 조립 루트·런타임: vendor와 선택 저장소 import, provider runtime bean. 일부러 공개 API로 내놓지 않는다 |
|
||||
| `api` (+ `.capability`, `.error`, `.query`, `.transaction`) | 프레임워크 없는 계약: operation·query 이름, 안정된 오류 계층, 커밋 완료 증거, keyset cursor |
|
||||
| `transaction` | `SpringTransaction`, 유일한 트랜잭션 엔진(Spring `PlatformTransactionManager` 위의 `TransactionPort`) |
|
||||
| `springdata` | repository fragment, 안전한 정렬, fetch plan, keyset 실행, stream guard |
|
||||
| `hibernate` (+ `.batch`, `.bulk`, `.stateless`) | statement inspector, 통계, batch, bulk DML, stateless session |
|
||||
| `postgresql` (+ `.error`, `.lock`, `.constraint`, `.json`, `.array`, `.range`, `.copy`) | SQLSTATE 분류, lock 옵션, JSONB, 배열과 범위, COPY |
|
||||
| `migration` | `FlywaySchemaPolicy`(`startup` 패키지의 위험 설정 guard가 조립한다) |
|
||||
| `startup` | package-private 기동 정책(`JpaStartupAutoConfiguration`): Flyway migration 전략, datasource env·제품 검사, OSIV·DDL·Hikari·TLS·H2 guard, `jpaplatform` actuator view, readiness `db` 기여. app-bootstrap에서 여기로 옮겼다 |
|
||||
| `cache`, `envers`, `querydsl`, `security`, `observation` | 골라 쓰는 라이브러리 capability와 runtime role 검증기 |
|
||||
| `experimental` | multi-tenancy, RLS, schema·database 테넌시, read replica — 배포가 스스로 만드는 라이브러리 코드. 켜는 flag가 없다 |
|
||||
| `testkit`(`src/testFixtures/java`) | ArchUnit 규칙, fixture, query·plan 단언, PostgreSQL 표, 장애 주입, Flyway validate gate, concurrent index inspector, lock-wait inspector |
|
||||
|
||||
`springdata`, `hibernate`(`.batch`, `.bulk`, `.stateless`, statement inspector), `postgresql`(`.error`, `.lock`,
|
||||
`.constraint`, `.json`, `.array`, `.range`, `.copy`), `api.query`, `envers`, `querydsl`, `cache`, `observation`,
|
||||
`experimental`은 **라이브러리 API**다: 어떤 설정도 그것을 조립하지 않고, 서비스가 이 leaf를 `implementation`으로 받는
|
||||
자기 어댑터 leaf에서 부른다. 진입점과 각각을 증명하는 시험은 [README.md](README.md) 「라이브러리 API」에 있다.
|
||||
|
||||
### Spring 조립 소유
|
||||
|
||||
`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`는 package-private 항목 둘을 내놓는다:
|
||||
`PersistenceJpaAutoConfiguration`과 `PersistenceJpaRuntimeConfig`. Boot가 그 후보를 따로따로 읽으므로 **둘 다**
|
||||
`app.persistence-jpa.enabled=true`를 요구한다. 첫째는 vendor·entity·repository와 capability 저장소 import를 가진다.
|
||||
둘째는 provider runtime bean(`HibernateProviderPolicy`, `PostgreSqlRuntimeRoleVerifier`)만 기여한다. 트랜잭션 엔진은
|
||||
`SpringTransaction` 하나뿐이다. 두 번째 엔진(`SpringJpaTransactionExecutor`/`FullTransactionRetryCoordinator`)은
|
||||
2026-09-25에 지웠다 — `docs/capability-status.md`를 본다. 첫째 후보의 조건이 이웃 import 후보를 막아 준다고 기대지
|
||||
않는다.
|
||||
|
||||
`enabled=false`는 bean만이 아니라 완전히 끄기다: `JpaActivationEnvironmentPostProcessor`(이 leaf의 `spring.factories`)가
|
||||
Boot의 `jdbc`/`hibernate`/`data.jpa`/`flyway` 자동 구성을 `spring.autoconfigure.exclude`에 붙인다. 그래서 DataSource,
|
||||
pool, EntityManagerFactory, Flyway가 하나도 없다.
|
||||
|
||||
소유자를 안전하게 지키는 PostgreSQL 멱등성도 같은 분할을 쓴다: 이 leaf는 `IdempotencyStorePort` 뒤의 실제 PostgreSQL
|
||||
store를 만들고(`PostgreSqlIdempotencyStoreConfig`, `app.capabilities.idempotency.provider=postgresql`일 때만 켜진다),
|
||||
`composition:idempotency`가 provider 고르기, TTL·lease·codec 정책, executor 만들기, 배타성 검증을 가진다. 그 provider를
|
||||
고르면 leaf는 `db/migration/jpa/core` + `db/migration/jpa/idempotency` Flyway stream도 적용하고 기동 때 capability
|
||||
registry 행을 켜며(`IdempotencySchemaStream`, `app.runtime.migration-on-startup=false`이면 건너뛴다), PostgreSQL이 아닌
|
||||
data source를 거절하고, `IdempotencyReaper`를 돌린다. V1·JDBC 멱등성 store도 `jdbc` provider 값도 없다.
|
||||
|
||||
이 모듈은 빌드 한 줄(`runtimeOnly project(':adapter:outbound:persistence-jpa')`)로 고르는 capability다. 템플릿의 기본
|
||||
조립은 이것을 싣지 않는다. 그래서 관계형 저장소가 있을 때만 뜻이 있는 것은 모두 여기 있고 모듈과 함께 켜진다:
|
||||
migration 기동 순서, 해석된 datasource·버전 검증, OSIV·DDL·pool·TLS·vendor 안전, 걸러 낸 관리 endpoint·보고
|
||||
(`startup`), metric을 단 다중 인스턴스 lock(`lock`), readiness `db` 기여, 출하하는 설정
|
||||
(`config/module-defaults/persistence-jpa.yml`). 유스케이스 조립은 아니다: driven 어댑터가 유스케이스를 만들거나 부르면
|
||||
안 되므로 outbox relay는 `composition:outbox-relay`다. leaf에는 `dev.caskeleton.bootstrap` import가 하나도 없어야 한다.
|
||||
기동 실패는 `adapter:outbound:support`(`support.startup`)를 거치고, 새 조립 도우미는 package-private로 둬서 배선
|
||||
실수로 `verifyJpaApiSurface`가 늘지 않게 한다.
|
||||
|
||||
### 양보할 수 없는 것
|
||||
|
||||
- `GenericRepository<T, ID>`도 플랫폼 기반 repository도 없다. 도메인이 자기 repository를 가진다.
|
||||
- `TransactionCompletionUnknownException`은 절대 재시도하지 않는다. `JpaFailureContext`는 재시도할 수 있는
|
||||
completion-unknown 실패를 나타내기를 거절하고, `SpringTransaction`은 아무것도 재시도하지 않는다.
|
||||
- 재시도하는 호출자는 새 트랜잭션과 새 Persistence Context에서 유스케이스 전체를 다시 돌린다.
|
||||
- OSIV는 모든 runtime profile에서 false다. schema 변경은 Flyway가 가지고 Hibernate는 검증만 한다.
|
||||
- 이미 쓰이는 테이블을 잠그는 migration은 `SET LOCAL lock_timeout = '5s';`로 시작한다
|
||||
(`docs/jpa/migration-guide.md` "Bound the lock wait"). `MigrationLockWaitTest`가 그것이 없는 migration을 거절한다. 그
|
||||
규칙 전에 릴리스한 migration 목록에는 새 migration을 넣지 않는다. 그 목록은 inspector가 문장을 새로 배우고 이미
|
||||
`main`에 있는 파일에서 그것을 찾았을 때만 늘어난다.
|
||||
- Flyway는 PostgreSQL migration lock을 열린 트랜잭션이 아니라 세션 동안 쥔다. 아니면 `CREATE INDEX CONCURRENTLY`
|
||||
migration이 Flyway를 영원히 기다린다: 모듈 기본값의 `spring.flyway.postgresql.transactional-lock: false`, 그리고 코드에서
|
||||
만드는 모든 Flyway는 `FlywaySchemaPolicy.configure()`에서 시작한다(`JpaProductionArchitectureTest`가
|
||||
`Flyway.configure()`와 Flyway 설정을 직접 만드는 것 — `new FluentConfiguration()`, `new ClassicConfiguration()`, 하위
|
||||
클래스 — 을 거절한다. `docs/jpa/migration-guide.md` "Who may change the schema").
|
||||
- metric tag, 예외 메시지, 로그는 SQL 매개변수, entity id, tenant id, 개인정보를 싣지 않는다.
|
||||
- 계약은 실제 PostgreSQL에 대고 돈다. H2는 어떤 계약도 만족시키지 않는다.
|
||||
|
||||
### 플랫폼 lane
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:outbound:persistence-jpa:test # hermetic unit lane
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest # real PostgreSQL
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest # Flyway upgrade scenarios
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformFailureTest # deadlock
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest # EXPLAIN structure
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest # runtime role privileges
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest # pool behaviour
|
||||
# Release blocking composition is CI-owned; locally run the exact database qualification set:
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest \
|
||||
:adapter:outbound:persistence-jpa:jpaPlatformMigrationTest \
|
||||
:adapter:outbound:persistence-jpa:jpaPlatformFailureTest \
|
||||
:adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest \
|
||||
:adapter:outbound:persistence-jpa:jpaPlatformSecurityTest \
|
||||
:adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest
|
||||
```
|
||||
|
||||
Docker를 쓰는 모든 lane은 실패하면 닫힌다. 고른 lane이 아무것도 찾지 못하거나 container가 시작하지 못하면 건너뛰기가
|
||||
아니라 오류다 — 건너뛴 계약은 아무도 시험하지 않은 데이터베이스에 대해 성공을 알린다.
|
||||
|
||||
## 책임
|
||||
|
||||
- JPA 엔티티.
|
||||
- Spring Data repository.
|
||||
- 영속 mapper.
|
||||
- repository 어댑터 구현.
|
||||
- outbox append: 모델 하나. `JpaOutboxStore`가 `OutboxAppendPort`를 구현하고 `ValidatedIntegrationEvent`의 정확한 envelope
|
||||
바이트와 hash를 저장한다. claim은 그것으로 같은 이벤트를 되살린다. 정해진 metadata가 다 갖춰지지 않은 행은 읽을 수
|
||||
없고 DEAD로 간다. 짐작으로 발행하지 않는다. `V19`는 발행하지 않은 정해진 형식 이전 행을 거절한다.
|
||||
- outbox relay fencing: `claimBatch`가 claim의 행 lock 아래에서 claim한 relay(`lease_owner`)를 기록하고
|
||||
`lease_token`을 올린다(`V17`). `markPublished`/`markFailed`/`markDead`는 `event_id` + `IN_FLIGHT` + owner + token에
|
||||
대한 조건부 UPDATE 하나이고 `APPLIED`/`STALE`을 돌려준다. 완료는 행을 읽어서 덮어쓰지 않는다. V2 outbox 세대는
|
||||
2026-09-25에 지웠다(`docs/capability-status.md`).
|
||||
- `TransactionPort` 구현(`SpringTransaction`) — 애플리케이션의 트랜잭션 의도와 Spring `PlatformTransactionManager` 사이의
|
||||
다리.
|
||||
- 감사 metadata 기반 + actor 이음매(`audit/AuditableEntity`, `audit/AuditContextPort`, `audit/DomainContextAuditContext`) —
|
||||
아래 「영속 감사 계약」을 본다.
|
||||
- 모든 RDBMS vendor가 같이 쓰는 vendor SPI 확장점:
|
||||
- `outbox/jpa/OutboxClaimRepository` — vendor 모듈이 claim 전략(예: FOR UPDATE SKIP LOCKED)을 구현한다. 구현은 그
|
||||
옆 `outbox/postgresql`과 `outbox/h2`에 있다.
|
||||
- `failure/SqlStateErrorMapping` — vendor 모듈이 vendor 전용 SQLState 행을 기여한다.
|
||||
|
||||
## vendor 고르기
|
||||
|
||||
vendor 조립 둘이 이 모듈에 있고, 각각 자기 하위 패키지에 있으며, 각각 같은 SPI bean 둘(outbox claim, SQLState 대응)을
|
||||
등록한다:
|
||||
|
||||
| vendor | 패키지 | 고르는 것 | schema 소유 |
|
||||
| --- | --- | --- | --- |
|
||||
| PostgreSQL | `.postgresql` | `app.persistence.vendor=postgresql`(기본값이기도 하다) | Flyway, `db/migration/postgresql` |
|
||||
| H2 | `.h2` | `app.persistence.vendor=h2` | Hibernate `ddl-auto`, 엔티티만 |
|
||||
|
||||
outbox와 멱등성 기능은 기능별, 그다음 vendor별로 조각을 모아 둔다: `outbox/{jpa,postgresql,h2}`와
|
||||
`idempotency/{jpa,postgresql}`. 어떤 claim repository를 등록할지는 여전히 위 vendor 설정이 정한다. 그 기능 클래스 중
|
||||
driver 타입을 import하는 것이 없으므로, 그것들이 `.postgresql` 밖에 있어도
|
||||
`PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`이 계속 지켜진다.
|
||||
|
||||
`config/PersistenceVendorSettings`가 선택자를 enum으로 바인딩한다. 그래서 모르는 값은 두 조립 중 어느 것도 읽지 않고
|
||||
`OutboxClaimRepository`가 없다는 오류로 나타나는 대신 기동 때 실패한다. 선택은 모듈이 정한다: 그
|
||||
`config/module-defaults/persistence-jpa.yml`이 모든 profile에서 vendor를 PostgreSQL로, `spring.flyway.enabled`를
|
||||
`APP_FLYWAY_ENABLED`(true)로 기본 설정한다. 조립 루트의 profile 파일은 더는 그것을 다시 적지 않는다(2026-11-01
|
||||
성숙도 리뷰 뒤로. 기본 조립 루트가 고르지 않은 capability의 설정을 알면 안 된다). H2는 `bootRunH2` 태스크가
|
||||
고르는, 개발자가 명시해서 빠지는 길이다. `PersistenceVendorProdSafetyValidator`(`startup`)는 어떤
|
||||
속성 출처가 주든 prod에서 H2를 거절한다. `bootRunH2`에서는 멱등성 provider가 `disabled`나 `redis`여야 한다:
|
||||
`postgresql` provider는 기동 때 H2 data source를 거절한다.
|
||||
|
||||
H2는 로컬 개발 저장소이지 두 번째 운영 대상이 아니다. migration 트리가 없으므로, migration에만 있는 테이블 —
|
||||
capability schema registry, Spring Integration lock 테이블 — 은 H2에 없다. vendor 동시성과 migration 충실도는
|
||||
`postgresqlIntegrationTest`에 남는다.
|
||||
|
||||
outbox claim은 H2가 돌리는 유일한 vendor 문장이고 내용이 같다 — H2 2.4.240은 `FOR UPDATE SKIP LOCKED`를 받고 잠긴 행을
|
||||
정말 건너뛰므로 claim이 뜻을 지킨다. `H2ClaimSqlTest`가 그것을 실제 H2에 대고 실행한다. H2에는 멱등성 store가 없다.
|
||||
|
||||
### capability로 막은 store
|
||||
|
||||
선택 capability 하나를 위한 어댑터는 이 모듈의 나머지와 달리 그 capability의 스위치를 단다. 지금은 `fileserver`
|
||||
패키지가 그 경우다: 거기 있는 모든 `Jpa*` 어댑터는
|
||||
`@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")`를 단다.
|
||||
|
||||
그 막음이 없으면 이 모듈을 넣기만 한 조립 루트도 그 bean을 만들고, 각 bean에는 파일 서버 설정만 주는 협력 객체가
|
||||
필요하다. 지운 샘플 모듈이 쓰지도 않는 Fileserver 협력 객체 때문에 기동에 실패한 일이 그 예다. 아무도 켜지 않은
|
||||
capability의 store는 있으면 안 된다.
|
||||
|
||||
## 허용
|
||||
|
||||
- `:application-core`
|
||||
- `:domain-core`
|
||||
- `:shared-contract`
|
||||
- `:adapter:outbound:support`(타입 있는 기동 실패, EnvironmentPostProcessor 순서, readiness group, module-defaults 읽기)
|
||||
- Spring Data JPA와 Spring transaction.
|
||||
|
||||
## 금지 (Forbidden)
|
||||
|
||||
- `adapter-web`, `app-bootstrap`, `adapter:outbound:support`를 뺀 다른 outbound 어댑터.
|
||||
- 표현 계층 DTO.
|
||||
- 업무 정책 판단.
|
||||
- 영속 어댑터 안에 숨긴 유스케이스 조율.
|
||||
- repository 어댑터가 애플리케이션 흐름을 감싸 `@Transactional`을 여는 것 — 포트를 가로지르는 트랜잭션은 애플리케이션
|
||||
유스케이스가 `TransactionPort`로 가진다. 어댑터 안의 트랜잭션은 포트 메서드 자체가 원자적이어야 하는 저장 프로토콜을
|
||||
정할 때만 허용한다(예: durable operation claim·읽기, live event 위치 할당 + insert).
|
||||
[application-core/AGENTS.md](../../../application-core/AGENTS.md)를 본다.
|
||||
- **DB driver**(`org.postgresql..`, `org.h2..`)나 **`org.flywaydb.database.postgresql..`** — vendor 전용이라 이 모듈의
|
||||
맞는 vendor 패키지(`.postgresql`, `.h2`)에만 둔다. NoSQL 전용 의존은 앞으로 생길 자기 모듈에만 둔다.
|
||||
`CleanArchitectureTest`의 ArchUnit `PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`과 `PERSISTENCE_RDBMS_STAYS_NEUTRAL_OF_H2`가
|
||||
강제한다.
|
||||
- NoSQL 어댑터 코드. MongoDB·Redis·DynamoDB 어댑터는 이 모듈의 자식이 아니라 이웃 모듈이다.
|
||||
- registry가 허용하지 않은 이웃 영속 어댑터나 inbound·outbound 어댑터.
|
||||
|
||||
## TransactionPort 구현 계약
|
||||
|
||||
`SpringTransaction`은 모드마다 `TransactionTemplate`을 하나씩 미리 만든다:
|
||||
|
||||
| 모드 | 전파 | 격리 | 읽기 전용 | timeout |
|
||||
|---|---|---|---|---|
|
||||
| `inWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `app.persistence-jpa.transaction.write-timeout`(30 s) |
|
||||
| `inRootWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `inWrite`와 같음 |
|
||||
| `inRead` | `REQUIRED` | `READ_COMMITTED`(pool) | `true` | `app.persistence-jpa.transaction.read-timeout`(30 s) |
|
||||
| `inNew` | `REQUIRES_NEW` | `READ_COMMITTED`(pool) | `false` | 30 s, 고정 |
|
||||
|
||||
격리 수준은 template이 아니라 pool에 고정한다: template은 `ISOLATION_DEFAULT`를 쓰고, 모듈 기본값이
|
||||
`spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`를 정하며(물리 연결마다 한 번 적용),
|
||||
`HikariPoolConstraintValidator`가 다른 수준이면 기동을 거절한다. template마다 수준을 대면 Spring이 begin마다
|
||||
`getTransactionIsolation()`을 부르고, pgjdbc는 그것에 `SHOW TRANSACTION ISOLATION LEVEL` 왕복으로 답했다.
|
||||
|
||||
모든 모드에는 시간 한계가 있다(2026-11-01부터). Spring이 남은 시간을 문장마다 넘기므로 느린 query나 lock 대기는 서버가
|
||||
취소하고(`57014` → `DB_QUERY_CANCELED`), 다음 문장 전에 기한이 지난 경우도 같은 코드를 받는다: JDBC 경로에서는 Spring의
|
||||
`TransactionTimedOutException`, JPA 경로(`JpaTransactionManager`, 운영)에서는 Hibernate 자신의 `TransactionException`이다.
|
||||
후자는 SQLState가 없고, `SpringTransaction`이 기한이 지났음을 알기 때문에 분류된다(`translateAfterDeadline`). 기한 뒤에
|
||||
던진 업무 예외는 바꾸지 않고 넘긴다.
|
||||
|
||||
미리 만든 template은 만든 뒤 바뀌지 않아서, 동시 호출자가 서로의 재설정을 볼 수 없다. `inRootWrite`는 미리 만든 쓰기
|
||||
template을 다시 쓰지만, 먼저 `TransactionSynchronizationManager.isActualTransactionActive()`를 검사한다. 실제 바깥
|
||||
트랜잭션이 있으면 action이나 `PlatformTransactionManager`를 부르기 전에 반드시
|
||||
`NestedRootTransactionRejectedException`을 던진다. `NEVER`나 `REQUIRES_NEW`를 쓰면 안 된다.
|
||||
|
||||
`inRootWrite`는 `TransactionTemplate.execute`가 커밋한 뒤에만 action 값을 돌려준다. 커밋이 실패하면 트랜잭션 예외를
|
||||
올리고 호출자에게 성공 값을 돌려주지 않는다.
|
||||
|
||||
### `inNew` 풀 크기 제약 (feature-application-port-usecase-contract)
|
||||
|
||||
`REQUIRES_NEW`는 바깥 트랜잭션의 연결을 쥔 채 새 물리 JDBC 연결을 얻는다. pool은 다음을 만족하게 잡는다:
|
||||
|
||||
```
|
||||
hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1
|
||||
```
|
||||
|
||||
레코드마다 `inNew`를 부르는 반복문은 금지다(pool 고갈 + 교착 위험). 레코드를 `inNew` **하나** 안에서 묶어 처리하거나,
|
||||
반복문을 트랜잭션 밖으로 뺀다.
|
||||
|
||||
## 영속 실패 번역 계약 (feature-persistence-failure-baseline)
|
||||
|
||||
날것의 Spring `DataAccessException`(과 그 안의 JPA 예외·SQLState·제약 이름)은 절대 표현 계층에 닿으면 안 된다.
|
||||
`failure/PersistenceExceptionTranslator`가 `DataAccessException`을 SQLState로 아래 §SQLState → 오류 코드 표와 대조해
|
||||
분류하고, `DB_*` `OperationalError` 코드 하나를 실은 프레임워크 중립 `shared.error.PersistenceFailureException`을 돌려준다.
|
||||
|
||||
**표준 행(core):**
|
||||
|
||||
| SQLState | code | category | http | retryable |
|
||||
|---|---|---|---|---|
|
||||
| `08*` | `DB_UNAVAILABLE` | `TRANSIENT_DEPENDENCY` | 503 | true |
|
||||
| `40001` | `DB_SERIALIZATION_FAILURE` | `CONFLICT` | 409 | true |
|
||||
| `23502` | `DB_NULL_VIOLATION` | `DATA_INTEGRITY` | 409 | false |
|
||||
| `23503` | `DB_FK_VIOLATION` | `DATA_INTEGRITY` | 409 | false |
|
||||
| `23505` | `DB_UNIQUE_VIOLATION` | `CONFLICT` | 409 | false |
|
||||
| `23514` | `DB_CHECK_VIOLATION` | `DATA_INTEGRITY` | 409 | false |
|
||||
|
||||
**vendor 전용 행(vendor 모듈이 `SqlStateErrorMapping` SPI로 기여):**
|
||||
|
||||
| SQLState | code | vendor |
|
||||
|---|---|---|
|
||||
| `40P01` | `DB_DEADLOCK` | PostgreSQL(`.postgresql` 패키지) |
|
||||
| `55P03` | `DB_LOCK_TIMEOUT` | PostgreSQL |
|
||||
| `25P03` | `DB_IDLE_IN_TX_TIMEOUT` | PostgreSQL |
|
||||
| `57014` | `DB_QUERY_CANCELED` | PostgreSQL |
|
||||
| `57P01`, `57P02` | `DB_UNAVAILABLE`(커밋 전. 커밋 중이면 completion-unknown) | PostgreSQL |
|
||||
| `23513` | `DB_CHECK_VIOLATION` | H2(`.h2` 패키지) — H2는 CHECK를 core 표가 대응시키는 표준 23514가 아니라 23513으로 알린다 |
|
||||
| `HYT00` | `DB_QUERY_CANCELED` | H2 — H2는 문장 timeout과 lock timeout을 상태 하나로 합친다 |
|
||||
|
||||
PostgreSQL 행은 두 번째 표가 아니다: 2026-11-01 전에는 손으로 관리하던 두 번째 표가 이미 어긋나 있었다.
|
||||
`PostgreSqlSqlStateErrorMapping`이 그 행을 `PostgreSqlFailureClassifier`(SQLState → `FailureCategory`)와
|
||||
`FailureCategory.operationalError()`(category → 코드)에서 끌어낸다 — 라이브러리 `PostgreSqlExceptionTranslator`가 쓰는
|
||||
것과 같은 분류다 — 그리고 위 표준 행, 전용 코드가 없는 category(`INTERNAL_ERROR`), `COMPLETION_UNKNOWN`(단계에
|
||||
따라 다르다)을 뺀다. PostgreSQL 상태를 더하려면 `PostgreSqlState`와 classifier에 더한다. 두 경로가 어떤 상태에서든
|
||||
다르면 `SqlStateClassificationParityTest`가 실패한다.
|
||||
|
||||
**SQLState가 없고 타입으로 분류:** 진 `@Version` 경쟁(`OptimisticLockingFailureException`, JPA
|
||||
`OptimisticLockException`) → `DB_OPTIMISTIC_CONFLICT`(409). 만료된 Spring 트랜잭션 기한(`TransactionTimedOutException`)
|
||||
→ `DB_QUERY_CANCELED`. `SpringTransaction`이 시작한 트랜잭션의 기한이 지난 뒤의 다른 영속 실패(JPA, Spring
|
||||
data-access, Spring transaction 예외) → `DB_QUERY_CANCELED`.
|
||||
|
||||
**커밋 단계(`translateCommitFailure`, ADR-JPA-003):** action이 돌아왔고 `SpringTransaction`이 자기가 시작한 쓰기
|
||||
트랜잭션을 커밋하는 중이면, `08*`, `40003`, vendor가 기여한 종료 상태(`SqlStateErrorMapping.commitOutcomeUnknownStates()`:
|
||||
PostgreSQL `57P01`, `57P02`), SQLState 없는 전송 끊김을 가진 실패는 `DB_UNAVAILABLE`이 아니라
|
||||
`TransactionCompletionUnknownException` → `DB_COMPLETION_UNKNOWN`(500, 절대 재시도하지 않음)이 된다: 서버가 이미 커밋했을
|
||||
수 있다. 서버가 분명히 거절한 커밋(예: 미뤄진 `23505`)은 위 자기 행을 지킨다. 읽기 전용 커밋은 `DB_UNAVAILABLE`을 지킨다.
|
||||
|
||||
- `DataAccessException`을 잡는 repository 어댑터는 `translator.translate(ex)`를 부르고 carrier를 다시 던진다
|
||||
(`ifPresent(e -> { throw e; })`). 빈 결과는 모르는 SQLState라는 뜻이다 — 원래 예외를 다시 던져 web catch-all이 일반
|
||||
`INTERNAL` envelope으로 답하게 한다(새는 것 없음).
|
||||
- category 정본은 값 10개의 `Category` enum이다 — `PERSISTENCE` category는 **없다**(설계 기록 §Audit CATEGORY_DRIFT).
|
||||
|
||||
## 영속 감사 계약 (feature-persistence-auditing-contract)
|
||||
|
||||
감사 metadata(`created_at` / `updated_at` / `created_by` / `updated_by`)는 기반 관심사이고 `domain-core`에 닿으면 안 된다.
|
||||
`audit/AuditableEntity` `@MappedSuperclass`에만 있다. 도메인 aggregate의 영속 엔티티가 그것을 상속해서 고른다(생성
|
||||
명령이 만드는 서비스 persistence leaf의 엔티티가 그렇게 한다). 도메인 aggregate 자체는 감사 필드를 하나도 갖지 않는다.
|
||||
ArchUnit `DOMAIN_IS_PURE`(`jakarta.persistence..` 없음)와 `DOMAIN_ENTITIES_DO_NOT_CARRY_AUDIT_FIELDS`(`..domain..` 아래에
|
||||
`createdAt`/`updatedAt`/`createdBy`/`updatedBy` 필드 없음)가 강제한다.
|
||||
|
||||
- **잡기 = 손으로 명시해 넣기(지금 기본).** repository 어댑터가 생성자로 `Clock`과 `AuditContextPort`를 받고 `save`에서
|
||||
감사 값을 넣는다: INSERT(version null) → `initializeAudit(now, actor)`. UPDATE(version 있음) → 저장된 `created_*`를 그대로
|
||||
넘기고 + `applyModification(now, actor)`. `created_*`는 `updatable = false`다.
|
||||
- **actor 이음매.** `AuditContextPort.currentActor()`는 runtime-context 전파 이음매를 읽고, principal이 묶여 있지 않으면
|
||||
(scheduler / Flyway / 익명) `"system"`으로 물러선다. actor 값의 뜻은
|
||||
feature-authentication-authorization-contract가 가진다(여기서는 UNSUPPORTED). 타입은 `String`으로 고정한다.
|
||||
- **빠지는 것.** `IdempotencyRecordEntity`(자기 `created_at`, `updated_at` 없음) 같은 기반·불변 엔티티는 `AuditableEntity`를
|
||||
상속하지 **않는다**. `version`·낙관적 lock은 이 감사 기반이 아니라 feature-persistence-failure-baseline /
|
||||
feature-transaction-concurrency-contract가 가진다.
|
||||
- **자랄 길(미룸).** 트리에 두 번째 감사 구현은 없다. 손으로 넣는 것이 실수가 너무 잦아지면, 정해진 `AuditableEntity`
|
||||
계약을 `created_*`/`updated_*` schema, actor 한계, `Clock`, `AuditContextPort` 뜻을 지키면서 한 번에 Spring Data
|
||||
listener로 옮긴다. bulk·native `@Query` UPDATE도 listener를 지나지 않으므로 계속 감사 열을 명시해 넣어야 한다.
|
||||
|
||||
## MapStruct 생성 mapper 예외 (feature-architecture-enforcement-rules)
|
||||
|
||||
영속 mapper에 MapStruct를 들이면, 생성된 mapper 클래스에 `javax.annotation.processing.Generated`가 붙는다. mapper 경계
|
||||
위반을 금지하는 아키텍처 규칙은 반드시 ArchUnit predicate로 생성 코드를 뺀다:
|
||||
|
||||
```java
|
||||
import javax.annotation.processing.Generated;
|
||||
|
||||
classes()
|
||||
.that().resideInAPackage("..adapter.persistence.mapper..")
|
||||
.and().areNotAnnotatedWith(Generated.class)
|
||||
.should() /* ... boundary rule ... */;
|
||||
```
|
||||
|
||||
> 애너테이션 FQN에 주의한다: MapStruct는 `javax.annotation.processing.Generated`를 쓴다. Spring AOT는
|
||||
> `org.springframework.aot.generate.Generated`를 쓴다 — 둘을 섞지 **않는다**. 예외는 반드시 빼려는 빌드 단계가 기대하는
|
||||
> 바로 그 애너테이션으로 범위를 잡는다.
|
||||
|
||||
지금 ca-tmpl mapper는 손으로 쓴 것이라 ArchUnit에 MapStruct 예외를 아직 배선하지 않았다 — 생성을 더할 때 위
|
||||
predicate를 따르고, fixture mapper로 red/green 시험을 더한다.
|
||||
|
||||
## NoSQL 확장 규칙
|
||||
|
||||
`adapter-persistence-nosql-core`를 미리 만들지 않는다. NoSQL 저장소는 모델과 운영 계약이 서로 다르다. 실제 MongoDB,
|
||||
Redis, DynamoDB 어댑터가 필요해지면 이웃 모듈을 만든다:
|
||||
|
||||
```text
|
||||
adapter-persistence-mongodb
|
||||
adapter-persistence-redis
|
||||
adapter-persistence-dynamodb
|
||||
```
|
||||
|
||||
그런 모듈은 application·domain 포트를 직접 구현하고 `adapter:outbound:persistence-jpa`에 의존하면 안 된다.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:outbound:persistence-jpa:test --console=plain
|
||||
```
|
||||
@@ -1,357 +1 @@
|
||||
# adapter:outbound:persistence-jpa — JPA·PostgreSQL 영속 어댑터
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-persistence-jpa`
|
||||
- Gradle 경로: `:adapter:outbound:persistence-jpa`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:persistence-jpa:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.persistence`.
|
||||
|
||||
예전에 코드 주석으로 두던 설계 결정(트랜잭션 template, 감사 값 잡기, 실패 번역 SPI, 멱등성·outbox 동시성, 분산
|
||||
lock TTL)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙과 계약 표의 정본으로 남는다.
|
||||
|
||||
이 모듈은 RDBMS·JPA 구현 기반이다. MongoDB, Redis, DynamoDB나 다른 NoSQL 저장소를 위한 저장소 중립 core가 아니다.
|
||||
앞으로의 NoSQL 영속 어댑터는 application·domain 포트를 직접 구현하고 이 모듈에 의존하면 안 된다.
|
||||
|
||||
## JPA 관계형 영속 플랫폼
|
||||
|
||||
`docs/design/2026-08-11-jpa-persistence-platform-design.md`의 플랫폼을 여기 구현했다. 설계는 그것을 Stable 라이브러리
|
||||
모듈 18개로 모델링한다. 이 저장소의 실패하면 닫히는 registry가 그 배치보다 앞서므로, 그 모듈들은 이 leaf의
|
||||
**패키지**이고 `docs/jpa/repository-adaptation.md`가 그 대응을 적는다. 타입을 다른 패키지로 옮기기 전에 그것을 읽는다.
|
||||
|
||||
| 플랫폼 패키지 | 가지는 것 |
|
||||
|---|---|
|
||||
| `autoconfigure` | package-private Boot 조립 루트·런타임: vendor와 선택 저장소 import, provider runtime bean. 일부러 공개 API로 내놓지 않는다 |
|
||||
| `api` (+ `.capability`, `.error`, `.query`, `.transaction`) | 프레임워크 없는 계약: operation·query 이름, 안정된 오류 계층, 커밋 완료 증거, keyset cursor |
|
||||
| `transaction` | `SpringTransaction`, 유일한 트랜잭션 엔진(Spring `PlatformTransactionManager` 위의 `TransactionPort`) |
|
||||
| `springdata` | repository fragment, 안전한 정렬, fetch plan, keyset 실행, stream guard |
|
||||
| `hibernate` (+ `.batch`, `.bulk`, `.stateless`) | statement inspector, 통계, batch, bulk DML, stateless session |
|
||||
| `postgresql` (+ `.error`, `.lock`, `.constraint`, `.json`, `.array`, `.range`, `.copy`) | SQLSTATE 분류, lock 옵션, JSONB, 배열과 범위, COPY |
|
||||
| `migration` | `FlywaySchemaPolicy`(`startup` 패키지의 위험 설정 guard가 조립한다) |
|
||||
| `startup` | package-private 기동 정책(`JpaStartupAutoConfiguration`): Flyway migration 전략, datasource env·제품 검사, OSIV·DDL·Hikari·TLS·H2 guard, `jpaplatform` actuator view, readiness `db` 기여. app-bootstrap에서 여기로 옮겼다 |
|
||||
| `cache`, `envers`, `querydsl`, `security`, `observation` | 골라 쓰는 라이브러리 capability와 runtime role 검증기 |
|
||||
| `experimental` | multi-tenancy, RLS, schema·database 테넌시, read replica — 배포가 스스로 만드는 라이브러리 코드. 켜는 flag가 없다 |
|
||||
| `testkit`(`src/testFixtures/java`) | ArchUnit 규칙, fixture, query·plan 단언, PostgreSQL 표, 장애 주입, Flyway validate gate, concurrent index inspector, lock-wait inspector |
|
||||
|
||||
`springdata`, `hibernate`(`.batch`, `.bulk`, `.stateless`, statement inspector), `postgresql`(`.error`, `.lock`,
|
||||
`.constraint`, `.json`, `.array`, `.range`, `.copy`), `api.query`, `envers`, `querydsl`, `cache`, `observation`,
|
||||
`experimental`은 **라이브러리 API**다: 어떤 설정도 그것을 조립하지 않고, 서비스가 이 leaf를 `implementation`으로 받는
|
||||
자기 어댑터 leaf에서 부른다. 진입점과 각각을 증명하는 시험은 [README.md](README.md) 「라이브러리 API」에 있다.
|
||||
|
||||
### Spring 조립 소유
|
||||
|
||||
`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`는 package-private 항목 둘을 내놓는다:
|
||||
`PersistenceJpaAutoConfiguration`과 `PersistenceJpaRuntimeConfig`. Boot가 그 후보를 따로따로 읽으므로 **둘 다**
|
||||
`app.persistence-jpa.enabled=true`를 요구한다. 첫째는 vendor·entity·repository와 capability 저장소 import를 가진다.
|
||||
둘째는 provider runtime bean(`HibernateProviderPolicy`, `PostgreSqlRuntimeRoleVerifier`)만 기여한다. 트랜잭션 엔진은
|
||||
`SpringTransaction` 하나뿐이다. 두 번째 엔진(`SpringJpaTransactionExecutor`/`FullTransactionRetryCoordinator`)은
|
||||
2026-09-25에 지웠다 — `docs/capability-status.md`를 본다. 첫째 후보의 조건이 이웃 import 후보를 막아 준다고 기대지
|
||||
않는다.
|
||||
|
||||
`enabled=false`는 bean만이 아니라 완전히 끄기다: `JpaActivationEnvironmentPostProcessor`(이 leaf의 `spring.factories`)가
|
||||
Boot의 `jdbc`/`hibernate`/`data.jpa`/`flyway` 자동 구성을 `spring.autoconfigure.exclude`에 붙인다. 그래서 DataSource,
|
||||
pool, EntityManagerFactory, Flyway가 하나도 없다.
|
||||
|
||||
소유자를 안전하게 지키는 PostgreSQL 멱등성도 같은 분할을 쓴다: 이 leaf는 `IdempotencyStorePort` 뒤의 실제 PostgreSQL
|
||||
store를 만들고(`PostgreSqlIdempotencyStoreConfig`, `app.capabilities.idempotency.provider=postgresql`일 때만 켜진다),
|
||||
`composition:idempotency`가 provider 고르기, TTL·lease·codec 정책, executor 만들기, 배타성 검증을 가진다. 그 provider를
|
||||
고르면 leaf는 `db/migration/jpa/core` + `db/migration/jpa/idempotency` Flyway stream도 적용하고 기동 때 capability
|
||||
registry 행을 켜며(`IdempotencySchemaStream`, `app.runtime.migration-on-startup=false`이면 건너뛴다), PostgreSQL이 아닌
|
||||
data source를 거절하고, `IdempotencyReaper`를 돌린다. V1·JDBC 멱등성 store도 `jdbc` provider 값도 없다.
|
||||
|
||||
이 모듈은 빌드 한 줄(`runtimeOnly project(':adapter:outbound:persistence-jpa')`)로 고르는 capability다. 템플릿의 기본
|
||||
조립은 이것을 싣지 않는다. 그래서 관계형 저장소가 있을 때만 뜻이 있는 것은 모두 여기 있고 모듈과 함께 켜진다:
|
||||
migration 기동 순서, 해석된 datasource·버전 검증, OSIV·DDL·pool·TLS·vendor 안전, 걸러 낸 관리 endpoint·보고
|
||||
(`startup`), metric을 단 다중 인스턴스 lock(`lock`), readiness `db` 기여, 출하하는 설정
|
||||
(`config/module-defaults/persistence-jpa.yml`). 유스케이스 조립은 아니다: driven 어댑터가 유스케이스를 만들거나 부르면
|
||||
안 되므로 outbox relay는 `composition:outbox-relay`다. leaf에는 `dev.caskeleton.bootstrap` import가 하나도 없어야 한다.
|
||||
기동 실패는 `adapter:outbound:support`(`support.startup`)를 거치고, 새 조립 도우미는 package-private로 둬서 배선
|
||||
실수로 `verifyJpaApiSurface`가 늘지 않게 한다.
|
||||
|
||||
### 양보할 수 없는 것
|
||||
|
||||
- `GenericRepository<T, ID>`도 플랫폼 기반 repository도 없다. 도메인이 자기 repository를 가진다.
|
||||
- `TransactionCompletionUnknownException`은 절대 재시도하지 않는다. `JpaFailureContext`는 재시도할 수 있는
|
||||
completion-unknown 실패를 나타내기를 거절하고, `SpringTransaction`은 아무것도 재시도하지 않는다.
|
||||
- 재시도하는 호출자는 새 트랜잭션과 새 Persistence Context에서 유스케이스 전체를 다시 돌린다.
|
||||
- OSIV는 모든 runtime profile에서 false다. schema 변경은 Flyway가 가지고 Hibernate는 검증만 한다.
|
||||
- 이미 쓰이는 테이블을 잠그는 migration은 `SET LOCAL lock_timeout = '5s';`로 시작한다
|
||||
(`docs/jpa/migration-guide.md` "Bound the lock wait"). `MigrationLockWaitTest`가 그것이 없는 migration을 거절한다. 그
|
||||
규칙 전에 릴리스한 migration 목록에는 새 migration을 넣지 않는다. 그 목록은 inspector가 문장을 새로 배우고 이미
|
||||
`main`에 있는 파일에서 그것을 찾았을 때만 늘어난다.
|
||||
- Flyway는 PostgreSQL migration lock을 열린 트랜잭션이 아니라 세션 동안 쥔다. 아니면 `CREATE INDEX CONCURRENTLY`
|
||||
migration이 Flyway를 영원히 기다린다: 모듈 기본값의 `spring.flyway.postgresql.transactional-lock: false`, 그리고 코드에서
|
||||
만드는 모든 Flyway는 `FlywaySchemaPolicy.configure()`에서 시작한다(`JpaProductionArchitectureTest`가
|
||||
`Flyway.configure()`와 Flyway 설정을 직접 만드는 것 — `new FluentConfiguration()`, `new ClassicConfiguration()`, 하위
|
||||
클래스 — 을 거절한다. `docs/jpa/migration-guide.md` "Who may change the schema").
|
||||
- metric tag, 예외 메시지, 로그는 SQL 매개변수, entity id, tenant id, 개인정보를 싣지 않는다.
|
||||
- 계약은 실제 PostgreSQL에 대고 돈다. H2는 어떤 계약도 만족시키지 않는다.
|
||||
|
||||
### 플랫폼 lane
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:outbound:persistence-jpa:test # hermetic unit lane
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest # real PostgreSQL
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest # Flyway upgrade scenarios
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformFailureTest # deadlock
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest # EXPLAIN structure
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest # runtime role privileges
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest # pool behaviour
|
||||
# Release blocking composition is CI-owned; locally run the exact database qualification set:
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest \
|
||||
:adapter:outbound:persistence-jpa:jpaPlatformMigrationTest \
|
||||
:adapter:outbound:persistence-jpa:jpaPlatformFailureTest \
|
||||
:adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest \
|
||||
:adapter:outbound:persistence-jpa:jpaPlatformSecurityTest \
|
||||
:adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest
|
||||
```
|
||||
|
||||
Docker를 쓰는 모든 lane은 실패하면 닫힌다. 고른 lane이 아무것도 찾지 못하거나 container가 시작하지 못하면 건너뛰기가
|
||||
아니라 오류다 — 건너뛴 계약은 아무도 시험하지 않은 데이터베이스에 대해 성공을 알린다.
|
||||
|
||||
## 책임
|
||||
|
||||
- JPA 엔티티.
|
||||
- Spring Data repository.
|
||||
- 영속 mapper.
|
||||
- repository 어댑터 구현.
|
||||
- outbox append: 모델 하나. `JpaOutboxStore`가 `OutboxAppendPort`를 구현하고 `ValidatedIntegrationEvent`의 정확한 envelope
|
||||
바이트와 hash를 저장한다. claim은 그것으로 같은 이벤트를 되살린다. 정해진 metadata가 다 갖춰지지 않은 행은 읽을 수
|
||||
없고 DEAD로 간다. 짐작으로 발행하지 않는다. `V19`는 발행하지 않은 정해진 형식 이전 행을 거절한다.
|
||||
- outbox relay fencing: `claimBatch`가 claim의 행 lock 아래에서 claim한 relay(`lease_owner`)를 기록하고
|
||||
`lease_token`을 올린다(`V17`). `markPublished`/`markFailed`/`markDead`는 `event_id` + `IN_FLIGHT` + owner + token에
|
||||
대한 조건부 UPDATE 하나이고 `APPLIED`/`STALE`을 돌려준다. 완료는 행을 읽어서 덮어쓰지 않는다. V2 outbox 세대는
|
||||
2026-09-25에 지웠다(`docs/capability-status.md`).
|
||||
- `TransactionPort` 구현(`SpringTransaction`) — 애플리케이션의 트랜잭션 의도와 Spring `PlatformTransactionManager` 사이의
|
||||
다리.
|
||||
- 감사 metadata 기반 + actor 이음매(`audit/AuditableEntity`, `audit/AuditContextPort`, `audit/DomainContextAuditContext`) —
|
||||
아래 「영속 감사 계약」을 본다.
|
||||
- 모든 RDBMS vendor가 같이 쓰는 vendor SPI 확장점:
|
||||
- `outbox/jpa/OutboxClaimRepository` — vendor 모듈이 claim 전략(예: FOR UPDATE SKIP LOCKED)을 구현한다. 구현은 그
|
||||
옆 `outbox/postgresql`과 `outbox/h2`에 있다.
|
||||
- `failure/SqlStateErrorMapping` — vendor 모듈이 vendor 전용 SQLState 행을 기여한다.
|
||||
|
||||
## vendor 고르기
|
||||
|
||||
vendor 조립 둘이 이 모듈에 있고, 각각 자기 하위 패키지에 있으며, 각각 같은 SPI bean 둘(outbox claim, SQLState 대응)을
|
||||
등록한다:
|
||||
|
||||
| vendor | 패키지 | 고르는 것 | schema 소유 |
|
||||
| --- | --- | --- | --- |
|
||||
| PostgreSQL | `.postgresql` | `app.persistence.vendor=postgresql`(기본값이기도 하다) | Flyway, `db/migration/postgresql` |
|
||||
| H2 | `.h2` | `app.persistence.vendor=h2` | Hibernate `ddl-auto`, 엔티티만 |
|
||||
|
||||
outbox와 멱등성 기능은 기능별, 그다음 vendor별로 조각을 모아 둔다: `outbox/{jpa,postgresql,h2}`와
|
||||
`idempotency/{jpa,postgresql}`. 어떤 claim repository를 등록할지는 여전히 위 vendor 설정이 정한다. 그 기능 클래스 중
|
||||
driver 타입을 import하는 것이 없으므로, 그것들이 `.postgresql` 밖에 있어도
|
||||
`PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`이 계속 지켜진다.
|
||||
|
||||
`config/PersistenceVendorSettings`가 선택자를 enum으로 바인딩한다. 그래서 모르는 값은 두 조립 중 어느 것도 읽지 않고
|
||||
`OutboxClaimRepository`가 없다는 오류로 나타나는 대신 기동 때 실패한다. 선택은 모듈이 정한다: 그
|
||||
`config/module-defaults/persistence-jpa.yml`이 모든 profile에서 vendor를 PostgreSQL로, `spring.flyway.enabled`를
|
||||
`APP_FLYWAY_ENABLED`(true)로 기본 설정한다. 조립 루트의 profile 파일은 더는 그것을 다시 적지 않는다(2026-11-01
|
||||
성숙도 리뷰 뒤로. 기본 조립 루트가 고르지 않은 capability의 설정을 알면 안 된다). H2는 `bootRunH2` 태스크가
|
||||
고르는, 개발자가 명시해서 빠지는 길이다. `PersistenceVendorProdSafetyValidator`(`startup`)는 어떤
|
||||
속성 출처가 주든 prod에서 H2를 거절한다. `bootRunH2`에서는 멱등성 provider가 `disabled`나 `redis`여야 한다:
|
||||
`postgresql` provider는 기동 때 H2 data source를 거절한다.
|
||||
|
||||
H2는 로컬 개발 저장소이지 두 번째 운영 대상이 아니다. migration 트리가 없으므로, migration에만 있는 테이블 —
|
||||
capability schema registry, Spring Integration lock 테이블 — 은 H2에 없다. vendor 동시성과 migration 충실도는
|
||||
`postgresqlIntegrationTest`에 남는다.
|
||||
|
||||
outbox claim은 H2가 돌리는 유일한 vendor 문장이고 내용이 같다 — H2 2.4.240은 `FOR UPDATE SKIP LOCKED`를 받고 잠긴 행을
|
||||
정말 건너뛰므로 claim이 뜻을 지킨다. `H2ClaimSqlTest`가 그것을 실제 H2에 대고 실행한다. H2에는 멱등성 store가 없다.
|
||||
|
||||
### capability로 막은 store
|
||||
|
||||
선택 capability 하나를 위한 어댑터는 이 모듈의 나머지와 달리 그 capability의 스위치를 단다. 지금은 `fileserver`
|
||||
패키지가 그 경우다: 거기 있는 모든 `Jpa*` 어댑터는
|
||||
`@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")`를 단다.
|
||||
|
||||
그 막음이 없으면 이 모듈을 넣기만 한 조립 루트도 그 bean을 만들고, 각 bean에는 파일 서버 설정만 주는 협력 객체가
|
||||
필요하다. 지운 샘플 모듈이 쓰지도 않는 Fileserver 협력 객체 때문에 기동에 실패한 일이 그 예다. 아무도 켜지 않은
|
||||
capability의 store는 있으면 안 된다.
|
||||
|
||||
## 허용
|
||||
|
||||
- `:application-core`
|
||||
- `:domain-core`
|
||||
- `:shared-contract`
|
||||
- `:adapter:outbound:support`(타입 있는 기동 실패, EnvironmentPostProcessor 순서, readiness group, module-defaults 읽기)
|
||||
- Spring Data JPA와 Spring transaction.
|
||||
|
||||
## 금지 (Forbidden)
|
||||
|
||||
- `adapter-web`, `app-bootstrap`, `adapter:outbound:support`를 뺀 다른 outbound 어댑터.
|
||||
- 표현 계층 DTO.
|
||||
- 업무 정책 판단.
|
||||
- 영속 어댑터 안에 숨긴 유스케이스 조율.
|
||||
- repository 어댑터가 애플리케이션 흐름을 감싸 `@Transactional`을 여는 것 — 포트를 가로지르는 트랜잭션은 애플리케이션
|
||||
유스케이스가 `TransactionPort`로 가진다. 어댑터 안의 트랜잭션은 포트 메서드 자체가 원자적이어야 하는 저장 프로토콜을
|
||||
정할 때만 허용한다(예: durable operation claim·읽기, live event 위치 할당 + insert).
|
||||
[application-core/CLAUDE.md](../../../application-core/CLAUDE.md)를 본다.
|
||||
- **DB driver**(`org.postgresql..`, `org.h2..`)나 **`org.flywaydb.database.postgresql..`** — vendor 전용이라 이 모듈의
|
||||
맞는 vendor 패키지(`.postgresql`, `.h2`)에만 둔다. NoSQL 전용 의존은 앞으로 생길 자기 모듈에만 둔다.
|
||||
`CleanArchitectureTest`의 ArchUnit `PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`과 `PERSISTENCE_RDBMS_STAYS_NEUTRAL_OF_H2`가
|
||||
강제한다.
|
||||
- NoSQL 어댑터 코드. MongoDB·Redis·DynamoDB 어댑터는 이 모듈의 자식이 아니라 이웃 모듈이다.
|
||||
- registry가 허용하지 않은 이웃 영속 어댑터나 inbound·outbound 어댑터.
|
||||
|
||||
## TransactionPort 구현 계약
|
||||
|
||||
`SpringTransaction`은 모드마다 `TransactionTemplate`을 하나씩 미리 만든다:
|
||||
|
||||
| 모드 | 전파 | 격리 | 읽기 전용 | timeout |
|
||||
|---|---|---|---|---|
|
||||
| `inWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `app.persistence-jpa.transaction.write-timeout`(30 s) |
|
||||
| `inRootWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `inWrite`와 같음 |
|
||||
| `inRead` | `REQUIRED` | `READ_COMMITTED`(pool) | `true` | `app.persistence-jpa.transaction.read-timeout`(30 s) |
|
||||
| `inNew` | `REQUIRES_NEW` | `READ_COMMITTED`(pool) | `false` | 30 s, 고정 |
|
||||
|
||||
격리 수준은 template이 아니라 pool에 고정한다: template은 `ISOLATION_DEFAULT`를 쓰고, 모듈 기본값이
|
||||
`spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`를 정하며(물리 연결마다 한 번 적용),
|
||||
`HikariPoolConstraintValidator`가 다른 수준이면 기동을 거절한다. template마다 수준을 대면 Spring이 begin마다
|
||||
`getTransactionIsolation()`을 부르고, pgjdbc는 그것에 `SHOW TRANSACTION ISOLATION LEVEL` 왕복으로 답했다.
|
||||
|
||||
모든 모드에는 시간 한계가 있다(2026-11-01부터). Spring이 남은 시간을 문장마다 넘기므로 느린 query나 lock 대기는 서버가
|
||||
취소하고(`57014` → `DB_QUERY_CANCELED`), 다음 문장 전에 기한이 지난 경우도 같은 코드를 받는다: JDBC 경로에서는 Spring의
|
||||
`TransactionTimedOutException`, JPA 경로(`JpaTransactionManager`, 운영)에서는 Hibernate 자신의 `TransactionException`이다.
|
||||
후자는 SQLState가 없고, `SpringTransaction`이 기한이 지났음을 알기 때문에 분류된다(`translateAfterDeadline`). 기한 뒤에
|
||||
던진 업무 예외는 바꾸지 않고 넘긴다.
|
||||
|
||||
미리 만든 template은 만든 뒤 바뀌지 않아서, 동시 호출자가 서로의 재설정을 볼 수 없다. `inRootWrite`는 미리 만든 쓰기
|
||||
template을 다시 쓰지만, 먼저 `TransactionSynchronizationManager.isActualTransactionActive()`를 검사한다. 실제 바깥
|
||||
트랜잭션이 있으면 action이나 `PlatformTransactionManager`를 부르기 전에 반드시
|
||||
`NestedRootTransactionRejectedException`을 던진다. `NEVER`나 `REQUIRES_NEW`를 쓰면 안 된다.
|
||||
|
||||
`inRootWrite`는 `TransactionTemplate.execute`가 커밋한 뒤에만 action 값을 돌려준다. 커밋이 실패하면 트랜잭션 예외를
|
||||
올리고 호출자에게 성공 값을 돌려주지 않는다.
|
||||
|
||||
### `inNew` 풀 크기 제약 (feature-application-port-usecase-contract)
|
||||
|
||||
`REQUIRES_NEW`는 바깥 트랜잭션의 연결을 쥔 채 새 물리 JDBC 연결을 얻는다. pool은 다음을 만족하게 잡는다:
|
||||
|
||||
```
|
||||
hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1
|
||||
```
|
||||
|
||||
레코드마다 `inNew`를 부르는 반복문은 금지다(pool 고갈 + 교착 위험). 레코드를 `inNew` **하나** 안에서 묶어 처리하거나,
|
||||
반복문을 트랜잭션 밖으로 뺀다.
|
||||
|
||||
## 영속 실패 번역 계약 (feature-persistence-failure-baseline)
|
||||
|
||||
날것의 Spring `DataAccessException`(과 그 안의 JPA 예외·SQLState·제약 이름)은 절대 표현 계층에 닿으면 안 된다.
|
||||
`failure/PersistenceExceptionTranslator`가 `DataAccessException`을 SQLState로 아래 §SQLState → 오류 코드 표와 대조해
|
||||
분류하고, `DB_*` `OperationalError` 코드 하나를 실은 프레임워크 중립 `shared.error.PersistenceFailureException`을 돌려준다.
|
||||
|
||||
**표준 행(core):**
|
||||
|
||||
| SQLState | code | category | http | retryable |
|
||||
|---|---|---|---|---|
|
||||
| `08*` | `DB_UNAVAILABLE` | `TRANSIENT_DEPENDENCY` | 503 | true |
|
||||
| `40001` | `DB_SERIALIZATION_FAILURE` | `CONFLICT` | 409 | true |
|
||||
| `23502` | `DB_NULL_VIOLATION` | `DATA_INTEGRITY` | 409 | false |
|
||||
| `23503` | `DB_FK_VIOLATION` | `DATA_INTEGRITY` | 409 | false |
|
||||
| `23505` | `DB_UNIQUE_VIOLATION` | `CONFLICT` | 409 | false |
|
||||
| `23514` | `DB_CHECK_VIOLATION` | `DATA_INTEGRITY` | 409 | false |
|
||||
|
||||
**vendor 전용 행(vendor 모듈이 `SqlStateErrorMapping` SPI로 기여):**
|
||||
|
||||
| SQLState | code | vendor |
|
||||
|---|---|---|
|
||||
| `40P01` | `DB_DEADLOCK` | PostgreSQL(`.postgresql` 패키지) |
|
||||
| `55P03` | `DB_LOCK_TIMEOUT` | PostgreSQL |
|
||||
| `25P03` | `DB_IDLE_IN_TX_TIMEOUT` | PostgreSQL |
|
||||
| `57014` | `DB_QUERY_CANCELED` | PostgreSQL |
|
||||
| `57P01`, `57P02` | `DB_UNAVAILABLE`(커밋 전. 커밋 중이면 completion-unknown) | PostgreSQL |
|
||||
| `23513` | `DB_CHECK_VIOLATION` | H2(`.h2` 패키지) — H2는 CHECK를 core 표가 대응시키는 표준 23514가 아니라 23513으로 알린다 |
|
||||
| `HYT00` | `DB_QUERY_CANCELED` | H2 — H2는 문장 timeout과 lock timeout을 상태 하나로 합친다 |
|
||||
|
||||
PostgreSQL 행은 두 번째 표가 아니다: 2026-11-01 전에는 손으로 관리하던 두 번째 표가 이미 어긋나 있었다.
|
||||
`PostgreSqlSqlStateErrorMapping`이 그 행을 `PostgreSqlFailureClassifier`(SQLState → `FailureCategory`)와
|
||||
`FailureCategory.operationalError()`(category → 코드)에서 끌어낸다 — 라이브러리 `PostgreSqlExceptionTranslator`가 쓰는
|
||||
것과 같은 분류다 — 그리고 위 표준 행, 전용 코드가 없는 category(`INTERNAL_ERROR`), `COMPLETION_UNKNOWN`(단계에
|
||||
따라 다르다)을 뺀다. PostgreSQL 상태를 더하려면 `PostgreSqlState`와 classifier에 더한다. 두 경로가 어떤 상태에서든
|
||||
다르면 `SqlStateClassificationParityTest`가 실패한다.
|
||||
|
||||
**SQLState가 없고 타입으로 분류:** 진 `@Version` 경쟁(`OptimisticLockingFailureException`, JPA
|
||||
`OptimisticLockException`) → `DB_OPTIMISTIC_CONFLICT`(409). 만료된 Spring 트랜잭션 기한(`TransactionTimedOutException`)
|
||||
→ `DB_QUERY_CANCELED`. `SpringTransaction`이 시작한 트랜잭션의 기한이 지난 뒤의 다른 영속 실패(JPA, Spring
|
||||
data-access, Spring transaction 예외) → `DB_QUERY_CANCELED`.
|
||||
|
||||
**커밋 단계(`translateCommitFailure`, ADR-JPA-003):** action이 돌아왔고 `SpringTransaction`이 자기가 시작한 쓰기
|
||||
트랜잭션을 커밋하는 중이면, `08*`, `40003`, vendor가 기여한 종료 상태(`SqlStateErrorMapping.commitOutcomeUnknownStates()`:
|
||||
PostgreSQL `57P01`, `57P02`), SQLState 없는 전송 끊김을 가진 실패는 `DB_UNAVAILABLE`이 아니라
|
||||
`TransactionCompletionUnknownException` → `DB_COMPLETION_UNKNOWN`(500, 절대 재시도하지 않음)이 된다: 서버가 이미 커밋했을
|
||||
수 있다. 서버가 분명히 거절한 커밋(예: 미뤄진 `23505`)은 위 자기 행을 지킨다. 읽기 전용 커밋은 `DB_UNAVAILABLE`을 지킨다.
|
||||
|
||||
- `DataAccessException`을 잡는 repository 어댑터는 `translator.translate(ex)`를 부르고 carrier를 다시 던진다
|
||||
(`ifPresent(e -> { throw e; })`). 빈 결과는 모르는 SQLState라는 뜻이다 — 원래 예외를 다시 던져 web catch-all이 일반
|
||||
`INTERNAL` envelope으로 답하게 한다(새는 것 없음).
|
||||
- category 정본은 값 10개의 `Category` enum이다 — `PERSISTENCE` category는 **없다**(설계 기록 §Audit CATEGORY_DRIFT).
|
||||
|
||||
## 영속 감사 계약 (feature-persistence-auditing-contract)
|
||||
|
||||
감사 metadata(`created_at` / `updated_at` / `created_by` / `updated_by`)는 기반 관심사이고 `domain-core`에 닿으면 안 된다.
|
||||
`audit/AuditableEntity` `@MappedSuperclass`에만 있다. 도메인 aggregate의 영속 엔티티가 그것을 상속해서 고른다(생성
|
||||
명령이 만드는 서비스 persistence leaf의 엔티티가 그렇게 한다). 도메인 aggregate 자체는 감사 필드를 하나도 갖지 않는다.
|
||||
ArchUnit `DOMAIN_IS_PURE`(`jakarta.persistence..` 없음)와 `DOMAIN_ENTITIES_DO_NOT_CARRY_AUDIT_FIELDS`(`..domain..` 아래에
|
||||
`createdAt`/`updatedAt`/`createdBy`/`updatedBy` 필드 없음)가 강제한다.
|
||||
|
||||
- **잡기 = 손으로 명시해 넣기(지금 기본).** repository 어댑터가 생성자로 `Clock`과 `AuditContextPort`를 받고 `save`에서
|
||||
감사 값을 넣는다: INSERT(version null) → `initializeAudit(now, actor)`. UPDATE(version 있음) → 저장된 `created_*`를 그대로
|
||||
넘기고 + `applyModification(now, actor)`. `created_*`는 `updatable = false`다.
|
||||
- **actor 이음매.** `AuditContextPort.currentActor()`는 runtime-context 전파 이음매를 읽고, principal이 묶여 있지 않으면
|
||||
(scheduler / Flyway / 익명) `"system"`으로 물러선다. actor 값의 뜻은
|
||||
feature-authentication-authorization-contract가 가진다(여기서는 UNSUPPORTED). 타입은 `String`으로 고정한다.
|
||||
- **빠지는 것.** `IdempotencyRecordEntity`(자기 `created_at`, `updated_at` 없음) 같은 기반·불변 엔티티는 `AuditableEntity`를
|
||||
상속하지 **않는다**. `version`·낙관적 lock은 이 감사 기반이 아니라 feature-persistence-failure-baseline /
|
||||
feature-transaction-concurrency-contract가 가진다.
|
||||
- **자랄 길(미룸).** 트리에 두 번째 감사 구현은 없다. 손으로 넣는 것이 실수가 너무 잦아지면, 정해진 `AuditableEntity`
|
||||
계약을 `created_*`/`updated_*` schema, actor 한계, `Clock`, `AuditContextPort` 뜻을 지키면서 한 번에 Spring Data
|
||||
listener로 옮긴다. bulk·native `@Query` UPDATE도 listener를 지나지 않으므로 계속 감사 열을 명시해 넣어야 한다.
|
||||
|
||||
## MapStruct 생성 mapper 예외 (feature-architecture-enforcement-rules)
|
||||
|
||||
영속 mapper에 MapStruct를 들이면, 생성된 mapper 클래스에 `javax.annotation.processing.Generated`가 붙는다. mapper 경계
|
||||
위반을 금지하는 아키텍처 규칙은 반드시 ArchUnit predicate로 생성 코드를 뺀다:
|
||||
|
||||
```java
|
||||
import javax.annotation.processing.Generated;
|
||||
|
||||
classes()
|
||||
.that().resideInAPackage("..adapter.persistence.mapper..")
|
||||
.and().areNotAnnotatedWith(Generated.class)
|
||||
.should() /* ... boundary rule ... */;
|
||||
```
|
||||
|
||||
> 애너테이션 FQN에 주의한다: MapStruct는 `javax.annotation.processing.Generated`를 쓴다. Spring AOT는
|
||||
> `org.springframework.aot.generate.Generated`를 쓴다 — 둘을 섞지 **않는다**. 예외는 반드시 빼려는 빌드 단계가 기대하는
|
||||
> 바로 그 애너테이션으로 범위를 잡는다.
|
||||
|
||||
지금 ca-tmpl mapper는 손으로 쓴 것이라 ArchUnit에 MapStruct 예외를 아직 배선하지 않았다 — 생성을 더할 때 위
|
||||
predicate를 따르고, fixture mapper로 red/green 시험을 더한다.
|
||||
|
||||
## NoSQL 확장 규칙
|
||||
|
||||
`adapter-persistence-nosql-core`를 미리 만들지 않는다. NoSQL 저장소는 모델과 운영 계약이 서로 다르다. 실제 MongoDB,
|
||||
Redis, DynamoDB 어댑터가 필요해지면 이웃 모듈을 만든다:
|
||||
|
||||
```text
|
||||
adapter-persistence-mongodb
|
||||
adapter-persistence-redis
|
||||
adapter-persistence-dynamodb
|
||||
```
|
||||
|
||||
그런 모듈은 application·domain 포트를 직접 구현하고 `adapter:outbound:persistence-jpa`에 의존하면 안 된다.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:outbound:persistence-jpa:test --console=plain
|
||||
```
|
||||
@AGENTS.md
|
||||
|
||||
@@ -3,9 +3,9 @@
|
||||
RDBMS/JPA 퍼시스턴스 베이스 모듈. 패키지 루트: `dev.caskeleton.adapter.persistence`.
|
||||
|
||||
허용/금지 의존, 테스트 명령, 그리고 **계약 테이블**(TransactionPort 모드표, SQLState → Error
|
||||
Code 매트릭스, auditing 계약, 분산 락 provider 선택표)의 SSOT 는 [CLAUDE.md](CLAUDE.md) 다.
|
||||
Code 매트릭스, auditing 계약, 분산 락 provider 선택표)의 SSOT 는 [AGENTS.md](AGENTS.md) 다.
|
||||
이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다
|
||||
"왜 이렇게 했나"가 궁금할 때 본다. 표가 CLAUDE.md 에 있으면 여기서는 중복하지 않고 그 근거만
|
||||
"왜 이렇게 했나"가 궁금할 때 본다. 표가 AGENTS.md 에 있으면 여기서는 중복하지 않고 그 근거만
|
||||
적는다.
|
||||
|
||||
## capability 모듈로 쓰기 — 제공하는 것, 추가할 한 줄, 필요한 env
|
||||
@@ -107,7 +107,7 @@ promotion gate, 생성하는 곳 없는 `JpaTransactionObservation` 등)은 `doc
|
||||
readOnly 를 바꿔 쓰면 같은 빈을 공유하는 동시 요청 사이에 race window 가 생긴다. 모드별로
|
||||
(`WRITE` / `READ_ONLY` / `REQUIRES_NEW`) 템플릿을 생성 시점에 하나씩 만들어 두면 그 race 가
|
||||
사라지고, 각 모드를 따로 감사(audit)할 수 있다. 세 템플릿 모두 isolation 을 `READ_COMMITTED`
|
||||
로 고정한다(모드표는 CLAUDE.md §TransactionPort implementation contract).
|
||||
로 고정한다(모드표는 AGENTS.md §TransactionPort implementation contract).
|
||||
|
||||
### 왜 `inRootWrite`가 별도 템플릿이나 `NEVER` propagation을 만들지 않나
|
||||
`inRootWrite`의 실행 속성은 `inWrite`와 같은 `WRITE + REQUIRED + READ_COMMITTED`라 기존
|
||||
@@ -179,7 +179,7 @@ Spring Boot 메인 클래스는 `dev.caskeleton.bootstrap` 에 있어서, `@Auto
|
||||
|
||||
## failure — 퍼시스턴스 실패 변환 SPI
|
||||
|
||||
매트릭스(SQLState → `DB_*` 코드, category, http, retryable)의 SSOT 는 CLAUDE.md §Persistence
|
||||
매트릭스(SQLState → `DB_*` 코드, category, http, retryable)의 SSOT 는 AGENTS.md §Persistence
|
||||
failure translation contract 다. 여기서는 SPI 구조와 fallback 근거만 적는다.
|
||||
|
||||
### SPI-pluggable 설계 (vendor 추출)
|
||||
@@ -502,7 +502,7 @@ stream migration이 중단되면 history/registry/object 상태를 먼저 확인
|
||||
|
||||
## lock — 분산 락
|
||||
|
||||
provider 선택표(flag → bean → registry)의 SSOT 는 CLAUDE.md(또는 app-bootstrap 와이어링)다.
|
||||
provider 선택표(flag → bean → registry)의 SSOT 는 AGENTS.md(또는 app-bootstrap 와이어링)다.
|
||||
여기서는 어댑터/설정 결정 근거만 적는다.
|
||||
|
||||
### `LockRegistryDistributedLock` 계약
|
||||
|
||||
@@ -0,0 +1,157 @@
|
||||
# adapter:outbound:persistence-mongo — 모듈 규칙
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-persistence-mongo`
|
||||
- Gradle 경로: `:adapter:outbound:persistence-mongo`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:persistence-mongo:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.mongo`. driven(outbound) 어댑터 — 골라 쓰는 MongoDB 문서 영속
|
||||
플랫폼이다. 설계 근거는 [README.md](README.md)에 있다. 설계 패키지가 가정한 모듈 배치를 이 leaf에 대응시킨 것은
|
||||
`docs/mongodb/repository-adaptation.md`에 있고, 그 대응이 바뀌면 고칠 파일이 그것이다.
|
||||
|
||||
## 책임
|
||||
|
||||
- 가짜 업무 도메인을 싣지 않고, 골라 쓰는 Mongo client, template, **플랫폼 정책** surface를 준다. 실제 fork가 자기
|
||||
문서, repository, mapper, application·domain 포트 구현을 더한다.
|
||||
- 멱등성·outbox·lock을 Mongo 위에 다시 구현하지 **않는다**(그것은 JPA에만 남는다).
|
||||
- 있으면 켜진다: `app.persistence-mongo.enabled=false`가 아니면 `MongoRootAutoConfiguration`과 그것이 import하는
|
||||
모든 것이 돈다(`matchIfMissing = true`. 출하하는 `config/mongo.yml`이 `APP_PERSISTENCE_MONGO_ENABLED`를 대응시키고
|
||||
기본은 `true`). 빌드에 없는 것이 보통의 꺼진 상태다. 연결 URI와 데이터베이스는 Spring의 표준 `spring.mongodb.*`
|
||||
설정에서 오고, 플랫폼 profile은 `app.persistence-mongo.platform.*`에서 온다.
|
||||
연결 출처는 실패하면 닫힌다: `spring.mongodb.uri` / `SPRING_MONGODB_URI`가 비어 있지 않거나, 고른 typed profile이
|
||||
`uri-secret`을 주고 배포가 `MongoCredentialResolver`를 줘야 한다. typed profile은 문서용만이 아니다:
|
||||
`MongoProfileClientSettingsAutoConfiguration`이 `MongoClientSettingsFactory`를 Boot의 실제
|
||||
`MongoClientSettings.Builder`에 가장 낮은 우선순위로 적용하므로, 그 TLS, Stable API, timeout, pool 정책이 일반
|
||||
기본값을 덮는다. typed profile이 없으면(URI만) `MongoUriOnlyClientDefaults`가 Boot가 connection string을 적용하기
|
||||
**전에** 유한한 socket·connect·server selection timeout과 pool 한계를 적용하므로, URI 매개변수가 여전히 이긴다.
|
||||
자기 설정 키는 없다.
|
||||
- 쓰는 쪽: 서비스 자신의 어댑터 leaf가 이 leaf를 `implementation`으로 받는다. 절차는
|
||||
`docs/mongodb/consumer-leaf-guide.md`다. 작동하는 예(문서, mapper, repository, 포트 구현)는 시험 소스 패키지
|
||||
`…mongo.example`이고, `mongoStableContractTest`가 돌린다.
|
||||
- `META-INF/spring.factories`로 등록한 `MongoDefaultsEnvironmentPostProcessor`가 `config/mongo.yml`을 가장 낮은
|
||||
우선순위로 읽고, 명시한 `enabled=false`이면 Boot 4의 Mongo 자동 구성(Boot 자신의 등록 파일에서 읽는다)을
|
||||
`spring.autoconfigure.exclude`에 붙인다.
|
||||
- surface는 두 가지다. 자동 구성 bean(README.md 「자동 구성」에 적힌 것)은 `enabled=true`로 켜진다. 나머지는 모두
|
||||
**라이브러리 API**다(README.md 「라이브러리 API」): 서비스 자신의 어댑터 leaf가 이 leaf를 `implementation`으로
|
||||
받아 타입을 만든다. 라이브러리 API는 bean으로 등록하지 않고 자기 속성이 없다.
|
||||
- Mongo health 연동은 leaf가 가진다. MongoRootAutoConfiguration이 내부 MongoPlatformHealthConfiguration을 import하고,
|
||||
그것이 MongoPlatformHealthIndicator를 안정된 bean 이름 mongoPlatformHealthContributor 아래 Boot의 HealthIndicator
|
||||
SPI에 맞춘다. 바깥 endpoint 노출은 여전히 애플리케이션 Actuator 노출 정책이 정한다.
|
||||
|
||||
## 허용
|
||||
|
||||
- 프로젝트 의존 둘. `Sha256`과 `HmacSha256` 도우미를 위한 `shared-contract`(테넌트 관찰 키, admin 명령 digest,
|
||||
credential fingerprint, keyset cursor tag. `MongoDigestOutputTest`가 출력을 고정한다). `SecretSourcePort`만을 위한
|
||||
`application-core`. registry 항목의 `allowed_dependencies`는 `["application-core", "shared-contract"]`이고 빌드가
|
||||
실제로 쓰는 것과 맞는다. `MongoProfileClientSettingsAutoConfiguration`의 bridge가 typed profile의 `uri-secret`을
|
||||
배포가 설정한 비밀 값 backend로 해석한다. `verifyCleanArchitectureDependencies`는 해석된 edge가 선언된 것의
|
||||
부분집합인지만 보므로 쓰지 않는 허가는 매번 통과한다. `MongoRegistryPermissionParityTest`가 반대 방향을 보고 두
|
||||
집합이 다르면 실패한다.
|
||||
- 서비스는 `app-bootstrap/build.gradle`에서 주석 처리한 한 줄
|
||||
`runtimeOnly project(':adapter:outbound:persistence-mongo')`로 이 leaf를 고른다. 기본 조립은 싣지 않는다. leaf는
|
||||
imperative만이다: reactive 쌍둥이(`reactive/**`, reactive 트랜잭션·세션), change-stream 소비자, change-stream →
|
||||
메시징 bridge는 2026-09-25에 지웠다(`docs/capability-status.md`). 그래서 leaf는 reactive starter도
|
||||
reactive-streams driver도 싣지 않는다(`MongoReactiveDriverAbsenceTest`).
|
||||
- 외부 의존: (sync) Mongo starter, spring-boot-autoconfigure, spring-boot-health, micrometer-core, slf4j-api,
|
||||
configuration processor. Boot Health가 Jackson 애너테이션을 싣지만 런타임 JSON 직렬화는 애플리케이션의 몫이라서
|
||||
Jackson 애너테이션은 compile 전용이다. 버전은 공용 Spring Boot BOM에서 온다. driver 버전을 직접 고정하지 않는다.
|
||||
- 시험 전용: ArchUnit, Testcontainers(`mongodb`, `toxiproxy`).
|
||||
|
||||
## 금지 (Forbidden)
|
||||
|
||||
- inbound 어댑터, 이웃 outbound 어댑터, `app-bootstrap`(ArchUnit `OUTBOUND_ADAPTERS_*` 규칙 묶음).
|
||||
- 운영 코드에 자리표시용 `Example*` 문서, repository, record, 어댑터 타입을 싣기.
|
||||
- 따로 승인된 계약 없이 Mongo 위에 멱등성·outbox·lock을 더하기.
|
||||
- 줄 안에 완전한 이름으로 쓴 타입 참조, 파일 하나에 공개 최상위 타입 둘 이상.
|
||||
|
||||
### 패키지 경계 규칙 (`MongoModuleBoundaryTest`)
|
||||
|
||||
설계의 모듈 의존 표를 그대로 옮긴 것이다. 하나라도 어기면 빌드가 실패한다:
|
||||
|
||||
- `…mongo.api..`는 Spring, MongoDB driver, BSON, Reactor를 import하지 않는다. 프레임워크 없는 핵심 계약이다.
|
||||
`api/package-info.java`가 이유를 적는다.
|
||||
- Stable 패키지는 `…mongo.advanced..`에 의존하지 않는다.
|
||||
- 운영 패키지는 `…mongo.testkit..`에 의존하지 않는다.
|
||||
- `query` ↛ `aggregation`, `schema` ↛ 실행 패키지, `observation` ↛ 실행 패키지, `migration` ↛ `migration.flamingock`.
|
||||
|
||||
### 일관성에 묶인 template
|
||||
|
||||
`MongoConsistencyBinder`는 일관성 profile마다 `MongoTemplate`을 하나 끌어낸다. Spring Data는 template의 지원 계약에
|
||||
setter만 내놓고 getter를 내놓지 않는다. 그래서 따라가야 하는 부분 — write-concern resolver, 쓰기 결과 검사,
|
||||
lifecycle 이벤트, entity callback과 auditing을 주는 `ApplicationContext` — 을 `MongoTemplateSupportContract`로 명시해
|
||||
넘긴다. 여기서 private 필드에 대한 리플렉션은 금지다. context 밖에서 프로그램으로 callback을 등록한 template은
|
||||
묶인 경로로 다시 만들 수 없다. 그 설정은 소리 없이 버리지 않고 지원하지 않는 것으로 둔다.
|
||||
|
||||
### 공개 surface
|
||||
|
||||
jar 하나 안의 모든 공개 최상위 타입이므로, `public`은 어느 패키지에 있든 모든 채택자에게 공개다.
|
||||
`verifyMongoApiSurface`(`check` 안)가 surface를 개수를 담은 `docs/architecture/mongo-api-surface.txt`와 비교한다.
|
||||
늘리려면 `updateMongoApiSurface -PapproveMongoApiSurfaceChange`가 필요하고, 그것은 리뷰 결정이다.
|
||||
|
||||
아키텍처 규칙 catalog(`…mongo.architecture`)는 운영이 아니라 **testkit** source set에 있다: ArchUnit 입력이고, 그것을
|
||||
싣으면 모든 쓰는 쪽의 runtime classpath에 규칙 글이 올라갔다. 같은 이유로 릴리스 gate도 testkit 전용이고, 구현은
|
||||
둘이 아니라 하나다: `…mongo.testkit.release`가 lane이 쓴 JUnit XML을 읽고, `scripts/verify-mongodb-platform.sh`와
|
||||
`src/adapter/outbound/persistence-mongo/release/release-contracts.json`이 그것을 돌린다. 운영 classpath에 있던 두 번째
|
||||
짝 — 손으로 만든 category 이름 집합과 그것을 검사한 gate — 은 자기 시험 말고는 호출자가 없었고 category 뒤에 정본도
|
||||
없었다. 옮기지 않고 없앴다.
|
||||
|
||||
아직 남았고, 리뷰 정리의 일부로 일부러 하지 않은 것: 구현 패키지를 `internal` 루트 아래로 옮기고 그 안의 가시성을
|
||||
낮추는 일. 약 200개 파일에 걸친 기계적 변경이라 자기 커밋에 둔다. 그 뒤에는 위 snapshot이 surface가 실제로
|
||||
줄었다는 증거가 된다.
|
||||
|
||||
### credential과 운영 profile
|
||||
|
||||
운영 `MongoProfileProperties`는 TLS, 인증, 엄격한 Stable API, standalone이 아닌 topology, 유한한 양의 timeout을
|
||||
선언해야 한다. `validate()`가 그것을 모두 강제한다. URI는 `secret://` 참조이고, 그것을 connection string으로 바꾸는
|
||||
것은 `MongoCredentialResolver`뿐이다 — 값을 호출자가 준 함수에 넘기고 돌려주지 않으니, credential은 필드나 bean
|
||||
속성이나 로그 줄이 아니라 호출 한 번의 지역 변수다.
|
||||
|
||||
`platform.profiles`가 비어 있지 않으면 채택은 일부러 실패하면 닫힌다. 조립 변경 하나에서 데이터 plane
|
||||
`MongoCredentialResolver`와 함께 `MongoTopologyProbe`, `MongoSecurityProfile`, admin `MongoCredentialReference`,
|
||||
`MongoSchemaVersionRange`를 준다. README.md에 필드 14개짜리 운영 profile 예가 다 있다. profile을 조금씩 주며 그
|
||||
요구를 기동 실패 하나씩으로 알아내는 것은 받아들인 채택 길이 아니다.
|
||||
|
||||
기본 resolver는 `SecretSourcePort` 위의 bridge다(`MongoCredentialResolver.fromSecretSource`. 그 포트에 bean이 있고
|
||||
다른 resolver가 없을 때 등록한다). 키는 Redis·HTTP client 모듈처럼 참조의 마지막 경로 조각이다. 싣지 않은 것:
|
||||
실제 인증서를 가진 container가 필요한 TLS lane(믿는 CA, 틀린 CA, hostname 불일치, 만료된 인증서). 교체 순서 — 새
|
||||
generation 준비, traffic 전환, 옛 lease 비우기, 닫기 — 는 `MongoClientGenerationConcurrencyTest`가 덮는다.
|
||||
|
||||
### 문체가 아닌 플랫폼 불변식
|
||||
|
||||
- 트랜잭션 본문 재시도와 커밋 재시도는 **따로 도는 반복문**이다: 본문 시도마다 새 세션, 모르는 커밋에는 커밋만
|
||||
재시도. 커밋이 모호해진 뒤에는 본문을 다시 돌리지 않는다(`MongoTransactionRetryCoordinator`, ADR-MONGO-003).
|
||||
- `MongoExecutionOutcome`의 모호한 값 둘을 성공이나 실패로 뭉개면 안 된다.
|
||||
- BSON 표현은 라이브러리 기본값이 아니라 `MongoTypeRepresentationManifest`에서 온다(ADR-MONGO-002).
|
||||
- index와 validator 변경은 manifest와 admin plane을 거친다. 모든 drop은 소유권이 막는다(ADR-MONGO-004).
|
||||
- 모든 구체 Advanced 타입은 `@MongoAdvancedEntryPoint(capability)`나 `@MongoAdvancedPolicy`를 단다. entry point는
|
||||
`MongoAdvancedCapabilityGuard`를 받고, 존재하기 전에 `require`를 부른다. `MongoAdvancedRules`가 두 절반을 강제한다.
|
||||
「실행되는 것은 막는다」가 「누가 기억해 낸 것은 막는다」가 되지 않게 하는 것이 분류 규칙이다.
|
||||
- flag에는 설정 속성이 없다. Advanced 타입은 라이브러리 API다: 채택자의 어댑터가 코드로
|
||||
`MongoAdvancedCapabilityFlags`와 guard를 만든다. Stable 자동 구성은 `..advanced..` 아래의 어떤 것도 참조하면 안
|
||||
된다.
|
||||
- 이 leaf가 바인딩하는 모든 설정 키는 동작을 바꿔야 한다. 아무것도 읽지 않는 키나, 효과가 기동 실패뿐인 키는
|
||||
문서로 남기지 않고 지운다(AGENTS.md capability 규칙 3). `docs/capability-status.md`가 무엇을 왜 지웠는지 적는다.
|
||||
- 인터페이스는 이 leaf 안에 구현이 있을 때만 싣는다. Search, vector, time series, GridFS는 계약만 있었고
|
||||
2026-09-25에 지웠다.
|
||||
- observation tag는 `MongoObservationConvention`의 허용 목록으로 제한한다.
|
||||
|
||||
## 테스트
|
||||
|
||||
`MongoCapabilityActivationTest`는 실제 `SpringApplication`을 띄워 있음 = 켜짐, 명시한 `enabled=false` = client·
|
||||
template·플랫폼 bean 없음(Boot의 Mongo 자동 구성 포함)을 증명한다. `MongoPersistenceConfigTest`는 타입 있는 켜기
|
||||
바인딩과, 네트워크 연결 없이 mock `MongoClient`와 실제 `MongoTemplate`으로 켜진 기반을 덮는다.
|
||||
|
||||
밀폐된 계약 시험은 `@Tag("mongodb-contract")`를 달고 `check`가 의존하는 `mongoStableContractTest`에서 돈다. container
|
||||
lane은 `mongodb-replicaset` / `mongodb-failover`를 달고 자기 태스크에서만 돈다. 기본 `test` 태스크는 그것을 뺀다.
|
||||
`check` 안에 Docker가 필요한 lane이 있으면 사람들이 `check`를 건너뛰게 되기 때문이다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:outbound:persistence-mongo:check --console=plain
|
||||
```
|
||||
|
||||
릴리스 gate는 저장소 루트에서 돈다: `scripts/verify-mongodb-platform.sh`(Stable)와
|
||||
`scripts/verify-mongodb-advanced.sh`(Advanced).
|
||||
@@ -1,157 +1 @@
|
||||
# adapter:outbound:persistence-mongo — 모듈 규칙
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-persistence-mongo`
|
||||
- Gradle 경로: `:adapter:outbound:persistence-mongo`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:persistence-mongo:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.mongo`. driven(outbound) 어댑터 — 골라 쓰는 MongoDB 문서 영속
|
||||
플랫폼이다. 설계 근거는 [README.md](README.md)에 있다. 설계 패키지가 가정한 모듈 배치를 이 leaf에 대응시킨 것은
|
||||
`docs/mongodb/repository-adaptation.md`에 있고, 그 대응이 바뀌면 고칠 파일이 그것이다.
|
||||
|
||||
## 책임
|
||||
|
||||
- 가짜 업무 도메인을 싣지 않고, 골라 쓰는 Mongo client, template, **플랫폼 정책** surface를 준다. 실제 fork가 자기
|
||||
문서, repository, mapper, application·domain 포트 구현을 더한다.
|
||||
- 멱등성·outbox·lock을 Mongo 위에 다시 구현하지 **않는다**(그것은 JPA에만 남는다).
|
||||
- 있으면 켜진다: `app.persistence-mongo.enabled=false`가 아니면 `MongoRootAutoConfiguration`과 그것이 import하는
|
||||
모든 것이 돈다(`matchIfMissing = true`. 출하하는 `config/mongo.yml`이 `APP_PERSISTENCE_MONGO_ENABLED`를 대응시키고
|
||||
기본은 `true`). 빌드에 없는 것이 보통의 꺼진 상태다. 연결 URI와 데이터베이스는 Spring의 표준 `spring.mongodb.*`
|
||||
설정에서 오고, 플랫폼 profile은 `app.persistence-mongo.platform.*`에서 온다.
|
||||
연결 출처는 실패하면 닫힌다: `spring.mongodb.uri` / `SPRING_MONGODB_URI`가 비어 있지 않거나, 고른 typed profile이
|
||||
`uri-secret`을 주고 배포가 `MongoCredentialResolver`를 줘야 한다. typed profile은 문서용만이 아니다:
|
||||
`MongoProfileClientSettingsAutoConfiguration`이 `MongoClientSettingsFactory`를 Boot의 실제
|
||||
`MongoClientSettings.Builder`에 가장 낮은 우선순위로 적용하므로, 그 TLS, Stable API, timeout, pool 정책이 일반
|
||||
기본값을 덮는다. typed profile이 없으면(URI만) `MongoUriOnlyClientDefaults`가 Boot가 connection string을 적용하기
|
||||
**전에** 유한한 socket·connect·server selection timeout과 pool 한계를 적용하므로, URI 매개변수가 여전히 이긴다.
|
||||
자기 설정 키는 없다.
|
||||
- 쓰는 쪽: 서비스 자신의 어댑터 leaf가 이 leaf를 `implementation`으로 받는다. 절차는
|
||||
`docs/mongodb/consumer-leaf-guide.md`다. 작동하는 예(문서, mapper, repository, 포트 구현)는 시험 소스 패키지
|
||||
`…mongo.example`이고, `mongoStableContractTest`가 돌린다.
|
||||
- `META-INF/spring.factories`로 등록한 `MongoDefaultsEnvironmentPostProcessor`가 `config/mongo.yml`을 가장 낮은
|
||||
우선순위로 읽고, 명시한 `enabled=false`이면 Boot 4의 Mongo 자동 구성(Boot 자신의 등록 파일에서 읽는다)을
|
||||
`spring.autoconfigure.exclude`에 붙인다.
|
||||
- surface는 두 가지다. 자동 구성 bean(README.md 「자동 구성」에 적힌 것)은 `enabled=true`로 켜진다. 나머지는 모두
|
||||
**라이브러리 API**다(README.md 「라이브러리 API」): 서비스 자신의 어댑터 leaf가 이 leaf를 `implementation`으로
|
||||
받아 타입을 만든다. 라이브러리 API는 bean으로 등록하지 않고 자기 속성이 없다.
|
||||
- Mongo health 연동은 leaf가 가진다. MongoRootAutoConfiguration이 내부 MongoPlatformHealthConfiguration을 import하고,
|
||||
그것이 MongoPlatformHealthIndicator를 안정된 bean 이름 mongoPlatformHealthContributor 아래 Boot의 HealthIndicator
|
||||
SPI에 맞춘다. 바깥 endpoint 노출은 여전히 애플리케이션 Actuator 노출 정책이 정한다.
|
||||
|
||||
## 허용
|
||||
|
||||
- 프로젝트 의존 둘. `Sha256`과 `HmacSha256` 도우미를 위한 `shared-contract`(테넌트 관찰 키, admin 명령 digest,
|
||||
credential fingerprint, keyset cursor tag. `MongoDigestOutputTest`가 출력을 고정한다). `SecretSourcePort`만을 위한
|
||||
`application-core`. registry 항목의 `allowed_dependencies`는 `["application-core", "shared-contract"]`이고 빌드가
|
||||
실제로 쓰는 것과 맞는다. `MongoProfileClientSettingsAutoConfiguration`의 bridge가 typed profile의 `uri-secret`을
|
||||
배포가 설정한 비밀 값 backend로 해석한다. `verifyCleanArchitectureDependencies`는 해석된 edge가 선언된 것의
|
||||
부분집합인지만 보므로 쓰지 않는 허가는 매번 통과한다. `MongoRegistryPermissionParityTest`가 반대 방향을 보고 두
|
||||
집합이 다르면 실패한다.
|
||||
- 서비스는 `app-bootstrap/build.gradle`에서 주석 처리한 한 줄
|
||||
`runtimeOnly project(':adapter:outbound:persistence-mongo')`로 이 leaf를 고른다. 기본 조립은 싣지 않는다. leaf는
|
||||
imperative만이다: reactive 쌍둥이(`reactive/**`, reactive 트랜잭션·세션), change-stream 소비자, change-stream →
|
||||
메시징 bridge는 2026-09-25에 지웠다(`docs/capability-status.md`). 그래서 leaf는 reactive starter도
|
||||
reactive-streams driver도 싣지 않는다(`MongoReactiveDriverAbsenceTest`).
|
||||
- 외부 의존: (sync) Mongo starter, spring-boot-autoconfigure, spring-boot-health, micrometer-core, slf4j-api,
|
||||
configuration processor. Boot Health가 Jackson 애너테이션을 싣지만 런타임 JSON 직렬화는 애플리케이션의 몫이라서
|
||||
Jackson 애너테이션은 compile 전용이다. 버전은 공용 Spring Boot BOM에서 온다. driver 버전을 직접 고정하지 않는다.
|
||||
- 시험 전용: ArchUnit, Testcontainers(`mongodb`, `toxiproxy`).
|
||||
|
||||
## 금지 (Forbidden)
|
||||
|
||||
- inbound 어댑터, 이웃 outbound 어댑터, `app-bootstrap`(ArchUnit `OUTBOUND_ADAPTERS_*` 규칙 묶음).
|
||||
- 운영 코드에 자리표시용 `Example*` 문서, repository, record, 어댑터 타입을 싣기.
|
||||
- 따로 승인된 계약 없이 Mongo 위에 멱등성·outbox·lock을 더하기.
|
||||
- 줄 안에 완전한 이름으로 쓴 타입 참조, 파일 하나에 공개 최상위 타입 둘 이상.
|
||||
|
||||
### 패키지 경계 규칙 (`MongoModuleBoundaryTest`)
|
||||
|
||||
설계의 모듈 의존 표를 그대로 옮긴 것이다. 하나라도 어기면 빌드가 실패한다:
|
||||
|
||||
- `…mongo.api..`는 Spring, MongoDB driver, BSON, Reactor를 import하지 않는다. 프레임워크 없는 핵심 계약이다.
|
||||
`api/package-info.java`가 이유를 적는다.
|
||||
- Stable 패키지는 `…mongo.advanced..`에 의존하지 않는다.
|
||||
- 운영 패키지는 `…mongo.testkit..`에 의존하지 않는다.
|
||||
- `query` ↛ `aggregation`, `schema` ↛ 실행 패키지, `observation` ↛ 실행 패키지, `migration` ↛ `migration.flamingock`.
|
||||
|
||||
### 일관성에 묶인 template
|
||||
|
||||
`MongoConsistencyBinder`는 일관성 profile마다 `MongoTemplate`을 하나 끌어낸다. Spring Data는 template의 지원 계약에
|
||||
setter만 내놓고 getter를 내놓지 않는다. 그래서 따라가야 하는 부분 — write-concern resolver, 쓰기 결과 검사,
|
||||
lifecycle 이벤트, entity callback과 auditing을 주는 `ApplicationContext` — 을 `MongoTemplateSupportContract`로 명시해
|
||||
넘긴다. 여기서 private 필드에 대한 리플렉션은 금지다. context 밖에서 프로그램으로 callback을 등록한 template은
|
||||
묶인 경로로 다시 만들 수 없다. 그 설정은 소리 없이 버리지 않고 지원하지 않는 것으로 둔다.
|
||||
|
||||
### 공개 surface
|
||||
|
||||
jar 하나 안의 모든 공개 최상위 타입이므로, `public`은 어느 패키지에 있든 모든 채택자에게 공개다.
|
||||
`verifyMongoApiSurface`(`check` 안)가 surface를 개수를 담은 `docs/architecture/mongo-api-surface.txt`와 비교한다.
|
||||
늘리려면 `updateMongoApiSurface -PapproveMongoApiSurfaceChange`가 필요하고, 그것은 리뷰 결정이다.
|
||||
|
||||
아키텍처 규칙 catalog(`…mongo.architecture`)는 운영이 아니라 **testkit** source set에 있다: ArchUnit 입력이고, 그것을
|
||||
싣으면 모든 쓰는 쪽의 runtime classpath에 규칙 글이 올라갔다. 같은 이유로 릴리스 gate도 testkit 전용이고, 구현은
|
||||
둘이 아니라 하나다: `…mongo.testkit.release`가 lane이 쓴 JUnit XML을 읽고, `scripts/verify-mongodb-platform.sh`와
|
||||
`src/adapter/outbound/persistence-mongo/release/release-contracts.json`이 그것을 돌린다. 운영 classpath에 있던 두 번째
|
||||
짝 — 손으로 만든 category 이름 집합과 그것을 검사한 gate — 은 자기 시험 말고는 호출자가 없었고 category 뒤에 정본도
|
||||
없었다. 옮기지 않고 없앴다.
|
||||
|
||||
아직 남았고, 리뷰 정리의 일부로 일부러 하지 않은 것: 구현 패키지를 `internal` 루트 아래로 옮기고 그 안의 가시성을
|
||||
낮추는 일. 약 200개 파일에 걸친 기계적 변경이라 자기 커밋에 둔다. 그 뒤에는 위 snapshot이 surface가 실제로
|
||||
줄었다는 증거가 된다.
|
||||
|
||||
### credential과 운영 profile
|
||||
|
||||
운영 `MongoProfileProperties`는 TLS, 인증, 엄격한 Stable API, standalone이 아닌 topology, 유한한 양의 timeout을
|
||||
선언해야 한다. `validate()`가 그것을 모두 강제한다. URI는 `secret://` 참조이고, 그것을 connection string으로 바꾸는
|
||||
것은 `MongoCredentialResolver`뿐이다 — 값을 호출자가 준 함수에 넘기고 돌려주지 않으니, credential은 필드나 bean
|
||||
속성이나 로그 줄이 아니라 호출 한 번의 지역 변수다.
|
||||
|
||||
`platform.profiles`가 비어 있지 않으면 채택은 일부러 실패하면 닫힌다. 조립 변경 하나에서 데이터 plane
|
||||
`MongoCredentialResolver`와 함께 `MongoTopologyProbe`, `MongoSecurityProfile`, admin `MongoCredentialReference`,
|
||||
`MongoSchemaVersionRange`를 준다. README.md에 필드 14개짜리 운영 profile 예가 다 있다. profile을 조금씩 주며 그
|
||||
요구를 기동 실패 하나씩으로 알아내는 것은 받아들인 채택 길이 아니다.
|
||||
|
||||
기본 resolver는 `SecretSourcePort` 위의 bridge다(`MongoCredentialResolver.fromSecretSource`. 그 포트에 bean이 있고
|
||||
다른 resolver가 없을 때 등록한다). 키는 Redis·HTTP client 모듈처럼 참조의 마지막 경로 조각이다. 싣지 않은 것:
|
||||
실제 인증서를 가진 container가 필요한 TLS lane(믿는 CA, 틀린 CA, hostname 불일치, 만료된 인증서). 교체 순서 — 새
|
||||
generation 준비, traffic 전환, 옛 lease 비우기, 닫기 — 는 `MongoClientGenerationConcurrencyTest`가 덮는다.
|
||||
|
||||
### 문체가 아닌 플랫폼 불변식
|
||||
|
||||
- 트랜잭션 본문 재시도와 커밋 재시도는 **따로 도는 반복문**이다: 본문 시도마다 새 세션, 모르는 커밋에는 커밋만
|
||||
재시도. 커밋이 모호해진 뒤에는 본문을 다시 돌리지 않는다(`MongoTransactionRetryCoordinator`, ADR-MONGO-003).
|
||||
- `MongoExecutionOutcome`의 모호한 값 둘을 성공이나 실패로 뭉개면 안 된다.
|
||||
- BSON 표현은 라이브러리 기본값이 아니라 `MongoTypeRepresentationManifest`에서 온다(ADR-MONGO-002).
|
||||
- index와 validator 변경은 manifest와 admin plane을 거친다. 모든 drop은 소유권이 막는다(ADR-MONGO-004).
|
||||
- 모든 구체 Advanced 타입은 `@MongoAdvancedEntryPoint(capability)`나 `@MongoAdvancedPolicy`를 단다. entry point는
|
||||
`MongoAdvancedCapabilityGuard`를 받고, 존재하기 전에 `require`를 부른다. `MongoAdvancedRules`가 두 절반을 강제한다.
|
||||
「실행되는 것은 막는다」가 「누가 기억해 낸 것은 막는다」가 되지 않게 하는 것이 분류 규칙이다.
|
||||
- flag에는 설정 속성이 없다. Advanced 타입은 라이브러리 API다: 채택자의 어댑터가 코드로
|
||||
`MongoAdvancedCapabilityFlags`와 guard를 만든다. Stable 자동 구성은 `..advanced..` 아래의 어떤 것도 참조하면 안
|
||||
된다.
|
||||
- 이 leaf가 바인딩하는 모든 설정 키는 동작을 바꿔야 한다. 아무것도 읽지 않는 키나, 효과가 기동 실패뿐인 키는
|
||||
문서로 남기지 않고 지운다(AGENTS.md capability 규칙 3). `docs/capability-status.md`가 무엇을 왜 지웠는지 적는다.
|
||||
- 인터페이스는 이 leaf 안에 구현이 있을 때만 싣는다. Search, vector, time series, GridFS는 계약만 있었고
|
||||
2026-09-25에 지웠다.
|
||||
- observation tag는 `MongoObservationConvention`의 허용 목록으로 제한한다.
|
||||
|
||||
## 테스트
|
||||
|
||||
`MongoCapabilityActivationTest`는 실제 `SpringApplication`을 띄워 있음 = 켜짐, 명시한 `enabled=false` = client·
|
||||
template·플랫폼 bean 없음(Boot의 Mongo 자동 구성 포함)을 증명한다. `MongoPersistenceConfigTest`는 타입 있는 켜기
|
||||
바인딩과, 네트워크 연결 없이 mock `MongoClient`와 실제 `MongoTemplate`으로 켜진 기반을 덮는다.
|
||||
|
||||
밀폐된 계약 시험은 `@Tag("mongodb-contract")`를 달고 `check`가 의존하는 `mongoStableContractTest`에서 돈다. container
|
||||
lane은 `mongodb-replicaset` / `mongodb-failover`를 달고 자기 태스크에서만 돈다. 기본 `test` 태스크는 그것을 뺀다.
|
||||
`check` 안에 Docker가 필요한 lane이 있으면 사람들이 `check`를 건너뛰게 되기 때문이다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:outbound:persistence-mongo:check --console=plain
|
||||
```
|
||||
|
||||
릴리스 gate는 저장소 루트에서 돈다: `scripts/verify-mongodb-platform.sh`(Stable)와
|
||||
`scripts/verify-mongodb-advanced.sh`(Advanced).
|
||||
@AGENTS.md
|
||||
|
||||
+1
-1
@@ -55,7 +55,7 @@ class MongoNamespaceContractTest {
|
||||
@DisplayName("operator-facing Mongo documentation names only the Boot 4 canonical namespace")
|
||||
void operatorDocumentationDoesNotRecommendTheDeprecatedNamespace() {
|
||||
Path module = repositoryRoot().resolve("src/adapter/outbound/persistence-mongo");
|
||||
List<Path> documents = List.of(module.resolve("README.md"), module.resolve("CLAUDE.md"));
|
||||
List<Path> documents = List.of(module.resolve("README.md"), module.resolve("AGENTS.md"));
|
||||
|
||||
assertThat(documents)
|
||||
.allSatisfy(path -> assertThat(Files.isRegularFile(path)).as(path.toString()).isTrue());
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
# adapter:outbound:persistence-notification — 알림 관계형 영속
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-persistence-notification`. Gradle 경로와 허용 edge는
|
||||
`src/config/architecture/modules.json`에 있다.
|
||||
- 이 모듈만 시험: `./gradlew :adapter:outbound:persistence-notification:test --console=plain`.
|
||||
- 패키지 루트: `dev.caskeleton.adapter.outbound.persistence.notification`. 패키지 규칙은
|
||||
`persistence-fileserver`와 같아서 두 capability leaf를 같은 방식으로 읽는다:
|
||||
- `platform.entity` — JPA 행만.
|
||||
- `platform.repository` — Spring Data 인터페이스와 그것이 돌리는 SQL 글(`RecipientClaimSql`).
|
||||
- `platform` — store 어댑터(`Jpa*`, `Jdbc*`, inbox의 `JpaNotificationInbox`와 그 outbox 도우미),
|
||||
`NotificationRecordMapper`, payload codec.
|
||||
- `configuration` — store를 bean으로 등록하는 자동 구성 창구. leaf 루트에는 scan 설정과 schema stream이 있다.
|
||||
엔티티 생성자·접근자·변경자는 store가 다른 패키지에서 쓰니 public이다. 엔티티는 leaf를 떠나지 않는다(포트는
|
||||
record를 싣는다). 가시성이 더는 그것을 말해 주지 않으므로 규칙이 말한다:
|
||||
`JpaArchitectureRules.entitiesAreUsedOnlyInsideTheirLeaf`를 `JpaProductionArchitectureTest`(app-bootstrap
|
||||
`architectureTest`)가 운영 그래프에 대고 이 leaf와 `persistence-fileserver`에 돌린다.
|
||||
|
||||
## 시험은 어디 있나
|
||||
|
||||
| 무엇 | 어디 | 돌리기 |
|
||||
|---|---|---|
|
||||
| 단위·배선 시험 | 이 leaf, `src/test` | `:adapter:outbound:persistence-notification:test` |
|
||||
| 이 store들의 실제 PostgreSQL 시험 | `persistence-jpa`, `src/postgresqlIntegrationTest/.../persistence/notification`(그 lane이 container와 Flyway 배선을 가진다) | `:adapter:outbound:persistence-jpa:postgresqlIntegrationTest --tests '<class>'` |
|
||||
| store가 통과해야 하는 포트 계약 | `application-notification` testFixtures, `*.testkit.*Contract`(preference, suppression, deduplication, request, reconciliation job, admin operation, template registry, recipient lease, recipient delivery, delivery attempt, attempt resolver, delivery projection, provider event ledger, contact point, 그리고 contact point·suppression store 위의 부수 효과) | 메모리 fake(`application-notification` 시험)와 `persistence-jpa`의 `PostgreSql*ContractTest`가 모두 계약을 상속한다. PostgreSQL 쪽은 `jpaPlatformContractTest`가 돌린다 |
|
||||
| migration 고정 | `persistence-jpa/src/test/resources/db/applied-migrations.sha256` | `:adapter:outbound:persistence-jpa:test`의 `AppliedMigrationImmutabilityTest` |
|
||||
|
||||
`application-notification` testFixtures에 계약이 있는 포트의 store는 따로 손으로 쓴 PostgreSQL 시험이 아니라
|
||||
그 계약의 PostgreSQL 하위 클래스로 시험한다. vendor에 관한 경우(CHECK 제약, bulk update의 `@Version`)는 하위
|
||||
클래스에 남긴다. 계약이 없는 포트(serving-state 읽기 모델, 동의, inbox)와 그 이유는
|
||||
`docs/testing/TESTING_STRATEGY.md` 9.2절에 있다.
|
||||
|
||||
## 규칙
|
||||
|
||||
- **모든 쓰기는 호출자의 트랜잭션에 합류한다.** store 쓰기는 `CallerTransaction.require("<what>")`로
|
||||
시작한다. 트랜잭션은 유스케이스가 가진다(소유자 결정 2026-09-25).
|
||||
- **migration**은 `src/main/resources/db/migration/jpa/notification-platform`에 있고 자기 Flyway stream
|
||||
(`NotificationSchemaStream`, history 테이블 `flyway_jpa_notification_history`)으로 돈다. 적용한 파일은 고치지
|
||||
않는다: 다음 `V<n>__`를 더하고, 그 SHA-256을 `applied-migrations.sha256`에 고정하고,
|
||||
`NotificationFixtures.migrations()`에 더한다. 행을 지우는 migration은 어떤 행이 남고 왜인지 SQL 주석에
|
||||
적는다. 이미 있는 테이블을 잠그는 migration은 `SET LOCAL lock_timeout = '5s';`로 시작한다
|
||||
(`docs/jpa/migration-guide.md` "Bound the lock wait". persistence-jpa의 `MigrationLockWaitTest`가 그것이 없는
|
||||
migration을 거절한다).
|
||||
- **insert냐 update냐는 데이터베이스가 정한다.** 찾은 뒤 insert하지 않는다: `ON CONFLICT (<unique key>) DO
|
||||
NOTHING`으로 insert하고, 아무것도 insert하지 않았으면 관리되는 엔티티로 있는 행을 update한다
|
||||
(`JpaSuppressionStore.upsert`, `JpaPolicyStores.Preferences.save`, `DeduplicationClaims.insertOrFind`). 충돌
|
||||
대상에는 migration에 unique 제약이 있어야 한다.
|
||||
- **`@Version` 테이블의 bulk·native `UPDATE`는 version을 올린다**(`version = version + 1`). 호출자가 그 행을 다시
|
||||
읽을 수 있으면 `@Modifying(clearAutomatically = true, flushAutomatically = true)`다. version 부분은
|
||||
`JpaVersionedBulkUpdateRule`(persistence-jpa testFixtures)이 `:app-bootstrap:architectureTest`에서 강제한다.
|
||||
- repository는 `CrudRepository`가 아니라 `Repository`를 상속하고, 테넌트 범위의 finder만 내놓는다.
|
||||
@@ -1,52 +1 @@
|
||||
# adapter:outbound:persistence-notification — 알림 관계형 영속
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-persistence-notification`. Gradle 경로와 허용 edge는
|
||||
`src/config/architecture/modules.json`에 있다.
|
||||
- 이 모듈만 시험: `./gradlew :adapter:outbound:persistence-notification:test --console=plain`.
|
||||
- 패키지 루트: `dev.caskeleton.adapter.outbound.persistence.notification`. 패키지 규칙은
|
||||
`persistence-fileserver`와 같아서 두 capability leaf를 같은 방식으로 읽는다:
|
||||
- `platform.entity` — JPA 행만.
|
||||
- `platform.repository` — Spring Data 인터페이스와 그것이 돌리는 SQL 글(`RecipientClaimSql`).
|
||||
- `platform` — store 어댑터(`Jpa*`, `Jdbc*`, inbox의 `JpaNotificationInbox`와 그 outbox 도우미),
|
||||
`NotificationRecordMapper`, payload codec.
|
||||
- `configuration` — store를 bean으로 등록하는 자동 구성 창구. leaf 루트에는 scan 설정과 schema stream이 있다.
|
||||
엔티티 생성자·접근자·변경자는 store가 다른 패키지에서 쓰니 public이다. 엔티티는 leaf를 떠나지 않는다(포트는
|
||||
record를 싣는다). 가시성이 더는 그것을 말해 주지 않으므로 규칙이 말한다:
|
||||
`JpaArchitectureRules.entitiesAreUsedOnlyInsideTheirLeaf`를 `JpaProductionArchitectureTest`(app-bootstrap
|
||||
`architectureTest`)가 운영 그래프에 대고 이 leaf와 `persistence-fileserver`에 돌린다.
|
||||
|
||||
## 시험은 어디 있나
|
||||
|
||||
| 무엇 | 어디 | 돌리기 |
|
||||
|---|---|---|
|
||||
| 단위·배선 시험 | 이 leaf, `src/test` | `:adapter:outbound:persistence-notification:test` |
|
||||
| 이 store들의 실제 PostgreSQL 시험 | `persistence-jpa`, `src/postgresqlIntegrationTest/.../persistence/notification`(그 lane이 container와 Flyway 배선을 가진다) | `:adapter:outbound:persistence-jpa:postgresqlIntegrationTest --tests '<class>'` |
|
||||
| store가 통과해야 하는 포트 계약 | `application-notification` testFixtures, `*.testkit.*Contract`(preference, suppression, deduplication, request, reconciliation job, admin operation, template registry, recipient lease, recipient delivery, delivery attempt, attempt resolver, delivery projection, provider event ledger, contact point, 그리고 contact point·suppression store 위의 부수 효과) | 메모리 fake(`application-notification` 시험)와 `persistence-jpa`의 `PostgreSql*ContractTest`가 모두 계약을 상속한다. PostgreSQL 쪽은 `jpaPlatformContractTest`가 돌린다 |
|
||||
| migration 고정 | `persistence-jpa/src/test/resources/db/applied-migrations.sha256` | `:adapter:outbound:persistence-jpa:test`의 `AppliedMigrationImmutabilityTest` |
|
||||
|
||||
`application-notification` testFixtures에 계약이 있는 포트의 store는 따로 손으로 쓴 PostgreSQL 시험이 아니라
|
||||
그 계약의 PostgreSQL 하위 클래스로 시험한다. vendor에 관한 경우(CHECK 제약, bulk update의 `@Version`)는 하위
|
||||
클래스에 남긴다. 계약이 없는 포트(serving-state 읽기 모델, 동의, inbox)와 그 이유는
|
||||
`docs/testing/TESTING_STRATEGY.md` 9.2절에 있다.
|
||||
|
||||
## 규칙
|
||||
|
||||
- **모든 쓰기는 호출자의 트랜잭션에 합류한다.** store 쓰기는 `CallerTransaction.require("<what>")`로
|
||||
시작한다. 트랜잭션은 유스케이스가 가진다(소유자 결정 2026-09-25).
|
||||
- **migration**은 `src/main/resources/db/migration/jpa/notification-platform`에 있고 자기 Flyway stream
|
||||
(`NotificationSchemaStream`, history 테이블 `flyway_jpa_notification_history`)으로 돈다. 적용한 파일은 고치지
|
||||
않는다: 다음 `V<n>__`를 더하고, 그 SHA-256을 `applied-migrations.sha256`에 고정하고,
|
||||
`NotificationFixtures.migrations()`에 더한다. 행을 지우는 migration은 어떤 행이 남고 왜인지 SQL 주석에
|
||||
적는다. 이미 있는 테이블을 잠그는 migration은 `SET LOCAL lock_timeout = '5s';`로 시작한다
|
||||
(`docs/jpa/migration-guide.md` "Bound the lock wait". persistence-jpa의 `MigrationLockWaitTest`가 그것이 없는
|
||||
migration을 거절한다).
|
||||
- **insert냐 update냐는 데이터베이스가 정한다.** 찾은 뒤 insert하지 않는다: `ON CONFLICT (<unique key>) DO
|
||||
NOTHING`으로 insert하고, 아무것도 insert하지 않았으면 관리되는 엔티티로 있는 행을 update한다
|
||||
(`JpaSuppressionStore.upsert`, `JpaPolicyStores.Preferences.save`, `DeduplicationClaims.insertOrFind`). 충돌
|
||||
대상에는 migration에 unique 제약이 있어야 한다.
|
||||
- **`@Version` 테이블의 bulk·native `UPDATE`는 version을 올린다**(`version = version + 1`). 호출자가 그 행을 다시
|
||||
읽을 수 있으면 `@Modifying(clearAutomatically = true, flushAutomatically = true)`다. version 부분은
|
||||
`JpaVersionedBulkUpdateRule`(persistence-jpa testFixtures)이 `:app-bootstrap:architectureTest`에서 강제한다.
|
||||
- repository는 `CrudRepository`가 아니라 `Repository`를 상속하고, 테넌트 범위의 finder만 내놓는다.
|
||||
@AGENTS.md
|
||||
|
||||
@@ -73,7 +73,7 @@ executor, operations).
|
||||
등록된 script(`RedisScriptRegistry`). 서비스가 SDK를 조립하는 곳에서 넘긴다.
|
||||
|
||||
패키지 규칙(driver 가두기, 문자열 명령 surface 없음, 트랜잭션과 raw gateway의 불변식)은
|
||||
`src/adapter/outbound/cache-redis/CLAUDE.md`의 「Redis 런타임과 골라 쓰는 typed SDK」에 있다.
|
||||
`src/adapter/outbound/cache-redis/AGENTS.md`의 「Redis 런타임과 골라 쓰는 typed SDK」에 있다.
|
||||
`RedisSdkModuleBoundaryTest`가 강제한다.
|
||||
|
||||
## env 키
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
# adapter:outbound:support — outbound 공용 지원
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-support`
|
||||
- Gradle 경로: `:adapter:outbound:support`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:support:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound`와 `dev.caskeleton.adapter.outbound.support`.
|
||||
|
||||
## 책임
|
||||
|
||||
- 다시 쓰는 outbound correlation, fail-open 의존성 로그, 자동 구성 이음매를 가진다.
|
||||
- 등록된 messaging·cache·notification·httpclient leaf가 쓰는 기술 지원을 준다.
|
||||
- 템플릿의 `IntegrationEventEncoderPort`(`messaging/JsonIntegrationEventEncoder`)를 가진다.
|
||||
`IntegrationEventEncoderAutoConfiguration`이 모든 contract contribution bean 위에 등록하고, 서비스 자신의
|
||||
인코더가 있으면 물러선다. 여기 있는 이유는 유스케이스가 outbox에 append하기 전에 인코딩하는데, 메시징 모듈을
|
||||
싣지 않는 조립도 있기 때문이다. 이것은 외부 시스템 프로토콜이 아니라 애플리케이션 자신의 envelope v1
|
||||
형식이다.
|
||||
- 디렉터리 descriptor 기준의 로컬 파일 시스템 기본 장치(`filesystem/SecureDirectoryWalk`,
|
||||
`filesystem/SecureFileAccess`)를 가진다: root 아래에서 디렉터리 descriptor를 하나씩 따라가며
|
||||
`NOFOLLOW_LINKS`로 열기, 만들기, 지우기, stat, 옮기기를 하고, symbolic 경로 요소와 바깥으로 나가기를 타입 있는
|
||||
`IOException`으로 거절한다. 저장 capability가 그것을 자기 실패 어휘로 바꾼다(파일 서버의
|
||||
`LocalStorageFailures`). 여기는 오류 코드를 모른다.
|
||||
- 유일한 엄격 설정 바인딩 `StrictSettingsBinder`를 가진다. inbound leaf가 쓸 수 있는 유일한 support
|
||||
클래스이기도 하다: `adapter:inbound:web`이 이것으로 `app.security`를 바인딩한다(registry edge와 클래스 이름을
|
||||
댄 ArchUnit 예외, 2026-11-01부터). 타입에 있는 설정의 빈 값(`APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT=`)은
|
||||
설정 안 함으로 바인딩한다. 타입에 없는 이름 아래의 빈 값은 계속 거절한다(2026-11-03에 정함).
|
||||
- 기능 전용 client와 라우팅 정책은 그것을 가진 leaf에 둔다.
|
||||
|
||||
## 경계
|
||||
|
||||
- 허용 프로젝트 의존은 registry가 가진다: application, domain, shared 계약.
|
||||
- inbound 전송, 영속, bootstrap, 샘플 의존이 없다.
|
||||
- 업무 규칙이나 특정 외부 시스템 프로토콜 구현이 없다.
|
||||
|
||||
## 테스트
|
||||
|
||||
지원 동작은 이 모듈만 보는 단위 시험으로 본다. 시험할 계약이 설정 배선 자체가 아니면 Spring application
|
||||
context를 띄우지 않는다.
|
||||
@@ -1,42 +1 @@
|
||||
# adapter:outbound:support — outbound 공용 지원
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-support`
|
||||
- Gradle 경로: `:adapter:outbound:support`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:support:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound`와 `dev.caskeleton.adapter.outbound.support`.
|
||||
|
||||
## 책임
|
||||
|
||||
- 다시 쓰는 outbound correlation, fail-open 의존성 로그, 자동 구성 이음매를 가진다.
|
||||
- 등록된 messaging·cache·notification·httpclient leaf가 쓰는 기술 지원을 준다.
|
||||
- 템플릿의 `IntegrationEventEncoderPort`(`messaging/JsonIntegrationEventEncoder`)를 가진다.
|
||||
`IntegrationEventEncoderAutoConfiguration`이 모든 contract contribution bean 위에 등록하고, 서비스 자신의
|
||||
인코더가 있으면 물러선다. 여기 있는 이유는 유스케이스가 outbox에 append하기 전에 인코딩하는데, 메시징 모듈을
|
||||
싣지 않는 조립도 있기 때문이다. 이것은 외부 시스템 프로토콜이 아니라 애플리케이션 자신의 envelope v1
|
||||
형식이다.
|
||||
- 디렉터리 descriptor 기준의 로컬 파일 시스템 기본 장치(`filesystem/SecureDirectoryWalk`,
|
||||
`filesystem/SecureFileAccess`)를 가진다: root 아래에서 디렉터리 descriptor를 하나씩 따라가며
|
||||
`NOFOLLOW_LINKS`로 열기, 만들기, 지우기, stat, 옮기기를 하고, symbolic 경로 요소와 바깥으로 나가기를 타입 있는
|
||||
`IOException`으로 거절한다. 저장 capability가 그것을 자기 실패 어휘로 바꾼다(파일 서버의
|
||||
`LocalStorageFailures`). 여기는 오류 코드를 모른다.
|
||||
- 유일한 엄격 설정 바인딩 `StrictSettingsBinder`를 가진다. inbound leaf가 쓸 수 있는 유일한 support
|
||||
클래스이기도 하다: `adapter:inbound:web`이 이것으로 `app.security`를 바인딩한다(registry edge와 클래스 이름을
|
||||
댄 ArchUnit 예외, 2026-11-01부터). 타입에 있는 설정의 빈 값(`APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT=`)은
|
||||
설정 안 함으로 바인딩한다. 타입에 없는 이름 아래의 빈 값은 계속 거절한다(2026-11-03에 정함).
|
||||
- 기능 전용 client와 라우팅 정책은 그것을 가진 leaf에 둔다.
|
||||
|
||||
## 경계
|
||||
|
||||
- 허용 프로젝트 의존은 registry가 가진다: application, domain, shared 계약.
|
||||
- inbound 전송, 영속, bootstrap, 샘플 의존이 없다.
|
||||
- 업무 규칙이나 특정 외부 시스템 프로토콜 구현이 없다.
|
||||
|
||||
## 테스트
|
||||
|
||||
지원 동작은 이 모듈만 보는 단위 시험으로 본다. 시험할 계약이 설정 배선 자체가 아니면 Spring application
|
||||
context를 띄우지 않는다.
|
||||
@AGENTS.md
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
허용/금지 의존 정책은 `src/build.gradle` 의
|
||||
`allowedProjectDependencies['adapter:outbound:support']` 항목이 SSOT 다(이 모듈은 아직 별도
|
||||
CLAUDE.md 를 두지 않았다). 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용
|
||||
AGENTS.md 를 두지 않았다). 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용
|
||||
기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다.
|
||||
|
||||
## 왜 별도 모듈인가
|
||||
|
||||
@@ -0,0 +1,121 @@
|
||||
# app-bootstrap — 애플리케이션 진입점과 조립 루트
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `app-bootstrap`
|
||||
- Gradle 경로: `:app-bootstrap`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :app-bootstrap:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.bootstrap`.
|
||||
|
||||
## 책임
|
||||
|
||||
- Spring Boot 진입점(`CaSkeletonApplication`).
|
||||
- 런타임 설정과 로깅 시작.
|
||||
- 모듈을 가로지르는 마지막 배선.
|
||||
- 모든 모듈을 들여다보는 아키텍처 시험.
|
||||
|
||||
## 허용
|
||||
|
||||
- 이 모듈의 Gradle 의존성이 분명히 선언하고 아키텍처 registry가 허용한 런타임 leaf. 해석된 Gradle
|
||||
runtime 그래프가 런타임의 정본이다. 구성원 목록을 metadata에 다시 적지 않는다.
|
||||
- Spring Boot 시작·런타임 의존성.
|
||||
- 시험에서 ArchUnit.
|
||||
|
||||
## 금지
|
||||
|
||||
- 구체적인 업무 정책.
|
||||
- bootstrap 아래에 직접 쓴 controller, 유스케이스, repository 어댑터, mapper.
|
||||
- 업무 로직을 구현하는 설정 클래스.
|
||||
- `application-core`나 `domain-core` 포트를 구현하기. 포트를 구현하는 클래스는 의존성을 어떻게
|
||||
설정했든 outbound 어댑터이고 `adapter/outbound/*` leaf에 둔다 —
|
||||
`CompositionRootBoundaryArchitectureTest`가 예외 없이 강제한다.
|
||||
- 기동 실패를 `throw new IllegalStateException(...)`으로 내기. `StartupFailures`
|
||||
(`adapter:outbound:support`, 패키지 `support.startup`: `envValidation` / `profileMismatch` /
|
||||
`requiredAdapterDisabled` / `migrationFailed`)를 써서 실패가 sysexits 종료 코드와 구조화된 로그
|
||||
필드를 싣게 한다 — `StartupFailureContractArchitectureTest`가 강제한다.
|
||||
- 「운영 환경인가?」를 이 모듈 안에서 답하기. 저장소 전체의 profile 어휘는
|
||||
`dev.caskeleton.shared.runtime.RuntimeEnvironment`가 가진다.
|
||||
- `src/test`에서 `org.testcontainers`에 의존하기. 실제 서비스를 쓰는 시험은 `src/integrationTest`에
|
||||
둔다. `docs/testing/TESTING_STRATEGY.md`를 본다.
|
||||
|
||||
## 패키지 배치
|
||||
|
||||
아래 규칙은 그것이 없어서 이 모듈의 리뷰 대상이 된 어긋남이 생겼기 때문에 있다
|
||||
(`docs/reviews/2026-09-07-app-bootstrap-module-code-review.md`). capability의 절반은 `autoconfigure/`
|
||||
아래, 절반은 패키지 루트에 있었다. `Settings` 클래스는 규칙 없이 `settings/` 패키지와 각 기능
|
||||
패키지에 나뉘어 있었다. 그리고 같은 분해 문제를 같은 leaf에서 두 가지로 풀었다 — Notification은 작은
|
||||
설정 아홉 개로, Redis는 376줄 클래스 하나로.
|
||||
|
||||
- **capability의 조립은 그 capability 자신의 모듈에 있다.** 그 모듈의 `AutoConfiguration.imports`가
|
||||
등록하고, 설정은 그 모듈의 `config/module-defaults/*.yml`에 둔다. JPA(기동 guard, Flyway 전략,
|
||||
lock decorator, readiness, `JpaActivationEnvironmentPostProcessor`의 완전히 끄기 처리)는
|
||||
`adapter:outbound:persistence-jpa`, Redis(readiness)는 `adapter:outbound:cache-redis`, 알림은
|
||||
`composition:notification-platform`이다. 모든 capability는 `build.gradle`에서 주석 처리한
|
||||
`runtimeOnly` 한 줄이다. 기본 조립은 web, 관측, core들, support, identifier다. 이 leaf는 capability
|
||||
목록을 두지 않는다: 스위치 registry도, capability 사이 의존 검증기도, 켜기 endpoint도 없다.
|
||||
component scan은 `dev.caskeleton.bootstrap`만 본다. web(`WebAdapterAutoConfiguration`,
|
||||
`WebSecurityAutoConfiguration`, `WebMethodSecurityAutoConfiguration`)과 support
|
||||
(`OutboundSupportConfig`)는 자기 `AutoConfiguration.imports`로 들어온다. `autoconfigure/<name>/`에
|
||||
남는 것은 모든 애플리케이션에 필요한 애플리케이션 조립인 `common`(시계)뿐이다. outbox relay,
|
||||
멱등성 executor, durable operation(유스케이스와 `/operations` endpoint. 2026-11-01 성숙도 리뷰 뒤로 bootstrap 밖)은
|
||||
`composition:outbox-relay`, `composition:idempotency`, `composition:durable-operation`이다. 각각
|
||||
`runtimeOnly` 한 줄로 고르고, 자기 포트가 생기기 전에는 아무것도 만들지 않는다. capability의
|
||||
role → permission 대응은 `config/security.yml`이 아니라 그 capability의 `config/module-defaults`
|
||||
파일에 담긴다. 모든 조립 루트에 필요한 런타임 배선 — tracing, metric 계약 filter, domain-context
|
||||
전파, 사용자 principal 가명화(`PrivacySettings`), actuator chain — 은 `composition:service-runtime`이다.
|
||||
- **`<Capability>Settings`는 `settings/`가 아니라 그 capability 옆에 둔다.** `settings/` 패키지는
|
||||
어느 capability에도 속하지 않는 설정 — `BootstrapSettings`, `RuntimeSafetySettings` — 만 담는다.
|
||||
이 설정은 `StrictSettingsBinder`로 엄격하게 바인딩하고 scan하지 않는다. 로깅에는 settings record가
|
||||
없다. `logback-spring.xml`이 `app.logging.*`을 직접 읽고 `LoggingConfigurationRule`이 Logback이 쓸
|
||||
수 없는 값을 거절한다.
|
||||
- **`runtime/`은 애플리케이션 자체에 대한 guard를 담는다** — 비밀 값, 숫자 한계, 오류 상세 노출,
|
||||
여러 인스턴스 조율, runtime profile 검사(`RuntimeEnvironmentProfileValidator`). capability 설정에
|
||||
대한 guard(JPA OSIV·DDL·pool·TLS·vendor guard, Mongo 연결 출처 규칙, GraphQL 배포 모드 규칙)는 그
|
||||
capability의 모듈과 함께 나간다. 그래야 capability가 있을 때만 정확히 존재한다.
|
||||
- **기동 실패 어휘는 `adapter:outbound:support`에 있다**(`support.startup`: phase, 오류 코드, 예외,
|
||||
`StartupFailures`, `StartupValidationContext`, `StartupOrder`, `ReadinessGroup`, `RuntimeWarnings`).
|
||||
그래서 capability 모듈은 이 leaf에 의존하지 않고 같은 방식으로 실패한다. `runtime/startup/`에는
|
||||
`StartupFailureExceptionReporter`만 남는다.
|
||||
- **환경만 보는 guard는 `StartupRule` bean이다**(`support.startup`). 위반을 돌려주고, 유일한
|
||||
`StartupRuleRunner`가 다른 singleton이 생기기 전에 그것을 올린다(`Environment`, bean factory, 정적
|
||||
`RequiredProductionSecrets`의 `ObjectProvider`만 받는 `static` `@Bean` 메서드로 선언한다. 모든
|
||||
profile에서 runner는 어떤 규칙을 돌리기 전에 규칙마다, 그리고 `RequiredProductionSecrets`마다 하나씩
|
||||
만든다. 그중 하나가 만드는 다른 bean이 있으면 그 이름을 대며 기동을 실패시킨다. runtime 클래스에
|
||||
`@Value`/`@Autowired`/`@Inject`/`@Resource` 멤버, `@PostConstruct`/`@PreDestroy` 콜백,
|
||||
`@ConfigurationProperties` 바인딩이 있는 것도 이름을 대며 실패시킨다 — 그런 것은 post-processor보다
|
||||
먼저 만들어져 값이 비어 있게 된다). 다른 bean이 필요한 guard는 bean으로 남는다. capability의 운영
|
||||
비밀 값은 그 capability의 것이다: 그 모듈이 `RequiredProductionSecrets` bean을 내놓고,
|
||||
`SecretSourceValidator`는 어떤 role이 있는지 모르는 채로 이름을 검사한다.
|
||||
|
||||
## 분해 기준
|
||||
|
||||
취향에 맡기지 않고 적어 둔다. 「충분히 길다고 느꼈다」가 같은 질문에 두 가지 답을 낳았기 때문이다.
|
||||
|
||||
- `@Configuration` 하나는 조립 관심사 하나를 담는다. 대략 **`@Bean` 메서드 여덟 개**를 넘거나, 서로
|
||||
관계없는 포트 묶음 둘을 조립하게 되면 — 둘 중 먼저 오는 때에 — 나눈다.
|
||||
- `@ConfigurationProperties` 클래스 하나는 capability namespace 하나를 가진다.
|
||||
- 설정이 둘 이상 필요한 capability는 루트 클래스를 둔다. 루트가 `enabled` 조건,
|
||||
`@EnableConfigurationProperties`, 관심사별 클래스의 `@Import`를 가진다. 아무것도 scan하지 않는다:
|
||||
조건이 걸린 루트에서 `@Import`해야 `enabled=false`가 권고가 아니라 실제로 끄는 스위치가 된다.
|
||||
`cache-redis`의 `capability/RedisCapabilityConfig`가 참조 예다. 다시 쓸 Spring 조립을 가진 optional
|
||||
어댑터 capability는 자기 루트를 내놓는다. 알림은 `adapter:outbound:notification`의
|
||||
`NotificationPlatformAutoConfiguration`과 `composition:notification-platform`의
|
||||
`NotificationApplicationCompositionAutoConfiguration`을 쓴다. JPA는
|
||||
`adapter:outbound:persistence-jpa`의 package-private `PersistenceJpaAutoConfiguration`,
|
||||
`PersistenceJpaRuntimeConfig`, `startup.JpaStartupAutoConfiguration`을 쓰고, 이 모듈은 기본 조립에
|
||||
없다(`build.gradle`의 `// runtimeOnly project(':adapter:outbound:persistence-jpa')`).
|
||||
Mongo도 같은 규칙을 따른다: persistence-mongo leaf가 MongoRootAutoConfiguration과 그 내부 health
|
||||
bridge를 가지고, bootstrap은 Mongo 전용 운영 health 설정을 가지지 않는다.
|
||||
- 나눈 capability의 공용 도우미는 `*Util` 바구니가 아니라 하는 일을 이름으로 단 자기 타입을 가진다 —
|
||||
`cache-redis`의 `capability/RedisKeys`가 참조 예다.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :app-bootstrap:test
|
||||
./gradlew verifyCleanArchitectureDependencies
|
||||
```
|
||||
+1
-121
@@ -1,121 +1 @@
|
||||
# app-bootstrap — 애플리케이션 진입점과 조립 루트
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `app-bootstrap`
|
||||
- Gradle 경로: `:app-bootstrap`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :app-bootstrap:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.bootstrap`.
|
||||
|
||||
## 책임
|
||||
|
||||
- Spring Boot 진입점(`CaSkeletonApplication`).
|
||||
- 런타임 설정과 로깅 시작.
|
||||
- 모듈을 가로지르는 마지막 배선.
|
||||
- 모든 모듈을 들여다보는 아키텍처 시험.
|
||||
|
||||
## 허용
|
||||
|
||||
- 이 모듈의 Gradle 의존성이 분명히 선언하고 아키텍처 registry가 허용한 런타임 leaf. 해석된 Gradle
|
||||
runtime 그래프가 런타임의 정본이다. 구성원 목록을 metadata에 다시 적지 않는다.
|
||||
- Spring Boot 시작·런타임 의존성.
|
||||
- 시험에서 ArchUnit.
|
||||
|
||||
## 금지
|
||||
|
||||
- 구체적인 업무 정책.
|
||||
- bootstrap 아래에 직접 쓴 controller, 유스케이스, repository 어댑터, mapper.
|
||||
- 업무 로직을 구현하는 설정 클래스.
|
||||
- `application-core`나 `domain-core` 포트를 구현하기. 포트를 구현하는 클래스는 의존성을 어떻게
|
||||
설정했든 outbound 어댑터이고 `adapter/outbound/*` leaf에 둔다 —
|
||||
`CompositionRootBoundaryArchitectureTest`가 예외 없이 강제한다.
|
||||
- 기동 실패를 `throw new IllegalStateException(...)`으로 내기. `StartupFailures`
|
||||
(`adapter:outbound:support`, 패키지 `support.startup`: `envValidation` / `profileMismatch` /
|
||||
`requiredAdapterDisabled` / `migrationFailed`)를 써서 실패가 sysexits 종료 코드와 구조화된 로그
|
||||
필드를 싣게 한다 — `StartupFailureContractArchitectureTest`가 강제한다.
|
||||
- 「운영 환경인가?」를 이 모듈 안에서 답하기. 저장소 전체의 profile 어휘는
|
||||
`dev.caskeleton.shared.runtime.RuntimeEnvironment`가 가진다.
|
||||
- `src/test`에서 `org.testcontainers`에 의존하기. 실제 서비스를 쓰는 시험은 `src/integrationTest`에
|
||||
둔다. `docs/testing/TESTING_STRATEGY.md`를 본다.
|
||||
|
||||
## 패키지 배치
|
||||
|
||||
아래 규칙은 그것이 없어서 이 모듈의 리뷰 대상이 된 어긋남이 생겼기 때문에 있다
|
||||
(`docs/reviews/2026-09-07-app-bootstrap-module-code-review.md`). capability의 절반은 `autoconfigure/`
|
||||
아래, 절반은 패키지 루트에 있었다. `Settings` 클래스는 규칙 없이 `settings/` 패키지와 각 기능
|
||||
패키지에 나뉘어 있었다. 그리고 같은 분해 문제를 같은 leaf에서 두 가지로 풀었다 — Notification은 작은
|
||||
설정 아홉 개로, Redis는 376줄 클래스 하나로.
|
||||
|
||||
- **capability의 조립은 그 capability 자신의 모듈에 있다.** 그 모듈의 `AutoConfiguration.imports`가
|
||||
등록하고, 설정은 그 모듈의 `config/module-defaults/*.yml`에 둔다. JPA(기동 guard, Flyway 전략,
|
||||
lock decorator, readiness, `JpaActivationEnvironmentPostProcessor`의 완전히 끄기 처리)는
|
||||
`adapter:outbound:persistence-jpa`, Redis(readiness)는 `adapter:outbound:cache-redis`, 알림은
|
||||
`composition:notification-platform`이다. 모든 capability는 `build.gradle`에서 주석 처리한
|
||||
`runtimeOnly` 한 줄이다. 기본 조립은 web, 관측, core들, support, identifier다. 이 leaf는 capability
|
||||
목록을 두지 않는다: 스위치 registry도, capability 사이 의존 검증기도, 켜기 endpoint도 없다.
|
||||
component scan은 `dev.caskeleton.bootstrap`만 본다. web(`WebAdapterAutoConfiguration`,
|
||||
`WebSecurityAutoConfiguration`, `WebMethodSecurityAutoConfiguration`)과 support
|
||||
(`OutboundSupportConfig`)는 자기 `AutoConfiguration.imports`로 들어온다. `autoconfigure/<name>/`에
|
||||
남는 것은 모든 애플리케이션에 필요한 애플리케이션 조립인 `common`(시계)뿐이다. outbox relay,
|
||||
멱등성 executor, durable operation(유스케이스와 `/operations` endpoint. 2026-11-01 성숙도 리뷰 뒤로 bootstrap 밖)은
|
||||
`composition:outbox-relay`, `composition:idempotency`, `composition:durable-operation`이다. 각각
|
||||
`runtimeOnly` 한 줄로 고르고, 자기 포트가 생기기 전에는 아무것도 만들지 않는다. capability의
|
||||
role → permission 대응은 `config/security.yml`이 아니라 그 capability의 `config/module-defaults`
|
||||
파일에 담긴다. 모든 조립 루트에 필요한 런타임 배선 — tracing, metric 계약 filter, domain-context
|
||||
전파, 사용자 principal 가명화(`PrivacySettings`), actuator chain — 은 `composition:service-runtime`이다.
|
||||
- **`<Capability>Settings`는 `settings/`가 아니라 그 capability 옆에 둔다.** `settings/` 패키지는
|
||||
어느 capability에도 속하지 않는 설정 — `BootstrapSettings`, `RuntimeSafetySettings` — 만 담는다.
|
||||
이 설정은 `StrictSettingsBinder`로 엄격하게 바인딩하고 scan하지 않는다. 로깅에는 settings record가
|
||||
없다. `logback-spring.xml`이 `app.logging.*`을 직접 읽고 `LoggingConfigurationRule`이 Logback이 쓸
|
||||
수 없는 값을 거절한다.
|
||||
- **`runtime/`은 애플리케이션 자체에 대한 guard를 담는다** — 비밀 값, 숫자 한계, 오류 상세 노출,
|
||||
여러 인스턴스 조율, runtime profile 검사(`RuntimeEnvironmentProfileValidator`). capability 설정에
|
||||
대한 guard(JPA OSIV·DDL·pool·TLS·vendor guard, Mongo 연결 출처 규칙, GraphQL 배포 모드 규칙)는 그
|
||||
capability의 모듈과 함께 나간다. 그래야 capability가 있을 때만 정확히 존재한다.
|
||||
- **기동 실패 어휘는 `adapter:outbound:support`에 있다**(`support.startup`: phase, 오류 코드, 예외,
|
||||
`StartupFailures`, `StartupValidationContext`, `StartupOrder`, `ReadinessGroup`, `RuntimeWarnings`).
|
||||
그래서 capability 모듈은 이 leaf에 의존하지 않고 같은 방식으로 실패한다. `runtime/startup/`에는
|
||||
`StartupFailureExceptionReporter`만 남는다.
|
||||
- **환경만 보는 guard는 `StartupRule` bean이다**(`support.startup`). 위반을 돌려주고, 유일한
|
||||
`StartupRuleRunner`가 다른 singleton이 생기기 전에 그것을 올린다(`Environment`, bean factory, 정적
|
||||
`RequiredProductionSecrets`의 `ObjectProvider`만 받는 `static` `@Bean` 메서드로 선언한다. 모든
|
||||
profile에서 runner는 어떤 규칙을 돌리기 전에 규칙마다, 그리고 `RequiredProductionSecrets`마다 하나씩
|
||||
만든다. 그중 하나가 만드는 다른 bean이 있으면 그 이름을 대며 기동을 실패시킨다. runtime 클래스에
|
||||
`@Value`/`@Autowired`/`@Inject`/`@Resource` 멤버, `@PostConstruct`/`@PreDestroy` 콜백,
|
||||
`@ConfigurationProperties` 바인딩이 있는 것도 이름을 대며 실패시킨다 — 그런 것은 post-processor보다
|
||||
먼저 만들어져 값이 비어 있게 된다). 다른 bean이 필요한 guard는 bean으로 남는다. capability의 운영
|
||||
비밀 값은 그 capability의 것이다: 그 모듈이 `RequiredProductionSecrets` bean을 내놓고,
|
||||
`SecretSourceValidator`는 어떤 role이 있는지 모르는 채로 이름을 검사한다.
|
||||
|
||||
## 분해 기준
|
||||
|
||||
취향에 맡기지 않고 적어 둔다. 「충분히 길다고 느꼈다」가 같은 질문에 두 가지 답을 낳았기 때문이다.
|
||||
|
||||
- `@Configuration` 하나는 조립 관심사 하나를 담는다. 대략 **`@Bean` 메서드 여덟 개**를 넘거나, 서로
|
||||
관계없는 포트 묶음 둘을 조립하게 되면 — 둘 중 먼저 오는 때에 — 나눈다.
|
||||
- `@ConfigurationProperties` 클래스 하나는 capability namespace 하나를 가진다.
|
||||
- 설정이 둘 이상 필요한 capability는 루트 클래스를 둔다. 루트가 `enabled` 조건,
|
||||
`@EnableConfigurationProperties`, 관심사별 클래스의 `@Import`를 가진다. 아무것도 scan하지 않는다:
|
||||
조건이 걸린 루트에서 `@Import`해야 `enabled=false`가 권고가 아니라 실제로 끄는 스위치가 된다.
|
||||
`cache-redis`의 `capability/RedisCapabilityConfig`가 참조 예다. 다시 쓸 Spring 조립을 가진 optional
|
||||
어댑터 capability는 자기 루트를 내놓는다. 알림은 `adapter:outbound:notification`의
|
||||
`NotificationPlatformAutoConfiguration`과 `composition:notification-platform`의
|
||||
`NotificationApplicationCompositionAutoConfiguration`을 쓴다. JPA는
|
||||
`adapter:outbound:persistence-jpa`의 package-private `PersistenceJpaAutoConfiguration`,
|
||||
`PersistenceJpaRuntimeConfig`, `startup.JpaStartupAutoConfiguration`을 쓰고, 이 모듈은 기본 조립에
|
||||
없다(`build.gradle`의 `// runtimeOnly project(':adapter:outbound:persistence-jpa')`).
|
||||
Mongo도 같은 규칙을 따른다: persistence-mongo leaf가 MongoRootAutoConfiguration과 그 내부 health
|
||||
bridge를 가지고, bootstrap은 Mongo 전용 운영 health 설정을 가지지 않는다.
|
||||
- 나눈 capability의 공용 도우미는 `*Util` 바구니가 아니라 하는 일을 이름으로 단 자기 타입을 가진다 —
|
||||
`cache-redis`의 `capability/RedisKeys`가 참조 예다.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :app-bootstrap:test
|
||||
./gradlew verifyCleanArchitectureDependencies
|
||||
```
|
||||
@AGENTS.md
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
이 모듈은 비즈니스 로직을 담지 않는다. Spring Boot 기동, 런타임 설정 바인딩, 기본 runtime
|
||||
모듈 간 최종 와이어링, 그리고 composition classpath를 대상으로 한 중앙 아키텍처 테스트만 둔다.
|
||||
모든 leaf의 프로젝트 edge는 JSON registry를 읽는 Gradle 방향 게이트가 별도로 검사한다. 허용/금지 의존, 책임 범위, 테스트 명령 같은 **모듈 규칙**의
|
||||
SSOT 는 [CLAUDE.md](CLAUDE.md) 다.
|
||||
SSOT 는 [AGENTS.md](AGENTS.md) 다.
|
||||
|
||||
기본 composition의 SSOT는 `build.gradle`의 실제 project dependency graph다. registry는 runtime
|
||||
membership 목록을 두지 않는다. `allowed_dependencies` 밖의 project는 방향 게이트가 막는다.
|
||||
@@ -417,7 +417,7 @@ relay 조립(`OutboxRelayAutoConfiguration`, 스케줄러·metrics·leader token
|
||||
## build.gradle — 의존성 구성 근거
|
||||
|
||||
app-bootstrap 은 합성 루트라 "왜 이 의존성이, 왜 이 scope 로" 결정이 많다. 빌드 파일에는 한 줄
|
||||
요약만 두고, 비자명한 근거는 여기에 모은다. 바탕 원칙은 **api vs implementation 정책**(CLAUDE.md):
|
||||
요약만 두고, 비자명한 근거는 여기에 모은다. 바탕 원칙은 **api vs implementation 정책**(AGENTS.md):
|
||||
모듈 간 의존은 기본 `implementation`이라 transitive 로 새지 않는다 — 그래서 테스트에서 그 타입이
|
||||
필요하면 여기서 **명시적으로** 다시 선언한다.
|
||||
|
||||
|
||||
+1
-1
@@ -14,7 +14,7 @@ import org.junit.jupiter.api.Test;
|
||||
/**
|
||||
* Freezes what is left of the Fileserver's exemption from the inbound use-case contract.
|
||||
*
|
||||
* <p>{@code application-core/CLAUDE.md} requires every inbound port implementation to extend {@code
|
||||
* <p>{@code application-core/AGENTS.md} requires every inbound port implementation to extend {@code
|
||||
* CommandUseCase} or {@code QueryUseCase} and to declare {@code @UseCaseCapability}. The ArchUnit
|
||||
* rules that enforce it only match types that implement {@link UseCase}; a service that never does
|
||||
* is invisible to them.
|
||||
|
||||
+1
-1
@@ -121,7 +121,7 @@ class ForbiddenApiArchitectureTest {
|
||||
+ root
|
||||
+ " lives in one of the listed operational contract packages, and the root holds"
|
||||
+ " only its package-info; a business or domain concept belongs to the module that"
|
||||
+ " owns it (shared-contract CLAUDE.md)")
|
||||
+ " owns it (shared-contract AGENTS.md)")
|
||||
.allowEmptyShould(true);
|
||||
}
|
||||
|
||||
|
||||
+2
-2
@@ -10,7 +10,7 @@ import org.springframework.boot.context.properties.ConfigurationProperties;
|
||||
|
||||
/**
|
||||
* Naming convention enforcement — the machine-checkable subset of the naming table in {@code
|
||||
* src/application-core/CLAUDE.md} ("Naming convention"), which is the rule book.
|
||||
* src/application-core/AGENTS.md} ("Naming convention"), which is the rule book.
|
||||
*
|
||||
* <p>This test enforces only the rules that ArchUnit can decide reliably (N6 configuration binding,
|
||||
* I5 throwables, and the two package-ownership rules beside that table). The rest of that table —
|
||||
@@ -55,7 +55,7 @@ class NamingConventionTest {
|
||||
|
||||
// Package ownership — a business feature package does not take a template package's name. The
|
||||
// template's own packages are listed in TemplatePackageOwnership (machine copy of the "Package
|
||||
// ownership" table in src/application-core/CLAUDE.md); everything else under the two roots is a
|
||||
// ownership" table in src/application-core/AGENTS.md); everything else under the two roots is a
|
||||
// feature, so a derived service adds features without editing the list. A feature always has a
|
||||
// domain package (docs/manual/03-placement.md ①), which is where a feature named after an
|
||||
// application template package — `operation`, `lock`, `cache` — shows up.
|
||||
|
||||
+1
-1
@@ -110,7 +110,7 @@ class TemplatePackageOwnershipRuleTest {
|
||||
.as(
|
||||
"a name in TemplatePackageOwnership.APPLICATION_PACKAGES that no longer exists was"
|
||||
+ " renamed or removed without the list (and the table in"
|
||||
+ " src/application-core/CLAUDE.md) following it")
|
||||
+ " src/application-core/AGENTS.md) following it")
|
||||
.containsAll(TemplatePackageOwnership.APPLICATION_PACKAGES.keySet());
|
||||
assertThat(domain)
|
||||
.as("TemplatePackageOwnership.DOMAIN_PACKAGES names a package that no longer exists")
|
||||
|
||||
+2
-2
@@ -15,7 +15,7 @@ import java.util.TreeSet;
|
||||
* owns each, and which packages are a service's business features.
|
||||
*
|
||||
* <p>This is the machine copy of the "Package ownership" tables in {@code
|
||||
* src/application-core/CLAUDE.md}, which are the rule book. A template change that adds, renames,
|
||||
* src/application-core/AGENTS.md}, which are the rule book. A template change that adds, renames,
|
||||
* moves or removes one of these packages changes the table and this class together. Two tests hold
|
||||
* them to it: {@code TemplatePackageOwnershipDocumentTest} (document-contract lane, main stage)
|
||||
* fails when the table and this class differ in a name or an owning leaf, or when a listed package
|
||||
@@ -107,7 +107,7 @@ record TemplatePackageOwnership(String applicationRoot, String domainRoot) {
|
||||
+ name.get()
|
||||
+ "', a name the template already uses. A feature beside a template package"
|
||||
+ " of the same name merges into the same tree on every upstream update."
|
||||
+ " Rename the feature (template packages: src/application-core/CLAUDE.md"
|
||||
+ " Rename the feature (template packages: src/application-core/AGENTS.md"
|
||||
+ " \"Package ownership\")."));
|
||||
}
|
||||
}
|
||||
|
||||
+2
-2
@@ -19,7 +19,7 @@ import org.junit.jupiter.api.Test;
|
||||
|
||||
/**
|
||||
* The template package list exists twice — the "Package ownership" tables in {@code
|
||||
* src/application-core/CLAUDE.md}, which people and agents read, and {@link
|
||||
* src/application-core/AGENTS.md}, which people and agents read, and {@link
|
||||
* TemplatePackageOwnership}, which the architecture rules read — and nothing held the two together
|
||||
* (original review 2026-11-01 §16.3). Changing either one alone fails here: a name or an owning
|
||||
* leaf that differs, or a listed package that is not in the leaf the table says owns it.
|
||||
@@ -29,7 +29,7 @@ import org.junit.jupiter.api.Test;
|
||||
@Tag("document-contract")
|
||||
class TemplatePackageOwnershipDocumentTest {
|
||||
|
||||
private static final String RULE_BOOK = "src/application-core/CLAUDE.md";
|
||||
private static final String RULE_BOOK = "src/application-core/AGENTS.md";
|
||||
private static final String REGISTRY = "src/config/architecture/modules.json";
|
||||
private static final String APPLICATION_TABLE = "| 패키지 (`dev.caskeleton.application.*`) |";
|
||||
private static final String DOMAIN_TABLE = "| 패키지 (`dev.caskeleton.domain.*`) |";
|
||||
|
||||
+1
-1
@@ -34,7 +34,7 @@ import org.junit.jupiter.api.Test;
|
||||
*
|
||||
* <p>So the rule is one-directional and mechanical: a vendor library named in a public or protected
|
||||
* signature is declared {@code api}; one used only behind private members stays {@code
|
||||
* implementation}. {@code src/platforms/messaging/CLAUDE.md} states it as policy — this holds it to
|
||||
* implementation}. {@code src/platforms/messaging/AGENTS.md} states it as policy — this holds it to
|
||||
* the source so the two cannot drift.
|
||||
*
|
||||
* <p>The libraries checked are the ones an adopter would otherwise have to reverse-engineer into
|
||||
|
||||
+1
-1
@@ -3,7 +3,7 @@ package dev.caskeleton.onboarding.domain.feature;
|
||||
/**
|
||||
* Aggregate-level persistence for {@link FeatureAggregate}. The domain owns it because it stores
|
||||
* and returns whole aggregates — the {@code *Repository} side of the naming rule in {@code
|
||||
* application-core/CLAUDE.md}; a technical store the application owns is a {@code *StorePort}.
|
||||
* application-core/AGENTS.md}; a technical store the application owns is a {@code *StorePort}.
|
||||
*/
|
||||
public interface FeatureAggregateRepository {
|
||||
|
||||
|
||||
@@ -0,0 +1,336 @@
|
||||
# application-core — 애플리케이션 유스케이스
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `application-core`
|
||||
- Gradle 경로: `:application-core`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :application-core:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준은 공용 버전 카탈로그(`src/gradle/libs.versions.toml`)가 고정한 Spring Boot 4.x다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.application`.
|
||||
|
||||
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT).
|
||||
|
||||
## 책임 (Responsibility)
|
||||
|
||||
- 유스케이스 inbound 포트(`CommandUseCase`, `QueryUseCase`)와 그 command·query 계약.
|
||||
- 유스케이스가 의존하는 outbound 포트(`*Port` 인터페이스).
|
||||
- 애플리케이션 예외와 정책 타입.
|
||||
- 포트를 거쳐 도메인 모델을 조율한다.
|
||||
- `TransactionPort` 추상화로 애플리케이션 트랜잭션 경계를 가진다.
|
||||
- `CorrelationIdPort` 같은 포트로 프레임워크 없는 호출 문맥을 내놓는다. MDC 같은 실제 저장소는
|
||||
어댑터가 가진다.
|
||||
- 프레임워크 없는 integration event 초안(semantic draft), 검증된 이벤트의 값 계약, 정확한 타입의
|
||||
payload를 내놓는 SPI를 가진다. 메시징 semantic contract R1 경계까지만이다.
|
||||
|
||||
## 허용
|
||||
|
||||
- `:domain-core`
|
||||
- `:shared-contract`
|
||||
- Java 표준 라이브러리 타입.
|
||||
|
||||
## 금지 (Forbidden)
|
||||
|
||||
- `adapter-*` 구현 클래스.
|
||||
- `app-bootstrap`.
|
||||
- controller의 요청·응답 DTO.
|
||||
- JPA 엔티티와 Spring Data repository.
|
||||
- HTTP 상태, 전송 타입(`org.springframework.web..`).
|
||||
- `org.springframework.transaction.annotation.Transactional`(대신 `TransactionPort`를 쓴다).
|
||||
- `org.springframework.context.ApplicationContext` — 직접 의존 금지
|
||||
(`getBean(Class)` 같은 리플렉션식 우회는 ArchUnit 규칙 `APPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXT`가 막는다). 문자열 키로
|
||||
bean을 찾기, `Class.forName(String)`, `BeanFactory#getBeansOfType`은 ArchUnit 정적 분석이
|
||||
보지 못하는 곳이다. 코드 리뷰 체크리스트로 막는다.
|
||||
- Lombok(`lombok..`) — `domain-core`에서도 금지다. `application-core`에서는 지금 Lombok이
|
||||
계약 범위에 없다. 쓰려면 바이트코드가 불투명해지는 비용을 먼저 따진다.
|
||||
- 이 모듈 안의 영속 계층 트랜잭션 애너테이션은 종류를 가리지 않고 금지다.
|
||||
- 진단 프레임워크(`org.slf4j`, `java.util.logging`, Logback, Log4j, Micrometer). 진단 의도는
|
||||
전용 outbound `*Port`로 나타내고, 어떻게 남길지는 어댑터가 정한다.
|
||||
- 메시징 provider·런타임 타입: 물리 topic, Kafka record나 metadata, JSON tree·raw JSON payload,
|
||||
serializer·schema validator 구현, 보안 토폴로지, publication epoch.
|
||||
|
||||
## 계약 타입
|
||||
|
||||
| 타입 | 용도 |
|
||||
|---|---|
|
||||
| `usecase.UseCase<I, O>` | inbound 포트의 기반 타입. 구체 inbound 포트는 반드시 `CommandUseCase`나 `QueryUseCase`를 상속한다. |
|
||||
| `usecase.CommandUseCase<C extends Command, R>` | 쓰기 유스케이스의 inbound 포트. 구현은 반드시 `@UseCaseCapability`를 단다. |
|
||||
| `usecase.QueryUseCase<Q extends Query, R>` | 읽기 전용 유스케이스의 inbound 포트. 구현은 반드시 `transactionMode = READ_ONLY`와 `repositoryAccess = READ_REPOSITORY`를 선언한다. |
|
||||
| `command.Command` | 쓰기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. |
|
||||
| `query.Query` | 읽기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. |
|
||||
| `transaction.TransactionPort` | 합류할 수 있는 쓰기·읽기, 물리 루트에서만 하는 쓰기, 독립 쓰기 경계를 내놓는 outbound 포트. `adapter:outbound:persistence-jpa`의 `SpringTransaction`이 구현한다. |
|
||||
| `secret.SecretSourcePort` | 프레임워크 없는 outbound 비밀 해석 이음매. 배포가 app-bootstrap에서 backend를 고른다. 실제 환경 변수·클라우드·vault 리더는 outbound 어댑터 leaf에 둔다. |
|
||||
| `transaction.NestedRootTransactionRejectedException` | `inRootWrite`가 실제로 열린 바깥 트랜잭션을 찾았을 때, action이나 provider 부작용 전에 바로 던지는 실패 신호. |
|
||||
| `transaction.TransactionMode` | `WRITE` / `READ_ONLY` / `REQUIRES_NEW`. `NESTED`와 `NEVER`는 일부러 없다. |
|
||||
| `transaction.Isolation` | `READ_COMMITTED`(고정 기본값) / `REPEATABLE_READ` / `SERIALIZABLE`. `READ_UNCOMMITTED`는 금지다(선언하지 않았다). vendor 기본값은 쓰지 않는다(엔진마다 기본값이 다르다 — PostgreSQL은 READ COMMITTED, MySQL InnoDB는 REPEATABLE READ). 더 엄격한 수준을 `TransactionPort`로 넘기는 일은 `feature-application-port-usecase-contract`와 함께 바꿀 `planned` 항목이다. 지금 호출 경로는 `READ_COMMITTED`로 고정한다. |
|
||||
| `capability.UseCaseCapability` | 모든 구체 유스케이스에 반드시 다는 애너테이션: `transactionMode`, `idempotency`, `repositoryAccess`, `externalOutboundAllowed`를 선언한다. |
|
||||
| `capability.Idempotency` | `IDEMPOTENT` / `KEYED` / `NOT_IDEMPOTENT`. |
|
||||
| `capability.RepositoryAccess` | `NONE` / `READ_REPOSITORY` / `WRITE_REPOSITORY`. |
|
||||
| `messaging.contract.IntegrationEventContractContribution<P>` | 닫힌 정확한 record payload 타입, 정해진 component 순서, 로컬 schema identity·hash, provider 중립 descriptor 기여. |
|
||||
| `messaging.event.IntegrationEventDraft<P>` | 로컬 인코딩 전의 타입 있는 semantic 이벤트. JSON·Kafka·영속 상태가 아니다. `IntegrationEventDrafts`로만 만든다(`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`). |
|
||||
| `messaging.event.IntegrationEventDrafts` | 기능이 초안을 만드는 유일한 길: contract id·version·destination은 contract에서, correlation은 요청 값이 정규형이면 그 값(아니면 event id), 테넌트가 없는 기능은 `SINGLE_TENANT_SCOPE`. |
|
||||
| `messaging.event.IntegrationIdentity` | event id, correlation·causation id, aggregate id의 유일한 문법과 길이 한계. 값은 `isCanonical(value, bound)`로 시험한다. 패턴을 복사하지 않는다. |
|
||||
| `messaging.event.ValidatedIntegrationEvent` | 안정된 semantic identity와 바뀌지 않는 정확한 인코딩 바이트·hash. 뒤의 durable append 경계로 넘길 준비가 된 값이다. |
|
||||
| `messaging.event.IntegrationEventEncoderPort` | 프레임워크 없는 로컬 경계(초안 → 검증된 이벤트). outbound 어댑터가 구현한다(템플릿은 `adapter:outbound:support`의 `JsonIntegrationEventEncoder`). |
|
||||
| `outbox.OutboxAppendPort` | 유일한 outbox append: `ValidatedIntegrationEvent` 하나를 호출자의 쓰기 트랜잭션 안에서 넣는다. |
|
||||
| `tenant.TenantId` | 테넌트 식별자와 그 유일한 문법(`[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`). web과 GraphQL 전송 문맥이 모두 이 값을 싣는다. 전송 계층이 검증된 인증 데이터로만 만든다. |
|
||||
|
||||
## 알림 (NOTIF-ADR-005)
|
||||
|
||||
알림 타입은 이 leaf에 하나도 없다. `..notification.platform..`과
|
||||
`dev.caskeleton.application.notification` 바로 아래의 단순한 `NotificationPort`, `Notification`,
|
||||
`NotificationChannel`은 모두 leaf `application-notification`의 것이다. 패키지 접두어가 같은 것이
|
||||
유일한 연결이다. R1 조율 타입은 2026-09-25에 지웠다.
|
||||
|
||||
## 이름 규칙 (Naming convention)
|
||||
|
||||
이 절이 저장소의 이름 규칙 정본이다. 기계로 볼 수 있는 행은 `NamingConventionTest`(app-bootstrap
|
||||
architectureTest)가 강제한다. 나머지는 리뷰 규칙이고, 리뷰가 이 표와 대조한다. 새 기능은 「새 코드」
|
||||
열을 따른다. 「이미 있는 예외」는 누가 실수로 따라 하지 않게 이름을 적어 둔 것이다.
|
||||
|
||||
| 역할 | 이름 | 위치 | 이미 있는 예외(따라 하지 않는다) |
|
||||
|---|---|---|---|
|
||||
| 유스케이스(inbound 포트 구현) | `<Verb><Noun>UseCase`, ArchUnit이 강제 | 기능의 `application` 패키지 | `*ApplicationUseCase`(application-fileserver, application-notification), `*Service`(notification, fileserver) |
|
||||
| command·query record | `*Command` / `*Query` | 그 유스케이스 옆 | — |
|
||||
| aggregate 영속(aggregate 전체를 저장하고 돌려준다) | `<Aggregate>Repository` | aggregate의 **domain** 패키지, 도메인이 가진다 | — |
|
||||
| 애플리케이션이 가진 기술 저장소(outbox, 멱등성, operation 행) | `<Thing>StorePort` | application 패키지 | `*WritePort`(옛 onboarding fixture, 지움) |
|
||||
| aggregate가 아니라 projection을 돌려주는 읽기 모델 | `<Thing>QueryPort` | application 패키지. projection만 돌려준다(ArchUnit) | — |
|
||||
| 그 밖의 outbound 포트 | `<Capability>Port` | application 패키지 | — |
|
||||
| 서버가 정하는 id 생성 | `<Aggregate>IdFactory extends IdFactory<<Aggregate>Id>` | domain 패키지. id record는 `implements ResourceId<Self>` | `OutboxEventIdFactory`(샘플. event id는 resource id가 아니다) |
|
||||
| 설정 바인딩 | `*Settings`(운영) 또는 `*Policy`(인가·도메인 정책), ArchUnit이 강제 | 그것을 바인딩하는 leaf | — |
|
||||
| Throwable | `*Exception`, ArchUnit이 강제 | — | — |
|
||||
| 포트의 계약 시험 키트 | 포트 소유자의 testFixtures에 둔 추상 `<Port>Contract`. fake의 시험과 각 어댑터의 시험이 상속한다 | testFixtures | 값 타입 시험의 이름이 한때 `*ContractTest`였다. 지금은 `*ValueTypesTest`다 |
|
||||
|
||||
저장소의 한 줄 규칙: **도메인이 알아볼 만한 것을 저장하면 도메인의 `Repository`다. 애플리케이션에
|
||||
필요한 배관이면 application의 `StorePort`다.**
|
||||
|
||||
## 패키지 소유 (Package ownership)
|
||||
|
||||
이 절은 **템플릿이 어떤 패키지를 가지는지**와 업무 기능이 어디로 가는지의 정본이다.
|
||||
`docs/manual/03-placement.md`가 이곳을 가리킨다.
|
||||
|
||||
- 업무 기능은 `dev.caskeleton.application.<feature>`다(그리고 `dev.caskeleton.domain.<feature>`,
|
||||
`...adapter.inbound.web.<feature>`, `...bootstrap.autoconfigure.<feature>`). 루트마다 바로 아래에
|
||||
기능 하나당 패키지 하나를 두고, `command`·`usecase`·`port` 하위 패키지를 두지 않는다.
|
||||
- `<feature>`는 아래 템플릿 패키지 이름 중 하나가 **아니다**. 같은 이름의 템플릿 패키지 옆에 둔
|
||||
기능은 같은 패키지 트리에 들어가고, upstream 템플릿 갱신이 올 때마다 그 기능에 섞여 들어간다.
|
||||
- 템플릿 패키지는 기능 패키지를 import하지 않는다. 이름이 맞아도 업무 코드를 템플릿 패키지에 넣지
|
||||
않는다.
|
||||
- 두 루트 아래에서 여기 적히지 않은 것은 모두 기능이다. 파생 서비스는 이 목록을 고치지 않고 기능을
|
||||
더한다. 템플릿은 자기 패키지를 더하거나, 이름을 바꾸거나, 지울 때 이 목록을 고친다.
|
||||
|
||||
| 패키지 (`dev.caskeleton.application.*`) | 소유 leaf | 담는 것 |
|
||||
|---|---|---|
|
||||
| `usecase`, `command`, `query` | application-core | inbound 포트 기반 타입과 command·query 표지 |
|
||||
| `capability` | application-core | `@UseCaseCapability`와 그 enum |
|
||||
| `transaction` | application-core | `TransactionPort`와 그 모드 |
|
||||
| `security` | application-core | 인가 포트, `@RequiresPermission`, `@SystemInvoked`, `@SystemCaller`, `ObjectAccessPolicy` |
|
||||
| `tenant` | application-core | `TenantId` |
|
||||
| `observability` | application-core | `CorrelationIdPort`, `UserPrincipalPseudonymizerPort` |
|
||||
| `secret` | application-core | `SecretSourcePort`, `SecretReference` |
|
||||
| `messaging` | application-core | integration event semantic contract |
|
||||
| `outbox` | application-core | 트랜잭션 outbox append와 relay |
|
||||
| `idempotency` | application-core | 키 기반 멱등성 executor와 store 포트 |
|
||||
| `operation` | application-core | durable(오래 걸리는) operation |
|
||||
| `lease`, `lock` | application-core | 분산 lease·lock 포트 |
|
||||
| `cache` | application-core | cache region 포트 |
|
||||
| `realtime` | application-core | live event 재생 포트 |
|
||||
| `notification` | application-notification | 알림 capability |
|
||||
| `fileserver` | application-fileserver | 파일 서버 capability |
|
||||
| `objectstorage` | application-objectstorage | 오브젝트 스토리지 capability(`content.CallBudget`은 그것이 싣는 호출 기한이다) |
|
||||
|
||||
| 패키지 (`dev.caskeleton.domain.*`) | 소유 leaf | 담는 것 |
|
||||
|---|---|---|
|
||||
| `identifier` | domain-core | `ResourceId`, `IdFactory` |
|
||||
| `stereotype` | domain-core | `@AggregateRoot`, `@DomainEvent`, `@ValueObject` |
|
||||
|
||||
강제하는 곳:
|
||||
|
||||
- `scripts/new-feature.sh`는 다섯 루트 중 어디든, 어느 leaf든 이미 패키지로 있는 기능 이름을
|
||||
거절한다. 템플릿 패키지도 모두 여기 걸린다.
|
||||
- `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`: 두 루트 아래의 기능
|
||||
패키지는 이 표의 이름을 쓰지 않는다. 기능마다 domain 패키지가 있으므로 `operation`이라는 기능은
|
||||
`dev.caskeleton.domain.operation`에서 걸린다.
|
||||
- `NamingConventionTest.TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`: 템플릿 패키지 안에 쓴
|
||||
기능 클래스는 템플릿 이름을 지니지만 자기 도메인을 import한다. 실패하는 것은 그 import다.
|
||||
- 이 표가 정본이다. 규칙이 읽는 기계용 사본은 `TemplatePackageOwnership`이다(app-bootstrap
|
||||
`src/test`에 있어서 architecture suite와 document-contract lane이 모두 본다).
|
||||
`TemplatePackageOwnershipDocumentTest`(document-contract lane, `mainCheck`)는 표와 그 클래스의
|
||||
패키지 이름이나 소유 leaf가 다르거나, 표에 적힌 패키지가 표가 말한 leaf에 없으면 실패한다.
|
||||
`TemplatePackageOwnershipRuleTest`(architectureTest)는 적힌 이름이 운영 클래스 어디에도 없으면
|
||||
실패한다. 새 템플릿 패키지는 같은 변경에서 둘 모두에 들어간다.
|
||||
- 못 잡는 것: 아무도 적지 않은 새 템플릿 패키지. 기능은 같은 leaf에 생성되므로
|
||||
(`scripts/new-feature.sh`) 적히지 않은 패키지는 기능과 구별되지 않는다. 적는 것까지가 패키지를
|
||||
더하는 일이다.
|
||||
- 버린 대안: 적힌 최상위 패키지만 허용하기(파생 기능마다 템플릿 목록을 고쳐야 한다 — 기능마다
|
||||
병합 충돌이 난다), 플랫폼 패키지용 `application-platform` leaf를 따로 두기(2026-11-01 성숙도
|
||||
리뷰에서 따졌다: 경계는 더 분명하지만, 이름 규칙에 필요한 것보다 registry edge가 많아진다).
|
||||
|
||||
## 정해진 유스케이스 모양 (Canonical use case shape)
|
||||
|
||||
```java
|
||||
@RequiresPermission("user:register")
|
||||
@UseCaseCapability(
|
||||
transactionMode = TransactionMode.WRITE,
|
||||
idempotency = Idempotency.KEYED,
|
||||
repositoryAccess = RepositoryAccess.WRITE_REPOSITORY)
|
||||
public class RegisterUserUseCase implements CommandUseCase<RegisterUserCommand, User> {
|
||||
|
||||
private final UserRepository users;
|
||||
private final TransactionPort tx;
|
||||
|
||||
public RegisterUserUseCase(UserRepository users, TransactionPort tx) {
|
||||
this.users = users;
|
||||
this.tx = tx;
|
||||
}
|
||||
|
||||
@Override
|
||||
public User handle(RegisterUserCommand cmd) {
|
||||
return tx.inWrite(() -> {
|
||||
// ... domain coordination
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
이 클래스는 평범한 Java다. 조립 루트가 포트와 설정 값을 넣어 만든다. application-core는 DI
|
||||
프레임워크에 스스로 등록하지 않는다. 클래스는 **final이 아니다**: 상태를 바꾸는 유스케이스는
|
||||
`@RequiresPermission`을 선언하고, web 어댑터는 CGLIB proxy로 그것을 강제하는데, CGLIB는 final
|
||||
클래스를 상속하지 못한다(`RequiresPermissionProxyabilityTest`). 같은 이유로 bean으로 등록한다.
|
||||
`new`로 만든 유스케이스는 검사를 받지 않는다. 시스템만 부르는 유스케이스(스케줄러, relay, 메시지
|
||||
소비자)는 권한 대신 `@SystemInvoked(reason = ...)`를 달고 bean이 아니다. 권한 검사가 없는 쓰기라서
|
||||
사용자 요청이 닿으면 안 되기 때문이다. 그 시스템 호출자가 유스케이스를 만든다: 스케줄러는 조립
|
||||
모듈, 메시지 핸들러는 `..adapter.inbound.messaging..` 안의 `@SystemCaller(reason = ...)`, 예약
|
||||
작업은 서비스 자신의 `..adapter.inbound.scheduler..` 패키지 안의 `@SystemCaller`다. 이 셋과 각각의
|
||||
위치는 `docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」가 정본 목록이다. 모두 강제된다:
|
||||
`@SystemInvoked` bean은 기동에 실패한다. `@SystemCaller`가 아닌 inbound 어댑터가 그 유스케이스에
|
||||
의존하면 `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`가 실패한다.
|
||||
`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`는 그 표지(그리고 표지가 붙은 클래스 안에 든
|
||||
클래스)를 사용자 전송 계층에 두지 못하게 한다. `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`는 사용자
|
||||
전송 계층이 시스템 호출자를 부르지 못하게 한다(그 클래스로든, 그것이 구현한 프로젝트 인터페이스로든).
|
||||
`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`는 시스템 호출자가 `Runnable`이나 프로젝트 밖의 다른
|
||||
타입이 되지 못하게 한다. 그런 타입은 어떤 의존 규칙도 따라가지 못한다. 타입 이름이 드러나지 않는
|
||||
경로(이름으로 찾는 bean, 설정이 넘겨주는 함수)는 보지 못한다. 매뉴얼 07장이 그 경로와 그것을 막는
|
||||
곳을 적는다. `@RequiresPermission` bean이 있는데 강제할 advisor가 없는 조립도 기동에 실패한다
|
||||
(`composition:service-runtime`의 `PermissionEnforcementGuard`, 두 검사 모두).
|
||||
|
||||
## 허용하는 트랜잭션 모양 (Allowed transactional shapes)
|
||||
|
||||
| 유스케이스 모양 | `transactionMode` | TransactionPort 호출 | 언제 |
|
||||
|---|---|---|---|
|
||||
| 쓰기 command | `WRITE` | `tx.inWrite(...)` | `CommandUseCase`의 기본. |
|
||||
| 물리 루트 쓰기 command | `WRITE` | `tx.inRootWrite(...)` | 바깥 트랜잭션이 없음을 증명하고 커밋 뒤에 결과를 내놓아야 하는 조율일 때만. |
|
||||
| 읽기 전용 query | `READ_ONLY` | `tx.inRead(...)` | `QueryUseCase`의 기본. |
|
||||
| outbox·감사·보상 | `REQUIRES_NEW` | `tx.inNew(...)` | 유스케이스가 반드시 호출자와 따로 커밋해야 할 때만. |
|
||||
|
||||
`NESTED`와 `NEVER` 전파는 금지다.
|
||||
`inRootWrite`는 action이나 `PlatformTransactionManager`를 부르기 전에 실제로 열린 바깥 트랜잭션을
|
||||
반드시 거절한다. 루트 전용 동작을 `REQUIRES_NEW`로 흉내 내면 안 된다.
|
||||
`WRITE_REPOSITORY + WRITE` 유스케이스의 직접 경계 적합성 규칙은 `inWrite`와 `inRootWrite`가 모두
|
||||
만족한다. READ와 REQUIRES_NEW의 대응은 계속 서로 배타적이다.
|
||||
|
||||
### 콜백 시그니처 계약
|
||||
|
||||
`TransactionPort` 콜백은 `Supplier<T>` / `Runnable`이라 checked 예외를 던지지 못한다. Spring
|
||||
`TransactionCallback<T>`의 제약과 같다. 도메인의 checked 예외는 `RuntimeException` 하위 클래스로
|
||||
감싼다(`DomainException extends RuntimeException`). `IOException`은 `UncheckedIOException`으로
|
||||
감싼다. `SQLException`은 Spring의 `DataAccessException` 계층이 자동으로 번역한다.
|
||||
|
||||
### `inNew` 풀 크기 제약
|
||||
|
||||
`inNew`는 새 물리 JDBC 연결을 얻는다. 풀 크기는 반드시 다음을 만족한다.
|
||||
|
||||
```
|
||||
hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1
|
||||
```
|
||||
|
||||
**금지**: 많은 레코드를 도는 반복문 안에서 `tx.inNew(...)`를 부른다 — 풀이 바닥나고 교착이 생길
|
||||
수 있다. 레코드를 `inNew` 호출 **하나** 안에서 묶어 처리하거나, 반복문을 트랜잭션 경계 밖으로 뺀다.
|
||||
|
||||
## 멱등성 (KEYED) — feature-rate-limit-idempotency-contract
|
||||
|
||||
`@UseCaseCapability(idempotency = Idempotency.KEYED)`는 **지원한다**. KEYED 유스케이스는 자기 일을
|
||||
`dev.caskeleton.application.idempotency.IdempotencyExecutor`로 감싼다. 소유자를 안전하게 지키는
|
||||
유일한 세대다. V1 `IdempotencyScope`/`tryBegin` API는 없어졌다.
|
||||
|
||||
- **범위(scope)**: 호출자가 `IdempotencyScopeDigest`를 넘긴다. principal + client key + operation
|
||||
code의 버전 있는 HMAC이고, executor가 받기 전에 계산한다. 원본 `Idempotency-Key`는 이 계층에도
|
||||
store에도 닿지 않는다.
|
||||
- **store**: `IdempotencyStorePort`. `app.capabilities.idempotency.provider`로 고른 provider 정확히
|
||||
하나가 내놓는다(`redis` → `cache-redis`, `postgresql` → `persistence-jpa`, 기본값 `disabled`).
|
||||
운영에서 메모리 저장소는 금지다.
|
||||
- **executor**: `composition:idempotency`의 `IdempotencyAutoConfiguration`이 `IdempotencySettings`로
|
||||
한 번 만든다(처리 lease 30s, 재생 TTL `APP_IDEMPOTENCY_TTL` 24h ≤72h이고 lease보다 짧지 않다, 실패
|
||||
보존 24h이고 재생 TTL보다 짧지 않다). 유스케이스나 서비스 자신의 설정에서 만들지 않는다.
|
||||
- action은 `IdempotentAction.Outcome`(`Success` / `RetryableNoEffect` / `EffectUnknown`)을
|
||||
돌려준다. 던진 예외는 효과를 모름(effect-unknown)으로 센다. 처리 중이면 409
|
||||
`IDEMPOTENT_IN_FLIGHT`, fingerprint(SHA-256)가 다르면 422 `IDEMPOTENT_REQUEST_MISMATCH`다.
|
||||
`IdempotencyUnavailableException`과 `IdempotencyRecoveryRequiredException`은 store가 결과를
|
||||
증명하지 못했다는 뜻이니 무턱대고 다시 시도하지 않는다.
|
||||
- 모든 store는 처리 lease가 끝난 실행에 `RecoveryRequired`로 답하고 그 실행을 넘겨받지 않는다.
|
||||
넘겨받는 것은 시작하지 않은 claim이나 다시 시도할 수 있는 실패뿐이다. 이 답은 레코드를 가진
|
||||
쪽에게 남긴다: 가진 쪽이 늦게 보낸 첫 `complete`/`markFailed`는 기록한다. lease가 끝난 것은
|
||||
갱신하지 않고, lease가 끝난 claim은 시작하지 않는다. 둘 다 `NOT_OWNER`가 아니라 `LEASE_EXPIRED`로
|
||||
답하고, executor는 거절된 시작을 「적용 안 됨」으로 바꾼다(소유자 결정 2026-11-04). 레코드는
|
||||
lease에 재생 TTL을 더한 만큼 산다. `IdempotencyStoreContract`가 Redis와 PostgreSQL을 실제 서버에서
|
||||
둘 모두에 맞춘다. 메모리 fake는 시간을 모델링하지 않으니 계약 중 시간이 없는 경우만 돈다.
|
||||
- 모든 전이는 그 레코드를 claim한 operation을 이름으로 댄다(`IdempotencyOwner.claimOperationId()`).
|
||||
다른 operation이면 모든 store에서 `OPERATION_CONFLICT`이고 아무것도 바꾸지 않는다. owner token을
|
||||
다른 operation으로 가져온 조회도 같다(소유자 결정 2026-11-06).
|
||||
- 이미 적용된 전이는 그것을 적용한 handle에게만 「already …」로 확인해 준다. 그 handle은 그 전이로
|
||||
옮겨 간, 한 revision 뒤의 레코드다. 다른 handle은 모두 `NOT_OWNER`다. 넘겨받기 전의 같은 시도의
|
||||
handle도, 갱신을 적용한 handle로 하는 시작도 그렇다. 놓아준 handle로 하는 시작은 store가 놓아준
|
||||
레코드를 남기느냐에 따라 `ABSENT`나 `NOT_OWNER`다(소유자 결정 2026-11-06,
|
||||
`IdempotencyStoreContract`).
|
||||
- 적용한 handle이 다른 disposition으로 `markFailed`를 다시 보내면 `OPERATION_CONFLICT`이고 기록된
|
||||
실패가 남는다. retention만 다르면 `ALREADY_MARKED_SAME_OPERATION`이고 처음 retention이 남는다 —
|
||||
retention은 완료의 재생 TTL처럼 비교하지 않는다(소유자 결정 2026-11-07).
|
||||
|
||||
예전 ArchUnit 동결 규칙 `inbound_port_implementations_do_not_declare_keyed_idempotency`와 그 fixture는
|
||||
이 브랜치가 병합될 때 지웠다.
|
||||
|
||||
## 읽기·query 경로 (feature-application-query-bypass-contract)
|
||||
|
||||
읽기 쪽에는 똑같이 유효한 모양이 둘 있다. 읽기마다 고르고, 하나를 강요하지 않는다.
|
||||
|
||||
| 모양 | 돌려주는 것 | 언제 | 어떻게 |
|
||||
|---|---|---|---|
|
||||
| **aggregate를 거쳐서**(단순 읽기의 기본) | `*Repository` 포트로 받은 도메인 aggregate | 읽기 모양 == 쓰기 aggregate **이고** aggregate가 최소 불변식 경계일 때(지연 컬렉션이 필요 없음) | `QueryUseCase` → repository 포트 → `Order` |
|
||||
| **projection (CQRS-lite)** | `*QueryPort`로 받은 애플리케이션 계층 projection DTO | 읽기 모양 ≠ 쓰기, 또는 aggregate 수화·지연 컬렉션 join을 건너뛰려 할 때 | `QueryUseCase` → `*QueryPort` → `OrderSummary`(record). query는 JPQL `SELECT new` / JdbcTemplate |
|
||||
|
||||
- **순수성 가드레일(core, 기계로 강제):** 단순 이름이 `QueryPort`로 끝나는 읽기 포트는 반드시
|
||||
애플리케이션 계층 projection DTO만 돌려준다 — 도메인 aggregate, JPA 엔티티, web 타입은 **제네릭
|
||||
타입 인자를 거쳐서도**(`List<DomainType>`) 안 된다. ArchUnit
|
||||
`QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`가 강제한다. projection 사용 자체는 강요된 기본이
|
||||
아니라 **선택**이다.
|
||||
- **엄격한 절차:** 모든 읽기는 `QueryUseCase` bean을 거친다. web → 읽기 포트로 바로 가는 얇은
|
||||
경로는 없다. 그런 경로는 필수인 `@UseCaseCapability` 적합성 검사를 건너뛴다.
|
||||
- **트랜잭션:** 읽기의 기본은 `TransactionPort.inRead`다. 트랜잭션 없는(autocommit) 읽기는
|
||||
`spring.jpa.open-in-view=false`가 확인됐고 **그리고** 읽기가 projection만 쓰고(지연 접근 없음)
|
||||
**그리고** 문장 하나일 때만 고를 수 있다. 아니면 `inRead`를 쓴다.
|
||||
- **capability:** repository를 쓰는 projection 읽기도 `repositoryAccess = READ_REPOSITORY`다.
|
||||
「projection이냐 aggregate냐」는 돌려주는 *모양* 축이고, repository 접근 *수준* 축과 따로다 — 새
|
||||
enum이 없다. outbound HTTP 읽기(repository 없음)는 `RepositoryAccess.NONE`이다.
|
||||
- 물리적으로 따로 둔 읽기 저장소를 쓰는 완전한 CQRS는 범위 밖이다. 올려서 정할 일이다.
|
||||
|
||||
## ArchUnit 가드레일(강제됨)
|
||||
|
||||
- `APPLICATION_DOES_NOT_DEPEND_ON_ADAPTERS_OR_TRANSPORT`
|
||||
- `APPLICATION_DOES_NOT_USE_SPRING_TRANSACTIONAL_ANNOTATION`
|
||||
- `APPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXT`
|
||||
- `APPLICATION_HAS_NO_DIAGNOSTIC_FRAMEWORK`
|
||||
- `INBOUND_PORT_IMPLEMENTATIONS_END_WITH_USE_CASE`
|
||||
- `INBOUND_PORT_IMPLEMENTATIONS_DECLARE_CAPABILITY`
|
||||
- `QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`(`*QueryPort` 반환 순수성)
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :application-core:test
|
||||
./gradlew :app-bootstrap:architectureTest
|
||||
```
|
||||
|
||||
위 메시징 타입은 semantic contract R1까지만 세운다. JSON Schema 검증, Kafka 발행, durable outbox
|
||||
영속, 그 밖의 메시징 R2 capability를 주장하지 않는다.
|
||||
@@ -1,336 +1 @@
|
||||
# application-core — 애플리케이션 유스케이스
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `application-core`
|
||||
- Gradle 경로: `:application-core`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :application-core:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준은 공용 버전 카탈로그(`src/gradle/libs.versions.toml`)가 고정한 Spring Boot 4.x다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.application`.
|
||||
|
||||
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT).
|
||||
|
||||
## 책임 (Responsibility)
|
||||
|
||||
- 유스케이스 inbound 포트(`CommandUseCase`, `QueryUseCase`)와 그 command·query 계약.
|
||||
- 유스케이스가 의존하는 outbound 포트(`*Port` 인터페이스).
|
||||
- 애플리케이션 예외와 정책 타입.
|
||||
- 포트를 거쳐 도메인 모델을 조율한다.
|
||||
- `TransactionPort` 추상화로 애플리케이션 트랜잭션 경계를 가진다.
|
||||
- `CorrelationIdPort` 같은 포트로 프레임워크 없는 호출 문맥을 내놓는다. MDC 같은 실제 저장소는
|
||||
어댑터가 가진다.
|
||||
- 프레임워크 없는 integration event 초안(semantic draft), 검증된 이벤트의 값 계약, 정확한 타입의
|
||||
payload를 내놓는 SPI를 가진다. 메시징 semantic contract R1 경계까지만이다.
|
||||
|
||||
## 허용
|
||||
|
||||
- `:domain-core`
|
||||
- `:shared-contract`
|
||||
- Java 표준 라이브러리 타입.
|
||||
|
||||
## 금지 (Forbidden)
|
||||
|
||||
- `adapter-*` 구현 클래스.
|
||||
- `app-bootstrap`.
|
||||
- controller의 요청·응답 DTO.
|
||||
- JPA 엔티티와 Spring Data repository.
|
||||
- HTTP 상태, 전송 타입(`org.springframework.web..`).
|
||||
- `org.springframework.transaction.annotation.Transactional`(대신 `TransactionPort`를 쓴다).
|
||||
- `org.springframework.context.ApplicationContext` — 직접 의존 금지
|
||||
(`getBean(Class)` 같은 리플렉션식 우회는 ArchUnit 규칙 `APPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXT`가 막는다). 문자열 키로
|
||||
bean을 찾기, `Class.forName(String)`, `BeanFactory#getBeansOfType`은 ArchUnit 정적 분석이
|
||||
보지 못하는 곳이다. 코드 리뷰 체크리스트로 막는다.
|
||||
- Lombok(`lombok..`) — `domain-core`에서도 금지다. `application-core`에서는 지금 Lombok이
|
||||
계약 범위에 없다. 쓰려면 바이트코드가 불투명해지는 비용을 먼저 따진다.
|
||||
- 이 모듈 안의 영속 계층 트랜잭션 애너테이션은 종류를 가리지 않고 금지다.
|
||||
- 진단 프레임워크(`org.slf4j`, `java.util.logging`, Logback, Log4j, Micrometer). 진단 의도는
|
||||
전용 outbound `*Port`로 나타내고, 어떻게 남길지는 어댑터가 정한다.
|
||||
- 메시징 provider·런타임 타입: 물리 topic, Kafka record나 metadata, JSON tree·raw JSON payload,
|
||||
serializer·schema validator 구현, 보안 토폴로지, publication epoch.
|
||||
|
||||
## 계약 타입
|
||||
|
||||
| 타입 | 용도 |
|
||||
|---|---|
|
||||
| `usecase.UseCase<I, O>` | inbound 포트의 기반 타입. 구체 inbound 포트는 반드시 `CommandUseCase`나 `QueryUseCase`를 상속한다. |
|
||||
| `usecase.CommandUseCase<C extends Command, R>` | 쓰기 유스케이스의 inbound 포트. 구현은 반드시 `@UseCaseCapability`를 단다. |
|
||||
| `usecase.QueryUseCase<Q extends Query, R>` | 읽기 전용 유스케이스의 inbound 포트. 구현은 반드시 `transactionMode = READ_ONLY`와 `repositoryAccess = READ_REPOSITORY`를 선언한다. |
|
||||
| `command.Command` | 쓰기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. |
|
||||
| `query.Query` | 읽기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. |
|
||||
| `transaction.TransactionPort` | 합류할 수 있는 쓰기·읽기, 물리 루트에서만 하는 쓰기, 독립 쓰기 경계를 내놓는 outbound 포트. `adapter:outbound:persistence-jpa`의 `SpringTransaction`이 구현한다. |
|
||||
| `secret.SecretSourcePort` | 프레임워크 없는 outbound 비밀 해석 이음매. 배포가 app-bootstrap에서 backend를 고른다. 실제 환경 변수·클라우드·vault 리더는 outbound 어댑터 leaf에 둔다. |
|
||||
| `transaction.NestedRootTransactionRejectedException` | `inRootWrite`가 실제로 열린 바깥 트랜잭션을 찾았을 때, action이나 provider 부작용 전에 바로 던지는 실패 신호. |
|
||||
| `transaction.TransactionMode` | `WRITE` / `READ_ONLY` / `REQUIRES_NEW`. `NESTED`와 `NEVER`는 일부러 없다. |
|
||||
| `transaction.Isolation` | `READ_COMMITTED`(고정 기본값) / `REPEATABLE_READ` / `SERIALIZABLE`. `READ_UNCOMMITTED`는 금지다(선언하지 않았다). vendor 기본값은 쓰지 않는다(엔진마다 기본값이 다르다 — PostgreSQL은 READ COMMITTED, MySQL InnoDB는 REPEATABLE READ). 더 엄격한 수준을 `TransactionPort`로 넘기는 일은 `feature-application-port-usecase-contract`와 함께 바꿀 `planned` 항목이다. 지금 호출 경로는 `READ_COMMITTED`로 고정한다. |
|
||||
| `capability.UseCaseCapability` | 모든 구체 유스케이스에 반드시 다는 애너테이션: `transactionMode`, `idempotency`, `repositoryAccess`, `externalOutboundAllowed`를 선언한다. |
|
||||
| `capability.Idempotency` | `IDEMPOTENT` / `KEYED` / `NOT_IDEMPOTENT`. |
|
||||
| `capability.RepositoryAccess` | `NONE` / `READ_REPOSITORY` / `WRITE_REPOSITORY`. |
|
||||
| `messaging.contract.IntegrationEventContractContribution<P>` | 닫힌 정확한 record payload 타입, 정해진 component 순서, 로컬 schema identity·hash, provider 중립 descriptor 기여. |
|
||||
| `messaging.event.IntegrationEventDraft<P>` | 로컬 인코딩 전의 타입 있는 semantic 이벤트. JSON·Kafka·영속 상태가 아니다. `IntegrationEventDrafts`로만 만든다(`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`). |
|
||||
| `messaging.event.IntegrationEventDrafts` | 기능이 초안을 만드는 유일한 길: contract id·version·destination은 contract에서, correlation은 요청 값이 정규형이면 그 값(아니면 event id), 테넌트가 없는 기능은 `SINGLE_TENANT_SCOPE`. |
|
||||
| `messaging.event.IntegrationIdentity` | event id, correlation·causation id, aggregate id의 유일한 문법과 길이 한계. 값은 `isCanonical(value, bound)`로 시험한다. 패턴을 복사하지 않는다. |
|
||||
| `messaging.event.ValidatedIntegrationEvent` | 안정된 semantic identity와 바뀌지 않는 정확한 인코딩 바이트·hash. 뒤의 durable append 경계로 넘길 준비가 된 값이다. |
|
||||
| `messaging.event.IntegrationEventEncoderPort` | 프레임워크 없는 로컬 경계(초안 → 검증된 이벤트). outbound 어댑터가 구현한다(템플릿은 `adapter:outbound:support`의 `JsonIntegrationEventEncoder`). |
|
||||
| `outbox.OutboxAppendPort` | 유일한 outbox append: `ValidatedIntegrationEvent` 하나를 호출자의 쓰기 트랜잭션 안에서 넣는다. |
|
||||
| `tenant.TenantId` | 테넌트 식별자와 그 유일한 문법(`[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`). web과 GraphQL 전송 문맥이 모두 이 값을 싣는다. 전송 계층이 검증된 인증 데이터로만 만든다. |
|
||||
|
||||
## 알림 (NOTIF-ADR-005)
|
||||
|
||||
알림 타입은 이 leaf에 하나도 없다. `..notification.platform..`과
|
||||
`dev.caskeleton.application.notification` 바로 아래의 단순한 `NotificationPort`, `Notification`,
|
||||
`NotificationChannel`은 모두 leaf `application-notification`의 것이다. 패키지 접두어가 같은 것이
|
||||
유일한 연결이다. R1 조율 타입은 2026-09-25에 지웠다.
|
||||
|
||||
## 이름 규칙 (Naming convention)
|
||||
|
||||
이 절이 저장소의 이름 규칙 정본이다. 기계로 볼 수 있는 행은 `NamingConventionTest`(app-bootstrap
|
||||
architectureTest)가 강제한다. 나머지는 리뷰 규칙이고, 리뷰가 이 표와 대조한다. 새 기능은 「새 코드」
|
||||
열을 따른다. 「이미 있는 예외」는 누가 실수로 따라 하지 않게 이름을 적어 둔 것이다.
|
||||
|
||||
| 역할 | 이름 | 위치 | 이미 있는 예외(따라 하지 않는다) |
|
||||
|---|---|---|---|
|
||||
| 유스케이스(inbound 포트 구현) | `<Verb><Noun>UseCase`, ArchUnit이 강제 | 기능의 `application` 패키지 | `*ApplicationUseCase`(application-fileserver, application-notification), `*Service`(notification, fileserver) |
|
||||
| command·query record | `*Command` / `*Query` | 그 유스케이스 옆 | — |
|
||||
| aggregate 영속(aggregate 전체를 저장하고 돌려준다) | `<Aggregate>Repository` | aggregate의 **domain** 패키지, 도메인이 가진다 | — |
|
||||
| 애플리케이션이 가진 기술 저장소(outbox, 멱등성, operation 행) | `<Thing>StorePort` | application 패키지 | `*WritePort`(옛 onboarding fixture, 지움) |
|
||||
| aggregate가 아니라 projection을 돌려주는 읽기 모델 | `<Thing>QueryPort` | application 패키지. projection만 돌려준다(ArchUnit) | — |
|
||||
| 그 밖의 outbound 포트 | `<Capability>Port` | application 패키지 | — |
|
||||
| 서버가 정하는 id 생성 | `<Aggregate>IdFactory extends IdFactory<<Aggregate>Id>` | domain 패키지. id record는 `implements ResourceId<Self>` | `OutboxEventIdFactory`(샘플. event id는 resource id가 아니다) |
|
||||
| 설정 바인딩 | `*Settings`(운영) 또는 `*Policy`(인가·도메인 정책), ArchUnit이 강제 | 그것을 바인딩하는 leaf | — |
|
||||
| Throwable | `*Exception`, ArchUnit이 강제 | — | — |
|
||||
| 포트의 계약 시험 키트 | 포트 소유자의 testFixtures에 둔 추상 `<Port>Contract`. fake의 시험과 각 어댑터의 시험이 상속한다 | testFixtures | 값 타입 시험의 이름이 한때 `*ContractTest`였다. 지금은 `*ValueTypesTest`다 |
|
||||
|
||||
저장소의 한 줄 규칙: **도메인이 알아볼 만한 것을 저장하면 도메인의 `Repository`다. 애플리케이션에
|
||||
필요한 배관이면 application의 `StorePort`다.**
|
||||
|
||||
## 패키지 소유 (Package ownership)
|
||||
|
||||
이 절은 **템플릿이 어떤 패키지를 가지는지**와 업무 기능이 어디로 가는지의 정본이다.
|
||||
`docs/manual/03-placement.md`가 이곳을 가리킨다.
|
||||
|
||||
- 업무 기능은 `dev.caskeleton.application.<feature>`다(그리고 `dev.caskeleton.domain.<feature>`,
|
||||
`...adapter.inbound.web.<feature>`, `...bootstrap.autoconfigure.<feature>`). 루트마다 바로 아래에
|
||||
기능 하나당 패키지 하나를 두고, `command`·`usecase`·`port` 하위 패키지를 두지 않는다.
|
||||
- `<feature>`는 아래 템플릿 패키지 이름 중 하나가 **아니다**. 같은 이름의 템플릿 패키지 옆에 둔
|
||||
기능은 같은 패키지 트리에 들어가고, upstream 템플릿 갱신이 올 때마다 그 기능에 섞여 들어간다.
|
||||
- 템플릿 패키지는 기능 패키지를 import하지 않는다. 이름이 맞아도 업무 코드를 템플릿 패키지에 넣지
|
||||
않는다.
|
||||
- 두 루트 아래에서 여기 적히지 않은 것은 모두 기능이다. 파생 서비스는 이 목록을 고치지 않고 기능을
|
||||
더한다. 템플릿은 자기 패키지를 더하거나, 이름을 바꾸거나, 지울 때 이 목록을 고친다.
|
||||
|
||||
| 패키지 (`dev.caskeleton.application.*`) | 소유 leaf | 담는 것 |
|
||||
|---|---|---|
|
||||
| `usecase`, `command`, `query` | application-core | inbound 포트 기반 타입과 command·query 표지 |
|
||||
| `capability` | application-core | `@UseCaseCapability`와 그 enum |
|
||||
| `transaction` | application-core | `TransactionPort`와 그 모드 |
|
||||
| `security` | application-core | 인가 포트, `@RequiresPermission`, `@SystemInvoked`, `@SystemCaller`, `ObjectAccessPolicy` |
|
||||
| `tenant` | application-core | `TenantId` |
|
||||
| `observability` | application-core | `CorrelationIdPort`, `UserPrincipalPseudonymizerPort` |
|
||||
| `secret` | application-core | `SecretSourcePort`, `SecretReference` |
|
||||
| `messaging` | application-core | integration event semantic contract |
|
||||
| `outbox` | application-core | 트랜잭션 outbox append와 relay |
|
||||
| `idempotency` | application-core | 키 기반 멱등성 executor와 store 포트 |
|
||||
| `operation` | application-core | durable(오래 걸리는) operation |
|
||||
| `lease`, `lock` | application-core | 분산 lease·lock 포트 |
|
||||
| `cache` | application-core | cache region 포트 |
|
||||
| `realtime` | application-core | live event 재생 포트 |
|
||||
| `notification` | application-notification | 알림 capability |
|
||||
| `fileserver` | application-fileserver | 파일 서버 capability |
|
||||
| `objectstorage` | application-objectstorage | 오브젝트 스토리지 capability(`content.CallBudget`은 그것이 싣는 호출 기한이다) |
|
||||
|
||||
| 패키지 (`dev.caskeleton.domain.*`) | 소유 leaf | 담는 것 |
|
||||
|---|---|---|
|
||||
| `identifier` | domain-core | `ResourceId`, `IdFactory` |
|
||||
| `stereotype` | domain-core | `@AggregateRoot`, `@DomainEvent`, `@ValueObject` |
|
||||
|
||||
강제하는 곳:
|
||||
|
||||
- `scripts/new-feature.sh`는 다섯 루트 중 어디든, 어느 leaf든 이미 패키지로 있는 기능 이름을
|
||||
거절한다. 템플릿 패키지도 모두 여기 걸린다.
|
||||
- `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`: 두 루트 아래의 기능
|
||||
패키지는 이 표의 이름을 쓰지 않는다. 기능마다 domain 패키지가 있으므로 `operation`이라는 기능은
|
||||
`dev.caskeleton.domain.operation`에서 걸린다.
|
||||
- `NamingConventionTest.TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`: 템플릿 패키지 안에 쓴
|
||||
기능 클래스는 템플릿 이름을 지니지만 자기 도메인을 import한다. 실패하는 것은 그 import다.
|
||||
- 이 표가 정본이다. 규칙이 읽는 기계용 사본은 `TemplatePackageOwnership`이다(app-bootstrap
|
||||
`src/test`에 있어서 architecture suite와 document-contract lane이 모두 본다).
|
||||
`TemplatePackageOwnershipDocumentTest`(document-contract lane, `mainCheck`)는 표와 그 클래스의
|
||||
패키지 이름이나 소유 leaf가 다르거나, 표에 적힌 패키지가 표가 말한 leaf에 없으면 실패한다.
|
||||
`TemplatePackageOwnershipRuleTest`(architectureTest)는 적힌 이름이 운영 클래스 어디에도 없으면
|
||||
실패한다. 새 템플릿 패키지는 같은 변경에서 둘 모두에 들어간다.
|
||||
- 못 잡는 것: 아무도 적지 않은 새 템플릿 패키지. 기능은 같은 leaf에 생성되므로
|
||||
(`scripts/new-feature.sh`) 적히지 않은 패키지는 기능과 구별되지 않는다. 적는 것까지가 패키지를
|
||||
더하는 일이다.
|
||||
- 버린 대안: 적힌 최상위 패키지만 허용하기(파생 기능마다 템플릿 목록을 고쳐야 한다 — 기능마다
|
||||
병합 충돌이 난다), 플랫폼 패키지용 `application-platform` leaf를 따로 두기(2026-11-01 성숙도
|
||||
리뷰에서 따졌다: 경계는 더 분명하지만, 이름 규칙에 필요한 것보다 registry edge가 많아진다).
|
||||
|
||||
## 정해진 유스케이스 모양 (Canonical use case shape)
|
||||
|
||||
```java
|
||||
@RequiresPermission("user:register")
|
||||
@UseCaseCapability(
|
||||
transactionMode = TransactionMode.WRITE,
|
||||
idempotency = Idempotency.KEYED,
|
||||
repositoryAccess = RepositoryAccess.WRITE_REPOSITORY)
|
||||
public class RegisterUserUseCase implements CommandUseCase<RegisterUserCommand, User> {
|
||||
|
||||
private final UserRepository users;
|
||||
private final TransactionPort tx;
|
||||
|
||||
public RegisterUserUseCase(UserRepository users, TransactionPort tx) {
|
||||
this.users = users;
|
||||
this.tx = tx;
|
||||
}
|
||||
|
||||
@Override
|
||||
public User handle(RegisterUserCommand cmd) {
|
||||
return tx.inWrite(() -> {
|
||||
// ... domain coordination
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
이 클래스는 평범한 Java다. 조립 루트가 포트와 설정 값을 넣어 만든다. application-core는 DI
|
||||
프레임워크에 스스로 등록하지 않는다. 클래스는 **final이 아니다**: 상태를 바꾸는 유스케이스는
|
||||
`@RequiresPermission`을 선언하고, web 어댑터는 CGLIB proxy로 그것을 강제하는데, CGLIB는 final
|
||||
클래스를 상속하지 못한다(`RequiresPermissionProxyabilityTest`). 같은 이유로 bean으로 등록한다.
|
||||
`new`로 만든 유스케이스는 검사를 받지 않는다. 시스템만 부르는 유스케이스(스케줄러, relay, 메시지
|
||||
소비자)는 권한 대신 `@SystemInvoked(reason = ...)`를 달고 bean이 아니다. 권한 검사가 없는 쓰기라서
|
||||
사용자 요청이 닿으면 안 되기 때문이다. 그 시스템 호출자가 유스케이스를 만든다: 스케줄러는 조립
|
||||
모듈, 메시지 핸들러는 `..adapter.inbound.messaging..` 안의 `@SystemCaller(reason = ...)`, 예약
|
||||
작업은 서비스 자신의 `..adapter.inbound.scheduler..` 패키지 안의 `@SystemCaller`다. 이 셋과 각각의
|
||||
위치는 `docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」가 정본 목록이다. 모두 강제된다:
|
||||
`@SystemInvoked` bean은 기동에 실패한다. `@SystemCaller`가 아닌 inbound 어댑터가 그 유스케이스에
|
||||
의존하면 `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`가 실패한다.
|
||||
`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`는 그 표지(그리고 표지가 붙은 클래스 안에 든
|
||||
클래스)를 사용자 전송 계층에 두지 못하게 한다. `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`는 사용자
|
||||
전송 계층이 시스템 호출자를 부르지 못하게 한다(그 클래스로든, 그것이 구현한 프로젝트 인터페이스로든).
|
||||
`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`는 시스템 호출자가 `Runnable`이나 프로젝트 밖의 다른
|
||||
타입이 되지 못하게 한다. 그런 타입은 어떤 의존 규칙도 따라가지 못한다. 타입 이름이 드러나지 않는
|
||||
경로(이름으로 찾는 bean, 설정이 넘겨주는 함수)는 보지 못한다. 매뉴얼 07장이 그 경로와 그것을 막는
|
||||
곳을 적는다. `@RequiresPermission` bean이 있는데 강제할 advisor가 없는 조립도 기동에 실패한다
|
||||
(`composition:service-runtime`의 `PermissionEnforcementGuard`, 두 검사 모두).
|
||||
|
||||
## 허용하는 트랜잭션 모양 (Allowed transactional shapes)
|
||||
|
||||
| 유스케이스 모양 | `transactionMode` | TransactionPort 호출 | 언제 |
|
||||
|---|---|---|---|
|
||||
| 쓰기 command | `WRITE` | `tx.inWrite(...)` | `CommandUseCase`의 기본. |
|
||||
| 물리 루트 쓰기 command | `WRITE` | `tx.inRootWrite(...)` | 바깥 트랜잭션이 없음을 증명하고 커밋 뒤에 결과를 내놓아야 하는 조율일 때만. |
|
||||
| 읽기 전용 query | `READ_ONLY` | `tx.inRead(...)` | `QueryUseCase`의 기본. |
|
||||
| outbox·감사·보상 | `REQUIRES_NEW` | `tx.inNew(...)` | 유스케이스가 반드시 호출자와 따로 커밋해야 할 때만. |
|
||||
|
||||
`NESTED`와 `NEVER` 전파는 금지다.
|
||||
`inRootWrite`는 action이나 `PlatformTransactionManager`를 부르기 전에 실제로 열린 바깥 트랜잭션을
|
||||
반드시 거절한다. 루트 전용 동작을 `REQUIRES_NEW`로 흉내 내면 안 된다.
|
||||
`WRITE_REPOSITORY + WRITE` 유스케이스의 직접 경계 적합성 규칙은 `inWrite`와 `inRootWrite`가 모두
|
||||
만족한다. READ와 REQUIRES_NEW의 대응은 계속 서로 배타적이다.
|
||||
|
||||
### 콜백 시그니처 계약
|
||||
|
||||
`TransactionPort` 콜백은 `Supplier<T>` / `Runnable`이라 checked 예외를 던지지 못한다. Spring
|
||||
`TransactionCallback<T>`의 제약과 같다. 도메인의 checked 예외는 `RuntimeException` 하위 클래스로
|
||||
감싼다(`DomainException extends RuntimeException`). `IOException`은 `UncheckedIOException`으로
|
||||
감싼다. `SQLException`은 Spring의 `DataAccessException` 계층이 자동으로 번역한다.
|
||||
|
||||
### `inNew` 풀 크기 제약
|
||||
|
||||
`inNew`는 새 물리 JDBC 연결을 얻는다. 풀 크기는 반드시 다음을 만족한다.
|
||||
|
||||
```
|
||||
hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1
|
||||
```
|
||||
|
||||
**금지**: 많은 레코드를 도는 반복문 안에서 `tx.inNew(...)`를 부른다 — 풀이 바닥나고 교착이 생길
|
||||
수 있다. 레코드를 `inNew` 호출 **하나** 안에서 묶어 처리하거나, 반복문을 트랜잭션 경계 밖으로 뺀다.
|
||||
|
||||
## 멱등성 (KEYED) — feature-rate-limit-idempotency-contract
|
||||
|
||||
`@UseCaseCapability(idempotency = Idempotency.KEYED)`는 **지원한다**. KEYED 유스케이스는 자기 일을
|
||||
`dev.caskeleton.application.idempotency.IdempotencyExecutor`로 감싼다. 소유자를 안전하게 지키는
|
||||
유일한 세대다. V1 `IdempotencyScope`/`tryBegin` API는 없어졌다.
|
||||
|
||||
- **범위(scope)**: 호출자가 `IdempotencyScopeDigest`를 넘긴다. principal + client key + operation
|
||||
code의 버전 있는 HMAC이고, executor가 받기 전에 계산한다. 원본 `Idempotency-Key`는 이 계층에도
|
||||
store에도 닿지 않는다.
|
||||
- **store**: `IdempotencyStorePort`. `app.capabilities.idempotency.provider`로 고른 provider 정확히
|
||||
하나가 내놓는다(`redis` → `cache-redis`, `postgresql` → `persistence-jpa`, 기본값 `disabled`).
|
||||
운영에서 메모리 저장소는 금지다.
|
||||
- **executor**: `composition:idempotency`의 `IdempotencyAutoConfiguration`이 `IdempotencySettings`로
|
||||
한 번 만든다(처리 lease 30s, 재생 TTL `APP_IDEMPOTENCY_TTL` 24h ≤72h이고 lease보다 짧지 않다, 실패
|
||||
보존 24h이고 재생 TTL보다 짧지 않다). 유스케이스나 서비스 자신의 설정에서 만들지 않는다.
|
||||
- action은 `IdempotentAction.Outcome`(`Success` / `RetryableNoEffect` / `EffectUnknown`)을
|
||||
돌려준다. 던진 예외는 효과를 모름(effect-unknown)으로 센다. 처리 중이면 409
|
||||
`IDEMPOTENT_IN_FLIGHT`, fingerprint(SHA-256)가 다르면 422 `IDEMPOTENT_REQUEST_MISMATCH`다.
|
||||
`IdempotencyUnavailableException`과 `IdempotencyRecoveryRequiredException`은 store가 결과를
|
||||
증명하지 못했다는 뜻이니 무턱대고 다시 시도하지 않는다.
|
||||
- 모든 store는 처리 lease가 끝난 실행에 `RecoveryRequired`로 답하고 그 실행을 넘겨받지 않는다.
|
||||
넘겨받는 것은 시작하지 않은 claim이나 다시 시도할 수 있는 실패뿐이다. 이 답은 레코드를 가진
|
||||
쪽에게 남긴다: 가진 쪽이 늦게 보낸 첫 `complete`/`markFailed`는 기록한다. lease가 끝난 것은
|
||||
갱신하지 않고, lease가 끝난 claim은 시작하지 않는다. 둘 다 `NOT_OWNER`가 아니라 `LEASE_EXPIRED`로
|
||||
답하고, executor는 거절된 시작을 「적용 안 됨」으로 바꾼다(소유자 결정 2026-11-04). 레코드는
|
||||
lease에 재생 TTL을 더한 만큼 산다. `IdempotencyStoreContract`가 Redis와 PostgreSQL을 실제 서버에서
|
||||
둘 모두에 맞춘다. 메모리 fake는 시간을 모델링하지 않으니 계약 중 시간이 없는 경우만 돈다.
|
||||
- 모든 전이는 그 레코드를 claim한 operation을 이름으로 댄다(`IdempotencyOwner.claimOperationId()`).
|
||||
다른 operation이면 모든 store에서 `OPERATION_CONFLICT`이고 아무것도 바꾸지 않는다. owner token을
|
||||
다른 operation으로 가져온 조회도 같다(소유자 결정 2026-11-06).
|
||||
- 이미 적용된 전이는 그것을 적용한 handle에게만 「already …」로 확인해 준다. 그 handle은 그 전이로
|
||||
옮겨 간, 한 revision 뒤의 레코드다. 다른 handle은 모두 `NOT_OWNER`다. 넘겨받기 전의 같은 시도의
|
||||
handle도, 갱신을 적용한 handle로 하는 시작도 그렇다. 놓아준 handle로 하는 시작은 store가 놓아준
|
||||
레코드를 남기느냐에 따라 `ABSENT`나 `NOT_OWNER`다(소유자 결정 2026-11-06,
|
||||
`IdempotencyStoreContract`).
|
||||
- 적용한 handle이 다른 disposition으로 `markFailed`를 다시 보내면 `OPERATION_CONFLICT`이고 기록된
|
||||
실패가 남는다. retention만 다르면 `ALREADY_MARKED_SAME_OPERATION`이고 처음 retention이 남는다 —
|
||||
retention은 완료의 재생 TTL처럼 비교하지 않는다(소유자 결정 2026-11-07).
|
||||
|
||||
예전 ArchUnit 동결 규칙 `inbound_port_implementations_do_not_declare_keyed_idempotency`와 그 fixture는
|
||||
이 브랜치가 병합될 때 지웠다.
|
||||
|
||||
## 읽기·query 경로 (feature-application-query-bypass-contract)
|
||||
|
||||
읽기 쪽에는 똑같이 유효한 모양이 둘 있다. 읽기마다 고르고, 하나를 강요하지 않는다.
|
||||
|
||||
| 모양 | 돌려주는 것 | 언제 | 어떻게 |
|
||||
|---|---|---|---|
|
||||
| **aggregate를 거쳐서**(단순 읽기의 기본) | `*Repository` 포트로 받은 도메인 aggregate | 읽기 모양 == 쓰기 aggregate **이고** aggregate가 최소 불변식 경계일 때(지연 컬렉션이 필요 없음) | `QueryUseCase` → repository 포트 → `Order` |
|
||||
| **projection (CQRS-lite)** | `*QueryPort`로 받은 애플리케이션 계층 projection DTO | 읽기 모양 ≠ 쓰기, 또는 aggregate 수화·지연 컬렉션 join을 건너뛰려 할 때 | `QueryUseCase` → `*QueryPort` → `OrderSummary`(record). query는 JPQL `SELECT new` / JdbcTemplate |
|
||||
|
||||
- **순수성 가드레일(core, 기계로 강제):** 단순 이름이 `QueryPort`로 끝나는 읽기 포트는 반드시
|
||||
애플리케이션 계층 projection DTO만 돌려준다 — 도메인 aggregate, JPA 엔티티, web 타입은 **제네릭
|
||||
타입 인자를 거쳐서도**(`List<DomainType>`) 안 된다. ArchUnit
|
||||
`QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`가 강제한다. projection 사용 자체는 강요된 기본이
|
||||
아니라 **선택**이다.
|
||||
- **엄격한 절차:** 모든 읽기는 `QueryUseCase` bean을 거친다. web → 읽기 포트로 바로 가는 얇은
|
||||
경로는 없다. 그런 경로는 필수인 `@UseCaseCapability` 적합성 검사를 건너뛴다.
|
||||
- **트랜잭션:** 읽기의 기본은 `TransactionPort.inRead`다. 트랜잭션 없는(autocommit) 읽기는
|
||||
`spring.jpa.open-in-view=false`가 확인됐고 **그리고** 읽기가 projection만 쓰고(지연 접근 없음)
|
||||
**그리고** 문장 하나일 때만 고를 수 있다. 아니면 `inRead`를 쓴다.
|
||||
- **capability:** repository를 쓰는 projection 읽기도 `repositoryAccess = READ_REPOSITORY`다.
|
||||
「projection이냐 aggregate냐」는 돌려주는 *모양* 축이고, repository 접근 *수준* 축과 따로다 — 새
|
||||
enum이 없다. outbound HTTP 읽기(repository 없음)는 `RepositoryAccess.NONE`이다.
|
||||
- 물리적으로 따로 둔 읽기 저장소를 쓰는 완전한 CQRS는 범위 밖이다. 올려서 정할 일이다.
|
||||
|
||||
## ArchUnit 가드레일(강제됨)
|
||||
|
||||
- `APPLICATION_DOES_NOT_DEPEND_ON_ADAPTERS_OR_TRANSPORT`
|
||||
- `APPLICATION_DOES_NOT_USE_SPRING_TRANSACTIONAL_ANNOTATION`
|
||||
- `APPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXT`
|
||||
- `APPLICATION_HAS_NO_DIAGNOSTIC_FRAMEWORK`
|
||||
- `INBOUND_PORT_IMPLEMENTATIONS_END_WITH_USE_CASE`
|
||||
- `INBOUND_PORT_IMPLEMENTATIONS_DECLARE_CAPABILITY`
|
||||
- `QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`(`*QueryPort` 반환 순수성)
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :application-core:test
|
||||
./gradlew :app-bootstrap:architectureTest
|
||||
```
|
||||
|
||||
위 메시징 타입은 semantic contract R1까지만 세운다. JSON Schema 검증, Kafka 발행, durable outbox
|
||||
영속, 그 밖의 메시징 R2 capability를 주장하지 않는다.
|
||||
@AGENTS.md
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
애플리케이션 유스케이스 계층. 패키지 루트: `dev.caskeleton.application`.
|
||||
|
||||
허용/금지 의존, 유스케이스 형태, 트랜잭션 모드, 명명 규칙 같은 **모듈 규칙**은
|
||||
[CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를
|
||||
[AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를
|
||||
모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 아래 설명은 별도
|
||||
추적 ID를 몰라도 읽히도록 결정의 배경과 트레이드오프를 문장으로 풀어 둔다.
|
||||
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
# composition:outbox-relay
|
||||
|
||||
- 모듈 ID `composition-outbox-relay`, Gradle 경로 `:composition:outbox-relay`. registry 정본:
|
||||
`src/config/architecture/modules.json`.
|
||||
- 책임: 애플리케이션의 outbox relay를 조립하고 돌린다. `app.outbox.*`(`OutboxSettings`, 엄격한
|
||||
바인딩)로 `PublishPendingOutboxEventsUseCase`를 손으로 만들고, `OutboxRelayScheduler`(고정 지연
|
||||
tick, 메시징 플랫폼의 admission phase보다 위에서 멈추는 `SmartLifecycle`)에서 돌리며, outbox metric
|
||||
(`OutboxMetrics`: 자기 스레드에서 도는 gauge, relay가 내는 cycle 결과 counter)을 가진다.
|
||||
- 경계: 포트만 이름으로 댄다 — `OutboxStorePort`, `OutboxMessagePublishPort`,
|
||||
`OutboxRelayFailureReportPort`, `TransactionPort`. 모듈 타입은 대지 않으니 persistence나 messaging
|
||||
줄을 지우면 relay도 빠진다. 업무 규칙, SQL, broker 타입이 없다. relay 유스케이스는 bean이 아니다
|
||||
(`@SystemInvoked`, 권한 검사 없음). 허용 edge는 registry 항목에서만 온다.
|
||||
- 기동 거절은 여기 있다. 설정과 포트가 만나는 곳이 여기뿐이기 때문이다: 최악의 경우
|
||||
(`batch-size` × 발행 포트의 `longestAttempt`)가 `in-flight-timeout`에 닿는 batch는 기동에 실패한다.
|
||||
- 시험: `./gradlew :composition:outbox-relay:check`. 종료 순서는 플랫폼 자신의 phase 상수에 맞춰
|
||||
고정한다(`OutboxRelayShutdownOrderTest`). relay → bridge → 실제 Kafka로 가는 끝에서 끝까지 경로는
|
||||
`:adapter:outbound:messaging-kafka:messagingKafkaRelayIntegrationTest`다.
|
||||
- 설계와 버린 대안: `README.md`. 운영: `docs/runbooks/outbox-publish-failed.md`,
|
||||
`docs/runbooks/outbox-dead-letter.md`.
|
||||
@@ -1,19 +1 @@
|
||||
# composition:outbox-relay
|
||||
|
||||
- 모듈 ID `composition-outbox-relay`, Gradle 경로 `:composition:outbox-relay`. registry 정본:
|
||||
`src/config/architecture/modules.json`.
|
||||
- 책임: 애플리케이션의 outbox relay를 조립하고 돌린다. `app.outbox.*`(`OutboxSettings`, 엄격한
|
||||
바인딩)로 `PublishPendingOutboxEventsUseCase`를 손으로 만들고, `OutboxRelayScheduler`(고정 지연
|
||||
tick, 메시징 플랫폼의 admission phase보다 위에서 멈추는 `SmartLifecycle`)에서 돌리며, outbox metric
|
||||
(`OutboxMetrics`: 자기 스레드에서 도는 gauge, relay가 내는 cycle 결과 counter)을 가진다.
|
||||
- 경계: 포트만 이름으로 댄다 — `OutboxStorePort`, `OutboxMessagePublishPort`,
|
||||
`OutboxRelayFailureReportPort`, `TransactionPort`. 모듈 타입은 대지 않으니 persistence나 messaging
|
||||
줄을 지우면 relay도 빠진다. 업무 규칙, SQL, broker 타입이 없다. relay 유스케이스는 bean이 아니다
|
||||
(`@SystemInvoked`, 권한 검사 없음). 허용 edge는 registry 항목에서만 온다.
|
||||
- 기동 거절은 여기 있다. 설정과 포트가 만나는 곳이 여기뿐이기 때문이다: 최악의 경우
|
||||
(`batch-size` × 발행 포트의 `longestAttempt`)가 `in-flight-timeout`에 닿는 batch는 기동에 실패한다.
|
||||
- 시험: `./gradlew :composition:outbox-relay:check`. 종료 순서는 플랫폼 자신의 phase 상수에 맞춰
|
||||
고정한다(`OutboxRelayShutdownOrderTest`). relay → bridge → 실제 Kafka로 가는 끝에서 끝까지 경로는
|
||||
`:adapter:outbound:messaging-kafka:messagingKafkaRelayIntegrationTest`다.
|
||||
- 설계와 버린 대안: `README.md`. 운영: `docs/runbooks/outbox-publish-failed.md`,
|
||||
`docs/runbooks/outbox-dead-letter.md`.
|
||||
@AGENTS.md
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
# domain-core — 순수 도메인 계층
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `domain-core`
|
||||
- Gradle 경로: `:domain-core`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :domain-core:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.domain`.
|
||||
|
||||
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT).
|
||||
|
||||
## 책임
|
||||
|
||||
- 업무 개념, 엔티티, 값 객체, enum, 도메인 이벤트, 도메인 서비스.
|
||||
- 이 참조 구현이 아직 도메인 소유 영속 계약을 두는 곳의 repository 포트.
|
||||
- 도메인 불변식과 핵심 규칙.
|
||||
|
||||
## 허용
|
||||
|
||||
- Java 표준 라이브러리.
|
||||
- 값만 담은 공용 운영 타입은 정말 필요할 때만.
|
||||
|
||||
## 금지
|
||||
|
||||
- Spring 애너테이션.
|
||||
- JPA 애너테이션.
|
||||
- Servlet·HTTP 타입.
|
||||
- 어댑터, application, bootstrap, 표현 계층 DTO 의존.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :domain-core:test
|
||||
```
|
||||
@@ -1,38 +1 @@
|
||||
# domain-core — 순수 도메인 계층
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `domain-core`
|
||||
- Gradle 경로: `:domain-core`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :domain-core:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.domain`.
|
||||
|
||||
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT).
|
||||
|
||||
## 책임
|
||||
|
||||
- 업무 개념, 엔티티, 값 객체, enum, 도메인 이벤트, 도메인 서비스.
|
||||
- 이 참조 구현이 아직 도메인 소유 영속 계약을 두는 곳의 repository 포트.
|
||||
- 도메인 불변식과 핵심 규칙.
|
||||
|
||||
## 허용
|
||||
|
||||
- Java 표준 라이브러리.
|
||||
- 값만 담은 공용 운영 타입은 정말 필요할 때만.
|
||||
|
||||
## 금지
|
||||
|
||||
- Spring 애너테이션.
|
||||
- JPA 애너테이션.
|
||||
- Servlet·HTTP 타입.
|
||||
- 어댑터, application, bootstrap, 표현 계층 DTO 의존.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :domain-core:test
|
||||
```
|
||||
@AGENTS.md
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
순수 도메인 계층 모듈. 패키지 루트: `dev.caskeleton.domain`.
|
||||
|
||||
허용/금지 의존, 책임 범위, 테스트 명령 같은 **모듈 규칙**은 [CLAUDE.md](CLAUDE.md) 가 SSOT 다.
|
||||
허용/금지 의존, 책임 범위, 테스트 명령 같은 **모듈 규칙**은 [AGENTS.md](AGENTS.md) 가 SSOT 다.
|
||||
이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다
|
||||
"왜 이렇게 했나"가 궁금할 때 본다. 플랜/스펙 추적용 ID는
|
||||
더 이상 코드 주석에 두지 않고, 그 근거를 아래에 쉬운 말로 풀어 둔다.
|
||||
|
||||
@@ -0,0 +1,88 @@
|
||||
# grpc-advanced — 고급 gRPC capability의 지역 정본
|
||||
|
||||
이 문서는 `grpc-advanced:*` family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은
|
||||
`src/config/architecture/modules.json`이 SSOT다. 루트 `AGENTS.md`와 충돌하면
|
||||
루트가 이긴다.
|
||||
|
||||
이 family는 Stable gRPC 플랫폼(`grpc:*`)이 **의도적으로 제외한** 능력들을 담는다. 별도 디렉터리와
|
||||
별도 Gradle prefix인 이유는 하나다: "Stable starter가 advanced module을 참조하면 build가 실패한다"는
|
||||
불변 조건을 registry의 `allowed_dependencies`만으로 기계 검증할 수 있게 하기 위해서다.
|
||||
|
||||
## 의존 방향
|
||||
|
||||
```text
|
||||
grpc-advanced:* → grpc:* (허용)
|
||||
grpc:* → grpc-advanced:* (금지 — registry가 거부한다)
|
||||
```
|
||||
|
||||
`grpc-spring-boot-starter`의 registry 엔트리에는 어떤 advanced id도 없다.
|
||||
`verifyCleanArchitectureDependencies`가 build time에 이 규칙을 강제한다. runtime 검사는 없다.
|
||||
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유
|
||||
|
||||
`grpc-advanced`(`GrpcDiagnosticsRedactor`)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이
|
||||
`grpc-advanced:* → grpc:*`로 닫혀 있고 `shared-contract` edge가 없는 것은 의도다. `grpc/AGENTS.md`의
|
||||
같은 절과 이유가 같다(vendored 플랫폼, messaging family와 같은 배치).
|
||||
|
||||
## Capability grade와 feature flag
|
||||
|
||||
capability마다 별도 flag를 갖는다. 하나의 "advanced" 스위치로 묶지 않는 이유는, gRPC-Web을 켜는
|
||||
결정(프록시 하나)과 xDS를 켜는 결정(control plane과 그 장애 모드 전체)이 같은 결정이 아니기
|
||||
때문이다. 하나의 스위치는 두 번째 결정을 실수로 내리게 만든다.
|
||||
|
||||
| grade | 시작 가능 | production 추가 승인 |
|
||||
| --- | --- | --- |
|
||||
| `ADVANCED_STABLE` | O | 불필요 |
|
||||
| `EXPERIMENTAL` | O | **필요** |
|
||||
| `WATCH` | X (추적만) | — |
|
||||
| `DISABLED` | X | — |
|
||||
|
||||
property key는 `app.grpc.advanced.<capability>.enabled`이고 전부 기본 off다.
|
||||
`GrpcAdvancedModuleGuard`가 세 조건(flag 미설정 / grade가 시작 불가 / production 승인 없음)을
|
||||
구분해서 거부하며, 세 경우의 조치가 다르므로 메시지도 다르다.
|
||||
|
||||
## Leaf별 담당 capability
|
||||
|
||||
| leaf | 패키지(`dev.caskeleton.grpc.advanced.*`) | capability |
|
||||
| --- | --- | --- |
|
||||
| `grpc-advanced` | `bootstrap` | capability grade, feature flag, module guard, capability별 promotion gate |
|
||||
| `grpc-advanced` | `edition` | Protobuf Edition 2024 opt-in lane, Edition 2026 watch lane |
|
||||
| `grpc-advanced` | `streaming` | client streaming(session/dedup/checkpoint), bidi(dual sequence), manual flow control |
|
||||
| `grpc-advanced` | `resilience`·`discovery`·`xds` | read-only hedging, custom name resolver SPI, custom load balancer SPI, proxyless xDS |
|
||||
| `grpc-advanced` | `diagnostics` | Channelz/CSDS 진단 |
|
||||
| `grpc-advanced-compat` | `web`·`integration`·`reactor`·`kotlin` | gRPC-Web, Spring Integration bridge, Reactor adapter, Kotlin coroutine 취소 bridge |
|
||||
|
||||
`grpc-advanced-compat`만 따로 있는 이유는 Reactor·Spring Integration이라는 실제 의존성 경계다. 나머지
|
||||
다섯 capability는 framework 의존이 없어 한 leaf에 있다(2026-09-28까지는 leaf 다섯 개). capability별
|
||||
독립은 leaf 경계가 아니라 capability flag와 promotion 레코드가 보장한다. 참조 Envoy 설정은 jar에 싣지
|
||||
않는 테스트 fixture(`grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`)다.
|
||||
|
||||
## Promotion은 capability별로 독립이다
|
||||
|
||||
승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른
|
||||
것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고
|
||||
호출처가 없어 2026-09-25 리뷰 후속 작업에서 삭제했다. 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의
|
||||
리뷰 규칙이다.
|
||||
|
||||
승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가
|
||||
더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다.
|
||||
|
||||
## 이 저장소에서 검증할 수 없는 것
|
||||
|
||||
capability별로 필요한 실제 인프라가 이 저장소에 없다.
|
||||
|
||||
- `grpc-web` → gRPC-Web 프록시
|
||||
- `servlet-compat` → Servlet 컨테이너
|
||||
- `xds` → 중지 가능한 xDS control plane
|
||||
- `kotlin` → Kotlin 툴체인
|
||||
|
||||
인프라 없이 도는 suite는 통과하면서 아무것도 증명하지 않으므로, suite가 없는 것보다 나쁘다.
|
||||
이 사실을 상수로 반환하던 gate 클래스(`GrpcKotlinCompatibilityGate`, `GrpcAdvancedInfrastructureTestkit`
|
||||
등)는 2026-09-25 삭제됐다 — 지원 여부는 이 문서와 support matrix가 적는다.
|
||||
|
||||
## 금지
|
||||
|
||||
- Stable leaf(`grpc:*`)가 이 family를 참조하는 것.
|
||||
- capability grade 없이, 또는 flag 없이 advanced 코드 경로를 실행하는 것.
|
||||
- `WATCH` capability를 스키마 소스로 사용하는 것.
|
||||
- 실제 인프라 없이 실행한 suite를 promotion evidence로 인용하는 것.
|
||||
@@ -1,88 +1 @@
|
||||
# grpc-advanced — 고급 gRPC capability의 지역 정본
|
||||
|
||||
이 문서는 `grpc-advanced:*` family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은
|
||||
`src/config/architecture/modules.json`이 SSOT다. Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면
|
||||
root가 이긴다.
|
||||
|
||||
이 family는 Stable gRPC 플랫폼(`grpc:*`)이 **의도적으로 제외한** 능력들을 담는다. 별도 디렉터리와
|
||||
별도 Gradle prefix인 이유는 하나다: "Stable starter가 advanced module을 참조하면 build가 실패한다"는
|
||||
불변 조건을 registry의 `allowed_dependencies`만으로 기계 검증할 수 있게 하기 위해서다.
|
||||
|
||||
## 의존 방향
|
||||
|
||||
```text
|
||||
grpc-advanced:* → grpc:* (허용)
|
||||
grpc:* → grpc-advanced:* (금지 — registry가 거부한다)
|
||||
```
|
||||
|
||||
`grpc-spring-boot-starter`의 registry 엔트리에는 어떤 advanced id도 없다.
|
||||
`verifyCleanArchitectureDependencies`가 build time에 이 규칙을 강제한다. runtime 검사는 없다.
|
||||
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유
|
||||
|
||||
`grpc-advanced`(`GrpcDiagnosticsRedactor`)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이
|
||||
`grpc-advanced:* → grpc:*`로 닫혀 있고 `shared-contract` edge가 없는 것은 의도다. `grpc/CLAUDE.md`의
|
||||
같은 절과 이유가 같다(vendored 플랫폼, messaging family와 같은 배치).
|
||||
|
||||
## Capability grade와 feature flag
|
||||
|
||||
capability마다 별도 flag를 갖는다. 하나의 "advanced" 스위치로 묶지 않는 이유는, gRPC-Web을 켜는
|
||||
결정(프록시 하나)과 xDS를 켜는 결정(control plane과 그 장애 모드 전체)이 같은 결정이 아니기
|
||||
때문이다. 하나의 스위치는 두 번째 결정을 실수로 내리게 만든다.
|
||||
|
||||
| grade | 시작 가능 | production 추가 승인 |
|
||||
| --- | --- | --- |
|
||||
| `ADVANCED_STABLE` | O | 불필요 |
|
||||
| `EXPERIMENTAL` | O | **필요** |
|
||||
| `WATCH` | X (추적만) | — |
|
||||
| `DISABLED` | X | — |
|
||||
|
||||
property key는 `app.grpc.advanced.<capability>.enabled`이고 전부 기본 off다.
|
||||
`GrpcAdvancedModuleGuard`가 세 조건(flag 미설정 / grade가 시작 불가 / production 승인 없음)을
|
||||
구분해서 거부하며, 세 경우의 조치가 다르므로 메시지도 다르다.
|
||||
|
||||
## Leaf별 담당 capability
|
||||
|
||||
| leaf | 패키지(`dev.caskeleton.grpc.advanced.*`) | capability |
|
||||
| --- | --- | --- |
|
||||
| `grpc-advanced` | `bootstrap` | capability grade, feature flag, module guard, capability별 promotion gate |
|
||||
| `grpc-advanced` | `edition` | Protobuf Edition 2024 opt-in lane, Edition 2026 watch lane |
|
||||
| `grpc-advanced` | `streaming` | client streaming(session/dedup/checkpoint), bidi(dual sequence), manual flow control |
|
||||
| `grpc-advanced` | `resilience`·`discovery`·`xds` | read-only hedging, custom name resolver SPI, custom load balancer SPI, proxyless xDS |
|
||||
| `grpc-advanced` | `diagnostics` | Channelz/CSDS 진단 |
|
||||
| `grpc-advanced-compat` | `web`·`integration`·`reactor`·`kotlin` | gRPC-Web, Spring Integration bridge, Reactor adapter, Kotlin coroutine 취소 bridge |
|
||||
|
||||
`grpc-advanced-compat`만 따로 있는 이유는 Reactor·Spring Integration이라는 실제 의존성 경계다. 나머지
|
||||
다섯 capability는 framework 의존이 없어 한 leaf에 있다(2026-09-28까지는 leaf 다섯 개). capability별
|
||||
독립은 leaf 경계가 아니라 capability flag와 promotion 레코드가 보장한다. 참조 Envoy 설정은 jar에 싣지
|
||||
않는 테스트 fixture(`grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`)다.
|
||||
|
||||
## Promotion은 capability별로 독립이다
|
||||
|
||||
승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른
|
||||
것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고
|
||||
호출처가 없어 2026-09-25 리뷰 후속 작업에서 삭제했다. 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의
|
||||
리뷰 규칙이다.
|
||||
|
||||
승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가
|
||||
더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다.
|
||||
|
||||
## 이 저장소에서 검증할 수 없는 것
|
||||
|
||||
capability별로 필요한 실제 인프라가 이 저장소에 없다.
|
||||
|
||||
- `grpc-web` → gRPC-Web 프록시
|
||||
- `servlet-compat` → Servlet 컨테이너
|
||||
- `xds` → 중지 가능한 xDS control plane
|
||||
- `kotlin` → Kotlin 툴체인
|
||||
|
||||
인프라 없이 도는 suite는 통과하면서 아무것도 증명하지 않으므로, suite가 없는 것보다 나쁘다.
|
||||
이 사실을 상수로 반환하던 gate 클래스(`GrpcKotlinCompatibilityGate`, `GrpcAdvancedInfrastructureTestkit`
|
||||
등)는 2026-09-25 삭제됐다 — 지원 여부는 이 문서와 support matrix가 적는다.
|
||||
|
||||
## 금지
|
||||
|
||||
- Stable leaf(`grpc:*`)가 이 family를 참조하는 것.
|
||||
- capability grade 없이, 또는 flag 없이 advanced 코드 경로를 실행하는 것.
|
||||
- `WATCH` capability를 스키마 소스로 사용하는 것.
|
||||
- 실제 인프라 없이 실행한 suite를 promotion evidence로 인용하는 것.
|
||||
@AGENTS.md
|
||||
|
||||
@@ -0,0 +1,192 @@
|
||||
# grpc — gRPC 플랫폼 family의 지역 정본
|
||||
|
||||
이 문서는 `grpc:*` family의 **지역 정본(local authority)**이다. gRPC platform은 기본 application build와 분리된
|
||||
`src/platforms/optional-build` build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급,
|
||||
Stable 범위의 경계와 application에 채택될 때 필요한 계약이다.
|
||||
|
||||
루트 `AGENTS.md`와 충돌하면 루트가 이긴다.
|
||||
|
||||
이 family는 Clean Architecture의 계층이 아니라 **벤더드 RPC 플랫폼**이다 — `messaging:*`와 같은
|
||||
자리에 있고 같은 이유로 있다. 자기 API(port)와 adapter와 조립 경계(starter)를 가지며, 애플리케이션은
|
||||
`adapter:inbound:grpc`를 통해 라이브러리로서 도달한다.
|
||||
|
||||
설계 근거와 원본 계획 대비 deviation은
|
||||
[docs/design/2026-08-30-grpc-platform-adaptation-design.md](../../../docs/design/2026-08-30-grpc-platform-adaptation-design.md)가 SSOT다.
|
||||
|
||||
## Family와 framework 규칙
|
||||
|
||||
leaf의 정확한 id는 registry에서 읽는다.
|
||||
|
||||
| Family | 역할 | 허용 framework |
|
||||
| --- | --- | --- |
|
||||
| `grpc-core-api` | 식별자, method policy, 실행 증거, 실패 모델, deadline, request context, operation ledger port | **Java stdlib만.** io.grpc / Spring / protobuf / DB 타입 금지 |
|
||||
| `grpc-contract` | `.proto` 스키마 소스(`src/main/proto`)와 protoc 생성 message. lint/breaking은 Buf(`buf.yaml`, CI job `grpc-proto-buf`) | `protobuf-java`(생성 코드 runtime)만. 규칙을 Java로 재구현하지 않는다 |
|
||||
| `grpc-runtime` | policy(validation, context, status/rich error, TLS/credential, deadline/cancellation, retry, idempotency, streaming, size/compression) · server(typed service adapter SPI, interceptor 순서, Netty profile) · client(named channel, runtime generation, typed stub factory) · discovery(Static/DNS, pick_first/round_robin, Kubernetes routing) · admin(health, reflection, drain, policy snapshot) | `io.grpc:grpc-api`, `grpc-stub`. Spring·Netty 자체 금지 — Netty profile은 설정 모델이다 |
|
||||
| `grpc-observability` | bounded metric/trace convention | `io.micrometer:micrometer-core`만 |
|
||||
| `grpc-operation-ledger-jpa` | mutation idempotency의 durable 저장 | `jakarta.persistence`, `spring-data-jpa`. **port는 core-api에 있다** |
|
||||
| `grpc-spring-boot-starter` | 조립 경계, typed properties, startup validator | Spring Boot autoconfigure. 여기서만 |
|
||||
| `grpc-testkit` | in-process / 실제 Netty / fault / performance 인증 | io.grpc netty-shaded, inprocess. production leaf가 의존하지 않는다 |
|
||||
|
||||
`grpc-core-api`가 io.grpc를 이름조차 부르지 않는다는 것이 이 family의 핵심 제약이다. 실행 증거와
|
||||
실패 모델은 "전송이 무엇을 했는가"를 기술하는 계약이고, 그 계약 안에 전송 타입이 들어가면 계약이
|
||||
전송의 일부가 된다. `GrpcStatusCode`가 io.grpc의 코드를 미러링하는 이유가 이것이고, 양방향 번역은
|
||||
`grpc-runtime`의 `GrpcStatusMapping`이 단독으로 소유한다.
|
||||
|
||||
기본 전송 한도(메시지 1 MiB, metadata 8 KiB)는 `grpc-core-api`의 `GrpcTransportLimits` 한 곳에 있고,
|
||||
server profile·named channel profile·method size profile·method policy 기본값·metadata budget이 모두
|
||||
그 상수를 쓴다. `GrpcPlatformStartupValidator`는 method의 inbound 한도가 server profile 한도보다 크면
|
||||
기동을 거부한다.
|
||||
|
||||
`.proto`의 proto 조직 이름은 `caskeleton`이다(`package caskeleton.grpc.common.v1`, 생성 Java 패키지
|
||||
`caskeleton.grpc.common.v1.generated` — 손으로 쓴 `dev.caskeleton`과 겹치지 않는다). 템플릿을 재사용할
|
||||
때 바꾸는 방법은 `AGENTS.md` 「템플릿 재사용 체크리스트」에 있다.
|
||||
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유
|
||||
|
||||
`grpc-runtime`(`GrpcRequestFingerprint`, `GrpcResumeTokenCodec`)은 SHA-256·HMAC-SHA256 계산을 자기
|
||||
안에 둔다. 템플릿의 `shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이
|
||||
family는 optional build에 있는 vendored 플랫폼이고 registry edge는 `grpc:*` 안에서만 닫힌다(위 표).
|
||||
`shared-contract` edge를 주면 플랫폼이 템플릿 계약 leaf에 묶여 따로 떼어 쓸 수 없게 된다 — messaging
|
||||
family가 같은 이유로 고른 배치(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정함)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과
|
||||
같은 규칙인지 함께 본다.
|
||||
|
||||
## 증거 등급 — testkit이 하나의 leaf인 이유
|
||||
|
||||
원본 계획은 testkit을 core/in-process/netty/fault 4개 모듈로 쪼갠다. 목적은 "in-process 결과를
|
||||
네트워크 증거로 오해하지 않게 한다"이고, 이 저장소는 그 목적을 모듈 경계가 아니라 **strict test
|
||||
lane**으로 표현한다(`ca.strict-test-lane`: lane은 아무것도 실행하지 않으면 실패하고 up-to-date
|
||||
결과를 제공하지 않는다).
|
||||
|
||||
`grpc-testkit`의 네 lane과 그 태그:
|
||||
|
||||
| lane | 태그 | 증명하는 것 |
|
||||
| --- | --- | --- |
|
||||
| `grpcInProcessContractTest` | `grpc-inprocess` | adapter, interceptor 순서, status, validation, idempotency replay |
|
||||
| `grpcNettyContractTest` | `grpc-netty` | 실제 소켓 위의 HTTP/2, TLS/mTLS, metadata·message hard limit, GOAWAY, drain |
|
||||
| `grpcFaultTest` | `grpc-fault` | 각 증거 경계에서의 연결 손실, completion unknown, partial stream |
|
||||
| `grpcPerformanceTest` | `grpc-performance` | latency percentile, saturation, drain budget |
|
||||
|
||||
lane 분리만으로는 리포트가 잘못된 run을 인용하는 것을 막지 못하므로 `GrpcEvidenceGrade`가 런타임
|
||||
체크로 이를 붙든다: `CONTRACT` 등급으로 `tls`를 주장하면 예외다.
|
||||
|
||||
**performance lane은 기본 `test`에서 제외된다**(leaf `build.gradle`). 공유 CI runner에서의 측정은
|
||||
release path의 flaky gate가 되고, flaky gate는 꺼진다.
|
||||
|
||||
## Stable 범위
|
||||
|
||||
Stable RPC 유형은 **Unary와 Server Streaming뿐**이다. Client Streaming, Bidirectional Streaming,
|
||||
hedging, xDS, custom resolver/LB, gRPC-Web, Servlet, Reactor, Kotlin은 전부 `grpc-advanced:*`이며
|
||||
capability flag 뒤에 있다. `GrpcPlatformStartupValidator`가 Stable catalog에 streaming method가
|
||||
등록되면 startup을 거부한다.
|
||||
|
||||
`grpc-spring-boot-starter`는 어떤 advanced module도 참조하지 않는다. registry의
|
||||
`allowed_dependencies`와 `verifyCleanArchitectureDependencies`가 이를 build time에 강제한다.
|
||||
|
||||
## Optional build에 있다는 것의 의미
|
||||
|
||||
`grpc:*`와 `grpc-advanced:*`는 기본 `ca-skeleton` settings에 include되지 않는다. 따라서 일반
|
||||
`:app-bootstrap:build`는 이 project들을 configure하지 않는다(목록은 registry의 `"build": "optional-grpc"`). 플랫폼 자체는
|
||||
`./gradlew -p platforms/optional-build ci`로 검증하고, application runtime에 실제 채택하려면 composition root가
|
||||
명시적으로 dependency를 가져오는 별도 변경이 필요하다.
|
||||
|
||||
런타임 포함 여부와 qualification은 별개다. in-process·Netty·fault lane이 통과해도 실제 배포 환경의
|
||||
soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위는 release gate와 support matrix가
|
||||
별도로 정의한다.
|
||||
|
||||
## application이 이 family에 도달하는 경로
|
||||
|
||||
`messaging:*`가 겪은 bridge 부재(2026-08-14 messaging 모듈 리뷰)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는
|
||||
|
||||
```text
|
||||
application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-runtime SPI
|
||||
```
|
||||
|
||||
이고 `GrpcServiceAdapter`가 그 SPI를 소유한다. inbound adapter가 outbound adapter·persistence에
|
||||
직접 닿지 않는 규칙은 app-bootstrap ArchUnit(`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`)이
|
||||
검사한다. 현재 `adapter:inbound:grpc`는 이 family에 의존하지 않는다 — registry의
|
||||
`allowed_dependencies`를 보라. 배선은 별도 결정이며, 그때 registry edge와 브리지가 함께 들어간다.
|
||||
starter가 `operation-ledger-enabled=true`일 때 멱등성 판단 bean을 조립하는 것(03-11)은 이 배선이 아니다 —
|
||||
starter는 서버를 만들지 않고, 그 bean을 서버에 붙이는 일은 채택하는 쪽의 몫이다(아래 「Durable operation
|
||||
ledger adoption」).
|
||||
|
||||
## 테스트 명령
|
||||
|
||||
focused test는 registry의 `gradle_path`에서 파생한다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew -p platforms/optional-build :grpc:<leaf>:test --console=plain
|
||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest --console=plain
|
||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcNettyContractTest --console=plain
|
||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcFaultTest --console=plain
|
||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcPerformanceTest --console=plain
|
||||
```
|
||||
|
||||
## 금지
|
||||
|
||||
- `grpc-core-api`에서 io.grpc / Spring / protobuf / JPA 타입 사용.
|
||||
- Stable leaf에서 `:grpc-advanced:*` 참조.
|
||||
- `grpc-testkit`을 production leaf가 의존하는 것.
|
||||
- in-process 결과로 transport capability를 주장하는 것 (`GrpcEvidenceGrade`가 거부한다).
|
||||
- metric tag에 raw metadata·payload·actor/tenant/object/stream/idempotency 식별자를 넣는 것
|
||||
(`GrpcMetricCardinalityPolicy`가 거부한다).
|
||||
|
||||
|
||||
### 채택할 때의 관측 게이트
|
||||
|
||||
`grpc-observability`가 구현한 metric 이름은 **아직 `docs/registries/metrics.yaml`에 등록하지
|
||||
않았다**. 이 optional family는 출하하는 런타임 capability가 아니기 때문이다. 채택하면서 저장소의
|
||||
`.seconds` / `.total` 단위 이름 규칙에 맞는 registry 항목과 그에 맞는 검증 게이트를 더하기 전에는 그
|
||||
이름을 저장소가 인증한 metric처럼 내세우지 않는다.
|
||||
|
||||
|
||||
### durable operation 원장 채택
|
||||
|
||||
`grpc-spring-boot-starter`는 JPA 원장 어댑터를 전이 의존으로 끌어오지 않는다(2026-09-18 리뷰가 찾은 문제). durable
|
||||
operation 멱등성이 필요한 배포는 `:grpc:grpc-operation-ledger-jpa`를 직접 더하고,
|
||||
`GrpcOperationLedger` bean(`new JpaGrpcOperationLedger(repository)`)을 정의하고, 그 어댑터의 Flyway
|
||||
위치 `db/migration/grpc`(V001 테이블, V002 보존 index, V003 claim attempt)를 넣고, 아래 flag를 켠다.
|
||||
원장을 채택하지 않는 배포는 Spring Data JPA classpath 비용을 내지 않는다.
|
||||
|
||||
| 키 (`app.grpc.platform.*`) | 기본값 | 하는 일 |
|
||||
| --- | --- | --- |
|
||||
| `operation-ledger-enabled` | `false` | `true`: starter가 배포의 `GrpcOperationLedger` bean 위에 `GrpcIdempotencyInterceptor`(bean `grpcIdempotencyInterceptor`)와 `GrpcOperationLedgerRetention`(bean `grpcOperationLedgerRetention`)을 조립하고, 원장 bean이 없으면 기동을 거절한다. `false`: 두 bean 모두 없고, `IDEMPOTENCY_KEY_REQUIRED`인 메서드가 있으면 기동을 거절한다 |
|
||||
| `operation-ledger-claim-ttl` | `5m` | `IN_PROGRESS` claim의 주인이 살아 있다고 믿는 시간. 지나면 같은 요청의 재시도가 claim을 넘겨받는다(`GrpcOperationLedger.reclaimStale`). 키가 필요한 모든 메서드의 deadline보다 길지 않으면 기동에서 거절한다 |
|
||||
| `operation-ledger-retention` | `24h` | 끝난(`COMMITTED`/`FAILED_TERMINAL`) 레코드를 `GrpcOperationLedgerRetention.purgeExpired`가 지울 수 있게 되기 전까지 두는 시간. `IN_PROGRESS` 행은 지우지 않는다 |
|
||||
|
||||
기본값: 5분 TTL은 원장 계약 시험과 interceptor 시험이 인증한 값이다. unary deadline보다 훨씬 길고,
|
||||
주인이 죽은 키가 클라이언트의 재시도 인내 안에 풀릴 만큼 짧다. 24시간 보존은 HTTP 멱등성 재생 TTL
|
||||
(`app.capabilities.idempotency.replay-ttl`)과 같다. 레코드를 지운 뒤 같은 키로 하는 재시도는 새
|
||||
operation이므로, 보존 시간은 호출자의 재시도 창보다 길어야 한다.
|
||||
|
||||
이 키들은 `docs/registries/env-keys.yaml`에 없다. optional 빌드는 출하하는 런타임이 아니라서
|
||||
`app.grpc.platform.*` 키는 하나도 없다. 조립 루트가 플랫폼을 채택할 때 registry에 들어간다.
|
||||
|
||||
**starter가 interceptor를 조립하는 이유(선택지 (b)), (a)가 아닌 이유.** 2026-11-01 성숙도 리뷰는
|
||||
(a)를 제안했다: flag를 지우고 원장 bean이 있는지로 판단한다. 2026-11-03에 (b)를 골랐고 ADR-GRPC-004에
|
||||
적었다: flag를 남기고 flag는 말 그대로의 뜻이다 — true이면 판정 함수를 조립하고 그 TTL은 설정에서
|
||||
온다. (a)는 거짓 약속을 없앴겠지만 채택하는 쪽마다 같은 조립과 TTL 검증을 손으로 다시 만들게
|
||||
했다. (b)는 그것을 한곳에 둔다. interceptor bean에는 일부러 `@ConditionalOnMissingBean`이 없다:
|
||||
바꿔 넣은 bean은 `operation-ledger-claim-ttl`을 소리 없이 무시하게 된다. 돌고 있는 operation의
|
||||
중복은 기다리라고 하지 않고 거절한다(`REJECT_IN_PROGRESS`). 기다렸다가 다시 묻는 선택지는 키가
|
||||
필요한 메서드가 그것을 필요로 할 때 키가 된다.
|
||||
|
||||
**서버 배선은 여전히 채택하는 쪽의 몫이고, 따로 정할 일로 남는다.** starter는 서버를 만들지
|
||||
않으므로, 판정을 조립한다고 플랫폼이 `adapter:inbound:grpc`에 배선되지는 않는다(위 "배선은
|
||||
별도 결정"을 본다). `GrpcIdempotencyInterceptor`는 판정 함수이고 `io.grpc.ServerInterceptor`가
|
||||
아니다. 채택하는 쪽은 bean을 타입으로 주입받아 자기 `IDEMPOTENCY` 단계 interceptor
|
||||
(`GrpcServerInterceptorChain.builder().stage(GrpcServerInterceptorStage.IDEMPOTENCY, ...)`)나 자기
|
||||
typed service adapter에서 부른다: 변경 전에 `decide(...)`, 변경의 트랜잭션 안에서
|
||||
`recordCommit(...)`, 끝난 실패에 `recordFailure(...)`. 두 기록 호출은 모두 `PROCEED` 판정이 실어 온
|
||||
`GrpcClaimToken`을 받는다: claim을 넘겨준 시도의 커밋은 거절되고(그 트랜잭션은 롤백된다) 그 실패는
|
||||
무시된다. 그래서 느린 주인이 claim을 가져간 시도를 덮어쓰지 못한다(ADR-GRPC-004).
|
||||
|
||||
**지우기 일정은 채택하는 쪽의 몫이다.** `GrpcOperationLedgerRetention.purgeExpired(now)`는 기한이 지난
|
||||
끝난 행을 한계 있는 batch(문장 하나에 500)로 지우고, batch가 덜 차서 돌아오면 멈춘다. starter는 이것을
|
||||
예약하지 않는다: scheduler를 가지지 않고 어느 replica가 돌려야 하는지 알 수 없으며, 예약된 bean은 모든
|
||||
배포에 task scheduler를 강요하게 된다. 채택하는 쪽이 자기 scheduler에서 부른다(예: 한 시간마다).
|
||||
지우기가 잠긴 행을 건너뛰므로 여러 replica에서 동시에 돌려도 안전하다. 한 번도 돌리지 않아도 안전하지만
|
||||
테이블이 끝없이 커진다.
|
||||
|
||||
커밋은 변경의 트랜잭션 안에서 기록해야 하고 TTL은 키가 필요한 가장 느린 메서드보다 길어야 한다. 두
|
||||
이유는 모두 ADR-GRPC-004에 있다.
|
||||
@@ -1,192 +1 @@
|
||||
# grpc — gRPC 플랫폼 family의 지역 정본
|
||||
|
||||
이 문서는 `grpc:*` family의 **지역 정본(local authority)**이다. gRPC platform은 기본 application build와 분리된
|
||||
`src/platforms/optional-build` build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급,
|
||||
Stable 범위의 경계와 application에 채택될 때 필요한 계약이다.
|
||||
|
||||
Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 root가 이긴다.
|
||||
|
||||
이 family는 Clean Architecture의 계층이 아니라 **벤더드 RPC 플랫폼**이다 — `messaging:*`와 같은
|
||||
자리에 있고 같은 이유로 있다. 자기 API(port)와 adapter와 조립 경계(starter)를 가지며, 애플리케이션은
|
||||
`adapter:inbound:grpc`를 통해 라이브러리로서 도달한다.
|
||||
|
||||
설계 근거와 원본 계획 대비 deviation은
|
||||
[docs/design/2026-08-30-grpc-platform-adaptation-design.md](../../../docs/design/2026-08-30-grpc-platform-adaptation-design.md)가 SSOT다.
|
||||
|
||||
## Family와 framework 규칙
|
||||
|
||||
leaf의 정확한 id는 registry에서 읽는다.
|
||||
|
||||
| Family | 역할 | 허용 framework |
|
||||
| --- | --- | --- |
|
||||
| `grpc-core-api` | 식별자, method policy, 실행 증거, 실패 모델, deadline, request context, operation ledger port | **Java stdlib만.** io.grpc / Spring / protobuf / DB 타입 금지 |
|
||||
| `grpc-contract` | `.proto` 스키마 소스(`src/main/proto`)와 protoc 생성 message. lint/breaking은 Buf(`buf.yaml`, CI job `grpc-proto-buf`) | `protobuf-java`(생성 코드 runtime)만. 규칙을 Java로 재구현하지 않는다 |
|
||||
| `grpc-runtime` | policy(validation, context, status/rich error, TLS/credential, deadline/cancellation, retry, idempotency, streaming, size/compression) · server(typed service adapter SPI, interceptor 순서, Netty profile) · client(named channel, runtime generation, typed stub factory) · discovery(Static/DNS, pick_first/round_robin, Kubernetes routing) · admin(health, reflection, drain, policy snapshot) | `io.grpc:grpc-api`, `grpc-stub`. Spring·Netty 자체 금지 — Netty profile은 설정 모델이다 |
|
||||
| `grpc-observability` | bounded metric/trace convention | `io.micrometer:micrometer-core`만 |
|
||||
| `grpc-operation-ledger-jpa` | mutation idempotency의 durable 저장 | `jakarta.persistence`, `spring-data-jpa`. **port는 core-api에 있다** |
|
||||
| `grpc-spring-boot-starter` | 조립 경계, typed properties, startup validator | Spring Boot autoconfigure. 여기서만 |
|
||||
| `grpc-testkit` | in-process / 실제 Netty / fault / performance 인증 | io.grpc netty-shaded, inprocess. production leaf가 의존하지 않는다 |
|
||||
|
||||
`grpc-core-api`가 io.grpc를 이름조차 부르지 않는다는 것이 이 family의 핵심 제약이다. 실행 증거와
|
||||
실패 모델은 "전송이 무엇을 했는가"를 기술하는 계약이고, 그 계약 안에 전송 타입이 들어가면 계약이
|
||||
전송의 일부가 된다. `GrpcStatusCode`가 io.grpc의 코드를 미러링하는 이유가 이것이고, 양방향 번역은
|
||||
`grpc-runtime`의 `GrpcStatusMapping`이 단독으로 소유한다.
|
||||
|
||||
기본 전송 한도(메시지 1 MiB, metadata 8 KiB)는 `grpc-core-api`의 `GrpcTransportLimits` 한 곳에 있고,
|
||||
server profile·named channel profile·method size profile·method policy 기본값·metadata budget이 모두
|
||||
그 상수를 쓴다. `GrpcPlatformStartupValidator`는 method의 inbound 한도가 server profile 한도보다 크면
|
||||
기동을 거부한다.
|
||||
|
||||
`.proto`의 proto 조직 이름은 `caskeleton`이다(`package caskeleton.grpc.common.v1`, 생성 Java 패키지
|
||||
`caskeleton.grpc.common.v1.generated` — 손으로 쓴 `dev.caskeleton`과 겹치지 않는다). 템플릿을 재사용할
|
||||
때 바꾸는 방법은 `AGENTS.md` 「템플릿 재사용 체크리스트」에 있다.
|
||||
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유
|
||||
|
||||
`grpc-runtime`(`GrpcRequestFingerprint`, `GrpcResumeTokenCodec`)은 SHA-256·HMAC-SHA256 계산을 자기
|
||||
안에 둔다. 템플릿의 `shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이
|
||||
family는 optional build에 있는 vendored 플랫폼이고 registry edge는 `grpc:*` 안에서만 닫힌다(위 표).
|
||||
`shared-contract` edge를 주면 플랫폼이 템플릿 계약 leaf에 묶여 따로 떼어 쓸 수 없게 된다 — messaging
|
||||
family가 같은 이유로 고른 배치(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정함)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과
|
||||
같은 규칙인지 함께 본다.
|
||||
|
||||
## 증거 등급 — testkit이 하나의 leaf인 이유
|
||||
|
||||
원본 계획은 testkit을 core/in-process/netty/fault 4개 모듈로 쪼갠다. 목적은 "in-process 결과를
|
||||
네트워크 증거로 오해하지 않게 한다"이고, 이 저장소는 그 목적을 모듈 경계가 아니라 **strict test
|
||||
lane**으로 표현한다(`ca.strict-test-lane`: lane은 아무것도 실행하지 않으면 실패하고 up-to-date
|
||||
결과를 제공하지 않는다).
|
||||
|
||||
`grpc-testkit`의 네 lane과 그 태그:
|
||||
|
||||
| lane | 태그 | 증명하는 것 |
|
||||
| --- | --- | --- |
|
||||
| `grpcInProcessContractTest` | `grpc-inprocess` | adapter, interceptor 순서, status, validation, idempotency replay |
|
||||
| `grpcNettyContractTest` | `grpc-netty` | 실제 소켓 위의 HTTP/2, TLS/mTLS, metadata·message hard limit, GOAWAY, drain |
|
||||
| `grpcFaultTest` | `grpc-fault` | 각 증거 경계에서의 연결 손실, completion unknown, partial stream |
|
||||
| `grpcPerformanceTest` | `grpc-performance` | latency percentile, saturation, drain budget |
|
||||
|
||||
lane 분리만으로는 리포트가 잘못된 run을 인용하는 것을 막지 못하므로 `GrpcEvidenceGrade`가 런타임
|
||||
체크로 이를 붙든다: `CONTRACT` 등급으로 `tls`를 주장하면 예외다.
|
||||
|
||||
**performance lane은 기본 `test`에서 제외된다**(leaf `build.gradle`). 공유 CI runner에서의 측정은
|
||||
release path의 flaky gate가 되고, flaky gate는 꺼진다.
|
||||
|
||||
## Stable 범위
|
||||
|
||||
Stable RPC 유형은 **Unary와 Server Streaming뿐**이다. Client Streaming, Bidirectional Streaming,
|
||||
hedging, xDS, custom resolver/LB, gRPC-Web, Servlet, Reactor, Kotlin은 전부 `grpc-advanced:*`이며
|
||||
capability flag 뒤에 있다. `GrpcPlatformStartupValidator`가 Stable catalog에 streaming method가
|
||||
등록되면 startup을 거부한다.
|
||||
|
||||
`grpc-spring-boot-starter`는 어떤 advanced module도 참조하지 않는다. registry의
|
||||
`allowed_dependencies`와 `verifyCleanArchitectureDependencies`가 이를 build time에 강제한다.
|
||||
|
||||
## Optional build에 있다는 것의 의미
|
||||
|
||||
`grpc:*`와 `grpc-advanced:*`는 기본 `ca-skeleton` settings에 include되지 않는다. 따라서 일반
|
||||
`:app-bootstrap:build`는 이 project들을 configure하지 않는다(목록은 registry의 `"build": "optional-grpc"`). 플랫폼 자체는
|
||||
`./gradlew -p platforms/optional-build ci`로 검증하고, application runtime에 실제 채택하려면 composition root가
|
||||
명시적으로 dependency를 가져오는 별도 변경이 필요하다.
|
||||
|
||||
런타임 포함 여부와 qualification은 별개다. in-process·Netty·fault lane이 통과해도 실제 배포 환경의
|
||||
soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위는 release gate와 support matrix가
|
||||
별도로 정의한다.
|
||||
|
||||
## application이 이 family에 도달하는 경로
|
||||
|
||||
`messaging:*`가 겪은 bridge 부재(2026-08-14 messaging 모듈 리뷰)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는
|
||||
|
||||
```text
|
||||
application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-runtime SPI
|
||||
```
|
||||
|
||||
이고 `GrpcServiceAdapter`가 그 SPI를 소유한다. inbound adapter가 outbound adapter·persistence에
|
||||
직접 닿지 않는 규칙은 app-bootstrap ArchUnit(`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`)이
|
||||
검사한다. 현재 `adapter:inbound:grpc`는 이 family에 의존하지 않는다 — registry의
|
||||
`allowed_dependencies`를 보라. 배선은 별도 결정이며, 그때 registry edge와 브리지가 함께 들어간다.
|
||||
starter가 `operation-ledger-enabled=true`일 때 멱등성 판단 bean을 조립하는 것(03-11)은 이 배선이 아니다 —
|
||||
starter는 서버를 만들지 않고, 그 bean을 서버에 붙이는 일은 채택하는 쪽의 몫이다(아래 「Durable operation
|
||||
ledger adoption」).
|
||||
|
||||
## 테스트 명령
|
||||
|
||||
focused test는 registry의 `gradle_path`에서 파생한다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew -p platforms/optional-build :grpc:<leaf>:test --console=plain
|
||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest --console=plain
|
||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcNettyContractTest --console=plain
|
||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcFaultTest --console=plain
|
||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcPerformanceTest --console=plain
|
||||
```
|
||||
|
||||
## 금지
|
||||
|
||||
- `grpc-core-api`에서 io.grpc / Spring / protobuf / JPA 타입 사용.
|
||||
- Stable leaf에서 `:grpc-advanced:*` 참조.
|
||||
- `grpc-testkit`을 production leaf가 의존하는 것.
|
||||
- in-process 결과로 transport capability를 주장하는 것 (`GrpcEvidenceGrade`가 거부한다).
|
||||
- metric tag에 raw metadata·payload·actor/tenant/object/stream/idempotency 식별자를 넣는 것
|
||||
(`GrpcMetricCardinalityPolicy`가 거부한다).
|
||||
|
||||
|
||||
### 채택할 때의 관측 게이트
|
||||
|
||||
`grpc-observability`가 구현한 metric 이름은 **아직 `docs/registries/metrics.yaml`에 등록하지
|
||||
않았다**. 이 optional family는 출하하는 런타임 capability가 아니기 때문이다. 채택하면서 저장소의
|
||||
`.seconds` / `.total` 단위 이름 규칙에 맞는 registry 항목과 그에 맞는 검증 게이트를 더하기 전에는 그
|
||||
이름을 저장소가 인증한 metric처럼 내세우지 않는다.
|
||||
|
||||
|
||||
### durable operation 원장 채택
|
||||
|
||||
`grpc-spring-boot-starter`는 JPA 원장 어댑터를 전이 의존으로 끌어오지 않는다(2026-09-18 리뷰가 찾은 문제). durable
|
||||
operation 멱등성이 필요한 배포는 `:grpc:grpc-operation-ledger-jpa`를 직접 더하고,
|
||||
`GrpcOperationLedger` bean(`new JpaGrpcOperationLedger(repository)`)을 정의하고, 그 어댑터의 Flyway
|
||||
위치 `db/migration/grpc`(V001 테이블, V002 보존 index, V003 claim attempt)를 넣고, 아래 flag를 켠다.
|
||||
원장을 채택하지 않는 배포는 Spring Data JPA classpath 비용을 내지 않는다.
|
||||
|
||||
| 키 (`app.grpc.platform.*`) | 기본값 | 하는 일 |
|
||||
| --- | --- | --- |
|
||||
| `operation-ledger-enabled` | `false` | `true`: starter가 배포의 `GrpcOperationLedger` bean 위에 `GrpcIdempotencyInterceptor`(bean `grpcIdempotencyInterceptor`)와 `GrpcOperationLedgerRetention`(bean `grpcOperationLedgerRetention`)을 조립하고, 원장 bean이 없으면 기동을 거절한다. `false`: 두 bean 모두 없고, `IDEMPOTENCY_KEY_REQUIRED`인 메서드가 있으면 기동을 거절한다 |
|
||||
| `operation-ledger-claim-ttl` | `5m` | `IN_PROGRESS` claim의 주인이 살아 있다고 믿는 시간. 지나면 같은 요청의 재시도가 claim을 넘겨받는다(`GrpcOperationLedger.reclaimStale`). 키가 필요한 모든 메서드의 deadline보다 길지 않으면 기동에서 거절한다 |
|
||||
| `operation-ledger-retention` | `24h` | 끝난(`COMMITTED`/`FAILED_TERMINAL`) 레코드를 `GrpcOperationLedgerRetention.purgeExpired`가 지울 수 있게 되기 전까지 두는 시간. `IN_PROGRESS` 행은 지우지 않는다 |
|
||||
|
||||
기본값: 5분 TTL은 원장 계약 시험과 interceptor 시험이 인증한 값이다. unary deadline보다 훨씬 길고,
|
||||
주인이 죽은 키가 클라이언트의 재시도 인내 안에 풀릴 만큼 짧다. 24시간 보존은 HTTP 멱등성 재생 TTL
|
||||
(`app.capabilities.idempotency.replay-ttl`)과 같다. 레코드를 지운 뒤 같은 키로 하는 재시도는 새
|
||||
operation이므로, 보존 시간은 호출자의 재시도 창보다 길어야 한다.
|
||||
|
||||
이 키들은 `docs/registries/env-keys.yaml`에 없다. optional 빌드는 출하하는 런타임이 아니라서
|
||||
`app.grpc.platform.*` 키는 하나도 없다. 조립 루트가 플랫폼을 채택할 때 registry에 들어간다.
|
||||
|
||||
**starter가 interceptor를 조립하는 이유(선택지 (b)), (a)가 아닌 이유.** 2026-11-01 성숙도 리뷰는
|
||||
(a)를 제안했다: flag를 지우고 원장 bean이 있는지로 판단한다. 2026-11-03에 (b)를 골랐고 ADR-GRPC-004에
|
||||
적었다: flag를 남기고 flag는 말 그대로의 뜻이다 — true이면 판정 함수를 조립하고 그 TTL은 설정에서
|
||||
온다. (a)는 거짓 약속을 없앴겠지만 채택하는 쪽마다 같은 조립과 TTL 검증을 손으로 다시 만들게
|
||||
했다. (b)는 그것을 한곳에 둔다. interceptor bean에는 일부러 `@ConditionalOnMissingBean`이 없다:
|
||||
바꿔 넣은 bean은 `operation-ledger-claim-ttl`을 소리 없이 무시하게 된다. 돌고 있는 operation의
|
||||
중복은 기다리라고 하지 않고 거절한다(`REJECT_IN_PROGRESS`). 기다렸다가 다시 묻는 선택지는 키가
|
||||
필요한 메서드가 그것을 필요로 할 때 키가 된다.
|
||||
|
||||
**서버 배선은 여전히 채택하는 쪽의 몫이고, 따로 정할 일로 남는다.** starter는 서버를 만들지
|
||||
않으므로, 판정을 조립한다고 플랫폼이 `adapter:inbound:grpc`에 배선되지는 않는다(위 "배선은
|
||||
별도 결정"을 본다). `GrpcIdempotencyInterceptor`는 판정 함수이고 `io.grpc.ServerInterceptor`가
|
||||
아니다. 채택하는 쪽은 bean을 타입으로 주입받아 자기 `IDEMPOTENCY` 단계 interceptor
|
||||
(`GrpcServerInterceptorChain.builder().stage(GrpcServerInterceptorStage.IDEMPOTENCY, ...)`)나 자기
|
||||
typed service adapter에서 부른다: 변경 전에 `decide(...)`, 변경의 트랜잭션 안에서
|
||||
`recordCommit(...)`, 끝난 실패에 `recordFailure(...)`. 두 기록 호출은 모두 `PROCEED` 판정이 실어 온
|
||||
`GrpcClaimToken`을 받는다: claim을 넘겨준 시도의 커밋은 거절되고(그 트랜잭션은 롤백된다) 그 실패는
|
||||
무시된다. 그래서 느린 주인이 claim을 가져간 시도를 덮어쓰지 못한다(ADR-GRPC-004).
|
||||
|
||||
**지우기 일정은 채택하는 쪽의 몫이다.** `GrpcOperationLedgerRetention.purgeExpired(now)`는 기한이 지난
|
||||
끝난 행을 한계 있는 batch(문장 하나에 500)로 지우고, batch가 덜 차서 돌아오면 멈춘다. starter는 이것을
|
||||
예약하지 않는다: scheduler를 가지지 않고 어느 replica가 돌려야 하는지 알 수 없으며, 예약된 bean은 모든
|
||||
배포에 task scheduler를 강요하게 된다. 채택하는 쪽이 자기 scheduler에서 부른다(예: 한 시간마다).
|
||||
지우기가 잠긴 행을 건너뛰므로 여러 replica에서 동시에 돌려도 안전하다. 한 번도 돌리지 않아도 안전하지만
|
||||
테이블이 끝없이 커진다.
|
||||
|
||||
커밋은 변경의 트랜잭션 안에서 기록해야 하고 TTL은 키가 필요한 가장 느린 메서드보다 길어야 한다. 두
|
||||
이유는 모두 ADR-GRPC-004에 있다.
|
||||
@AGENTS.md
|
||||
|
||||
@@ -0,0 +1,176 @@
|
||||
# messaging — 메시징 플랫폼 family의 지역 정본
|
||||
|
||||
이 문서는 messaging family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은
|
||||
`src/config/architecture/modules.json`이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는
|
||||
것은 registry가 표현할 수 없는 것들이다: family별 framework 규칙, public surface 정책, Stable 승격에
|
||||
필요한 증거, runtime membership이 비어 있다는 사실의 의미.
|
||||
|
||||
루트 `AGENTS.md`와 충돌하면 루트가 이긴다.
|
||||
|
||||
## Family와 framework 규칙
|
||||
|
||||
leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이름의 접두사**가 아니라 아래 표의
|
||||
역할로 정해진다.
|
||||
|
||||
| Family | 역할 | 허용 framework |
|
||||
| --- | --- | --- |
|
||||
| `*-api` (`core-api` — `api`·`schema` 패키지, `policy`, `reliability-api`, `transport-spi`) | 값 타입, 포트, 정책 계약 | Java stdlib만. Spring/broker SDK/logging framework 금지 |
|
||||
| `schema-*` (json/avro/protobuf), `cloudevents` | 인코딩 구현 | 해당 codec 라이브러리만. Spring 금지 |
|
||||
| `runtime-core`, `security`, `observability`, `admin`(계약 `admin` + 실행 `admin.runtime`), `reliability` | framework-free 실행 로직 | Micrometer는 `observability`에서만. 나머지는 stdlib |
|
||||
| `kafka` | broker adapter | 해당 broker client. Spring은 client가 곧 Spring인 경우만 |
|
||||
| `reliability-jdbc-postgresql` | 관계형 신뢰성 adapter (outbox·inbox repository, admin journal) | Spring JDBC / Spring TX. **JPA 아님** — 이름이 곧 계약이다 |
|
||||
| `spring-boot-starter`, `spring-boot-starter-kafka` | 조립 경계 | Spring Boot autoconfigure. 여기서만 |
|
||||
| `testkit` | 테스트 지원 | Testcontainers, JUnit. production leaf가 의존하지 않는다 |
|
||||
|
||||
신뢰성 기능은 세 leaf다. `messaging-reliability-api`가 vendor 중립 port(`OutboxRepository`,
|
||||
`InboxRepository`)를, `messaging-reliability`가 그 port만 보는 relay·consumer 로직(stdlib)을,
|
||||
`messaging-reliability-jdbc-postgresql`이 port의 관계형 구현과 migration(`V1001..V1005`, `V1101`)을
|
||||
갖는다. 예전에는 `outbox-jdbc-postgresql` 하나가 relay 로직과 PG repository와 admin journal을 함께
|
||||
가졌고 inbox도 같은 모양이었다(2026-09-25 리뷰 후속 작업에서 나눴다). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring
|
||||
JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL
|
||||
전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다.
|
||||
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유
|
||||
|
||||
`messaging-admin`(`HmacApprovalVerifier`, `PlanDigest`)과 `messaging-claim-check`
|
||||
(`ClaimCheckIntegrityGuard`)는 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 템플릿의
|
||||
`shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 family는 이 애플리케이션의
|
||||
계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치), `messaging:*` leaf는
|
||||
`domain-core`·`application-core`·`shared-contract` 어느 타입에도 의존하지 않는다. 헬퍼 하나 때문에
|
||||
registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는
|
||||
`shared-contract`의 정본과 같은 규칙인지 함께 본다.
|
||||
|
||||
### 인증·인가 거부의 발행 재시도 여부 (Publish retryability of authentication and authorization)
|
||||
|
||||
이 제품 안에는 같은 category에 대한 재시도 규칙이 둘 있다. 의도다.
|
||||
|
||||
- category 기본값: `FailureDescriptor.defaultRetryable(AUTHENTICATION | AUTHORIZATION) = false`. 소비 쪽
|
||||
재시도 엔진(`DefaultRetryDecisionEngine`)은 policy가 category를 따로 정하지 않으면 이 기본값과
|
||||
descriptor의 `retryable`을 둘 다 요구한다. 그래서 인가받지 못한 메시지의 재전달은 지금도 재시도하지 않는다.
|
||||
- publish 거부의 `retryable`: `KafkaPublishFailureClassifier`는 인증·인가 거부에 `retryable = true`를 붙인다.
|
||||
broker가 레코드를 저장하지 않았고, credential 교체나 application보다 늦게 배포된 ACL은 몇 분 동안 모든
|
||||
publish를 거부한 뒤 멈추기 때문이다. `retryable`을 믿는 publisher가 그 몇 분 동안의 레코드를 영구 보류하지
|
||||
않게 하려는 것이다.
|
||||
|
||||
다시 시도하면 될 거부를 relay가 즉시 DEAD로 보내던 결함의 수정(2026-11-01 성숙도 리뷰 뒤)이 이 제품에서 바꾼 것(모두
|
||||
publish 경로, 소비 경로 동작은 그대로):
|
||||
|
||||
- `KafkaPublishFailureClassifier`: 인증·인가 거부를 `retryable = true`로.
|
||||
- `DefaultMessagePublisher`: runtime이 없을 때의 거부(`PUBLISH_RUNTIME_UNAVAILABLE`)를 `retryable = true`로.
|
||||
- `KafkaMessagingTransport`: 닫힌 transport의 거부(`KAFKA_TRANSPORT_CLOSED`)를 `retryable = true`로.
|
||||
- `MessagingShutdownLifecycle.PHASE`: platform 밖 relay의 순서 테스트가 참조하도록 public.
|
||||
|
||||
버린 대안: vendored 제품은 그대로 두고 application bridge(ACL)가 category를 보고 "인증·인가면 재시도"로
|
||||
번역하는 것. 버린 이유: `retryable`은 이 제품이 "같은 레코드를 나중에 다시 보내면 받아질 수 있나"를 말하는
|
||||
자리다. bridge가 category로 그 판단을 다시 하면 같은 사실을 제품과 bridge가 따로 정하고, 이 제품의
|
||||
`PublishResult`를 읽는 다른 호출자는 bridge와 다른 답을 본다. 대신 이 제품 주석은 소비자 이름(application
|
||||
relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(2026-11-03).
|
||||
|
||||
## Public surface 정책
|
||||
|
||||
- **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이
|
||||
숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다.
|
||||
(`kafka-clients`, `cloudevents-api`, `micrometer-core`, `avro`,
|
||||
`protobuf-java`가 이 규칙으로 `api`다.)
|
||||
- 반대로 **노출하지 않는 것은 `implementation`으로 낮춘다.** starter가 노출하지 않는 하위 모듈을
|
||||
`implementation`으로 내린 것이, JSON codec이 `ObjectMapper`를 private으로만 쓰고 Jackson을
|
||||
`implementation`으로 둔 것이 그 예다.
|
||||
- 이 규칙은 문서가 아니라 `MessagingPublicSurfaceContractTest`가 붙들고 있다. leaf의 production
|
||||
source에서 public/protected 시그니처에 등장하는 vendor 라이브러리를 뽑아 그 leaf의
|
||||
`build.gradle`이 `api`로 선언했는지 대조하고, starter의 `api` closure에 broker client 두 개가
|
||||
들어오지 않는 것도 함께 본다. Spring Framework/Boot는 대상이 아니다 — 조립 경계 안에서만
|
||||
등장하고 adopter가 이름 부를 일이 없다.
|
||||
- 새 public 타입은 그 모듈의 계약이다. 삭제·시그니처 변경은 breaking change로 취급한다.
|
||||
|
||||
## Application runtime에 포함되는 기준
|
||||
|
||||
기본 조립에는 Messaging family가 없다. 서비스가 `app-bootstrap/build.gradle`에
|
||||
`runtimeOnly project(':adapter:outbound:messaging-kafka')` 한 줄을 넣으면 그 모듈이 bridge와
|
||||
`messaging-spring-boot-starter`(Kafka transport 포함)의 transitive project graph를 runtime에 싣는다. 이
|
||||
사실의 SSOT는 Gradle `runtimeClasspath`이며 registry에 동일한 membership 목록을 복제하지 않는다.
|
||||
모듈이 있으면 켜지고(`app.messaging.enabled` 기본 `true`), `APP_MESSAGING_ENABLED=false`로만 끈다.
|
||||
|
||||
일부 codec(cloudevents 등)·claim-check·testkit처럼 starter graph에 들어오지 않는 leaf는 build-only다.
|
||||
RabbitMQ·Pulsar·NATS·Kafka Share·Spring Cloud Stream bridge leaf와 Debezium outbox 매핑은
|
||||
2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표).
|
||||
새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy,
|
||||
qualification/support 상태를 함께 변경한다.
|
||||
|
||||
## application이 이 family에 도달하는 경로 (cutover 완료)
|
||||
|
||||
리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한
|
||||
`application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다.
|
||||
|
||||
- application-owned port: `IntegrationEventPublishPort`
|
||||
- bridge: `adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter`
|
||||
- platform boundary: `EncodedMessagePublisher`
|
||||
- central implementation: `DefaultMessagePublisher`
|
||||
|
||||
bridge는 exact canonical envelope bytes를 다시 serialize하지 않고, destination/access/admission/runtime
|
||||
lease/transport/outcome normalization/observation은 platform 중앙 publish path를 그대로 탄다. bridge
|
||||
package는 `messaging-core-api`만 보며 concrete runtime/transport/Kafka 타입을
|
||||
직접 보지 않는다.
|
||||
|
||||
**application bridge cutover는 2026-09-28에 끝났다(2026-09-25 소유자 결정).** application의 outbox append는 canonical
|
||||
`OutboxAppendPort` 하나이고, relay는 claim한 row의 validated event를 이 bridge로만 보낸다. legacy
|
||||
`OutboxEvent`·`LegacyOutboxAppendPort`와 `MessageBroker → KafkaSender` R0 경로(TLS/SASL을 적용하지
|
||||
않던 두 번째 producer)는 삭제했다. 남은 Kafka producer는 platform의 것 하나이고, broker security
|
||||
profile(`KafkaSecurityConfigurer`)을 적용한다.
|
||||
|
||||
canonical bridge의 producer identity는 `app.messaging.producer-id`로 명시한다. 값이 없으면 bridge bean을
|
||||
만들지 않으며 `spring.application.name`/host/pod 이름에서 identity를 발명하지 않는다. bridge가 없으면
|
||||
relay가 발행할 곳이 없으므로 messaging 모듈이 켜진 상태에서는 기동이 거부된다.
|
||||
|
||||
`IntegrationEventEncoderPort`는 템플릿이 제공한다: `adapter:outbound:support`의
|
||||
`JsonIntegrationEventEncoder`가 envelope v1(`shared-contract`의 `contracts/messaging/envelope/v1.schema.json`)
|
||||
안에 payload record를 결정적 JSON으로 싣는다. 계약 catalog는 애플리케이션이 bean으로 등록한
|
||||
`IntegrationEventContractContribution`뿐이고, 선언한 payload schema hash가 classpath의 schema 파일과
|
||||
다르면 기동이 실패한다. payload를 JSON Schema로 매번 검증하려는 서비스는 자기 encoder bean을 두면 된다.
|
||||
|
||||
## Stable 승격에 필요한 증거
|
||||
|
||||
adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/support-matrix.md`가 현재
|
||||
상태를 기록한다):
|
||||
|
||||
1. 실제 broker container를 쓰는 fault 시나리오 lane이 존재하고, 그 lane이
|
||||
`BrokerCertificationEvidence`를 산출한다.
|
||||
2. `NetworkFaultScenario` 전 항목에 대해 evidence가 있거나, 없는 항목이 `knownGaps`로 명시된다.
|
||||
3. capability 선언이 코드에서 파생된다 — `MessagingCapabilities`에 손으로 `true`를 쓰는 것은
|
||||
증거가 아니다.
|
||||
4. publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은
|
||||
Experimental에서도 금지다.
|
||||
5. unknown failure의 기본값이 `AMBIGUOUS`다. `REJECTED`는 전송이 시작되지 않았다는 typed 증거가
|
||||
있을 때만.
|
||||
|
||||
Stable 문구는 evidence manifest가 존재할 때만 문서에 쓴다.
|
||||
|
||||
증거를 만드는 것은 인증 레인이고, manifest는 그 실행의 출력이다:
|
||||
|
||||
```bash
|
||||
./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence --console=plain
|
||||
```
|
||||
|
||||
레인(`messagingCertificationTest`)은 Toxiproxy를 broker 앞에 두고 장애를 주입하며,
|
||||
통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을
|
||||
`messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl`에 쓴다.
|
||||
게이트는 커밋된 manifest와 이번 실행의 출력을 대조한다 — **manifest를 손으로 고치면 실패하고,
|
||||
레인을 돌리면 manifest가 다시 쓰인다.** 이 레인만은 Docker 가드를 달지 않는다(없으면 실패한다).
|
||||
skip하는 인증 레인은 아무도 켜지 않은 브로커에 대해 성공을 보고하기 때문이며, 그래서 `test`에서는
|
||||
`messaging-certification` 태그로 제외된다.
|
||||
|
||||
## Focused test
|
||||
|
||||
leaf의 `gradle_path`를 registry에서 읽어 파생한다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew <gradle-path>:test --console=plain
|
||||
```
|
||||
|
||||
Family 전체 검증:
|
||||
|
||||
```bash
|
||||
./gradlew verifyCleanArchitectureDependencies --console=plain
|
||||
./gradlew architectureCheck --console=plain
|
||||
./gradlew verifyDependencyLocks --console=plain
|
||||
```
|
||||
@@ -1,176 +1 @@
|
||||
# messaging — 메시징 플랫폼 family의 지역 정본
|
||||
|
||||
이 문서는 messaging family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은
|
||||
`src/config/architecture/modules.json`이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는
|
||||
것은 registry가 표현할 수 없는 것들이다: family별 framework 규칙, public surface 정책, Stable 승격에
|
||||
필요한 증거, runtime membership이 비어 있다는 사실의 의미.
|
||||
|
||||
Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 root가 이긴다.
|
||||
|
||||
## Family와 framework 규칙
|
||||
|
||||
leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이름의 접두사**가 아니라 아래 표의
|
||||
역할로 정해진다.
|
||||
|
||||
| Family | 역할 | 허용 framework |
|
||||
| --- | --- | --- |
|
||||
| `*-api` (`core-api` — `api`·`schema` 패키지, `policy`, `reliability-api`, `transport-spi`) | 값 타입, 포트, 정책 계약 | Java stdlib만. Spring/broker SDK/logging framework 금지 |
|
||||
| `schema-*` (json/avro/protobuf), `cloudevents` | 인코딩 구현 | 해당 codec 라이브러리만. Spring 금지 |
|
||||
| `runtime-core`, `security`, `observability`, `admin`(계약 `admin` + 실행 `admin.runtime`), `reliability` | framework-free 실행 로직 | Micrometer는 `observability`에서만. 나머지는 stdlib |
|
||||
| `kafka` | broker adapter | 해당 broker client. Spring은 client가 곧 Spring인 경우만 |
|
||||
| `reliability-jdbc-postgresql` | 관계형 신뢰성 adapter (outbox·inbox repository, admin journal) | Spring JDBC / Spring TX. **JPA 아님** — 이름이 곧 계약이다 |
|
||||
| `spring-boot-starter`, `spring-boot-starter-kafka` | 조립 경계 | Spring Boot autoconfigure. 여기서만 |
|
||||
| `testkit` | 테스트 지원 | Testcontainers, JUnit. production leaf가 의존하지 않는다 |
|
||||
|
||||
신뢰성 기능은 세 leaf다. `messaging-reliability-api`가 vendor 중립 port(`OutboxRepository`,
|
||||
`InboxRepository`)를, `messaging-reliability`가 그 port만 보는 relay·consumer 로직(stdlib)을,
|
||||
`messaging-reliability-jdbc-postgresql`이 port의 관계형 구현과 migration(`V1001..V1005`, `V1101`)을
|
||||
갖는다. 예전에는 `outbox-jdbc-postgresql` 하나가 relay 로직과 PG repository와 admin journal을 함께
|
||||
가졌고 inbox도 같은 모양이었다(2026-09-25 리뷰 후속 작업에서 나눴다). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring
|
||||
JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL
|
||||
전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다.
|
||||
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유
|
||||
|
||||
`messaging-admin`(`HmacApprovalVerifier`, `PlanDigest`)과 `messaging-claim-check`
|
||||
(`ClaimCheckIntegrityGuard`)는 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 템플릿의
|
||||
`shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 family는 이 애플리케이션의
|
||||
계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치), `messaging:*` leaf는
|
||||
`domain-core`·`application-core`·`shared-contract` 어느 타입에도 의존하지 않는다. 헬퍼 하나 때문에
|
||||
registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는
|
||||
`shared-contract`의 정본과 같은 규칙인지 함께 본다.
|
||||
|
||||
### 인증·인가 거부의 발행 재시도 여부 (Publish retryability of authentication and authorization)
|
||||
|
||||
이 제품 안에는 같은 category에 대한 재시도 규칙이 둘 있다. 의도다.
|
||||
|
||||
- category 기본값: `FailureDescriptor.defaultRetryable(AUTHENTICATION | AUTHORIZATION) = false`. 소비 쪽
|
||||
재시도 엔진(`DefaultRetryDecisionEngine`)은 policy가 category를 따로 정하지 않으면 이 기본값과
|
||||
descriptor의 `retryable`을 둘 다 요구한다. 그래서 인가받지 못한 메시지의 재전달은 지금도 재시도하지 않는다.
|
||||
- publish 거부의 `retryable`: `KafkaPublishFailureClassifier`는 인증·인가 거부에 `retryable = true`를 붙인다.
|
||||
broker가 레코드를 저장하지 않았고, credential 교체나 application보다 늦게 배포된 ACL은 몇 분 동안 모든
|
||||
publish를 거부한 뒤 멈추기 때문이다. `retryable`을 믿는 publisher가 그 몇 분 동안의 레코드를 영구 보류하지
|
||||
않게 하려는 것이다.
|
||||
|
||||
다시 시도하면 될 거부를 relay가 즉시 DEAD로 보내던 결함의 수정(2026-11-01 성숙도 리뷰 뒤)이 이 제품에서 바꾼 것(모두
|
||||
publish 경로, 소비 경로 동작은 그대로):
|
||||
|
||||
- `KafkaPublishFailureClassifier`: 인증·인가 거부를 `retryable = true`로.
|
||||
- `DefaultMessagePublisher`: runtime이 없을 때의 거부(`PUBLISH_RUNTIME_UNAVAILABLE`)를 `retryable = true`로.
|
||||
- `KafkaMessagingTransport`: 닫힌 transport의 거부(`KAFKA_TRANSPORT_CLOSED`)를 `retryable = true`로.
|
||||
- `MessagingShutdownLifecycle.PHASE`: platform 밖 relay의 순서 테스트가 참조하도록 public.
|
||||
|
||||
버린 대안: vendored 제품은 그대로 두고 application bridge(ACL)가 category를 보고 "인증·인가면 재시도"로
|
||||
번역하는 것. 버린 이유: `retryable`은 이 제품이 "같은 레코드를 나중에 다시 보내면 받아질 수 있나"를 말하는
|
||||
자리다. bridge가 category로 그 판단을 다시 하면 같은 사실을 제품과 bridge가 따로 정하고, 이 제품의
|
||||
`PublishResult`를 읽는 다른 호출자는 bridge와 다른 답을 본다. 대신 이 제품 주석은 소비자 이름(application
|
||||
relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(2026-11-03).
|
||||
|
||||
## Public surface 정책
|
||||
|
||||
- **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이
|
||||
숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다.
|
||||
(`kafka-clients`, `cloudevents-api`, `micrometer-core`, `avro`,
|
||||
`protobuf-java`가 이 규칙으로 `api`다.)
|
||||
- 반대로 **노출하지 않는 것은 `implementation`으로 낮춘다.** starter가 노출하지 않는 하위 모듈을
|
||||
`implementation`으로 내린 것이, JSON codec이 `ObjectMapper`를 private으로만 쓰고 Jackson을
|
||||
`implementation`으로 둔 것이 그 예다.
|
||||
- 이 규칙은 문서가 아니라 `MessagingPublicSurfaceContractTest`가 붙들고 있다. leaf의 production
|
||||
source에서 public/protected 시그니처에 등장하는 vendor 라이브러리를 뽑아 그 leaf의
|
||||
`build.gradle`이 `api`로 선언했는지 대조하고, starter의 `api` closure에 broker client 두 개가
|
||||
들어오지 않는 것도 함께 본다. Spring Framework/Boot는 대상이 아니다 — 조립 경계 안에서만
|
||||
등장하고 adopter가 이름 부를 일이 없다.
|
||||
- 새 public 타입은 그 모듈의 계약이다. 삭제·시그니처 변경은 breaking change로 취급한다.
|
||||
|
||||
## Application runtime에 포함되는 기준
|
||||
|
||||
기본 조립에는 Messaging family가 없다. 서비스가 `app-bootstrap/build.gradle`에
|
||||
`runtimeOnly project(':adapter:outbound:messaging-kafka')` 한 줄을 넣으면 그 모듈이 bridge와
|
||||
`messaging-spring-boot-starter`(Kafka transport 포함)의 transitive project graph를 runtime에 싣는다. 이
|
||||
사실의 SSOT는 Gradle `runtimeClasspath`이며 registry에 동일한 membership 목록을 복제하지 않는다.
|
||||
모듈이 있으면 켜지고(`app.messaging.enabled` 기본 `true`), `APP_MESSAGING_ENABLED=false`로만 끈다.
|
||||
|
||||
일부 codec(cloudevents 등)·claim-check·testkit처럼 starter graph에 들어오지 않는 leaf는 build-only다.
|
||||
RabbitMQ·Pulsar·NATS·Kafka Share·Spring Cloud Stream bridge leaf와 Debezium outbox 매핑은
|
||||
2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표).
|
||||
새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy,
|
||||
qualification/support 상태를 함께 변경한다.
|
||||
|
||||
## application이 이 family에 도달하는 경로 (cutover 완료)
|
||||
|
||||
리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한
|
||||
`application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다.
|
||||
|
||||
- application-owned port: `IntegrationEventPublishPort`
|
||||
- bridge: `adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter`
|
||||
- platform boundary: `EncodedMessagePublisher`
|
||||
- central implementation: `DefaultMessagePublisher`
|
||||
|
||||
bridge는 exact canonical envelope bytes를 다시 serialize하지 않고, destination/access/admission/runtime
|
||||
lease/transport/outcome normalization/observation은 platform 중앙 publish path를 그대로 탄다. bridge
|
||||
package는 `messaging-core-api`만 보며 concrete runtime/transport/Kafka 타입을
|
||||
직접 보지 않는다.
|
||||
|
||||
**application bridge cutover는 2026-09-28에 끝났다(2026-09-25 소유자 결정).** application의 outbox append는 canonical
|
||||
`OutboxAppendPort` 하나이고, relay는 claim한 row의 validated event를 이 bridge로만 보낸다. legacy
|
||||
`OutboxEvent`·`LegacyOutboxAppendPort`와 `MessageBroker → KafkaSender` R0 경로(TLS/SASL을 적용하지
|
||||
않던 두 번째 producer)는 삭제했다. 남은 Kafka producer는 platform의 것 하나이고, broker security
|
||||
profile(`KafkaSecurityConfigurer`)을 적용한다.
|
||||
|
||||
canonical bridge의 producer identity는 `app.messaging.producer-id`로 명시한다. 값이 없으면 bridge bean을
|
||||
만들지 않으며 `spring.application.name`/host/pod 이름에서 identity를 발명하지 않는다. bridge가 없으면
|
||||
relay가 발행할 곳이 없으므로 messaging 모듈이 켜진 상태에서는 기동이 거부된다.
|
||||
|
||||
`IntegrationEventEncoderPort`는 템플릿이 제공한다: `adapter:outbound:support`의
|
||||
`JsonIntegrationEventEncoder`가 envelope v1(`shared-contract`의 `contracts/messaging/envelope/v1.schema.json`)
|
||||
안에 payload record를 결정적 JSON으로 싣는다. 계약 catalog는 애플리케이션이 bean으로 등록한
|
||||
`IntegrationEventContractContribution`뿐이고, 선언한 payload schema hash가 classpath의 schema 파일과
|
||||
다르면 기동이 실패한다. payload를 JSON Schema로 매번 검증하려는 서비스는 자기 encoder bean을 두면 된다.
|
||||
|
||||
## Stable 승격에 필요한 증거
|
||||
|
||||
adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/support-matrix.md`가 현재
|
||||
상태를 기록한다):
|
||||
|
||||
1. 실제 broker container를 쓰는 fault 시나리오 lane이 존재하고, 그 lane이
|
||||
`BrokerCertificationEvidence`를 산출한다.
|
||||
2. `NetworkFaultScenario` 전 항목에 대해 evidence가 있거나, 없는 항목이 `knownGaps`로 명시된다.
|
||||
3. capability 선언이 코드에서 파생된다 — `MessagingCapabilities`에 손으로 `true`를 쓰는 것은
|
||||
증거가 아니다.
|
||||
4. publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은
|
||||
Experimental에서도 금지다.
|
||||
5. unknown failure의 기본값이 `AMBIGUOUS`다. `REJECTED`는 전송이 시작되지 않았다는 typed 증거가
|
||||
있을 때만.
|
||||
|
||||
Stable 문구는 evidence manifest가 존재할 때만 문서에 쓴다.
|
||||
|
||||
증거를 만드는 것은 인증 레인이고, manifest는 그 실행의 출력이다:
|
||||
|
||||
```bash
|
||||
./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence --console=plain
|
||||
```
|
||||
|
||||
레인(`messagingCertificationTest`)은 Toxiproxy를 broker 앞에 두고 장애를 주입하며,
|
||||
통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을
|
||||
`messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl`에 쓴다.
|
||||
게이트는 커밋된 manifest와 이번 실행의 출력을 대조한다 — **manifest를 손으로 고치면 실패하고,
|
||||
레인을 돌리면 manifest가 다시 쓰인다.** 이 레인만은 Docker 가드를 달지 않는다(없으면 실패한다).
|
||||
skip하는 인증 레인은 아무도 켜지 않은 브로커에 대해 성공을 보고하기 때문이며, 그래서 `test`에서는
|
||||
`messaging-certification` 태그로 제외된다.
|
||||
|
||||
## Focused test
|
||||
|
||||
leaf의 `gradle_path`를 registry에서 읽어 파생한다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew <gradle-path>:test --console=plain
|
||||
```
|
||||
|
||||
Family 전체 검증:
|
||||
|
||||
```bash
|
||||
./gradlew verifyCleanArchitectureDependencies --console=plain
|
||||
./gradlew architectureCheck --console=plain
|
||||
./gradlew verifyDependencyLocks --console=plain
|
||||
```
|
||||
@AGENTS.md
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
# shared-contract — 골격 전체가 쓰는 운영 계약
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `shared-contract`
|
||||
- Gradle 경로: `:shared-contract`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :shared-contract:test --console=plain`
|
||||
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
- registry 정본: `src/config/architecture/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.shared`.
|
||||
|
||||
예전에 코드 주석에 두던 설계 결정(오류 코드 분류, 응답 envelope 모양, metric cardinality 한계,
|
||||
tracing 이음매, domain-context 전파)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙의 정본으로
|
||||
남는다.
|
||||
|
||||
## 책임 (Responsibility)
|
||||
- 응답 envelope(`response/Envelope`, `response/ApiError`, `response/BulkEnvelope`, `response/BulkItemResult`).
|
||||
- 오류 코드 계약(`error/ApiErrorCode` 인터페이스, `error/OperationalError` enum,
|
||||
`error/ApiErrorCarrier`)과 클라이언트에 보여 줄 문구 표 하나(`error/ClientErrorMessages`.
|
||||
한국어이고 `Category`마다 문구 하나이며 모든 전송 계층이 쓴다).
|
||||
- 계층을 가로지르는 mapper 표지 예외(`error/MappingException`).
|
||||
- 요청 값 계약(`request/Patch`).
|
||||
- tracing 계약 타입(`tracing/TraceParent`, `tracing/SpanErrorRecorder`) — W3C `traceparent` 값 타입과
|
||||
span 오류 기록 이음매(feature-distributed-tracing-contract. OTel tracer 런타임은 fork가 켜는
|
||||
이음매라서 이 타입들은 Java 표준 라이브러리만 쓴다).
|
||||
- 모든 leaf가 복사해 쓰던 표준 라이브러리 도우미(2026-09-25 리뷰 후속으로 여기로 옮겼다):
|
||||
`digest/Sha256`(SHA-256 digest 값과 유일한 `MessageDigest.getInstance("SHA-256")`),
|
||||
`digest/HmacSha256`(서명과 상수 시간 검증), `retry/Backoff`(상한 있는 지수 ceiling. "full jitter"는
|
||||
`U[0, ceiling]`이고 다른 뜻이 아니다). 들여온 `messaging:*`와 optional gRPC 빌드는 이 모듈에
|
||||
의존하지 않고 자기 사본을 둔다. 각 제품의 AGENTS.md가 이유를 적는다(다른 제품이다. 2026-08-14 메시징
|
||||
모듈 리뷰 뒤에 정했다). 이 도우미가 필요한 템플릿 leaf는 모두 `shared-contract` edge를 두고 복사하지
|
||||
않고 쓴다. identifier, persistence-mongo, application-objectstorage, redis-sdk가 바로 이 때문에
|
||||
edge를 받았고(2026-11-03에 정함), 각각 JVM 밖에서 계산한 벡터로 출력을 고정하는 시험이 있다.
|
||||
- `observability/MdcKeys`: 모든 전송 계층(web, GraphQL, STOMP, gRPC)이 요청의 correlation을 넣는
|
||||
snake_case MDC 키 이름(registry `docs/registries/mdc-keys.yaml`).
|
||||
- `ratelimit/`: web edge와 Redis 어댑터 사이에 있는 provider 중립 edge rate-limit 포트
|
||||
(`EdgeRateLimitPort`)와 그 값 타입(README 「ratelimit」).
|
||||
- `security/Permission`: `AuthorizationPort`에 묻는 `resource:action` 권한 값(README 「security」).
|
||||
- `concurrency/`: domain-context 전파 포트와 그 `ThreadLocal` 기본 구현(README 「concurrency」).
|
||||
- `runtime/RuntimeEnvironment`: 모든 leaf가 「운영 환경인가?」에 답할 때 쓰는 유일한 runtime profile
|
||||
어휘.
|
||||
- `metrics/ForbiddenMetricTags`: 어떤 metric도 실으면 안 되는 high-cardinality tag 키.
|
||||
- 이 모듈의 패키지는 위가 전부이고 다른 패키지는 둘 수 없다:
|
||||
`ForbiddenApiArchitectureTest.SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES`가
|
||||
`dev.caskeleton.shared` 아래 다른 패키지에 있는 클래스와 루트에 바로 있는 클래스를 거절한다. 루트에는
|
||||
`package-info`만 있다. 새 계약 패키지는 그 시험의 `SHARED_CONTRACT_PACKAGES`와 이 목록에 함께
|
||||
넣는다. `SharedContractPackageRuleTest`는 `SHARED_CONTRACT_PACKAGES`와 모듈의 패키지가 다르면
|
||||
실패한다.
|
||||
- 계약 시험만 읽는 registry 규칙 사본은 `main`이 아니라 `testFixtures`에 둔다:
|
||||
`metrics/MetricNaming`, `metrics/CardinalityBounds`, `metrics/AlertSeverity`,
|
||||
`tracing/BaggageAllowlist`. 운영 코드가 쓰게 될 때만 `main`으로 옮긴다.
|
||||
- `contracts/messaging/envelope/` 아래의 범용 메시징 envelope schema 리소스. 전송 중립 envelope
|
||||
metadata만 가진다. 기능 payload schema는 그 기능을 가진 모듈에 남는다. 리소스가 있다고 런타임에
|
||||
찾아지거나 등록되는 것은 아니다.
|
||||
|
||||
## 허용
|
||||
- Java 표준 라이브러리**만**. Spring, Jackson, JPA import는 없다.
|
||||
|
||||
## 금지 (Forbidden)
|
||||
- 업무·도메인 개념(도메인 오류 코드는 그것을 쓰는 모듈에 둔다).
|
||||
- 프레임워크 import(HTTP 상태는 전송 중립 `int`로 나타내고 web 모듈이 대응시킨다).
|
||||
- 메시징 어댑터의 Task 6 validator 검증이 생기기 전에 Draft 2020-12 validator 호환을 주장하기.
|
||||
|
||||
## 테스트
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :shared-contract:test
|
||||
```
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user