문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
199 lines
15 KiB
Markdown
199 lines
15 KiB
Markdown
# 09. outbox·이벤트
|
|
|
|
## 핵심
|
|
|
|
업무 저장과 이벤트 발행을 **같은 DB 트랜잭션**에 묶는다. 유스케이스는 broker에 직접 보내지 않고,
|
|
이벤트를 outbox 테이블에 업무 행과 함께 쓴다. 별도 relay가 커밋된 outbox 행을 broker로 옮긴다.
|
|
|
|
```text
|
|
use case ── tx.inWrite ─┬─▶ repository.save(aggregate) ┐ 한 커밋
|
|
└─▶ OutboxAppendPort.append(validated) ┘
|
|
▲
|
|
IntegrationEventDraft ──▶ IntegrationEventEncoderPort (계약으로 검증·인코딩)
|
|
|
|
(커밋 뒤, 따로) composition:outbox-relay ─▶ OutboxStorePort.claim(lease) ─▶ broker ─▶ 완료/재시도/DEAD
|
|
```
|
|
|
|
DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공하는 순간이 생긴다. outbox는 그 순간을
|
|
없앤다. 대가는 **적어도 한 번** 전달이다 — 소비자는 event id로 중복을 걸러야 한다.
|
|
|
|
정본: `src/application/core/README.md` 「계약 타입」(이벤트 타입 표). 메시징 라이브러리 쪽 정본은 그 repo의
|
|
[outbox-inbox.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/docs/messaging/outbox-inbox.md)와
|
|
[delivery-guarantees.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/docs/messaging/delivery-guarantees.md)다.
|
|
|
|
## 순서
|
|
|
|
1. 계약을 정한다: 계약 id(`<service>.<aggregate>.<event>`), 버전, payload record, JSON schema 파일과 해시.
|
|
예: `src/application/core/src/main/java/dev/caskeleton/application/operation/DurableOperationSubmittedContract.java`,
|
|
`src/application/core/src/main/resources/contracts/messaging/durable-operation.submitted/v1.schema.json`(해시는 계약 클래스 안).
|
|
2. payload record(`IntegrationPayload`)를 만든다.
|
|
3. 유스케이스의 `tx.inWrite` 안에서 저장 뒤 draft → encode → append. 예:
|
|
`SubmitDurableOperationUseCase`(application-core `operation`).
|
|
4. 계약 contribution을 조립에서 `@Bean`으로 등록한다. encoder는 컨텍스트의 계약 bean으로 만들어진다.
|
|
등록을 빠뜨리면 append 때 실패한다. 예: `DurableOperationAutoConfiguration.durableOperationSubmittedContract()`.
|
|
5. 테스트: 계약 contribution 테스트(해시 고정), 유스케이스가 append했는지(`InMemoryOutboxStore`),
|
|
소비자가 있으면 같은 event id를 두 번 받아도 효과가 한 번인지 보는 중복 제거 계약.
|
|
6. schema를 출시한다: `src/test/resources/contracts/released-payload-schemas.sha256`에 새 version 파일의
|
|
해시를 한 줄 더한다. 출시한 version 파일은 고치지 않는다 — 바뀌면 `ReleasedPayloadSchemaContract`
|
|
테스트가 실패한다. 필드를 바꾸는 변경은 새 version으로 낸다. 절차: `src/application/core/README.md`
|
|
"payload version 올리기".
|
|
|
|
## 판단 지점
|
|
|
|
### 도메인 이벤트가 필요한가, 통합 이벤트만인가
|
|
|
|
- **고르는 기준**: 같은 서비스 안에서 이 사실에 반응하는 코드가 있는가.
|
|
- **기본값**: 통합 이벤트만. 유스케이스가 저장 뒤 바로 payload를 만든다.
|
|
- **예외**: aggregate 안에서 일어난 사실을 여러 유스케이스가 같은 방식으로 내보내면 domain
|
|
`@DomainEvent` record를 두고 유스케이스가 그것을 payload로 옮긴다.
|
|
|
|
### payload에 무엇을 넣나
|
|
|
|
- **기본값**: id만(+ 소비자가 라우팅에 필요한 최소 값). 상태 전체를 넣으면 계약이 aggregate 변경마다 깨진다.
|
|
- **예외**: 소비자가 원 서비스를 다시 조회할 수 없는 경우(외부 파트너)는 필요한 상태를 넣고 버전을 올린다.
|
|
|
|
### event id·correlation·순서
|
|
|
|
draft는 `IntegrationEventDrafts.draft(contract, eventId, aggregate, order, occurredAt, requestCorrelationId, payload)`로
|
|
만든다(`src/application/core/src/main/java/dev/caskeleton/application/messaging/event/IntegrationEventDrafts.java`).
|
|
계약 id·payload 버전·목적지는 계약에서 오고, 기능이 정하는 것은 aggregate·순서·payload뿐이다.
|
|
`new IntegrationEventDraft<>(…)`를 직접 쓰면 빌드가 막는다(`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`).
|
|
예: `SubmitDurableOperationUseCase`.
|
|
|
|
- event id: 정규 소문자 UUIDv7, 소비자 중복 제거 키. draft(`IntegrationEventDraft`)가 다른 값(대문자,
|
|
v4, `event-1` 같은 문자열)을 거부하므로 업무 쓰기에서 바로 실패한다 — 커밋된 뒤 relay에서 DEAD가 되지
|
|
않는다. 같은 작업의 재시도가 같은 event id를 내야 하면(durable operation) 작업 id를 쓰고,
|
|
작업 id가 UUIDv7이 아니면 작업 id와 접수 시각에서 UUIDv7을 파생한다.
|
|
- correlation: 헬퍼가 정한다. 요청의 correlation id가 `IntegrationIdentity` 문법·길이에 맞으면 그것,
|
|
아니면 event id. 문법 밖 헤더가 업무 쓰기를 실패시키지 않는다. 값을 미리 검사해야 하면 문법을 베끼지
|
|
말고 `IntegrationIdentity.isCanonical(value, IntegrationIdentity.CORRELATION_MAX_LENGTH)`를 부른다
|
|
(aggregate id는 `AGGREGATE_ID_MAX_LENGTH`).
|
|
- tenant 범위: tenant가 없는 기능은 `IntegrationEventDrafts.SINGLE_TENANT_SCOPE`(`global`).
|
|
- aggregate 순서: `OutboxAggregateSequencePort.nextSequence(aggregate)`로 같은 `tx.inWrite` 안에서
|
|
받는다(V21 카운터, 커밋 순서를 따른다). 이벤트가 하나뿐인 aggregate는 `AggregateOrder.first()`. 발생
|
|
시각(벽시계)은 쓰지 않는다 — 서버 시계가 어긋나면 순서가 뒤집힌다. 벽시계 번호를 쓰던
|
|
서비스가 포트로 옮기면 V21 floor 덕분에 새 번호는 옛 번호 뒤에서 시작한다. 그래서 첫 번호가 1이
|
|
아니라 약 1.7×10¹⁵일 수 있다. 소비자는 번호를 "마지막으로 본 값보다 큰가"로만 비교하고 연속성을
|
|
가정하지 않는다. 비교는 aggregate identity(tenant scope 포함) 단위다. tenant scope를 바꾸는 배포는 옛
|
|
버전 인스턴스를 모두 멈춘 뒤 새 버전을 띄운다 — 섞여 돌면 새 scope의 번호가 옛 버전이 방금 쓴 번호보다
|
|
작을 수 있다(runbook `outbox-dead-letter.md` §8).
|
|
|
|
## relay와 실패
|
|
|
|
- relay는 `composition:outbox-relay`가 `new`로 조립해 스케줄러에만 준다. relay는 `@SystemInvoked`라 권한
|
|
선언이 없어서, bean이 되면 전송 계층이 **권한 검사 없이** 닿는다. 그래서 bean으로 등록하면
|
|
`PermissionEnforcementGuard`가 기동을 실패시킨다(07장 「시스템이 부르는 쓰기」).
|
|
- broker의 **재시도 가능한** 거부와 응답 없음은 DEAD가 아니라 backoff 재시도다. broker가 멈춰도 대량
|
|
DEAD가 되지 않는다(2026-11-01부터. 전에는 broker가 몇 분만 멈춰도 행이 대량으로 DEAD가 됐다). 대신
|
|
끝이 없다: 진짜 인증 오류, Kafka adapter가 이름을 모르는 broker 거부도 영원히 재시도된다. 행의 `last_failure_code`와 로그의 `error.reason`이 원인 코드를 남기고,
|
|
`outbox.retry.long.size`가 오래 재시도 중인 행을 센다. 처분(보류·재개·skip)은 publish-failed runbook
|
|
§4.1이다.
|
|
- 발행 응답을 못 받으면 결과 불명(`OutboxPublishAmbiguousException`) — 05장 규칙과 같다.
|
|
- 운영: `docs/runbooks/outbox-dead-letter.md`, `docs/runbooks/outbox-publish-failed.md`.
|
|
|
|
## 소비 — 이벤트를 받는 쪽
|
|
|
|
같은 메시지는 두 번 이상 올 수 있다. 소비 쪽은 **inbox 예약과 업무 쓰기를 한 트랜잭션**에 묶어 효과를
|
|
한 번으로 만든다.
|
|
|
|
```text
|
|
Kafka ─▶ platform consumer ─▶ (INBOX_TRANSACTIONAL이면) InboxMessageHandler
|
|
└─ 한 트랜잭션: messaging_inbox 예약 + handler ─▶ use case 쓰기
|
|
성공 → 커밋 → offset 커밋
|
|
예외·Retry → 예약과 쓰기가 함께 롤백 → 같은 메시지 재전달 → 다시 처리
|
|
이미 예약된 메시지 → handler를 부르지 않고 성공으로 넘김
|
|
```
|
|
|
|
### 순서
|
|
|
|
1. 조립에 한 줄 추가: `runtimeOnly project(':adapter:inbound:messaging')`(app-bootstrap). Kafka
|
|
capability(`adapter:outbound:messaging-kafka`)와 persistence-jpa가 함께 있어야 한다. 이 leaf가 inbox
|
|
저장소와 트랜잭션 runner를 서비스의 DataSource·트랜잭션 위에 조립한다.
|
|
2. inbox 테이블은 따로 만들지 않는다: 1번 줄의 leaf가 기동 중에 platform의
|
|
`db/migration/messaging/V1101__messaging_inbox.sql`을 자기 history 표(`flyway_messaging_inbox_history`)로
|
|
적용한다. `app.runtime.migration-on-startup=false`로 마이그레이션을 밖에서 돌리는 배포만 이 파일을 직접
|
|
적용한다.
|
|
3. destination을 선언한다: `guarantees.external-side-effect: INBOX_TRANSACTIONAL`, `consumer.group`,
|
|
`retry.mode`·`retry.max-attempts`, `dlq.destination`. 예: `src/adapter/inbound/messaging/README.md`.
|
|
4. 쓰기 use case와 handler를 만든다. 소비 스레드에는 인증이 없어서 `@RequiresPermission` use case는
|
|
매번 거부된다. 그래서 handler가 부르는 쓰기 use case는 `@SystemInvoked`이고, handler는 그 use case를
|
|
**직접 `new`로 만들어 혼자 들고 있는** `@SystemCaller`다(07장 「시스템이 부르는 쓰기」). 이 방법 하나만
|
|
기동 가드와 빌드 규칙을 모두 통과한다.
|
|
- use case: `@SystemInvoked(reason = ...)` + `@UseCaseCapability(WRITE, …, WRITE_REPOSITORY)`. 평소처럼
|
|
`tx.inWrite`로 쓰고, 바깥 inbox 트랜잭션에 합류한다. 업무 규칙은 여기에 둔다.
|
|
- handler(`MessageHandler<T>`): `adapter:inbound:messaging`(또는 서비스의 `..adapter.inbound.messaging..`
|
|
패키지)에 두고 `@SystemCaller(reason = ...)`를 단다. 생성자가 port를 받아 use case를 만든다.
|
|
delivery 하나를 use case 호출 하나로 바꾼다.
|
|
- bean은 handler 하나다. use case를 bean으로 등록하면 `PermissionEnforcementGuard`가 기동을 막는다.
|
|
표시 없이 use case에 의존하면 `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`가 빌드를 막는다.
|
|
|
|
```java
|
|
@SystemCaller(reason = "order-events 소비자: platform consumer 스레드만 부른다")
|
|
public final class OrderCreatedHandler implements MessageHandler<OrderCreatedEnvelope> {
|
|
private final ProjectOrderUseCase useCase; // @SystemInvoked, bean 아님
|
|
|
|
public OrderCreatedHandler(TransactionPort tx, OrderProjectionPort projections) {
|
|
this.useCase = new ProjectOrderUseCase(tx, projections);
|
|
}
|
|
// destination(), handle(delivery) → useCase.project(...)
|
|
}
|
|
|
|
@Bean // 이 leaf의 설정 클래스
|
|
OrderCreatedHandler orderCreatedHandler(TransactionPort tx, OrderProjectionPort projections) {
|
|
return new OrderCreatedHandler(tx, projections);
|
|
}
|
|
```
|
|
|
|
같은 쓰기를 사용자 요청(HTTP 등)도 부르면 use case를 둘로 나눈다. 사용자용은 `@RequiresPermission`,
|
|
소비용은 `@SystemInvoked`이고 업무 규칙은 domain에 둔다. payload는 다른 서비스가 보낸 입력이므로 use
|
|
case가 검증한다 — 권한 검사가 없다는 것이지 검증이 없다는 것이 아니다.
|
|
5. payload 타입을 정한다. 템플릿 relay가 보낸 메시지의 payload는 canonical envelope JSON 전체다
|
|
(`eventId`, `payload` 등). handler의 record는 그 모양이다. 등록 코드는 쓰지 않는다: handler의
|
|
`destination()`(계약 id, record class)과 `schemaVersions()`(읽는 payloadVersion, 기본 v1)가 decode
|
|
목록이 된다. 발행 쪽이 v2를 보내기 시작하면 handler가 `schemaVersions()`에 v2를 더한다 — 선언하지 않은
|
|
버전은 `SCHEMA_VERSION_NOT_REGISTERED`로 DLQ에 간다.
|
|
6. 테스트 본보기: `SystemInvokedConsumePathTest`(단위, 4단계 모양이 권한 가드 아래에서 기동하고 delivery가
|
|
use case에 한 번 닿는지, use case를 bean으로 두면 기동이 막히는지)와 `InboxRedeliveryIntegrationTest`
|
|
(lane `messagingInboxRedeliveryIntegrationTest`, 실제 Kafka + PostgreSQL, 같은 handler 모양). offset을
|
|
되감아 다시 전달해도, 처리 중 예외 뒤 재전달돼도 효과와 inbox 행이 하나인지 본다.
|
|
|
|
### 판단 지점
|
|
|
|
#### 멱등 키
|
|
|
|
- **기본값**: inbox가 message id(발행 쪽 event id)와 `consumer.group`으로 거른다. handler가 따로 할
|
|
일은 없다.
|
|
- `consumer.group`은 바꾸지 않는다. 이름이 바뀌면 이미 처리한 메시지도 처음 보는 것으로 본다.
|
|
- **예외**: 발행 쪽이 재시도마다 다른 event id를 낸다면 inbox가 못 거른다. 그때는 use case가 업무
|
|
키(주문 id + 상태 등)로 멱등하게 쓴다.
|
|
- 쓰기는 handler를 부른 스레드에서 끝낸다. 다른 스레드로 넘긴 쓰기는 inbox 트랜잭션 밖이다.
|
|
- 메일·외부 API 같은 DB 밖 부작용은 롤백되지 않는다. handler 안에서는 DB 쓰기와 outbox append만 하고,
|
|
외부 호출은 그 이벤트를 받는 별도 소비자가 한다.
|
|
|
|
#### inbox 보존 기간
|
|
|
|
- inbox 행은 broker가 같은 메시지를 다시 줄 수 있는 기간보다 오래 남아야 한다. 먼저 지우면 늦게 온
|
|
재전달이 효과를 한 번 더 낸다.
|
|
- **기본값**: `InboxRetentionPolicy` — 보존 7일, 재전달 창 1일. topic 보존 기간이나 offset을 되감는 운영
|
|
범위가 1일보다 길면 이 bean을 덮어쓴다. 너무 짧은 조합은 기동 때 `INBOX_RETENTION_TOO_SHORT`로 거부된다.
|
|
- 정리 job(`InboxCleanupJob`)은 bean만 있다. 어느 replica에서 언제 돌릴지는 서비스가 스케줄한다.
|
|
|
|
#### 실패 시 재처리
|
|
|
|
- handler가 예외를 던지거나 `Retry`로 답하면 예약과 쓰기가 함께 롤백되고, platform이 같은 메시지를
|
|
다시 준다. 다시 처리될 때 효과는 한 번이다.
|
|
- **기본값**: destination retry는 `NONE`(시도 1회)이라 실패하면 바로 DLQ로 간다. 일시 장애가 있는
|
|
소비자는 `retry.mode: PAUSE_PARTITION`과 `max-attempts`를 정한다. partition 순서는 유지된다.
|
|
- 다시 해도 소용없는 입력(검증 실패)은 예외 대신 `Reject`·`DeadLetter`로 답한다. 예외는 시도를 다 쓴
|
|
뒤에야 DLQ로 간다.
|
|
- DLQ가 없는 destination은 실패한 메시지 뒤에서 partition이 멈춘다. 운영 소비자는 DLQ를 둔다.
|
|
- offset을 되감아 다시 읽혀도 보존 기간 안의 메시지는 inbox가 건너뛴다.
|
|
|
|
## 지금 이해하면 되는 것
|
|
|
|
- 저장과 append는 같은 `tx.inWrite` 안.
|
|
- 계약(id·버전·schema·해시)을 먼저 정하고 계약 bean을 등록한다.
|
|
- 전달은 적어도 한 번. 소비자는 inbox(`INBOX_TRANSACTIONAL`)로 예약과 업무 쓰기를 한 트랜잭션에 묶는다.
|
|
- 실패한 처리는 예약까지 롤백되어 재전달에서 다시 처리된다. inbox 보존 기간은 재전달 창보다 길게.
|
|
- 소비 handler = `@SystemCaller` + `@SystemInvoked` use case를 직접 `new`. use case는 bean이 아니다.
|