docs!: 메시징 문서를 messaging-library로 보내고 관련 저장소 절을 채운다
앞 커밋이 메시징 플랫폼을 지웠지만 살아 있는 문서는 아직 src/platforms 경로와 docs/messaging/을 부른다. 기록 8개의 머리 블록 「현재 정본」도 지운 docs/messaging/support-matrix.md를 가리킨다. - docs/messaging/(10개)을 지운다. 같은 이름의 파일이 이력째 messaging-library에 있다. 이 repo에서 그 내용을 부르던 문서(manual 09, messaging-kafka README·AGENTS)는 그 repo 파일로 링크한다. - 기록(설계서 3, 계획서 3, 납품 패키지 2): 본문은 두고 머리 블록만 고쳤다. 플랫폼을 다룬 것은 「없음 — messaging-library로 옮겼다」, 앱 쪽 발행·소비를 다룬 것은 docs/manual/09-outbox-events.md. - docs/work/reference/related-repos.md: 관련 저장소 표(메시징 줄 채움), 라이브러리를 고치는 법, 템플릿에서 버전 올리는 법, 같이 고칠 때 composite build(Gradle 루트가 src/라 ../../messaging-library), registry 라이브러리 칸. 설계 14절이 근거다. - src/config/architecture/README.md: library_groups·allowed_libraries 설명. - docs/upgrade/2026-11-maturity-review.md 3.9절: B-57(지운 것), B-58(받는 법·패키지·auto-config 이름), B-59(registry 칸). - 진입 문서와 지역 지침(AGENTS.md, README.md, delegate, decisions, review-criteria, defect-patterns, gates, capability-status, manual 07, build-logic·persistence-jpa·inbound messaging·shared-contract 지침, env-keys 주석)에서 「들여온 제품」·src/platforms 문장을 별도 repo 라이브러리 문장으로 바꿨다. 위험: 다른 repo 파일을 가리키는 링크는 lychee가 외부 URL로 본다(공개 repo라 익명으로 읽힌다). 검증: python3 scripts/check-docs.py OK, check-work-docs.py OK(상대 링크 깨짐 0), check-repo-layout.py OK, python3 -m unittest discover -s scripts/tests OK. BREAKING CHANGE: docs/messaging/이 없어졌다. 메시징 문서는 messaging-library repo의 docs/messaging/에 있다. Refs: design-docs repo-structure/05-library-repos.md 4.3·14절
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
|
||||
- 모듈 ID `adapter-inbound-messaging`, Gradle 경로 `:adapter:inbound:messaging`. registry 정본:
|
||||
`src/config/architecture/modules.json`.
|
||||
- 책임: 들여온 메시징 플랫폼의 애플리케이션 소비 쪽이다 — 플랫폼이 애플리케이션에서 받아야 하는
|
||||
- 책임: 메시징 라이브러리(별도 repo messaging-library, Maven `dev.cakit.messaging`)의 애플리케이션 소비 쪽이다 — 라이브러리가 애플리케이션에서 받아야 하는
|
||||
inbox 부품(애플리케이션 DataSource 위의 `JdbcInboxRepository`, 그 `PlatformTransactionManager` 위의
|
||||
`TransactionRunner`, 자기 Flyway stream `MessagingInboxSchemaStream`인 inbox migration)과 애플리케이션의
|
||||
`MessageHandler` 구현들이다. 핸들러 하나는 전달 하나를 유스케이스 호출 하나로 바꾼다. 핸들러는 그 밖에
|
||||
@@ -14,7 +14,7 @@
|
||||
(`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>`)만 구현하고,
|
||||
`USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`). 핸들러는 프로젝트 타입(메시징 라이브러리의 `MessageHandler<T>`. `dev.cakit..`도 프로젝트 타입으로 친다)만 구현하고,
|
||||
`Runnable`이나 프로젝트 밖의 다른 타입은 구현하지 않는다(`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`).
|
||||
- 시험: 자동 구성과 inbox 동작을 보는 시험. `./gradlew :adapter:inbound:messaging:check`.
|
||||
실제 Kafka + PostgreSQL 재전달 lane은 `messagingInboxRedeliveryIntegrationTest`다(`:integrationCheck`).
|
||||
|
||||
@@ -3,10 +3,11 @@
|
||||
- 모듈 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는
|
||||
`adapter:outbound:messaging`(애플리케이션의 bridge)과 메시징 라이브러리의 `messaging-spring-boot-starter-kafka`(Kafka
|
||||
전송, Maven `dev.cakit.messaging`, 카탈로그 `libs.messaging.spring.boot.starter.kafka`)를 묶고, 모듈 기본값
|
||||
`config/module-defaults/messaging.yml`을 싣는다.
|
||||
- 경계: 여기 코드를 더하지 않는다. 발행 규칙은 bridge(`adapter:outbound:messaging`)에, Kafka 규칙은 메시징
|
||||
라이브러리(messaging-library repo의 [messaging/AGENTS.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/messaging/AGENTS.md))에 속한다. 여기 클래스를 두면 세 번째 자리가 생긴다. 허용 edge는
|
||||
registry 항목에서만 온다.
|
||||
- 시험: 켜기 시험(`./gradlew :adapter:outbound:messaging-kafka:test`)과 실제 Kafka lane
|
||||
`messagingKafkaRelayIntegrationTest`(relay → bridge → broker record 바이트, `:integrationCheck`).
|
||||
|
||||
@@ -15,7 +15,8 @@ adapter:outbound:messaging-kafka
|
||||
├─ config/module-defaults/messaging.yml (설정 기본값, support 로더가 읽음)
|
||||
├─ adapter:outbound:messaging OutboxMessagePublishPort,
|
||||
│ IntegrationEventPublishPort bridge
|
||||
└─ messaging:messaging-spring-boot-starter-kafka messaging platform + Kafka transport
|
||||
└─ dev.cakit.messaging:messaging-spring-boot-starter-kafka 메시징 라이브러리 + Kafka transport
|
||||
(별도 repo messaging-library, 카탈로그 messagingLibrary)
|
||||
```
|
||||
|
||||
| 포트 (application-core) | 구현 |
|
||||
@@ -31,7 +32,8 @@ adapter:outbound:messaging-kafka
|
||||
app-bootstrap은 이 파일을 모른다.
|
||||
- broker 주소는 `APP_MESSAGING_KAFKA_BROKERS` 하나(`app.messaging.brokers.kafka.bootstrap-servers`).
|
||||
`spring.kafka.bootstrap-servers`는 읽지 않는다. 논리 broker 이름은 `kafka` 하나다. Kafka 연결의
|
||||
TLS·SASL은 platform의 broker profile이 소유한다(`docs/messaging/configuration-reference.md`).
|
||||
TLS·SASL은 메시징 라이브러리의 broker profile이 소유한다(그 repo의
|
||||
[configuration-reference.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/docs/messaging/configuration-reference.md)).
|
||||
- 발행 경로는 하나다. 옛 `KafkaSender` seam(TLS/SASL 없는 R0 producer)은 outbox를 canonical로
|
||||
통일하면서 삭제했다(2026-09-28).
|
||||
- 발행할 event의 contract마다 destination을 선언해야 한다(`app.messaging.destinations.<logical
|
||||
@@ -44,7 +46,7 @@ adapter:outbound:messaging-kafka
|
||||
runtimeOnly project(':adapter:outbound:messaging-kafka') // Kafka 발행
|
||||
```
|
||||
|
||||
이 줄을 지우면 발행 포트 구현, Kafka client, messaging platform, 설정 기본값이 모두 함께 빠진다.
|
||||
이 줄을 지우면 발행 포트 구현, Kafka client, 메시징 라이브러리, 설정 기본값이 모두 함께 빠진다.
|
||||
|
||||
## 필요한 env 키
|
||||
|
||||
@@ -56,16 +58,16 @@ runtimeOnly project(':adapter:outbound:messaging-kafka') // Kafka 발행
|
||||
| 항상 | `APP_MESSAGING_PRODUCER_ID` (배포와 무관한 논리적 서비스 이름). 비어 있으면 기동이 실패한다 — 모든 발행이 canonical bridge를 지난다 |
|
||||
| 끌 때 | `APP_MESSAGING_ENABLED=false` |
|
||||
|
||||
`APP_MESSAGING_BROKER`는 platform이 쓸 broker 선택값이고 기본값이 `kafka`다. 등록된 broker가 Kafka
|
||||
하나라 바꿀 일이 없다. destination·broker profile·보안 설정은
|
||||
`docs/messaging/configuration-reference.md`.
|
||||
`APP_MESSAGING_BROKER`는 메시징 라이브러리가 쓸 broker 선택값이고 기본값이 `kafka`다. 등록된 broker가 Kafka
|
||||
하나라 바꿀 일이 없다. destination·broker profile·보안 설정은 messaging-library repo의
|
||||
[configuration-reference.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/docs/messaging/configuration-reference.md)다.
|
||||
|
||||
## 실제 broker로 도는 앱 발행 경로 lane (`messagingKafkaRelayIntegrationTest`)
|
||||
|
||||
앱이 실제로 쓰는 발행 경로 — `composition:outbox-relay` relay → `OutboxMessagePublishAdapter` →
|
||||
platform bridge → `DefaultMessagePublisher` → Kafka — 를 Testcontainers Kafka(`apache/kafka:4.1.0`,
|
||||
`-PmessagingKafkaImage=`로 교체)로 끝까지 돌린다(리뷰 2026-11-01 06-09). vendored 쪽 broker lane은
|
||||
platform 자기 relay와 publisher 직접 호출만 검증하므로 앱 경로의 증거가 아니다.
|
||||
`-PmessagingKafkaImage=`로 교체)로 끝까지 돌린다(리뷰 2026-11-01 06-09). 메시징 라이브러리 쪽 broker lane
|
||||
(그 repo의 인증 lane)은 라이브러리 자기 relay와 publisher 직접 호출만 검증하므로 앱 경로의 증거가 아니다.
|
||||
|
||||
- 정상 발행: append한 row를 relay가 보내고, 테스트가 topic에서 읽은 레코드 값이 envelope 바이트와
|
||||
같고 key가 partition key와 같다.
|
||||
|
||||
@@ -111,6 +111,7 @@ lock TTL)과 계약 표(트랜잭션 모드, SQLState → 오류 코드, vendor,
|
||||
- `:shared-contract`
|
||||
- `:adapter:outbound:support`(타입 있는 기동 실패, EnvironmentPostProcessor 순서, readiness group, module-defaults 읽기)
|
||||
- Spring Data JPA와 Spring transaction.
|
||||
- 시험만: 메시징 라이브러리 jar(`dev.cakit.messaging:messaging-reliability-jdbc-postgresql`)를 전용 구성 `messagingMigrations`로 받아 그 `db/migration` 트리를 푼다. migration 시험(`MigrationTrees`)이 같은 Flyway 이력에 들어가는 메시징 migration을 이 leaf의 것과 같은 규칙으로 보기 위해서다. 어떤 classpath에도 올리지 않으므로 registry 방향 검사(운영 구성만 본다) 밖이다. 다른 repo의 파일을 경로로 읽지 않는다.
|
||||
|
||||
## 금지 (Forbidden)
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ registry, settings, build-logic, 루트 라이프사이클이 정하는 것을
|
||||
|
||||
## 정본 넷
|
||||
|
||||
- `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로, Gradle path, 허용 production project dependency edge. runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 정본은 registry다. 문서는 개수를 적지 않는다. 산문에 적힌 숫자는 leaf가 더해지는 순간 틀린다. 그 숫자를 강제하던 태스크(`verifyDocumentedLeafCount`)는 지웠다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 사유는 아니고, 그 태스크는 모든 지역 문서와 `build.gradle`을 정규식으로 훑는 파서였다.
|
||||
- `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로, Gradle path, 허용 production project dependency edge, 그리고 별도 repo 라이브러리 edge(맨 위 `library_groups`, 행마다 `allowed_libraries`. 계층 leaf 행은 비워 둔다. 설명은 `src/config/architecture/README.md`). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 정본은 registry다. 문서는 개수를 적지 않는다. 산문에 적힌 숫자는 leaf가 더해지는 순간 틀린다. 그 숫자를 강제하던 태스크(`verifyDocumentedLeafCount`)는 지웠다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 사유는 아니고, 그 태스크는 모든 지역 문서와 `build.gradle`을 정규식으로 훑는 파서였다.
|
||||
- `src/settings.gradle`: `ca.architecture-registry` 설정 플러그인이 registry를 읽어 project를 include·mapping한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖 경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은 `verifyCleanArchitectureDependencies`가 답한다. settings에서 죽으면 실행할 수 있는 태스크가 하나도 없다.
|
||||
- `src/build-logic/`: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나(`strictTestLanes`). leaf는 `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다. `ca.architecture`가 아키텍처 검증 태스크를 가진다. 기능별 검사(notification·mongo·messaging·graphql·JPA readiness 등)는 build-logic이 아니라 그 leaf의 테스트다.
|
||||
- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전·리비전.
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -4,7 +4,7 @@
|
||||
프로젝트 edge를 정확히 적는다. 빈 `allowed_dependencies` 목록에도 뜻이 있다: 그 leaf가 일부러 다른
|
||||
프로젝트에 기대지 않는다는 뜻이지, registry 항목을 덜 채웠다는 뜻이 아니다.
|
||||
|
||||
`domain-core`, `shared-contract`, 들여온 메시징 제품의 `messaging-core-api`가 그 예다. 빈 목록은
|
||||
`domain-core`, `shared-contract`가 그 예다. 빈 목록은
|
||||
분명한 경계이고, 실제 프로젝트 edge를 들여와 리뷰하기 전까지 비어 있어야 한다. 반대로 목록에 적힌
|
||||
edge는 빌드가 실제로 쓰는 것과 맞아야 한다. 예를 들어 `adapter-outbound-persistence-mongo`의 목록은
|
||||
`["application-core", "shared-contract"]`이고 `MongoRegistryPermissionParityTest`가 두 방향을 모두
|
||||
@@ -12,3 +12,21 @@ edge는 빌드가 실제로 쓰는 것과 맞아야 한다. 예를 들어 `adapt
|
||||
|
||||
런타임 조립 구성원은 빌드 로직이 해석된 runtime classpath에서 얻는다. 이 registry에 모듈마다 칸으로
|
||||
다시 적지 않는다.
|
||||
|
||||
## 별도 repo 라이브러리: `library_groups`와 `allowed_libraries`
|
||||
|
||||
소유자가 다른 repo에서 배포하는 라이브러리(메시징 `dev.cakit.messaging`, gRPC `dev.cakit.grpc`)는 이 빌드의
|
||||
프로젝트가 아니라 외부 좌표다. 그래서 프로젝트 edge 규칙(`allowed_dependencies`)이 보지 못한다. 그 빈자리를
|
||||
두 칸이 메운다(설계 design-docs `repo-structure/05-library-repos.md` 10.2절 T2, 소유자 승인 2026-11-07).
|
||||
|
||||
- 맨 위 `library_groups`: 다스릴 라이브러리의 Maven group 접두사. 지금 `["dev.cakit"]`이다. 이 접두사와
|
||||
같거나 그 아래(`dev.cakit.` 다음) group만 다스린다. 다른 group(Spring, Kafka client 등)은 이 칸과 상관없다.
|
||||
- 행마다 선택 칸 `allowed_libraries`: 그 leaf가 쓸 수 있는 라이브러리 모듈의 `group:artifact` 목록. 없으면 빈
|
||||
목록과 같다. 값은 `library_groups` 안의 group이어야 하고 겹치면 안 된다(registry를 읽을 때 거절).
|
||||
- 방향 검사(`verifyModuleDependencyDirection`, `verifyCleanArchitectureDependencies` 아래)는 프로젝트 edge와 같은
|
||||
방식으로 대조한다: 운영 선언(`api`·`implementation`·`compileOnly`·`runtimeOnly`)의 소유 group 좌표와,
|
||||
`compileClasspath`에서 보이는 소유 group 모듈(라이브러리 모듈이 `api`로 내보낸 것 포함)이 모두 칸에 있어야
|
||||
한다. 시험 구성은 보지 않는다.
|
||||
- 그래서 지금 지키는 약속 셋이 검사로 남는다: bridge(`adapter-outbound-messaging`)는 `messaging-core-api`만 본다.
|
||||
Kafka capability(`adapter-outbound-messaging-kafka`)는 starter-kafka를 `runtimeOnly`로만 싣는다. 계층 leaf는
|
||||
칸이 비어 있으니 라이브러리를 쓸 수 없다.
|
||||
|
||||
@@ -27,7 +27,7 @@ tracing 이음매, domain-context 전파)은 [README.md](README.md)에 있다.
|
||||
- 모든 leaf가 복사해 쓰던 표준 라이브러리 도우미(2026-09-25 리뷰 후속으로 여기로 옮겼다):
|
||||
`digest/Sha256`(SHA-256 digest 값과 유일한 `MessageDigest.getInstance("SHA-256")`),
|
||||
`digest/HmacSha256`(서명과 상수 시간 검증), `retry/Backoff`(상한 있는 지수 ceiling. "full jitter"는
|
||||
`U[0, ceiling]`이고 다른 뜻이 아니다). 들여온 `messaging:*`와 별도 repo 라이브러리(grpc-library)는 이 모듈에
|
||||
`U[0, ceiling]`이고 다른 뜻이 아니다). 별도 repo 라이브러리(messaging-library, grpc-library)는 이 모듈에
|
||||
의존하지 않고 자기 사본을 둔다. 각 제품의 AGENTS.md(라이브러리는 그 repo)가 이유를 적는다(다른 제품이다.
|
||||
2026-08-14 메시징 모듈 리뷰 뒤에 정했다). 이 도우미가 필요한 템플릿 leaf는 모두 `shared-contract` edge를 두고 복사하지
|
||||
않고 쓴다. identifier, persistence-mongo, application-objectstorage, redis-sdk가 바로 이 때문에
|
||||
|
||||
Reference in New Issue
Block a user