refactor: 리펙토링 진행중 의존성 gradle은 얇게 유지, 각 모듈에서 처리하고 있는 부분에 대해서 리펙토링
This commit is contained in:
@@ -90,6 +90,8 @@ app:
|
||||
order-events-dlq:
|
||||
broker: kafka-primary
|
||||
kind: WORK_QUEUE
|
||||
guarantees:
|
||||
delivery: AT_MOST_ONCE # terminal DLQ: another DLQ is not required
|
||||
physical:
|
||||
topic: order.events.v1.dlt
|
||||
schema:
|
||||
@@ -121,6 +123,12 @@ app:
|
||||
| metric dimension 상한 | 200 | cardinality 폭발 방지 |
|
||||
|
||||
`schema.codec`은 `application/json`, `schema.compatibility`는 `BACKWARD_TRANSITIVE`,
|
||||
|
||||
> **현재 강제 범위:** `schema.compatibility` 값은 현재 정책 선언이며 runtime/CI에서 schema registry를
|
||||
> 조회해 호환성을 차단하지 않는다. Avro 비교기는 독립 utility/test로만 존재한다. 따라서 이 값을
|
||||
> 설정했다고 breaking schema가 자동 거부된다고 해석하면 안 된다. 실제 registry gate가 wiring되기
|
||||
> 전까지 호환성은 adopter의 schema CI가 소유한다.
|
||||
|
||||
`guarantees.delivery`는 `AT_LEAST_ONCE`, `retry.mode`는 `NONE`이 기본값이다. 자동 retry가 기본으로
|
||||
꺼져 있는 이유는 순서를 흐트러뜨리거나 비멱등 side effect를 두 번 실행하는 retry가 눈에 보이는
|
||||
실패보다 나쁘기 때문이다.
|
||||
|
||||
@@ -88,10 +88,23 @@ consumer recovery가 동시에 나빠지고, 유계·검증 가능한 실패가
|
||||
## DB 마이그레이션
|
||||
|
||||
```text
|
||||
V1__messaging_outbox.sql
|
||||
V2__messaging_inbox.sql
|
||||
V1001__messaging_outbox.sql
|
||||
V1002__messaging_outbox_lease_fencing.sql
|
||||
V1003__messaging_admin_operation_journal.sql
|
||||
V1004__messaging_outbox_canonical_metadata.sql
|
||||
V1101__messaging_inbox.sql
|
||||
```
|
||||
|
||||
Messaging owns Flyway versions `1000..1999`. The starter assembles both JDBC reliability modules,
|
||||
so their migrations deliberately share `classpath:db/migration/messaging` but must never reuse a
|
||||
version. Keeping them in this reserved range also prevents collisions with the application's
|
||||
ordinary `db/migration/postgresql` stream, whose low-numbered versions are independent.
|
||||
|
||||
When adopting outbox/inbox persistence, add `classpath:db/migration/messaging` to the deployment's
|
||||
Flyway locations together with its normal application migration location. Do not copy or renumber
|
||||
these files into the application's low-numbered stream; the reserved range is the namespace
|
||||
boundary.
|
||||
|
||||
Outbox row는 business transaction과 같은 transaction에서 쓴다.
|
||||
Inbox reservation은 handler side effect와 같은 transaction에서 쓴다.
|
||||
별도 transaction이면 각 패턴이 닫으려던 창이 그대로 열려 있다.
|
||||
|
||||
@@ -9,6 +9,22 @@
|
||||
|
||||
**둘 다 필요하다.** Outbox만으로는 exactly-once가 되지 않는다.
|
||||
|
||||
## 채택할 때 먼저 적용할 DB migration
|
||||
|
||||
Outbox/Inbox JDBC 모듈의 DDL은 `classpath:db/migration/messaging`에 있다. Messaging은
|
||||
Flyway version `1000..1999`를 예약해서 애플리케이션의 일반적인 저번호 migration과 버전이
|
||||
겹치지 않게 한다.
|
||||
|
||||
배포에서 이 JDBC 구현을 채택할 때는 기존 Flyway location에 다음 location을 **추가**한다.
|
||||
|
||||
```text
|
||||
classpath:db/migration/messaging
|
||||
```
|
||||
|
||||
현재 순서는 `V1001..V1004`(outbox/admin)와 `V1101`(inbox)이다. starter 테스트가 두 JDBC
|
||||
모듈을 실제 combined classpath로 올려 version 중복과 예약 대역 이탈을 검사한다. 개별 DDL의
|
||||
의미와 전환 순서는 [migration-guide.md](migration-guide.md)를 따른다.
|
||||
|
||||
## Outbox
|
||||
|
||||
business transaction과 **같은 transaction**에서 row를 쓴다. 둘 다 commit되거나 둘 다 안 된다.
|
||||
|
||||
@@ -20,18 +20,17 @@
|
||||
> `FOR UPDATE SKIP LOCKED`, `ON CONFLICT`, `TIMESTAMPTZ`)이므로, 그 이름은 쓰지 않는 기술을
|
||||
> 광고하고 vendor 중립 port(`messaging-reliability-api`)의 위치를 가렸다 (MSG-023).
|
||||
>
|
||||
> 또한 registry의 messaging leaf는 모두 `runtime_memberships`가 비어 있다. 이는 **build-only /
|
||||
> incubating** — 어느 composition root에도 편입되지 않았다는 뜻이며, 아래의 등급과는 다른 축이다.
|
||||
> 등급은 "무엇이 증명되었는가", membership은 "무엇이 실행되는가"를 말한다. 애플리케이션에 배선하려면
|
||||
> registry를 먼저 바꾸고 `verifyRuntimeModuleMembership`을 통과시켜야 한다. 자세한 규칙은
|
||||
> `src/messaging/CLAUDE.md`가 소유한다.
|
||||
> `modules.json`은 messaging leaf의 `gradle_path`와 허용 의존성을 관리하지만
|
||||
> `runtime_memberships` 필드는 없다. 실제 런타임 편입은 `app-bootstrap`의 Gradle 의존성과 starter /
|
||||
> auto-configuration 경로가 결정한다. 아래 등급은 "무엇이 증명되었는가"를 말하며 런타임 편입 여부와
|
||||
> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/messaging/CLAUDE.md`가 소유한다.
|
||||
|
||||
## 브로커 등급
|
||||
|
||||
| 브로커 | 등급 | 인증 기준 | Stable 기능 | 제한 |
|
||||
|---|---|---|---|---|
|
||||
| Kafka | Stable | 4.1.x | producer idempotence, consumer group, batch, pause/resume, replay, transaction capability | Share Group은 Experimental |
|
||||
| RabbitMQ | Experimental | 4.3.x | exchange/routing, publisher confirm, mandatory return, manual ACK, quorum queue, retry queue, DLQ | 장애 시나리오 레인 미실행 — 증거 없음. stream 및 특수 plugin 미지원 |
|
||||
| RabbitMQ | Experimental | 4.3.x | exchange/routing, publisher confirm, mandatory return, manual ACK, quorum queue, retry queue, DLQ | **현재 starter에서 선택 불가** — production `RabbitChannelPublisher`/transport bridge가 없어 `app.messaging.broker=rabbit`은 startup에서 거부된다. 장애 시나리오 증거도 아직 없음 |
|
||||
| Pulsar | Experimental | 4.0 LTS + 4.2 | typed publish/consume, Shared, Key_Shared, schema | transaction 미승격, 기본 비활성 |
|
||||
| NATS JetStream | Experimental | 2.14.x | stream, durable consumer, explicit ACK, dedupe, replay | native DLQ 없음(플랫폼이 대행), 기본 비활성 |
|
||||
| Artemis/JMS | Extension | 범위 밖 | adapter SPI만 | 별도 ADR + Contract Suite 통과 필요 |
|
||||
@@ -153,3 +152,23 @@ delivery timeout으로 나타난다. 이를 `REJECTED`로 보고하는 것은
|
||||
- 운영 application에서의 topology 파괴 작업
|
||||
- 일반 애플리케이션에 raw broker client 반환
|
||||
- DLQ publish 확인 전 source ACK
|
||||
|
||||
|
||||
## R1 compiler status
|
||||
|
||||
`adapter:outbound:messaging`의 contract/catalog/envelope compiler 군은 현재 **의도적으로 미배선**이다.
|
||||
`DISABLED` + 빈 catalog/binding이 zero-resource 상태이며, 이 R1 compiler를 legacy
|
||||
`MessagingConfig`에 연결해 Kafka ACK, wire compatibility, `ACTIVE_READY`, R2 qualification을
|
||||
주장하지 않는다. 코드는 다음 세대 계약을 보존하지만 현재 채택 경로가 아니며, 실제 활성화는 별도 R2
|
||||
composition/cutover에서 명시적으로 이뤄져야 한다.
|
||||
|
||||
|
||||
### Optional mapping / bridge utilities
|
||||
|
||||
- `messaging-cloudevents`는 starter runtime에 자동 편입되지 않는 **opt-in mapping utility**다.
|
||||
내부 envelope와 CloudEvent 객체 사이의 제한된 profile mapping을 제공하지만 binary/structured
|
||||
CloudEvents wire mode 전체를 구현하거나 임의 CloudEvents producer와의 1.0 interoperability를
|
||||
인증하지 않는다.
|
||||
- `messaging-spring-cloud-stream-bridge`는 현재 `ChannelSend` seam과 publish-evidence 판단을 제공하는
|
||||
framework-neutral bridge contract다. Spring Cloud Stream `StreamBridge` dependency/auto-configuration은
|
||||
제공하지 않으므로 shipped Spring Cloud Stream integration으로 분류하지 않는다.
|
||||
|
||||
Reference in New Issue
Block a user