Files
clean-architecture-backend-…/docs/manual/09-outbox-events.md
T
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 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
2026-11-11 22:15:42 +09:00

15 KiB

09. outbox·이벤트

핵심

업무 저장과 이벤트 발행을 같은 DB 트랜잭션에 묶는다. 유스케이스는 broker에 직접 보내지 않고, 이벤트를 outbox 테이블에 업무 행과 함께 쓴다. 별도 relay가 커밋된 outbox 행을 broker로 옮긴다.

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와 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 예약과 업무 쓰기를 한 트랜잭션에 묶어 효과를 한 번으로 만든다.

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가 빌드를 막는다.
    @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이 아니다.