---
kind: CONCEPT
slug: messaging-core-api-c03
title: 예약 네임스페이스를 봉투 필드와 헤더 전용으로 쪼갠다
topic: state-machines-and-ownership
project: clean-architecture-backend-template
status: 게시 전
sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
rootTreeNode: concept:messaging-core-api-c03
evidenceCapturedOn: 2026-09-01
assets:
  - key: messaging-core-api-c03
    file: ../../../final/evidence/rendered/messaging-core-api-c03.svg
evidence:
  - ../../../final/evidence/raw/messaging-core-api-c03.txt
source:
  - 원본 분석 절은 final/document.md#a19-messaging-core-api#L123 이다.
module: messaging-core-api
---

# 예약 네임스페이스를 봉투 필드와 헤더 전용으로 쪼갠다

`MessageEnvelope<T>`가 중심이고 나머지 11개가 그 필드 타입이다. `ReservedHeaders`의 23개 이름을 `CanonicalEnvelopeHeaders`가 둘로 쪼갠다.

## 본문

<!-- body:start -->

`MessageEnvelope<T>`가 중심이고 나머지 11개가 그 필드 타입이다. 봉투는 불변이고 네 가지 파생 메서드가 있다 — `withPayload`, `withContentType`, `withTenant`, `withHeaders`. 넷 다 `messageId`를 복사한다.

> "Encoding, decoding, Claim Check offloading, and DLQ forwarding all need this, and every one of them must keep `messageId()` intact — which is exactly what this method guarantees by construction" (`MessageEnvelope.java:80-82`)

## UuidV7 참조 위치

:::evidence key="messaging-core-api-c03" alt="코드베이스에서 UuidV7 를 검색한 출력 20줄. 이 기록이 세는 참조가 그 출력에 그대로 보인다." caption="UuidV7 코드베이스 검색 — 20줄 · exit 0" zoom="true"
:::

## 예약 네임스페이스가 둘로 쪼개진다

`ReservedHeaders`는 23개 이름 상수와 `msg.` **prefix 전체**를 소유한다. `CanonicalEnvelopeHeaders`는 그 예약 네임스페이스를 둘로 쪼갠다 — 봉투 필드가 이미 갖고 있는 15개(`ENVELOPE_FIELDS`)와, 봉투에 대응 필드가 없어서 헤더로만 이동할 수 있는 나머지 8개(`REDRIVE_ID`, `REDRIVE_COUNT`, `RETRY_ATTEMPT`, `FIRST_FAILURE_AT`, `LAST_FAILURE_AT`, `FAILURE_CATEGORY`, `FAILURE_CODE`, `ORIGIN_DESTINATION`).

## 목적지 쪽 어휘

`MessageDestination<T>`, `DestinationName`, `DestinationKind`(7), `MessagingCapabilities`(boolean 12), `DestinationCapabilities`, `ConfirmationRequirement`(3), `CapabilityRegistry`.

<!-- body:end -->