- 결정 7: `LegacyOutboxAppendPort`·legacy 저장 모델·relay·Kafka R0 seam 삭제, 템플릿 JSON encoder(`JsonIntegrationEventEncoder`),
durable operation·sample 이벤트가 `OutboxAppendPort` + encoder로, persistence-jpa V19(pre-canonical 미발행 row 거부)
- 결정 3: outbox relay·멱등성 executor 조립을 `composition:outbox-relay`·`composition:idempotency`로,
sample이 복사한 bootstrap 인프라를 `composition:service-runtime`으로(sample `SampleIdempotencyConfig` 복사본 삭제)
- persistence-jpa outbox·멱등성 패키지 feature 기준 이동, messaging outbox·inbox leaf를 reliability / reliability-jdbc-postgresql로
- messaging outbox header를 jsonb로(P18-new-1 — `\`로 끝나는 값이 다음 header를 삼키던 결함)
- 통합(충돌 22건): P25 A-10c(전략 선택 설정 삭제)를 service-runtime `DomainContextConfig`에 적용, P25 startup 예외 통합을
composition 설정 테스트에, P25 `CommandUseCase.handle` 이름을 PG 통합 테스트에, P15 `EventJson`은 호출자 0이 되어 삭제
- root CLAUDE.md의 legacy seam 문장 수정(P18-new-2)
검증: ./gradlew check architectureCheck verifyDependencyLocks verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys
configContractCheck :app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest
persistence-jpa jpaPlatformContractTest·postgresql{Idempotency,OutboxAppendTransactional,OutboxConcurrentRelay,OutboxRowLifecycle}IntegrationTest
:messaging:messaging-reliability-jdbc-postgresql:integrationTest --continue 통과(700 task)
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
9.1 KiB
messaging — local authority for the messaging platform 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, schema-api, policy, reliability-api, admin-api, transport-spi) |
값 타입, 포트, 정책 계약 | Java stdlib만. Spring/broker SDK/logging framework 금지 |
schema-* (json/avro/protobuf), cloudevents |
인코딩 구현 | 해당 codec 라이브러리만. Spring 금지 |
runtime-core, security, observability, 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도 같은 모양이었다(S7-#5b). 구현 leaf가 jdbc-postgresql로 명명된 이유: 구현은 Spring
JDBC이고 SQL은 jsonb · FOR UPDATE SKIP LOCKED · ON CONFLICT · TIMESTAMPTZ로 PostgreSQL
전용이다. jpa라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다.
Public surface 정책
- vendor 타입을 public signature에 노출하면 그 의존성은
api로 선언한다. 숨긴다고 타입이 숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다. (kafka-clients,cloudevents-api,micrometer-core,avro,protobuf-java,reactor-core가 이 규칙으로api다.) - 반대로 노출하지 않는 것은
implementation으로 낮춘다. starter가 노출하지 않는 하위 모듈을implementation으로 내린 것이, JSON codec이ObjectMapper를 private으로만 쓰고 Jackson을implementation으로 둔 것이 그 예다. - 이 규칙은 문서가 아니라
MessagingPublicSurfaceContractTest가 붙들고 있다. leaf의 production source에서 public/protected 시그니처에 등장하는 vendor 라이브러리를 뽑아 그 leaf의build.gradle이api로 선언했는지 대조하고, starter의apiclosure에 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에 도달하는 경로 (MSG-015, 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와 messaging-schema-api만 보며 concrete runtime/transport/Kafka 타입을
직접 보지 않는다.
MSG-015 cutover는 끝났다(2026-09-28, 소유자 결정 7). 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가 현재
상태를 기록한다):
- 실제 broker container를 쓰는 fault 시나리오 lane이 존재하고, 그 lane이
BrokerCertificationEvidence를 산출한다. NetworkFaultScenario전 항목에 대해 evidence가 있거나, 없는 항목이knownGaps로 명시된다.- capability 선언이 코드에서 파생된다 —
MessagingCapabilities에 손으로true를 쓰는 것은 증거가 아니다. - publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은 Experimental에서도 금지다(MSG-022).
- unknown failure의 기본값이
AMBIGUOUS다.REJECTED는 전송이 시작되지 않았다는 typed 증거가 있을 때만.
Stable 문구는 evidence manifest가 존재할 때만 문서에 쓴다.
증거를 만드는 것은 인증 레인이고, manifest는 그 실행의 출력이다:
./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에서 읽어 파생한다.
cd src
./gradlew <gradle-path>:test --console=plain
Family 전체 검증:
./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew architectureCheck --console=plain
./gradlew verifyDependencyLocks --console=plain