10 KiB
title, source_type, url, archive_url, related_branches, related_projects, tags, created
| title | source_type | url | archive_url | related_branches | related_projects | tags | created | ||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| official-doc / Spring for Apache Kafka — KafkaTemplate Send Result (SendResult, get(), flush()) | official-doc | https://docs.spring.io/spring-kafka/reference/kafka/sending-messages.html |
|
|
|
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."
[§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." | 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-forgetvoid가 아니라는 것)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")로만 서술하며 비동기 콜백을 먼저 제시한다.
- "messaging 포트가 SDK 타입(
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- 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 요약: (생성 시 링크)