Avro, Schema Registry 및 PostgreSQL을 사용한 Kafka 이벤트 기반 Spring Boot 애플리케이션 구축

Source: Dev.to

소개

Apache Kafka로 이벤트‑드리븐 시스템을 구축하고 있다면, 데이터 계약을 일찍부터 고민해야 합니다. 이 글에서는 다음을 활용한 실용적인 엔드‑투‑엔드 Spring Boot 예제를 보여줍니다:

• Apache Kafka
• Confluent Schema Registry
• Avro 직렬화
• PostgreSQL
• Docker Compose

전체 소스 코드는 글 말미에 링크된 저장소에서 확인할 수 있습니다.

왜 스키마 레지스트리 + Avro인가?

JSON은 작동합니다… 하지만 그렇지 않을 때도 있습니다. Kafka 기반 시스템에서 흔히 발생하는 문제:

• 프로듀서가 페이로드를 변경하면 컨슈머가 깨짐
• 스키마 버전 관리 부재
• 팀 간 데이터 계약이 불분명

Avro + 스키마 레지스트리는 다음과 같이 해결합니다:

• 스키마 호환성 강제
• 안전한 스키마 진화 허용
• 프로듀서와 컨슈머 분리

Architecture Overview

Client (Postman)
      |
      v
Spring Boot Producer (REST)
      |
      v
Kafka Topic (users.v1)
      |
      v
Spring Boot Consumer
      |
      v
PostgreSQL

• Producer는 POST /users 엔드포인트를 노출합니다.
• Payload는 Avro 레코드로 변환됩니다.
• 메시지는 Kafka에 게시됩니다.
• Consumer는 Avro를 역직렬화하고 데이터를 PostgreSQL에 저장합니다.

이 데모에 포함된 내용

• Spring Boot Kafka Producer (Avro)
• Spring Boot Kafka Consumer (Avro)
• Confluent Schema Registry
• Spring Data JPA를 사용한 PostgreSQL 영속성
• 역호환성을 갖춘 스키마 진화
• 로컬 개발을 위한 Docker Compose

로컬 설정 (Kafka + Schema Registry + PostgreSQL)

사전 요구 사항

• Java 21
• Maven
• Docker & Docker Compose

인프라 시작

docker compose up -d

시작된 서비스:

• Kafka → localhost:29092
• Schema Registry → (원본에서 주소가 생략됨)
• PostgreSQL → localhost:5432

애플리케이션 실행

Consumer

cd consumer-app
mvn spring-boot:run

Consumer는 users.v1 토픽을 수신하고 메시지를 PostgreSQL에 저장합니다.

Producer

cd producer-app
mvn spring-boot:run

Producer는 REST 엔드포인트를 노출합니다.

이벤트 생성

curl -X POST http://localhost:8080/users \
  -H "Content-Type: application/json" \
  -d '{
    "id": "u-1",
    "email": "user@test.com",
    "firstName": "John",
    "lastName": "Doe",
    "isActive": true,
    "age": 30
  }'

다음과 같은 결과를 확인할 수 있습니다:

• Avro 스키마가 등록(또는 검증)되었습니다
• 메시지가 Kafka에 발행되었습니다
• 컨슈머가 레코드를 PostgreSQL에 저장합니다

스키마 진화 (중요한 부분)

Avro는 규칙을 준수할 경우 안전한 진화를 허용합니다.

일반적인 단계:

1. 새로운 선택적 필드를 추가합니다.
2. 기본값을 제공합니다.
3. 호환성을 BACKWARD 로 유지합니다.

Schema Registry가 보장하는 내용:

• 기존 소비자는 계속 작동합니다.
• 새로운 생산자는 시스템을 깨뜨리지 않습니다.

이 데모는 장난감 예제가 아닌 실제 환경에서의 스키마 진화를 보여주기 위해 설계되었습니다.

Confluent Cloud 준비

이 프로젝트는 Spring 프로파일을 통해 Confluent Cloud를 지원합니다:

• SASL/SSL
• Schema Registry API 키
• use.latest.version=true
• auto.register.schemas=false

CI/CD 파이프라인에 최적입니다.

소스 코드

• Docker Compose 구성
• Avro 스키마
• 프로듀서 및 컨슈머 애플리케이션
• PostgreSQL 설정
• Postman 컬렉션

이 문서는 누구를 위한 것인가?

• Java 및 Spring Boot 개발자
• JSON을 넘어서는 Kafka 사용자
• 이벤트 기반 마이크로서비스를 구축하는 팀
• Schema Registry + Avro를 배우는 모든 사람

최종 생각

이는 간단한 hello‑world가 아니라 프로덕션 수준의 Kafka 예제입니다. 만약 다음에 대해 진지하게 생각한다면:

• 스키마 계약
• 하위 호환성
• 안전한 진화
• 실제 영속성

그러면 이 데모가 많은 시행착오를 줄여줄 것입니다.

도움이 되었다면 저장소에 별표를 달아 주세요. 혹은 포크해서 자신의 시스템에 맞게 적용하셔도 됩니다.