llm-wiki/raw/official-docs/spring-kafka-sending-messages-kafkatemplate.md

---
title: official-doc / Spring for Apache Kafka — KafkaTemplate Send Result (SendResult, get(), flush())
source_type: official-doc
url: https://docs.spring.io/spring-kafka/reference/kafka/sending-messages.html
archive_url:
related_branches: [feature-kafka-producer-runtime-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, messaging, kafka]
created: 2026-07-28
---

# Spring for Apache Kafka — KafkaTemplate Send Result (SendResult, get(), flush())

> Layer: `raw/` — 외부 자료(공식 문서)의 **원문 발췌·출처 기록**.
> 문서 버전: Spring for Apache Kafka **4.1.0** reference — "Sending Messages" §"Using KafkaTemplate".

## source_type

`official-doc` — Spring for Apache Kafka 공식 reference 문서 (docs.spring.io).

## Parent / 활용 branch

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-kafka-producer-runtime-contract]] | ca-skeleton 의 messaging 포트가 `void send` 대신 acknowledgement-aware 한 전송 결과(broker 가 확인한 topic/partition/offset)를 반환해야 하는지, 그 결과 타입을 Spring/Kafka SDK 타입(`SendResult`)으로 노출할지 프로젝트 자체 값 타입으로 감쌀지 판단할 **메커니즘 근거**(반환 타입, 구성 property, 동기 대기 방법, flush 시맨틱, 실패 전달 방식) |

## 출처

- 원본 URL: https://docs.spring.io/spring-kafka/reference/kafka/sending-messages.html
- 아카이브 URL: (미제공)
- 저자 / 조직: Spring team (Broadcom / VMware Tanzu — Spring for Apache Kafka 프로젝트)
- 발행일: 명시 없음 (버전 4.1.0 reference, "Stable" 채널)
- 마지막 확인일: 2026-07-28

## 왜 저장했는지

`feature-kafka-producer-runtime-contract` 브랜치가 messaging 포트의 `send()` 반환 타입을 정할 때 필요한 **메커니즘 사실**(반환 타입이 무엇인지, 무엇을 담는지, 어떻게 동기 대기하는지, flush/실패가 어떻게 전달되는지)을 공식 문서에서 확보하기 위함. 단, "포트가 SDK 타입을 그대로 반환해도 되는가"라는 **아키텍처 판단 자체는 이 문서가 증명하지 않는다** — 이는 ca-skeleton 의 framework-neutral 포트 원칙(별도 canonical 근거)과 대조해서 branch 가 별도로 결정해야 한다.

## 핵심 인용

> [§Using KafkaTemplate — Overview, 코드 시그니처] "CompletableFuture<SendResult<K, V>> send(ProducerRecord<K, V> record);"

> [§Using KafkaTemplate, 서술문] "Notice that the send methods return a CompletableFuture<SendResult>."

> [§Using KafkaTemplate] "SendResult has two properties, a ProducerRecord and RecordMetadata."

> [§Using KafkaTemplate] "The Throwable can be cast to a KafkaProducerException; its producerRecord property contains the failed record."

> [§Using KafkaTemplate] "If you wish to block the sending thread to await the result, you can invoke the future’s get() method; using the method with a timeout is recommended."

> [§Using KafkaTemplate] "If you have set a linger.ms, you may wish to invoke flush() before waiting or, for convenience, the template has a constructor with an autoFlush parameter that causes the template to flush() on each send."

> [§Using KafkaTemplate] "Flushing is only needed if you have set the linger.ms producer property and want to immediately send a partial batch."

## Claims Extracted

| Claim ID | Claim | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| SPRING-KAFKA-SEND-C1 | `KafkaTemplate` 의 `send`/`sendDefault` 전 오버로드는 `CompletableFuture<SendResult<K, V>>` 를 반환한다 (`void` 반환이 아니다) | "CompletableFuture<SendResult<K, V>> send(ProducerRecord<K, V> record);" / "Notice that the send methods return a CompletableFuture<SendResult>." | `official-vendor-doc` | Spring for Apache Kafka 4.1.0 `KafkaTemplate.send()`/`sendDefault()` 전 오버로드 | future 가 **정확히 언제** 완료되는지(broker acks 시점, in-flight retry 종료 시점 등)는 본문이 명시적으로 진술하지 않는다 — "broker 가 확인한 결과"라는 timing 주장은 이 인용만으로 증명되지 않으며, Kafka producer 자체의 `acks` 설정 공식 문서로 별도 보강 필요 |
| SPRING-KAFKA-SEND-C2 | `SendResult<K,V>` 는 `ProducerRecord` 와 `RecordMetadata` 두 property 로 구성된다 | "SendResult has two properties, a ProducerRecord and RecordMetadata." | `official-vendor-doc` | `SendResult<K,V>` 타입의 구조 | 이 문장 자체는 `RecordMetadata` 가 partition/offset 필드를 갖는다고 명시하지 않는다(본문은 "See the Kafka API documentation for information about those objects" 로 위임). 또한 "포트가 이 SDK 타입을 그대로 반환해도 된다"는 아키텍처 판단은 증명하지 않는다 |
| SPRING-KAFKA-SEND-C3 | send 결과를 동기적으로 기다리려면 반환된 future 의 `get()` 을 호출하며, timeout 있는 오버로드 사용이 권장된다 | "If you wish to block the sending thread to await the result, you can invoke the future’s get() method; using the method with a timeout is recommended." | `official-vendor-doc` | `CompletableFuture<SendResult<K,V>>` 를 동기적으로 대기하는 호출 패턴 일반 | 이 문장은 조건부("if you wish to block")이며, blocking 이 기본 권장 패턴이라는 뜻은 아니다 — 같은 섹션은 `whenComplete` 비동기 콜백을 먼저 예시로 제시한다. 포트가 반드시 blocking 방식을 채택해야 한다는 근거는 아니다 |
| SPRING-KAFKA-SEND-C4 | `linger.ms` 를 설정한 경우 대기 전 `flush()` 를 명시 호출하거나 `autoFlush` 생성자 파라미터로 매 send 마다 자동 flush 할 수 있으며, flush 는 partial batch 를 즉시 보내고 싶을 때만 필요하다 | "If you have set a linger.ms, you may wish to invoke flush() before waiting or, for convenience, the template has a constructor with an autoFlush parameter that causes the template to flush() on each send." / "Flushing is only needed if you have set the linger.ms producer property and want to immediately send a partial batch." | `official-vendor-doc` | `KafkaTemplate` 의 `flush()` 메서드와 `autoFlush` 생성자 파라미터 | flush 호출이 다른 스레드(동일 producer 공유)에 지연을 유발할 수 있다는 성능 경고는 다른 섹션("Using DefaultKafkaProducerFactory")의 별개 진술이며 이 claim 범위 밖이다. graceful shutdown 시 flush 순서를 어떻게 강제할지는 이 문서가 규정하지 않는다 |
| SPRING-KAFKA-SEND-C5 | send future 가 예외로 완료되면 그 `Throwable` 은 `KafkaProducerException` 으로 캐스팅 가능하고, 그 `producerRecord` property 가 실패한 레코드를 담는다 | "The Throwable can be cast to a KafkaProducerException; its producerRecord property contains the failed record." | `official-vendor-doc` | `whenComplete` 콜백의 `ex` 인자, 또는 동기 `get()` 호출 시 `ExecutionException.getCause()` 로 관찰되는 실패 케이스 | 어떤 하부 원인(네트워크 오류, 브로커 거부, 직렬화 실패 등)들이 `KafkaProducerException` 으로 래핑되는지에 대한 전체 목록은 제공하지 않는다 |

### Strength 참고

모두 `official-vendor-doc` — Spring for Apache Kafka 는 Spring 프로젝트 공식 reference 문서이며 RFC/표준(`official-standard`)은 아니다.

## Usage Boundaries

- 이 자료가 직접 증명하는 것:
  - `SPRING-KAFKA-SEND-C1`: `send()`/`sendDefault()` 의 반환 타입이 `CompletableFuture<SendResult<K, V>>` 라는 것(즉 fire-and-forget `void` 가 아니라는 것)
  - `SPRING-KAFKA-SEND-C2`: `SendResult` 가 `ProducerRecord` + `RecordMetadata` 를 담는다는 구조적 사실
  - `SPRING-KAFKA-SEND-C3`: 동기 대기 방법이 `future.get()`(timeout 권장)이라는 것
  - `SPRING-KAFKA-SEND-C4`: `flush()`/`autoFlush` 의 존재와 사용 조건(`linger.ms` 설정 시 partial batch 즉시 전송)
  - `SPRING-KAFKA-SEND-C5`: 실패 시 예외가 `KafkaProducerException` + `producerRecord` 로 전달된다는 것
- 이 자료가 증명하지 **않는** 것:
  - **"messaging 포트가 SDK 타입(`SendResult`, `RecordMetadata`)을 그대로 반환해도 되는가" 라는 아키텍처 판단.** 이 문서는 Spring Kafka 라이브러리 사용법을 설명할 뿐, ca-skeleton 의 framework-neutral 포트 원칙과의 정합성은 다루지 않는다. `SendResult` 를 그대로 포트 반환 타입으로 노출할지, 프로젝트 자체 값 타입(예: `topic`/`partition`/`offset` 만 담는 record)으로 감쌀지는 branch 가 별도 canonical 근거(포트 설계 원칙 문서)로 결정해야 한다.
  - future 가 "broker ack 시점"에 정확히 완료된다는 timing 보장 — 본문은 이를 명시적으로 진술하지 않는다(§핵심 인용/C1 참조). 이 timing 주장은 Kafka producer 의 `acks` 설정 공식 문서로 별도 검증 필요.
  - `RecordMetadata` 가 정확히 어떤 필드(partition, offset, timestamp 등)를 갖는지 — 본문은 "Kafka API documentation" 을 참조하라고 위임할 뿐 필드를 나열하지 않는다.
  - blocking(`get()`)이 권장되는 기본 패턴이라는 것 — 문서는 조건부("if you wish to block")로만 서술하며 비동기 콜백을 먼저 제시한다.
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-skeleton 의 messaging 포트 인터페이스 원칙(SDK 타입 노출 금지 여부)을 규정하는 canonical 문서와 대조
  - `RecordMetadata` 의 실제 필드 목록 — Kafka client 공식 Javadoc/문서로 별도 인용 필요
  - `acks=all` 등 delivery semantics 설정이 이 future 의 완료 시점에 미치는 영향 — Kafka producer configs 공식 문서로 별도 인용 필요

## 메모

- 이 문서는 "무엇을 반환하는가/무엇을 담는가/어떻게 대기하는가"라는 **메커니즘** 근거이며, "무엇을 반환해야 하는가"라는 **설계 결정**의 근거가 아니다. branch-note 의 D-row 에서 이 구분을 유지할 것.
- 추가로 봐야 할 동일 출처 페이지: Kafka producer configs 공식 문서(`acks`, `enable.idempotence`, `delivery.timeout.ms`) — 같은 branch 의 다른 결정(acks=all + idempotent producer 설정)의 근거로 별도 raw 문서 필요.

## 관련

- 같은 주제 다른 official-doc: (아직 없음 — Kafka producer configs 공식 문서 추가 시 링크)
- 이 자료를 인용한 wiki 요약: (생성 시 링크)