clean-architecture-backend-template/docs/messaging/configuration-reference.md

설정 레퍼런스

Prefix. Every property below binds under app.messaging, which is the prefix the deployed runtime and the APP_MESSAGING_* environment variables already use. Earlier revisions of this page documented a bare messaging prefix and the starter bound backend.messaging; neither bound what this page describes, so a deployment configured from it changed nothing. A key under either of the old prefixes now fails startup with a message naming the key — see MessagingPrefixMigrationValidator.

Destination profile

app:
  messaging:
  destinations:
    order-events:
      broker: kafka-primary
      kind: EVENT_STREAM            # ASYNC_COMMAND | DOMAIN_EVENT | INTEGRATION_EVENT
                                    # | WORK_QUEUE | PUBLISH_SUBSCRIBE | EVENT_STREAM | REQUEST_REPLY
      tier: M1                      # M1 | M2 | M3
      physical:
        topic: order.events.v1
      schema:
        codec: application/json
        compatibility: BACKWARD_TRANSITIVE
        message-types: [order.created]
      guarantees:
        delivery: AT_LEAST_ONCE     # AT_MOST_ONCE | AT_LEAST_ONCE
        ordering: KEY               # NONE | DESTINATION | PARTITION | KEY
        external-side-effect: INBOX_TRANSACTIONAL
      producer:
        confirmation: REPLICATION_OR_PERSISTENCE_ACK
        timeout: 5s
        mandatory-routing: true
        idempotent: true
      consumer:
        group: order-projection
        concurrency: 6
        max-in-flight-per-ordering-unit: 1
        prefetch: 16
        handler-timeout: 30s
        manual-settlement: false
      retry:
        mode: PAUSE_PARTITION       # NONE | INLINE | BLOCKING | PAUSE_PARTITION
                                    # | RETRY_DESTINATION | BROKER_DELAYED
        max-attempts: 3
        initial-delay: 200ms
        max-delay: 2s
        multiplier: 2.0
        jitter: true
        ordering-impact: PRESERVE   # PRESERVE | ALLOW_REORDER
      dlq:
        destination: order-events-dlq
        max-redrive-count: 1
      payload:
        max-bytes: 1048576
        claim-check-threshold-bytes: 1048576
      key-resolver-configured: true
      production: true
      topology-auto-create: false

기본값

설정	기본값	근거
logical payload 최대	1,048,576 bytes	portability. 초과는 Claim Check
global hard 최대	8,388,608 bytes	어떤 destination도 넘을 수 없는 상한
header 총 크기	32,768 bytes
header 개수	64
header key	128 bytes	metric tag 안전
header value	4,096 bytes
publish timeout	5s
handler timeout	30s
graceful shutdown drain	30s
일반 destination retry	0회	자동 retry는 opt-in
DLQ redrive batch	100	한 번의 작업이 source를 덮치지 않게
Outbox relay batch	100
Outbox lease	30s
Outbox polling	500ms
metric dimension 상한	200	cardinality 폭발 방지

Broker profile

Kafka

app:
  messaging:
  brokers:
    kafka-primary:
      type: kafka
      stable: true
      production: true
      bootstrap-servers: [broker-1:9093, broker-2:9093]
      enable-idempotence: true      # stable에서 필수
      acks: all                     # stable에서 필수
      max-in-flight-requests-per-connection: 5   # 최대 5
      delivery-timeout: 30s
      enable-auto-commit: false     # 항상 금지
      tls-enabled: true             # production 필수
      authentication-enabled: true  # production 필수

RabbitMQ

app:
  messaging:
  brokers:
    rabbit-primary:
      type: rabbitmq
      stable: true
      production: true
      addresses: [rabbit-1:5671]
      publisher-confirms: true      # stable에서 필수
      publisher-returns: true       # stable에서 필수
      mandatory: true               # stable에서 필수
      confirm-timeout: 5s
      auto-ack: false               # 항상 금지
      prefetch: 16
      quorum-queues: true           # durable work queue 필수
      tls-enabled: true
      authentication-enabled: true

보안

app:
  messaging:
  security:
    kafka-primary:
      producer: { type: SASL_SCRAM, credential-id: kafka-producer }
      consumer: { type: SASL_SCRAM, credential-id: kafka-consumer }
      # admin은 application runtime에 설정하지 않는다
      hostname-verification: true
      access:
        publishable: [order-events]
        consumable: []
        administrable: []

Experimental / Optional

기본값은 전부 false다.

app:
  messaging:
  experimental:
    kafka-share: false
    pulsar: false
    nats: false
  bridge:
    spring-cloud-stream: false

Backpressure

app:
  messaging:
  backpressure:
    global-limit: 512
    per-destination-limit: 64      # global-limit 이하여야 한다

per-destination-limit > global-limit이면 global limit이 limit이 아니게 되므로 부팅에 실패한다.