Files
messaging-library/messaging/CLAUDE.md
T

4.9 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 framework-free 실행 로직 Micrometer는 observability에서만. 나머지는 stdlib
kafka, rabbit, pulsar-experimental, nats-experimental, kafka-share-experimental broker adapter 해당 broker client. Spring은 rabbit의 spring-rabbit처럼 client가 곧 Spring인 경우만
outbox-jdbc-postgresql, inbox-jdbc-postgresql 관계형 신뢰성 adapter Spring JDBC / Spring TX. JPA 아님 — 이름이 곧 계약이다
spring-boot-starter, spring-cloud-stream-bridge 조립 경계 Spring Boot autoconfigure. 여기서만
testkit 테스트 지원 Testcontainers, JUnit. production leaf가 의존하지 않는다

outbox/inbox leaf가 jdbc-postgresql로 명명된 이유: 구현은 Spring JDBC이고 SQL은 ?::jsonb · FOR UPDATE SKIP LOCKED · ON CONFLICT · TIMESTAMPTZ로 PostgreSQL 전용이다. jpa라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다. vendor 중립 계약은 messaging-reliability-api에 있다.

Public surface 정책

  • vendor 타입을 public signature에 노출하면 그 의존성은 api로 선언한다. 숨긴다고 타입이 숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다. (kafka-clients, spring-rabbit, cloudevents-api, micrometer-core가 이 규칙으로 api다.)
  • 반대로 노출하지 않는 것은 implementation으로 낮춘다. starter가 노출하지 않는 하위 모듈을 implementation으로 내린 것이 그 예다.
  • 새 public 타입은 그 모듈의 계약이다. 삭제·시그니처 변경은 breaking change로 취급한다.

Runtime membership이 비어 있다는 것의 의미

registry의 모든 messaging leaf는 runtime_memberships가 비어 있다. 이는 build-only / incubating을 뜻한다:

  • 두 composition root(app-bootstrap, sample-portfolio) 중 어디에도 런타임으로 들어가 있지 않다.
  • 따라서 이 leaf들은 컴파일·테스트·계약 검증의 대상이지, 배포된 애플리케이션이 실행하는 코드가 아니다.
  • 애플리케이션에 실제로 배선하려면 registry의 runtime_memberships를 먼저 바꾸고 verifyRuntimeModuleMembership을 통과시켜야 한다. 코드만 추가하는 것으로는 런타임에 들어가지 않는다.
  • 지원 상태 문서(docs/messaging/support-matrix.md)의 tier는 이 사실과 별개다. tier는 "무엇이 증명되었는가", membership은 "무엇이 실행되는가"다.

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에서도 금지다(MSG-022).
  5. unknown failure의 기본값이 AMBIGUOUS다. REJECTED는 전송이 시작되지 않았다는 typed 증거가 있을 때만.

Stable 문구는 evidence manifest가 존재할 때만 문서에 쓴다.

Focused test

leaf의 gradle_path를 registry에서 읽어 파생한다.

cd src
./gradlew <gradle-path>:test --console=plain

Family 전체 검증:

./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew verifyDocumentedLeafCount --console=plain
./gradlew verifyDependencyLocks --console=plain