옮겨 온 문서는 템플릿 안의 family를 전제로 쓰였다. 루트 지침은
하네스 뼈대의 빈 양식이고, 모듈 지침·제품 문서는 템플릿 경로
(src/platforms/messaging, src/config/…, cd src)와 템플릿 소비자
(app-bootstrap, adapter:*, composition:*)를 이 repo 안의 것처럼 부른다.
- AGENTS.md(38줄)·CLAUDE.md: 꼭 지킬 것 일곱(api 모듈 순수성, 템플릿
타입·경로 금지, 배포 버전·적용된 migration 불변, 인증 manifest 손으로
고치지 않기 등), 지도, 맡은 일, 검증 진입점.
- README.md: 받는 법(exclusiveContent dev.cakit), migration 위치, 지원 표
(Boot 4.0.9, kafka-clients 4.1.2, apache/kafka:4.1.0, PostgreSQL 16,
Java 21), 구조, 문서 지도, 서명 공개 키(지문 …A1C936D7F791F8AB,
grpc-library와 같은 키), 이력(템플릿 2959eff0에서 filter-repo).
- CHANGELOG.md: 1.0.0 절과 템플릿 안 코드에서 옮기는 법(패키지,
Kafka 설정 키, Gradle 좌표, 바뀌지 않는 것).
- docs/README.md, docs/work/{README,gates,release}.md,
docs/problem-statement.md: grpc-library와 같은 모양으로, 메시징의
인증 증거 게이트·migration 규칙·템플릿과 같이 고치는 경로를 넣었다.
docs/vision.md는 소유자가 쓸 자리라 비워 둔다.
- messaging/AGENTS.md, docs/messaging/*, starter README: registry 경로를
이 repo 기준으로, 템플릿 쪽 경로·타입은 「백엔드 템플릿의」로 밝혔다.
시험이 읽는 문장(지원 표의 broker·버전, 설정 참조의 YAML)은 바꾸지
않았다.
검증: scripts/verify.sh docs rc=0(vision.md 자리 알림만). desktop
mainCheck는 이 커밋 직전 트리에서 rc=0이었다. 문서가 시험에 읽히는
부분은 다음 desktop 실행으로 다시 본다.
Refs: design-docs repo-structure/05-library-repos.md 14.2절
7.0 KiB
messaging-library
Spring Boot 앱에 브로커 중립 메시징을 붙이는 라이브러리다. 발행·소비 API와 transport SPI, Kafka adapter, 관계형 outbox·inbox(PostgreSQL)와 relay, 재시도·DLQ·redrive 정책, 보안·관측 규칙, schema codec(JSON·Avro·Protobuf·CloudEvents), 운영자 admin 계약, 실제 브로커로 만든 인증 증거를 준다.
앱 소유 port ──> 앱의 adapter(bridge) ──> messaging-core-api (Java 표준 라이브러리만: envelope·destination·publish 결과·port)
└─ messaging-spring-boot-starter (조립, broker 중립)
├─ messaging-runtime-core (중앙 publish 경로)
├─ messaging-reliability (+ -api, -jdbc-postgresql): outbox·inbox
├─ messaging-policy · -security · -observability · -admin
└─ messaging-spring-boot-starter-kafka (Kafka transport capability)
받는 법
Maven group은 dev.cakit.messaging, artifact는 모듈 이름 그대로다(messaging-core-api, messaging-spring-boot-starter-kafka, …). 저장소는 소유자 Gitea Packages이고, 공개라 읽을 때 토큰이 필요 없다.
// settings.gradle
dependencyResolutionManagement {
repositories {
exclusiveContent {
forRepository {
maven { url = 'https://git.learn.hyeonworks.com/api/packages/donghyeon.kang/maven' }
}
filter { includeGroupByRegex 'dev\\.cakit(\\..*)?' }
}
mavenCentral()
}
}
// build.gradle
dependencies {
implementation 'dev.cakit.messaging:messaging-core-api:1.0.0'
runtimeOnly 'dev.cakit.messaging:messaging-spring-boot-starter-kafka:1.0.0'
}
exclusiveContent는 dev.cakit group을 이 저장소에서만, 나머지는 Maven Central에서만 찾게 한다. 같은 이름을 공개 저장소에 올리는 공격이 통하지 않고, Gitea가 느려도 다른 의존성 해석에는 영향이 없다.
신뢰성 migration은 messaging-reliability-jdbc-postgresql jar 안의 classpath 위치 db/migration/messaging(V1001~V1005 outbox·admin journal, V1101 inbox)에 있다. 받는 앱의 Flyway가 그 위치를 읽게 한다. 이 위치와 파일 내용은 배포한 뒤 바꾸지 않는다.
지원 표
| 라이브러리 | Spring Boot(컴파일·시험한 줄) | Kafka client · 인증한 broker | PostgreSQL(시험) | Java |
|---|---|---|---|---|
| 1.0.x | 4.0.x (4.0.9) |
kafka-clients 4.1.2(Boot가 관리) · apache/kafka:4.1.0 |
16 | 21 |
무엇을 인증했고 무엇은 지켜보기만 하는지는 docs/messaging/support-matrix.md다. 인증 증거는 messaging/messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl이고, main 단계가 실제 Kafka로 다시 만들어 대조한다.
프로젝트 구조
| 폴더 | 무엇 |
|---|---|
messaging/ |
모듈. 규칙은 messaging/AGENTS.md |
build-logic/ |
백엔드 템플릿에서 복사해 줄인 Gradle convention 플러그인. 출처는 build-logic/UPSTREAM.md |
config/ |
모듈 registry(architecture/modules.json), Checkstyle·SpotBugs 설정, 테스트 컨테이너 이미지 |
scripts/ |
검증 진입점 verify.sh, 고정 도구 tool.sh, 릴리스 보조 release/ |
.gitea/workflows/ |
단계 파일: pr.yml(ci), main.yml(mainCheck), release.yml(releaseCheck release), signing-check.yml(수동) |
docs/ |
문서. 지도는 docs/README.md |
문서 지도
- 작업 방법:
docs/work/README.md(고치기·리뷰),docs/work/gates.md(게이트),docs/work/release.md(릴리스·버전 규칙·비밀 값) - 제품 문서:
docs/messaging/(설정 참조, 전달 보장, outbox·inbox, 재시도·DLQ·redrive, 보안, 운영, 지원 표, 실험 정책, 이전·cutover 안내) - 설계서:
docs/design/2026-08-10-messaging-platform-design.md - 바뀐 것:
CHANGELOG.md
서명
배포 파일마다 PGP 서명(.asc)이 붙는다. 서명 키는 RSA 4096, 지문 92646CEAFE816CF8B9C249F0A1C936D7F791F8AB, 2028-11-07에 만료된다. grpc-library와 같은 키다. 키를 바꾸는 법은 docs/work/release.md 1절이다.
-----BEGIN PGP PUBLIC KEY BLOCK-----
mQINBGrv1SYBEADGgq8CTE7wdDPIg0zNRXelPvlgyK04tpDTL0b9k1INxDwFEiS0
87bTL22Zjipp+2uDg012TALeLsDV12yh1IToNaYq7zR9bRvEua25+351zw91ojC+
z2/1Y7S98o813hu6qP6EFUHnsWPVLEt40mlGDn3kl8iXMLgjozVYbylomweh/Yvz
HLJd5lQGE76mIejIeGp3m1OA5M2RV4xspA8K8TZkXXSqe3nbfSjPXAOwysPmRRd9
IoLDwakSq4tRI9dlm08bzznsoaaTCRcJ0XAbJK7+ZrQkSwIrsi/gsBkCOJI6Wcs6
+R+9Wy7tYsyd59TdgIdjq3uHadSLWQ3dc0g0ux2krxSL0PHXrT9Upmcorj2+Ltkh
9J1I6hUv1O7e0Y8Es7Ov5WUPfdSdQ5ApwtwFX5aSwYokoW9wXMLg2zdQx0JEx1ix
/qTEvpSKfM0/zVbKJO9RDF/F7HZkDWSOhZe+4x7dak+xN6KOfEQVmcBneaGtPqgJ
eAsIBgRwp42G5llqnTcWAHLAKCDEE9wHK3+gJt5f5rO5e+r1GoYHLn0Iw3iiX6rC
NFot/5my/oePTeRur5tjv14kw1FMXHVNvLOxHeaiZzfVVjO/vbwAtGvZDiRdAgd6
kHyt9Ch/JccIa0ylA9Tttb0A33ZGTQl6sAC6jTSIhfnEAdlCX7MVAE8n4wARAQAB
tCNkb25naHllb24ua2FuZyA8ZG9uZzUxMjlAZ21haWwuY29tPokCVwQTAQoAQRYh
BJJkbOr+gWz4ucJJ8KHJNtf3kfirBQJq79UmAhsDBQkDwmcABQsJCAcCAiICBhUK
CQgLAgQWAgMBAh4HAheAAAoJEKHJNtf3kfir2j8P/RWRT0GTxBNQvm76iO6XnvFD
mDPGq37A5iuD4pJ624/BccKTGe8+WWqtlpAiN6AdHGNi/LGhuYaGL9ce6Gja5tTX
y/ZY8jthbEoi41g6cim8W8knd3v2Ne/qj3dKvphSiVsZBrumEzrZyw2UUD3IRqVx
r2WQZTcSa4UDd7+Qie0h8IrnmfMYIseDCWjDCATNJqr9PBGoKYehv8+Wo3QDVBRd
B0lWepudJjLTsPCXsgFnFJ2HmltRQr1JB+I4CPasfsBp3xqF23hywUuW6fOsHZvv
g5QU7qYfaoxG6E8krGpiibocF5EKXtpEYzDOBFoDS9uNVBAD/LzS7OGtTFr5x3qL
is3eccwNClQS1jeX8Guxam+TlO8XaqnQLCIpdau20/sge6PqXKXauKZiBTGCak1j
zVDQ/sro3VRPePusNHK1CdOi6wiruXw4ZLWO3aEHibi8LbgfwymxXHEtJO5zwFcD
qAnp7KEAkOG8y5LR0FfwWWYnqUZxWJ0ua2Acf8gL8o6DO5pVyJSYrdgCpWjwEWcp
Ms2iit9bCNIMaH6EVgLA2NWCuIL9xAFdXqw/VXrMVK3XXftzNvayvLJCH2eintRg
IKLO/ewISKIFQd3+II3/MM80eUvKGtfi8Y1mj1zyQtcPVykru5DEHjpaLs2SPxdI
Lp+HGQo/NvzwdpIV+8TQ
=eD8w
-----END PGP PUBLIC KEY BLOCK-----
받은 파일을 확인하는 법: 위 키를 gpg --import로 넣고 gpg --verify <파일>.asc <파일>. 배포 토큰 secret 이름은 설계 문서의 PACKAGES_TOKEN이 아니라 등록된 PACKAGE_TOKEN이다.
이력
- 2026-08-14 ~ 2026-11-07: 백엔드 템플릿
clean-architecture-backend-template안에서 만들었다(src/messaging/→ 2026-11-07부터src/platforms/messaging/). - 2026-11-08:
git filter-repo로 그 경로들과docs/messaging/, 설계서,messaging-certification.yml, 저장소 계약 테스트MessagingPublicSurfaceContractTest의 이력을 이 repo로 옮겼다(템플릿 main2959eff0기준). 옮긴 모듈 폴더의 트리 해시는 템플릿 기준 커밋과 같다. - filter-repo가 커밋 SHA를 모두 다시 썼다. 코드 주석과 문서가 부르는 커밋 SHA와 리뷰 ID(
MSG-…,RR-…,S7-#9c등)는 템플릿 repo 기준이다. 그 리뷰 문서는 템플릿docs/reviews/에 남아 있다. - 설계와 결정: design-docs
repo-structure/05-library-repos.md(소유자 승인 2026-11-07, 이름 변경 2026-11-08).