백엔드 데이터 인프라 90편 — Kafka API 5종 종합 (Producer · Consumer · Streams · Connect · Admin)

이 글은 백엔드 데이터 인프라 시리즈 130편 중 90편이에요. Part 5-2 Design 7편 으로 Kafka 의 내부 설계 를 잡았다면, 이번 90편부터는 Part 5-3 — Kafka API (4편). 첫 글은 5가지 API 의 자리 를 한눈에 — 다음 91~93편의 Producer / Consumer / Admin 깊이 전 큰 그림.

Kafka API가 어렵게 느껴지는 이유

API 가 다섯이고 각각의 역할도, 의존성도 다르다. 거기에 Connect 와 client 처럼 이름까지 비슷한 게 섞여 있어 처음 보면 헷갈리기 쉬워요.

첫째, 5가지 API 의 정확한 분담. 언제 어느 걸 쓸지가 명확해야 의존성·아키텍처 설계 가능.

둘째, kafka-clients vs kafka-streams 의존성. 같은 clients 아래 묶여 있지만 별도 의존성. Connect 도 별도.

이 글에서는 5가지 API 의 자리·의존성과, 다음 글들에서 깊이 풀어낼 영역까지 한 번에 잡아둡니다.

Kafka 5가지 핵심 API

핵심 — Producer / Consumer / Admin 은 같은 kafka-clients (Kafka 공식 Java 클라이언트 라이브러리) 의존성. Streams 와 Connect 는 별도.

API 별 자리 — 결정 가이드

나는 무엇을 하려나?
├─ 애플리케이션에서 Kafka 에 메시지 보냄
│   └─ Producer API
├─ 애플리케이션에서 Kafka 메시지 받음
│   └─ Consumer API
├─ Kafka 안에서 stream 처리 (topic A → 변환 → topic B)
│   └─ Streams API
├─ 외부 시스템 (DB·S3·Elasticsearch) ↔ Kafka 연결
│   └─ Connect API (보통 pre-built connector 사용)
└─ Topic 생성·삭제·ACL 관리 (운영 자동화)
    └─ Admin API

대부분의 백엔드 = Producer + Consumer 만. Streams·Connect·Admin 은 특수 자리.

1. Producer API

의존성

<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-clients</artifactId>
    <version>4.0.2</version>
</dependency>

가장 단순한 사용

Properties props = new Properties();
props.put("bootstrap.servers", "localhost:9092");
props.put("key.serializer", "org.apache.kafka.common.serialization.StringSerializer");
props.put("value.serializer", "org.apache.kafka.common.serialization.StringSerializer");

try (KafkaProducer<String, String> producer = new KafkaProducer<>(props)) {
    producer.send(new ProducerRecord<>("orders", "user42", "buy item"));
}

깊이 = 91편 Producer API.

2. Consumer API

의존성

같은 kafka-clients.

가장 단순한 사용

Properties props = new Properties();
props.put("bootstrap.servers", "localhost:9092");
props.put("group.id", "order-workers");
props.put("key.deserializer", "org.apache.kafka.common.serialization.StringDeserializer");
props.put("value.deserializer", "org.apache.kafka.common.serialization.StringDeserializer");

try (KafkaConsumer<String, String> consumer = new KafkaConsumer<>(props)) {
    consumer.subscribe(Arrays.asList("orders"));
    while (true) {
        ConsumerRecords<String, String> records = consumer.poll(Duration.ofMillis(1000));
        for (ConsumerRecord<String, String> record : records) {
            System.out.println(record.key() + " -> " + record.value());
        }
    }
}

깊이 = 92편 Consumer API.

3. Streams API

의존성

<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-streams</artifactId>
    <version>4.0.2</version>
</dependency>

kafka-streams 는 kafka-clients 와 별도 의존성이에요. 내부적으로는 producer + consumer 를 활용하지만, 그 위에 stream 처리 전용 추상화 를 한 겹 더 얹은 API.

가장 단순한 사용

StreamsBuilder builder = new StreamsBuilder();
KStream<String, String> input = builder.stream("input-topic");

input.mapValues(value -> value.toUpperCase())
     .to("output-topic");

KafkaStreams streams = new KafkaStreams(builder.build(), props);
streams.start();

StreamsBuilder 는 stream topology 를 선언적으로 짓는 빌더, KStream 은 토픽을 흐르는 레코드 스트림 추상이에요. 위 코드는 input-topic 의 모든 메시지를 uppercase 로 변환해 output-topic 으로 흘려보냅니다. 상태 저장·windowing (시간 구간 단위 집계)·조인 같은 풍부한 패턴까지 지원.

깊이 = 121~129편 Part 5-10 Streams (9편).

4. Connect API

두 가지 사용 모드

(A) Pre-built Connector 사용 (대부분)

# Docker 로 Kafka Connect 실행
$ docker run -d --name connect \
    -e CONNECT_BOOTSTRAP_SERVERS=localhost:9092 \
    confluentinc/cp-kafka-connect:latest

# REST API 로 connector 등록
$ curl -X POST -H "Content-Type: application/json" \
    --data '{
      "name": "jdbc-source",
      "config": {
        "connector.class": "io.confluent.connect.jdbc.JdbcSourceConnector",
        "connection.url": "jdbc:postgresql://...",
        "topic.prefix": "pg-"
      }
    }' \
    http://localhost:8083/connectors

코드 없이 설정만으로 PostgreSQL → Kafka 데이터 동기화. 가장 일반적.

(B) Custom Connector 작성

<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>connect-api</artifactId>
    <version>4.0.2</version>
</dependency>

connect-api 는 직접 connector 를 짤 때 쓰는 의존성이에요.

public class MyConnector extends SourceConnector {
    // SourceConnector 또는 SinkConnector 구현
}

특수한 외부 시스템 연결 시. 깊이 = 117~120편 Part 5-9 Connect (4편).

5. Admin API

의존성

같은 kafka-clients.

가장 단순한 사용

Properties props = new Properties();
props.put("bootstrap.servers", "localhost:9092");

try (AdminClient admin = AdminClient.create(props)) {
    // Topic 생성
    NewTopic topic = new NewTopic("new-topic", 3, (short) 2);
    admin.createTopics(Collections.singletonList(topic)).all().get();

    // Topic 목록
    Set<String> topics = admin.listTopics().names().get();
    System.out.println(topics);

    // Topic 정보
    DescribeTopicsResult result = admin.describeTopics(Collections.singletonList("new-topic"));
    TopicDescription desc = result.allTopicNames().get().get("new-topic");
    System.out.println(desc.partitions().size());

    // Topic 삭제
    admin.deleteTopics(Collections.singletonList("new-topic"));
}

AdminClient 는 토픽·ACL (Access Control List, 접근 권한 목록)·broker 설정을 코드에서 제어하는 진입점이에요. 93편 Admin API 에서 깊이 — 운영 자동화 (provisioning (자원 사전 준비)·monitoring·security) 패턴까지.

언어별 클라이언트

여기서 시험 함정이 하나 있어요 — Kafka 공식 maintain 은 Java 클라이언트만. 다른 언어 클라이언트는 오픈소스 커뮤니티 maintain.

대부분의 클라이언트가 librdkafka (C 로 짠 Kafka 클라이언트 코어 라이브러리) 기반. Java 외 모든 언어가 librdkafka wrapper.

Confluent 클라이언트 vs 다른 오픈소스

• Confluent (Kafka 상용 배포사) 시리즈 = librdkafka 기반, 공식적 신뢰, schema registry (스키마 중앙 관리 서비스) 통합
• kafka-python·kafkajs 등 = pure-language 구현, 작은 환경 친화

새 프로젝트는 Confluent 시리즈 권장 (호환성 + 성능).

같은 의존성·다른 사용 패턴

핵심 — Producer / Consumer / Admin 이 같은 kafka-clients 의존성:

<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-clients</artifactId>
    <version>4.0.2</version>
</dependency>

한 의존성으로 3가지 API 모두 가능. Streams 와 Connect 만 별도 의존성.

Spring Boot 환경 — spring-kafka

Spring 환경에서는 raw kafka-clients API 직접 사용 X. spring-kafka 추상화:

<dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
</dependency>

// Producer
@Autowired
private KafkaTemplate<String, String> kafkaTemplate;

// Consumer
@KafkaListener(topics = "orders", groupId = "workers")
public void listen(String message) { ... }

// Streams
@Bean
public KStream<String, String> kStream(StreamsBuilder builder) { ... }

// Admin
@Bean
public NewTopic ordersTopic() {
    return TopicBuilder.name("orders").partitions(3).replicas(2).build();
}

KafkaTemplate 은 Producer 를 감싼 Spring 헬퍼, @KafkaListener 는 Consumer 를 메서드 단위로 선언하는 어노테이션이에요. 훨씬 깔끔. 130편 Spring Kafka 에서 깊이.

API 별 자주 쓰이는 자리

여기서 CDC 는 Change Data Capture — DB 변경분을 스트림으로 흘려보내는 패턴이에요.

한계·실무 함정

1. Streams 와 일반 Consumer 혼동

Streams 는 Consumer + Producer 위에 빌드된 추상화. Streams 안에서 Consumer API 직접 호출 X. 둘 중 하나 선택.

2. Connect 가 별도 인프라

Connect 는 자체 worker 프로세스. 애플리케이션과 분리 운영. 모니터링·scaling 별도.

3. Admin API 권한

ACL 환경에서 admin 작업 = 별도 권한 필요 (Cluster:Describe·Topic:Create 등). 운영 환경에서 제한된 admin 사용자.

4. 버전 호환성

Kafka client 4.0 은 broker 2.5+ 와 호환 (보통 forward compatible — 구버전 broker 가 신버전 client 를 받아주는 호환). 그러나 최신 기능 사용은 client 와 broker 모두 최신.

5. Java 외 클라이언트의 성숙도 차이

언어마다 feature gap (지원 기능 격차) 존재. 최신 Kafka feature 사용 전 해당 언어 client 지원 확인.

시험 직전 한 번 더 — Kafka API 함정 압축 노트

• 5가지 API = Producer · Consumer · Streams · Connect · Admin
• 같은 의존성 kafka-clients = Producer + Consumer + Admin
• 별도 의존성 — Streams (kafka-streams)·Connect (connect-api)
• Producer = 메시지 send, KafkaProducer<K,V> + send()
• Consumer = 메시지 read, KafkaConsumer<K,V> + subscribe + poll
• Streams = topic → 변환 → topic, StreamsBuilder + KStream
• Connect = 외부 시스템 통합, 대부분 pre-built connector + REST API
• Admin = topic·broker·ACL 관리, AdminClient.create()
• 공식 maintain = Java 클라이언트만
• 다른 언어 = 오픈소스 커뮤니티, 대부분 librdkafka 기반
• 인기 = Confluent 시리즈 (Python·Node·Go·C#·...)
• pure-language = kafka-python·kafkajs 등
• Spring Boot = spring-kafka 추상화
• KafkaTemplate·@KafkaListener·StreamsBuilder + @Bean NewTopic
• Producer / Consumer 가 대부분 백엔드의 90%
• Streams·Connect·Admin = 특수 자리
• Streams = Consumer + Producer 위 추상화, 둘 중 선택
• Connect = 자체 worker 프로세스, 분리 운영
• Admin = DevOps 자동화·CI/CD provisioning
• Admin 권한 = ACL 환경에서 별도 제한
• 함정 — Streams 와 Consumer 혼동
• 함정 — Connect 별도 인프라 모니터링·scaling
• 함정 — Java 외 client feature gap
• 함정 — 최신 기능은 client + broker 모두 최신 필요

공식 문서: Kafka APIs 에서 모든 API 의 javadoc 과 사양을 확인할 수 있어요.

시리즈 다른 편 (앞뒤 글 모음)

이전 글:

• 85편 — Kafka Design: Efficiency (Zero-Copy · Batch 압축)
• 86편 — Kafka Design: Producer (Partition 선택·ACK·Idempotent)
• 87편 — Kafka Design: Consumer (Pull · Consumer Group · Offset)
• 88편 — Kafka Message Delivery Semantics (at-most·at-least·exactly-once)
• 89편 — Kafka Replication (ISR · Leader Election · Unclean)

다음 글:

• 91편 — Kafka Producer API 깊이 (Serializer · Callback · Interceptor)
• 92편 — Kafka Consumer API 깊이 (Commit · Rebalance · Seek)
• 93편 — Kafka Admin Client API (Topic·ACL·Consumer Group 관리)
• 94편 — Kafka Broker 설정 30가지 (실무 핵심)
• 95편 — Kafka Topic 설정 (Retention · Compression · Cleanup)