문제: 앞 커밋 뒤에도 알림·파일 서버 묶음이 합쳐지지 않았고, 포트 다수에 fake와 실제 구현이 함께 통과하는 공유 계약이 없었고, SpotBugs가 신뢰도 HIGH만 봤고, application-core에 관계없는 클래스 묶음 패키지(outbound)가 있었다. 묶음을 합치자 lane·검사가 새로 드러낸 결함도 있었다(JpaOutbox Store가 읽기 전용 트랜잭션에서 이벤트를 조용히 잃음, gRPC admission controller가 public synchronized라 외부 lock에 막힘, 소비자 decode 타입 등록 경로 없음, compose Redis 익명 접근, local-fileserver lane DB 없음). 방법: 리뷰 README 15절에 남은 결정을 모두 적고 그대로 고쳤다. 트랜잭션· 멱등성·발행·notification 포트에 testFixtures 계약 키트를 두고 fake와 PG·Redis 구현이 상속한다(fake 변이로 계약이 잡는지 확인). SpotBugs는 MEDIUM으로 내리고 진짜 결함은 고치고 오탐은 위치·패턴별 이유를 단 제외로 처리했다. 업무 기능 패키지 규칙을 application-core/CLAUDE.md에 정본으로 두고 ArchUnit 2개와 생성 명령이 강제한다. compose Redis는 infra/redis-sdk ACL로 뜬다. 묶음별 결과는 리뷰 README 16절에 있다. 위험·한계: APP_FLYWAY_ENABLED가 dev·prod에도 적용된다. app.security 오타 키가 이제 기동을 막는다. SES 콜백 replay 창 기본값이 1시간이다. 템플릿 패키지 목록은 CLAUDE.md 표와 TemplatePackageOwnership 두 곳에 있고 일치 검사는 없다. 실제 CI runner 실행은 확인하지 못했다. 검증: ci, mainCheck, integrationCheck, -p optional-platforms ci integrationCheck, performanceCheck, releaseCheck(-PgitRevision), verify-compose-profile-contracts(18 lane) 통과. compose lane 실제 기동: local-fileserver, notification ingest·serving·handoff, local-redis, all-adapters(smoke 3개 포함). Refs: docs/reviews/2026-11-01-maturity-review/README.md 15·16절 BREAKING CHANGE: APP_FLYWAY_ENABLED가 dev·prod 프로필에도 적용되고, app.security의 모르는 키는 기동을 거부한다. MessageHandler에 schemaVersions()가 생겨 decode 목록을 handler 선언에서 만든다.
9.0 KiB
Outbox · Inbox
이 템플릿 application의 소비 경로: application의
MessageHandler와 inbox 부품(애플리케이션 DataSource 위JdbcInboxRepository,PlatformTransactionManager위TransactionRunner)은adapter:inbound:messaging(src/adapter/inbound/messaging/README.md)이 둔다. platform starter는 두 bean이 있을 때IdempotentConsumer를 만들어INBOX_TRANSACTIONALdestination의 handler를 감싼다. 그 leaf는 inbox 마이그레이션(V1101)만 자기 history 표로 적용하므로, 아래 "location 추가"는 platform outbox를 쓰는 배포의 이야기다. payload decode 목록은 handler bean의 선언으로 만든다.
두 패턴이 각각 무엇을 해결하는가
| 패턴 | 해결하는 문제 | 해결하지 않는 문제 |
|---|---|---|
| Transactional Outbox | DB commit과 publish 사이의 창(窓) | 중복 |
| Inbox | 중복 delivery의 side effect | 유실 |
둘 다 필요하다. Outbox만으로는 exactly-once가 되지 않는다.
채택할 때 먼저 적용할 DB migration
Outbox/Inbox JDBC 모듈의 DDL은 classpath:db/migration/messaging에 있다. Messaging은
Flyway version 1000..1999를 예약해서 애플리케이션의 일반적인 저번호 migration과 버전이
겹치지 않게 한다.
배포에서 이 JDBC 구현을 채택할 때는 기존 Flyway location에 다음 location을 추가한다.
classpath:db/migration/messaging
현재 순서는 V1001..V1005(outbox/admin)와 V1101(inbox)이고, 모두
messaging-reliability-jdbc-postgresql에 있다. starter 테스트가 그 모듈을 실제 combined classpath로 올려 version 중복과 예약 대역 이탈을 검사한다. 개별 DDL의
의미와 전환 순서는 migration-guide.md를 따른다.
Outbox
business transaction과 같은 transaction에서 row를 쓴다. 둘 다 commit되거나 둘 다 안 된다.
BEGIN;
UPDATE orders SET status = 'PLACED' WHERE id = ?;
INSERT INTO messaging_outbox (message_id, destination, ...) VALUES (?, ?, ...);
COMMIT;
relay
claimBatch(owner, 100, 30s, now, maxAttempts) -- owner + fencing token으로 다중 relay 인스턴스 안전
→ publish (messageId 그대로)
→ CONFIRMED → markPublished
→ AMBIGUOUS → markAmbiguous (같은 messageId로 재시도 가능)
→ REJECTED → markFailed
row 하나의 실패는 그 row에서 끝난다. envelope로 만들 수 없는 row(예약 header msg.*를 담은 row
등)는 FAILED가 되고, publisher가 예외를 던지면 결과를 모르므로 AMBIGUOUS가 된다. 같은 batch의
나머지 row는 그대로 publish된다. pass 전체가 실패하면(DB 연결 등) WARN 로그를 남기고
messaging.outbox.relay.failed.passes 카운터를 올린다.
핵심 규칙: ambiguous는 같은 messageId로 재시도
새 id를 발급하면 "전달됐을 수도 있는 메시지"가 "확실히 두 번째인 메시지"가 되어 downstream의 어떤 중복 제거도 복구할 수 없다. failed로 표시하면 broker가 이미 가지고 있을 수 있는 메시지를 잃는다.
message_id를 primary key로 둔 것도 같은 이유다. 어떤 코드 경로도 실수로 새 id를 붙일 수 없다.
lease
status IN ('PENDING','AMBIGUOUS','IN_FLIGHT')
AND (lease_expires_at IS NULL OR lease_expires_at <= now)
AND next_attempt_at <= now
AND attempts < maxAttempts
AND (ordering_key IS NULL
OR 같은 destination·ordering_key의 더 오래된 미완료 row가 없음)
ordering_key가 있는 row는 같은 key의 더 오래된 row가 PENDING·AMBIGUOUS·IN_FLIGHT인 동안
claim되지 않는다. 이 조건이 없으면 두 relay가 같은 key의 두 row를 나눠 가져가거나, AMBIGUOUS로
재시도되는 row보다 뒤의 row가 먼저 나간다(OutboxPostgresIT#aNewerRowWaitsWhileAnOlderRowWithTheSameOrderingKeyIsUnfinished).
V1005의 partial index가 이 확인을 받친다. 더 오래된 row가 FAILED·EXHAUSTED가 되면 뒤의 row는
진행한다.
IN_FLIGHT가 목록에 있는 것이 핵심이다. relay가 publish 도중 죽으면 row는 IN_FLIGHT로 남는데,
이를 제외하면 그 메시지는 영원히 발행되지 않는다 — outbox가 막으려던 바로 그 실패다. 대신
lease가 만료됐을 때만 회수하므로, 살아 있는 relay가 들고 있는 row는 회수되지 않는다.
회수는 같은 message_id로 이루어지고 lease_token이 1 증가한다. 새 id를 발급하면 "전달됐을
수도 있는 메시지"가 "확실히 두 번째"가 되기 때문이다 (위의 AMBIGUOUS 논의와 같은 이유).
이 문단의 근거는 실제 PostgreSQL 컨테이너 레인이다:
OutboxPostgresIT#anExpiredLeaseBecomesClaimableAgain— 만료된 lease의 재회수OutboxPostgresIT#anExpiryReclaimKeepsTheMessageIdAndAdvancesTheToken— 같은 id, 증가한 tokenOutboxPostgresIT#aLeasedRowIsInvisibleToASecondRelayInstance— 살아 있는 lease는 회수 불가OutboxPostgresIT#aSupersededRelayCannotOverwriteTheOutcomeOfTheOneThatReplacedIt— fencing
partial index ix_messaging_outbox_claimable이 이 쿼리를 backlog 크기에 비례하게 유지한다.
PUBLISHED row는 retention job이 지울 때까지 쌓이기 때문이다.
Inbox
reservation과 side effect가 같은 transaction이어야 한다.
transactions.inTransaction(() -> {
if (!inbox.reserve(messageId, consumerId, now)) {
return InboxOutcome.duplicate(); // 이미 처리됨
}
return InboxOutcome.processed(sideEffect.get());
});
별도 transaction으로 예약하면 Inbox가 닫으려던 바로 그 창이 다시 열린다.
소비와 연결 (소유자 결정 10)
consume 계약은 MessageHandler<T> 하나다. handler를 bean으로 등록하면 messaging-spring-boot-starter-kafka가
그 handler가 가리키는 destination마다 Kafka consumer를 연다(app.messaging.enabled=false면 없다).
- destination profile이
guarantees.external-side-effect: INBOX_TRANSACTIONAL이면 platform이 handler를InboxMessageHandler로 감싼다. 예약과 handler의 쓰기가 같은 transaction에서 commit되고, 이미 예약된 message는 handler를 부르지 않고Success로 settle한다. 이 경우 애플리케이션이IdempotentConsumerbean(inbox repository + transaction runner)을 둬야 하며, 없으면 기동이 실패한다. - inbox의 consumer 식별자와 Kafka
group.id는 destination의consumer.group이다. 없으면 기동이 실패한다. - offset은 handler가
Success로 답하고 (inbox destination이면) 그 transaction이 commit된 뒤에만, 또는 DLQ 토픽 기록이 확인된 뒤에만 넘어간다. auto-commit은 쓰지 않는다. Retry·예외·timeout은retry.max-attempts까지 partition을 멈추고 다시 읽으며, 다 쓰면 DLQ 토픽에 원본 record를 남기고 넘어간다. DLQ가 없는 destination(at-most-once)은 넘어가지 않고 멈춘다.Reject는 at-most-once destination에서만 버리고, 그 밖에서는 dead letter로 보낸다.
실제 왕복·중복 제거·DLQ는 MessagingKafkaConsumeQualificationTest(Kafka + PostgreSQL Testcontainers)가 확인한다.
애플리케이션 경로(앱 outbox relay가 발행 → adapter:inbound:messaging이 조립한 inbox와 JPA 트랜잭션 →
handler)의 중복 전달·실패 재처리는 InboxRedeliveryIntegrationTest(lane
messagingInboxRedeliveryIntegrationTest)가 확인한다.
복합 키
PRIMARY KEY (message_id, consumer_id).
message_id만으로 중복 제거하면 같은 event를 소비하는 두 번째 consumer가 첫 번째에 의해 억제된다. 각 consumer가 한 번씩 처리해야 한다.
retention
broker의 최대 redelivery window보다 길어야 한다. row를 먼저 지우면 늦게 도착한 redelivery가 두 번 처리된다.
outbox·inbox cleanup job은 한 번에 최대 1,000행씩 지우고, 지운 수가 1,000보다 적으면 멈춘다. repository port에는 개수 제한 없는 삭제 메서드가 없다.
CDC 대안
relay는 polling 하나뿐이다. Debezium Event Router 매핑(DebeziumOutboxEventRouter 등)은 조립하는
곳이 없어 2026-09-25에 삭제했다(docs/capability-status.md 제거 표). messaging_outbox의
routing_key 컬럼은 남아 있으므로 CDC를 다시 들일 때 그 컬럼을 message key로 쓴다.
Claim Check
1 MiB 초과 payload는 broker 프레임을 키우지 않고 외부 저장소로 offload한다.
ClaimCheckReference는 digest를 필수로 가진다. claim check는 메시지를 서로 다른 retention과
replication을 가진 두 시스템으로 쪼개므로, consumer는 producer가 저장한 바로 그 bytes를 받았음을
증명할 수 있어야 한다. 그렇지 않으면 잘린 객체와 정상 객체를 구분할 수 없다.
ClaimCheckIntegrityGuard는 fetch 전에 만료를, fetch 후에 크기와 digest를 검사한다.
digest 불일치는 DESERIALIZATION이 아니라 validation 실패로 분류한다.
bytes가 깨진 JSON인 게 아니라, 틀린 bytes이기 때문이다.