Home on San Kim의 위키

1. 스케줄러 조사

Thu, 14 May 2026 00:00:00 +0900

배치 공통 플랫폼 구축 시 필요한 자동 스케줄링과 중복 실행 방지 솔루션을 비교·분석한다. 선택 기준은 Spring Batch와의 통합 난이도, 별도 인프라 필요 여부, 중복 실행 방지 메커니즘이다.

1. 핵심 요구사항#

요구사항	설명
자동 스케줄링	특정 시간에 Job 자동 실행 (cron 표현식)
중복 실행 방지	같은 Job이 동시에 2개 이상 실행되는 것 차단
런타임 변경	배포 없이 스케줄 cron 변경 가능 여부
인프라 비용	별도 서버/플랫폼 없이 애플리케이션 내장 가능 여부

2. 선택지별 분석#

2-1. `@Scheduled` + ShedLock#

Spring Batch App
├── @Scheduled(cron = "0 0 2 * * *") ← 스케줄
└── @SchedulerLock(name = "jobName") ← 중복 방지 (DB 락)

동작 원리

1. 초기설계

Tue, 12 May 2026 00:00:00 +0900

본 문서는 batch-common 공통 플랫폼의 패키지 구조와 각 기능 영역별 구현 목록 및 실제 구현 중 확인된 설계 결정 사항을 정리한다. 실제 코드는 /spring-batch-practice 저장소의 batch-common 모듈에 있다.

1. batch-common 실제 패키지 구조#

batch-common/
└── src/main/java/com/example/spring_batch_practice/
 │
 ├── core/ # 공통 인프라 (job 독립)
 │ ├── api/ # Admin REST API
 │ │ ├── BatchAdminController.java # GET/POST 엔드포인트
 │ │ ├── BatchJobService.java # 실행·중단·재시작·이력 조회
 │ │ └── dto/
 │ │ └── JobExecutionResponse.java # read/write/skip 집계 DTO
 │ │
 │ ├── error/
 │ │ └── BatchErrorConfig.java # Retry·Skip 정책 기본 빈
 │ │ # @ConditionalOnMissingBean → 잡별 재정의 가능
 │ │
 │ ├── item/
 │ │ ├── reader/
 │ │ │ ├── JdbcCursorReaderFactory.java # JdbcCursorItemReader 팩토리
 │ │ │ ├── JpaPagingReaderFactory.java # JpaPagingItemReader 팩토리
 │ │ │ └── MyBatisCursorReaderFactory.java # MyBatisCursorItemReader 팩토리
 │ │ └── writer/
 │ │ ├── JpaItemWriterFactory.java # JpaItemWriter 팩토리
 │ │ └── MyBatisBatchWriterFactory.java # MyBatisBatchItemWriter 팩토리
 │ │
 │ ├── listener/
 │ │ └── JobLoggingListener.java # 잡 실행 전후 로그 (시작·종료·소요시간)
 │ │
 │ └── partition/
 │ ├── RangePartitioner.java # ID 범위 기반 파티셔너 (JdbcTemplate 사용)
 │ └── PartitionStepHelper.java # 파티션 Step 정적 빌더
 │
 └── job/
 └── sample/ # 샘플 잡 (JPA vs MyBatis 비교용)
 ├── domain/
 │ └── Order.java # @Entity(name="BatchOrder"), @Table(name="orders")
 ├── mybatis/
 │ └── OrderMapper.java # @Mapper, SELECT/UPDATE/INSERT/DELETE
 ├── SampleJpaJobConfig.java # JpaCursorItemReader + JpaItemWriter
 └── SampleMyBatisJobConfig.java # MyBatisCursorItemReader + MyBatisBatchItemWriter

└── src/main/resources/
 ├── application.yaml
 ├── mapper/
 │ └── OrderMapper.xml # MyBatis SQL XML
 └── schema/
 ├── batch-schema-postgresql.sql # Spring Batch 메타 테이블 DDL (수동 관리)
 └── batch-schema-drop-postgresql.sql # 메타 테이블 DROP DDL

2. 의존성#

의존성	버전	용도
spring-boot-starter-batch	Boot 관리	배치 코어
spring-boot-starter-data-jpa	Boot 관리	JPA 리더·라이터
spring-boot-starter-web	Boot 관리	Admin REST API
spring-boot-starter-actuator	Boot 관리	헬스체크, 메트릭
mybatis-spring-boot-starter	3.0.4	MyBatis 자동구성 (`mybatis-spring` 포함 → 배치 클래스도 내장)
spring-cloud-starter-task	Cloud 관리	Task 메타 테이블
postgresql	Boot 관리	운영 DB
h2	Boot 관리	테스트 인메모리 DB
lombok	Boot 관리	보일러플레이트 제거
spring-batch-test	Boot 관리	`JobLauncherTestUtils`, `JobRepositoryTestUtils`

mybatis-spring-batch 별도 아티팩트는 존재하지 않는다. MyBatisCursorItemReader, MyBatisBatchItemWriter 등 배치 통합 클래스는 mybatis-spring (org.mybatis.spring.batch.*) 내에 포함되어 있으며, mybatis-spring-boot-starter를 추가하면 함께 제공된다.

Kafka 통합 테스트 — auto-offset-reset 미설정 시 메시지 유실

Mon, 11 May 2026 00:00:00 +0900

1. 문제#

Spring Boot + Testcontainers 기반 Kafka 통합 테스트에서 다음과 같은 실패가 반복 발생했다.

Wanted but not invoked:
orderEventConsumer.handle(<any OrderCreatedEvent>);
-> at com.example.order.kafka.OrderEventConsumer.handle(...)
Actually, there were zero interactions with this mock.

producer.publish() 로 메시지를 발행한 뒤 verify(consumer, timeout(5000).times(1)) 를 호출했지만, 컨슈머가 메시지를 수신하지 못했다.

영향 테스트:

OrderEventFlowTest.주문_이벤트_발행_후_컨슈머_수신()
OrderPubSubTest.여러_이벤트_연속_발행_모두_수신()
OrderIdempotencyTest.어노테이션_없을때_동일_eventId_두번_발행_두번_모두_처리() — latch.await(5s) timeout

2. 원인#

Race condition: 컨슈머의 파티션 할당보다 프로듀서의 발행이 먼저 완료된다.

[context 시작]
 ├─ producer bean 초기화 완료 (즉시)
 └─ consumer listener container 시작 → 백그라운드 스레드에서 join-group 진행 중

[test 메서드 실행 (context 준비 직후)]
 ├─ producer.publish() → 메시지 offset 0에 적재
 └─ consumer의 join-group이 아직 진행 중...

[몇 초 뒤]
 └─ consumer join-group 완료 → 파티션 할당
 → auto-offset-reset: latest (기본값)
 → 최신 offset = 1 (메시지 다음 위치)
 → offset 0의 메시지를 건너뜀 → 유실

실제 로그:

1. Colima — Mac Docker 환경 설정

Sun, 10 May 2026 00:00:00 +0900

Mac에서 Docker Desktop 없이 컨테이너를 실행하려면 Colima를 쓴다.
Colima는 Apple Silicon/Intel 모두 지원하며, Docker Desktop보다 가볍다.

1. 엔터프라이즈 환경에서 Colima를 쓰는 이유#

Docker Desktop 라이선스 제한#

Docker Desktop은 2022년부터 상업적 사용에 유료 구독을 요구한다.

무료 사용 조건 (모두 충족해야 함)

직원 수 250명 미만 AND

연 매출 $10M(약 130억 원) 미만

위 조건 중 하나라도 벗어나면 유료 플랜(Team/Business) 필요

“CLI만 쓰면 괜찮지 않나?”#

아니다. 라이선스는 GUI 사용 여부가 아니라 Docker Desktop 소프트웨어(데몬 + VM) 실행 기준이다.

1. Gradle 기초 개념

Sun, 10 May 2026 00:00:00 +0900

Gradle은 JVM 기반 프로젝트의 빌드 자동화 도구다.
의존성 다운로드 → 컴파일 → 테스트 → 패키징 → 배포까지 일련의 과정을 자동화한다.

1. 핵심 구성 요소#

kafka-practice/
├── settings.gradle.kts ← 프로젝트 구조 정의 (무엇을 빌드할지)
├── build.gradle.kts ← 빌드 로직 정의 (어떻게 빌드할지)
├── gradle/
│ ├── libs.versions.toml ← 버전 카탈로그 (의존성 버전 관리)
│ └── wrapper/ ← Gradle Wrapper (팀 전체 동일 버전 보장)
├── gradlew ← Gradle Wrapper 실행 스크립트 (Unix)
└── gradlew.bat ← Gradle Wrapper 실행 스크립트 (Windows)

2. 주요 블록#

`plugins {}`#

빌드에 사용할 플러그인을 선언한다.
플러그인은 태스크(compileJava, test, jar 등)와 설정 옵션을 제공한다.

1. SNAPSHOT vs Release

Sun, 10 May 2026 00:00:00 +0900

Gradle/Maven 버전 관리의 핵심 구분.
버전 번호 뒤에 -SNAPSHOT이 붙는지 여부가 전부다.

1. 개념 비교#

	SNAPSHOT (`1.0.0-SNAPSHOT`)	Release (`1.0.0`)
재배포	가능 — 같은 버전으로 계속 덮어씀	불가 — 동일 버전 재배포 시 Nexus 오류
소비자 동작	Gradle이 매번 Nexus에서 최신본 재확인	로컬 캐시 고정
강제 최신화	`--refresh-dependencies`	불필요 (버전 올려서 재배포)
Nexus 레포	`maven-snapshots`	`maven-releases`
용도	개발 중 반복 배포	버전 확정 후 배포

개발 중: version = '1.0.0-SNAPSHOT'
 └── publish → maven-snapshots → 소비자가 매번 최신본 수신

릴리즈: version = '1.0.0'
 └── publish → maven-releases → 이후 동일 버전 변경 불가 (immutable)

2. Nexus 레포 구조#

Nexus 설치 시 기본 생성되는 3개 레포 (별도 생성 불필요):

2. Groovy DSL vs Kotlin DSL (.kts)

Sun, 10 May 2026 00:00:00 +0900

Gradle 빌드 스크립트는 두 가지 언어로 작성할 수 있다.
build.gradle (Groovy) vs build.gradle.kts (Kotlin).
Gradle 공식은 Kotlin DSL을 기본으로 전환했고(Gradle 8.x), 신규 프로젝트는 .kts가 표준이다.

1. 핵심 차이#

항목	Groovy DSL	Kotlin DSL (.kts)
타입	동적 타입	정적 타입
IDE 자동완성	부분적 (추론 실패 많음)	완전 지원 (IntelliJ 기준)
오타 검출 시점	런타임 (빌드 실행 시)	컴파일 타임
리팩터링	불안정	안정적 (rename, find usages 등)
빌드 캐시 히트율	높음	높음 (동일)
첫 빌드 속도	빠름	약간 느림 (스크립트 컴파일)
생태계 표준	레거시	신규 표준

2. 문법 비교#

플러그인 선언#

// Groovy
plugins {
 id 'org.springframework.boot' version '3.5.14'
 id 'java'
}

// Kotlin DSL
plugins {
 id("org.springframework.boot") version "3.5.14"
 java
}

의존성 선언#

// Groovy
dependencies {
 implementation 'org.springframework.boot:spring-boot-starter-web'
 testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

// Kotlin DSL
dependencies {
 implementation("org.springframework.boot:spring-boot-starter-web")
 testImplementation("org.springframework.boot:spring-boot-starter-test")
}

태스크 정의#

// Groovy
test {
 useJUnitPlatform()
}

// Kotlin DSL
tasks.withType<Test> {
 useJUnitPlatform()
}

3. Kotlin DSL의 실질적 이득#

IDE 자동완성#

dependencies {
 implementation(libs. // ← 여기서 Ctrl+Space → libs에 등록된 라이브러리 전체 목록 표시

Groovy에서는 문자열이라 IDE가 추론 불가. Kotlin DSL + Version Catalog 조합이 특히 강력하다.

8. Kafka UI — 토픽·메시지·모니터링

Sun, 10 May 2026 00:00:00 +0900

Kafka UI(Provectus)는 브라우저에서 Kafka 클러스터를 관리·모니터링할 수 있는 오픈소스 웹 대시보드다.
토픽 CRUD, 메시지 발행/조회, 컨슈머 그룹 추적, 브로커 상태까지 한 화면에서 확인할 수 있다.

1. 실행#

docker-compose#

services:
 kafka-ui:
 image: provectuslabs/kafka-ui:latest
 ports:
 - "8989:8080"
 environment:
 KAFKA_CLUSTERS_0_NAME: local
 KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:9092
 # Schema Registry 연동 (선택)
 # KAFKA_CLUSTERS_0_SCHEMAREGISTRY: http://schema-registry:8081
 # Kafka Connect 연동 (선택)
 # KAFKA_CLUSTERS_0_KAFKACONNECT_0_NAME: connect
 # KAFKA_CLUSTERS_0_KAFKACONNECT_0_ADDRESS: http://kafka-connect:8083
 depends_on:
 - kafka

브라우저에서 http://localhost:8989 접속.

멀티 클러스터#

환경변수 인덱스를 올려서 여러 클러스터를 동시에 등록할 수 있다.

1. ArgoCD 개념

Mon, 04 May 2026 00:00:00 +0900

ArgoCD 는 K8s 클러스터의 실제 상태를 git 에 적힌 manifest 와 일치시키는 GitOps continuous delivery 도구. 빌드는 안 한다 — 그건 CI 의 일이다. ArgoCD 의 일은 git 의 선언 을 클러스터의 실제 로 옮기는 것 단 하나. 출처: Argo CD docs — What Is Argo CD

GitOps 자체의 정의·배경·역사 (왜 push 모델에서 pull 로 왔는지) 는 DevOps/GitOps/1. GitOps — 정의·배경·역사 참조. 본 문서는 그 구체 구현체 인 ArgoCD 만 다룬다.

1. GitOps — 정의·배경·역사

Mon, 04 May 2026 00:00:00 +0900

GitOps 는 “인프라/애플리케이션의 desired state 를 git 에 선언하고, 클러스터 안의 에이전트가 git 을 pull 해서 actual state 를 지속적으로 일치시키는” 운영 방식. 본 문서는 GitOps 의 정의·해결하려는 문제, 그리고 어떻게 여기까지 왔는지 의 흐름을 정리한다. 출처: gitops.tech, OpenGitOps Principles

1. 정의 (gitops.tech 인용)#

“GitOps is a way of implementing Continuous Deployment for cloud native applications. … using Git as a single source of truth for declarative infrastructure and applications, together with tools ensuring the actual state of infrastructure and applications converges towards the desired state declared in Git.”

1. 설계v1 - GitOps

Mon, 04 May 2026 00:00:00 +0900

본 문서는 Kafka 공통 플랫폼의 GitOps 기반 운영 방향성 — 즉, 어떤 운영 모델로 갈 것인가 를 정한다. GitOps + Pull 모델 채택의 근거를 1차 출처(gitops.tech, Confluent 블로그/docs) 인용으로 정리하고, 기존 push 기반 CI/CD 와의 차이를 비교한다.

관련 문서:

3. Topic 설계

4. Message Format 설계

5. 설계

1. 목표#

이 작업의 목표는 Kafka 클러스터 자체 의 구축이 아니라, Kafka 자원(Topic, ACL, Schema, Connector 등)을 조직 차원에서 일관되게 관리하기 위한 플랫폼/표준을 정립하는 것.

1. Connect 개념

Sat, 02 May 2026 00:00:00 +0900

Kafka Connect 는 Kafka 와 외부 시스템 사이의 데이터 이동을 코드 작성 없이 선언형 설정으로 처리하는 별도 프레임워크다. 본 문서는 sink 종류(DB, 검색엔진, 객체스토리지 등)와 무관하게 통용되는 Connect 의 개념·아키텍처·고가용성·자원을 1차 출처(Apache / Confluent docs) 인용 중심으로 정리한다.

관련 문서:

모니터링: 2. 모니터링

DB sink 시나리오의 구체 의문(Q&A): 3. DB Sink 시나리오 Q&A

1. Connect 개념#

출처: Confluent — Kafka Connect Concepts

1.1. Connect 란 무엇인가#

핵심 인용:

“You can deploy Kafka Connect as a … distributed, scalable, fault-tolerant service supporting an entire organization.” “a separate framework layer above the Kafka cluster itself.”

1. 카프카 개요

Tue, 21 Apr 2026 00:00:00 +0900

kafka 조금 아는 척하기 by 최범준님 시리즈를 통해 대략적인 개념을 정리한다.

1. 카프카 핵심#

1.1. 분산환경에서 메시지 처리 철학(Message Delivery Semantics)#

분산 네트워크 환경(언제든 끊길 수 있음)에서 시스템 간 메시지를 어떻게 처리할 것인지에 대해 3가지 철학이 Kafka 내부 아키텍처에서 구현함

의미론 (Semantics)	설명	데이터 유실	데이터 중복	카프카 기본 동작
At-most-once (최대 한 번)	메시지가 손실될지언정, 절대 중복해서 전달하지 않음	발생함	없음	`acks=0`, 혹은 컨슈머가 ‘읽자마자 커밋’ 할 때
At-least-once (최소 한 번)	메시지가 중복될지언정, 절대 유실시키지 않음	없음	발생함	카프카의 기본(Default) 철학
Exactly-once (정확히 한 번)	유실도 없고, 중복도 없이 정확히 한 번만 처리됨	없음	없음	—

Kafka는 왜 At-least-once 인가?

2. 실전 예제 설계

Wed, 13 May 2026 00:00:00 +0900

3가지 실전 배치 예제를 설계한다.
각 예제의 Job 흐름, 도메인, Skip/Retry 전략, 테스트 전략을 정리한다.

1. 예제 개요#

#	Job명	트리거	설명
1	`notificationResendJob`	REST API (trigger)	Job Parameter로 일자를 받아 해당 일자 이후 FAILED 알림 재발송
2	`scheduledNotificationResendJob`	Spring Scheduler (1분)	전체 FAILED 알림 재발송
3	`movieLoadJob`	Spring Scheduler (1분)	외부 API(Feign)에서 영화 데이터 조회 → IF 테이블 적재

2. 배치에서의 응답 방식#

Spring Batch Job은 비동기 처리가 기본이다.
HTTP 요청처럼 즉시 결과를 반환하지 않으며, 처리 결과는 로그와 BATCH_* 메타 테이블에 남는다.

Kafka 통합 테스트 — 컨테이너 종료 후 JVM hang

Mon, 11 May 2026 00:00:00 +0900

1. 문제#

Testcontainers 기반 Kafka 통합 테스트에서 테스트는 모두 통과하지만 Gradle 테스트 프로세스가 종료되지 않고 멈춘다. 테스트 클래스가 끝난 후에도 다음 경고가 반복 출력된다.

WARN [log-service] [vice-producer-1] o.a.k.c.NetworkClient :
 [Producer clientId=log-service-producer-1]
 Connection to node 1 (localhost/127.0.0.1:32989) could not be established.
 Node may not be available.

INFO [log-service] [ntainer#0-0-C-1] o.a.k.c.NetworkClient :
 [Consumer clientId=consumer-log-service-2, groupId=log-service] Node 1 disconnected.

2. 원인#

Spring 컨텍스트 캐싱 + Testcontainers 컨테이너 종료 순서 불일치 → Kafka 클라이언트 non-daemon 스레드가 JVM 종료를 막는다.

2. build.gradle.kts vs settings.gradle.kts

Sun, 10 May 2026 00:00:00 +0900

두 파일은 역할이 완전히 다르다.
settings.gradle.kts는 프로젝트 구조를 정의하고,
build.gradle.kts는 빌드 로직을 정의한다.

1. 평가 순서#

Gradle은 빌드 시작 시 다음 순서로 파일을 평가한다.

[1] settings.gradle.kts ← 가장 먼저 실행
 └── 어떤 모듈이 있는지, 플러그인 저장소는 어디인지 결정
 
[2] build.gradle.kts (root)
 └── 공통 설정 (전체 서브프로젝트에 적용할 것들)

[3] build.gradle.kts (각 서브프로젝트)
 └── 모듈별 의존성, 태스크 등

settings.gradle.kts가 평가되기 전까지 Gradle은 빌드 대상 모듈이 무엇인지조차 모른다.

2. settings.gradle.kts#

역할#

기능	설명
`rootProject.name`	프로젝트 이름 (Nexus 배포 시 groupId 등에 영향)
`include()`	서브모듈 등록
`pluginManagement {}`	플러그인 저장소 및 버전 선언
`dependencyResolutionManagement {}`	의존성 저장소 전역 통제, Version Catalog 선언

예시 (멀티모듈 프로젝트)#

rootProject.name = "kafka-practice"

include("kafka-common-lib", "order-service")

include()에 없는 디렉토리는 Gradle이 서브모듈로 인식하지 않는다.

2. 설계v2 - Connect 적용

Sat, 09 May 2026 00:00:00 +0900

SI 환경 공통 플랫폼. 운영 환경은 단순 배포 (GitOps/K8s 생략). 공통팀이 브로커 설정과 공통 라이브러리를 통제하고, 도메인 개발자는 가져다 쓰는 구조. 토픽 네이밍은 3. Topic 설계, 메시지 포맷은 4. Message Format 설계 참조.

1. 리포 구성 (2개)#

리포	담당	목적
`kafka-platform`	공통팀	브로커 설정, 토픽 선언, Connect 설정, 로컬 테스트 환경
`kafka-common-lib`	공통팀	Producer/Consumer client 라이브러리, 이벤트 POJO, 멱등성 처리

도메인 서비스는 kafka-common-lib 를 Maven/Gradle 의존성으로 가져다 쓴다.

2. Kafka 설정 — Hard vs Soft 구분#

Hard 설정 (변경 불가 — 공통팀만 통제)#

안정성·데이터 정합성에 직결. kafka-common-lib 내 Config 클래스에서 강제 적용 — 도메인 서비스에서 오버라이드해도 lib 설정이 우선.

2. 모니터링

Sat, 02 May 2026 00:00:00 +0900

본 문서는 Kafka Connect 클러스터를 운영할 때 보아야 할 메트릭·도구·표준 스택을 정리한다. sink 종류와 무관하게 통용되는 부분만 다루며, 외부 시스템(DB, ES 등) 내부 모니터링은 그 시스템 측 가이드 로 미룬다. 출처: Confluent — Kafka Connect Monitoring (JMX)

관련 문서:

개념·아키텍처·HA·자원: 1. Connect 개념

DB sink 시나리오의 모니터링 보완(예: DB connection pool): 3. DB Sink 시나리오 Q&A

1. 모니터링이 답해야 할 질문#

Connect 운영자가 매일 답하고 싶은 것은 결국 다음 4 가지다:

1. 버전 정리 — 4.0과 그 이전의 차이

Wed, 29 Apr 2026 00:00:00 +0900

본 문서는 Kafka 버전 흐름을 짚고, 4.0 과 3.x 의 주요 차이를 정리한다. 단정적 진술은 1차 출처(Apache Kafka 공식 release announcement, KIP 문서) 인용으로 갈음하고, 출처가 약한 내용은 (미확인) 표기.

1. 마일스톤 한눈에#

버전	릴리즈	핵심 의미	출처
2.8.0	2021-04	KRaft early access (KIP-500)	(미확인 — 본 문서 작성 시 직접 검증 안 함)
3.0.0	2021-09	KRaft 진행 / 메이저 정리	(미확인)
3.3.0	2022-10-03	KRaft production-ready (KIP-833, 신규 클러스터 한정)	KIP-833, Confluent blog
3.4 ~ 3.8	2023~2024	ZK→KRaft 마이그레이션 기능 추가, KIP-848 early access (3.7)	Confluent — Kafka 3.9 (간접)
3.9.0	2024-11-06	ZK 지원 마지막 메이저, Tiered Storage GA	Apache 공식 release announcement, Confluent blog
4.0.0	2025-03-18	ZK 완전 제거, Java 17 (broker), KIP-848 GA, KIP-932 EA	Apache 4.0 release announcement

3.9 의 트위터 공식 계정 발표: “Hello Apache Kafka 3.9.0! - last release using ZooKeeper - tiered storage is production-ready” — Apache Kafka X(Twitter)

3. Gradle Version Catalog

Sun, 10 May 2026 00:00:00 +0900

gradle/libs.versions.toml에 버전을 선언하고 모든 빌드 스크립트에서 타입세이프하게 참조하는 방식.
Gradle 7.4+에서 안정화, Gradle 8.x에서 사실상 표준이 됐다.

1. 도입 전 — 기존 버전 관리 방식들#

방법 A: 문자열 하드코딩#

dependencies {
 implementation("org.springframework.kafka:spring-kafka:3.2.1")
 implementation("org.springframework.boot:spring-boot-starter-data-redis:3.5.14")
}

모듈이 늘어날수록 같은 버전 문자열이 여러 파일에 흩어진다. 업그레이드 시 누락 위험.

방법 B: `val` 변수로 추출#

val springBootVersion = "3.5.14"

dependencies {
 implementation("org.springframework.boot:spring-boot-starter-web:$springBootVersion")
}

단일 파일 내에서는 관리되지만, plugins {} 블록 안에서 변수를 사용할 수 없다는 Gradle 제약이 있다.

3. 설계v3 - Connect 제외

Sun, 10 May 2026 00:00:00 +0900

Aiven JDBC Connector의 운영 리스크(Connect 라이선스 이슈 → 향후 리스크)가 현실화될 경우,
Kafka Connect를 걷어내고 log-service Spring Boot 모듈로 대체하는 설계를 정리한다.

1. 모듈 위치 (멀티모듈 구성)#

kafka-practice/
├── kafka-common-lib/ # 공통 라이브러리 (변경 없음)
├── order-service/ # 도메인 서비스 (변경 없음)
└── log-service/ # 신규 — Kafka → DB 적재 전담 서비스

settings.gradle.kts:

include("kafka-common-lib", "order-service", "log-service")

2. 패키지 트리#

log-service/
└── src/
 ├── main/
 │ ├── java/com/example/log/
 │ │ ├── LogServiceApplication.java # @SpringBootApplication
 │ │ ├── domain/
 │ │ │ └── SystemLog.java # JPA 엔티티
 │ │ ├── repository/
 │ │ │ └── SystemLogRepository.java # Spring Data JPA
 │ │ └── kafka/
 │ │ └── SystemLogConsumer.java # @KafkaListener + @IdempotentConsumer
 │ └── resources/
 │ ├── application.yaml # 공통 설정
 │ └── application-dev.yaml # 로컬 개발 설정
 └── test/
 └── java/com/example/log/
 ├── LogServiceApplicationTests.java
 └── kafka/
 └── SystemLogFlowTest.java # Testcontainers 통합 테스트

3. 핵심 클래스#

SystemLogConsumer#

@Component
public class SystemLogConsumer {

 @KafkaListener(topics = "prd.log.system.v1", groupId = "log-service")
 @IdempotentConsumer(keyType = IdempotencyKey.EVENT_ID, ttlSeconds = 86400)
 public void handle(SystemLogEvent event) {
 repository.save(SystemLog.from(event));
 }
}

@IdempotentConsumer — kafka-common-lib의 Redis 기반 멱등성 AOP 그대로 재사용
@KafkaListener — Kafka Connect 없이 Spring Kafka로 직접 소비

SystemLog (JPA 엔티티)#

@Entity
@Table(name = "system_log")
public class SystemLog {
 @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
 private Long id;

 @Column(name = "event_id", nullable = false, unique = true)
 private String eventId;

 @Column(name = "service_id", nullable = false)
 private String serviceId;

 private String level; // INFO / WARN / ERROR

 @Column(columnDefinition = "TEXT")
 private String message;

 @Column(name = "context_json", columnDefinition = "TEXT")
 private String contextJson; // Map<String,String> → "key=val,..." 형태

 @Column(name = "occurred_at")
 private Instant occurredAt;

 public static SystemLog from(SystemLogEvent event) { ... }
}

4. Kafka → DB 흐름#

도메인 서비스 (order-service 등)
 │
 │ kafkaTemplate.send("prd.log.system.v1", eventId, SystemLogEvent)
 ▼
Kafka (prd.log.system.v1 토픽)
 │
 ▼
log-service :: SystemLogConsumer.handle(SystemLogEvent)
 │
 ├── IdempotencyAspect → Redis SET NX "idempotency:{eventId}"
 │ 중복이면 skip, 신규면 proceed
 │
 ▼
SystemLogRepository.save(SystemLog.from(event))
 │
 ▼
PostgreSQL :: system_log 테이블

5. Kafka Connect와의 비교#

항목	Kafka Connect (JDBC Sink)	log-service
커넥터 의존	Aiven JDBC Connector 필요	없음
커스텀 이미지	buildx로 직접 빌드	불필요
멱등성	Connect 내장 (offset 기반)	`@IdempotentConsumer`
변환 로직	SMT (제한적)	Java 코드로 자유롭게
테스트	Connect Worker 환경 필요	Testcontainers로 단독 테스트
배포	Connect Worker 컨테이너	Spring Boot JAR (기존 패턴)

6. 테스트 전략#

SystemLogFlowTest (통합 테스트)#

테스트	검증 내용
`로그이벤트_발행후_DB_저장`	발행 → DB 저장 E2E, 저장된 필드값 일치 확인
`중복_eventId_한번만_저장`	동일 eventId 2회 발행 → DB row 1개만 생성
`다른_serviceId_이벤트_각각_저장`	서로 다른 이벤트 → 각각 저장 (count=2)
`다양한_레벨_이벤트_모두_저장`	INFO/WARN/ERROR 3건 → 모두 저장

Testcontainers 구성:

3. Topic 설계

Mon, 04 May 2026 00:00:00 +0900

본 문서는 토픽 네이밍 컨벤션 을 정한다. 출처: Confluent — Kafka Topic Naming Convention: Best Practices, Patterns, and Guidelines

관련 문서: 5. 설계 — 토픽 YAML 의 위치 (kafka-platform/topics/).

1. Confluent 가 권장하는 4가지 구성 요소#

Data Source / Domain — 발생 시스템 (예: sales, hr, product)
Data Type / Action — 이벤트 종류 (예: order, click, transaction)
Environment / Region — 배포 컨텍스트 (prod/dev 또는 us-east)
Version — 스키마 버전 (v1, v2)

2. 일반적 패턴 (Confluent 제시)#

패턴	예시
Hierarchical	`domain.data_type.region.version`
Action-Based	`user.signup.success`
Environment-Specific	`prod.order.events`, `dev.order.events`
Multi-Region	`global.sales.eu-west`

3. 본 조직 채택안 (제안)#

<env>.<domain>.<event>.<version> — Hierarchical + Environment-Specific 결합.

3. DB Sink 시나리오 Q&A

Sat, 02 May 2026 00:00:00 +0900

본 문서는 sink = 관계형 DB 라는 구체 시나리오에서 Connect 도입 시 떠올린 의문과 그 답을 정리한다. Connect 의 일반 개념은 1. Connect 개념, 모니터링 일반론은 2. 모니터링. 본 문서는 DB 적재 라는 케이스에 한정해 — connection 산정, schema 변환, batch insert, DB 측 모니터링, “그냥 직접 짜면 안 되나?” 같은 의문을 다룬다.

1. 시나리오#

본 조직의 적재 요구:

[Service A] ┌──→ [Postgres]
[Service B] ──→ [Kafka Broker] ←── [Connect Worker Cluster] ──┤
[ ... ] (JDBC Sink Connector) └──→ (필요 시 ES/S3 등 추가)

요구사항 (이전 프로젝트에서 직접 짠 consumer 가 했던 일):

@IdempotentConsumer — 멱등성 패턴 설계 분석

Mon, 11 May 2026 00:00:00 +0900

작성된 코드는 엔터프라이즈 환경에서 Kafka의 At-least-once 전송 보장으로 인해 필연적으로 발생하는 메시지 중복 수신 문제를 방어하기 위한 멱등성(Idempotency) 패턴이다.

비즈니스 로직(Consumer)과 인프라 로직(Redis 체크)을 AOP로 완벽하게 분리한 구조다.

1. 핵심 개념 — Redis `SET NX`#

SET NX는 “SET if Not eXists(존재하지 않을 때만 저장)“의 Redis 명령어 옵션이다. Spring Data Redis에서는 setIfAbsent()로 제공한다.

여러 Consumer Pod이 떠 있는 분산 환경에서, 네트워크 지연이나 리밸런싱 때문에 동일한 이벤트(예: 주문 완료 ID: 123)가 컨슈머 A와 B에 동시에 들어올 수 있다.

4. Connect 라이선스 이슈

Sun, 10 May 2026 00:00:00 +0900

Kafka Connect를 엔터프라이즈·SaaS 환경에서 도입할 때 반드시 검토해야 할 라이선스 문제.
특히 Confluent Community License 가 어디까지 허용되고 어디서 막히는지 분석한다.

1. 라이선스 계층 구조#

Kafka Connect 스택은 컴포넌트마다 라이선스가 다르다.

┌─────────────────────────────────────────────────────┐
│ Connect Worker (connect-distributed.sh) │
│ → Apache Kafka 내장 → Apache 2.0 ✓ │
├─────────────────────────────────────────────────────┤
│ Connector Plugin (JDBC Sink 등) │
│ → 벤더마다 다름 ← 여기서 문제 발생 │
├─────────────────────────────────────────────────────┤
│ JDBC Driver (PostgreSQL 등) │
│ → PostgreSQL JDBC: BSD-2-Clause ✓ │
└─────────────────────────────────────────────────────┘

Connect worker 자체는 Apache 2.0이다. 문제는 그 위에 올리는 커넥터 플러그인에 있다.

4. Message Format 설계

Mon, 04 May 2026 00:00:00 +0900

본 문서는 메시지의 직렬화 포맷·Schema Registry·호환성 정책·버전 관리 를 정한다. 본 시점에는 결정 단계 — 후보를 정리하고 비교하며, 본 조직 결정이 내려지면 §5 에 채워 넣는다.

관련 문서:

토픽 이름의 .v1 .v2 부분: 3. Topic 설계 §1, §3

kafka-common-lib 의 serde/ 위치: 5. 설계 §4

1. 직렬화 포맷 비교#

출처: Confluent — Schema Registry Concepts (Schema Formats)

포맷	스키마 필요	장점	단점	비고
Avro	✅ (`.avsc`)	Schema Registry 통합 표준 · binary 효율 · evolution rule 성숙	사람이 읽기 어려움 (binary)	Confluent 에코시스템의 default. 가장 흔한 운영 표준
Protobuf	✅ (`.proto`)	gRPC 와 호환 · 다국어 지원 우수	Avro 대비 evolution rule 가 약간 더 빡셈	이미 gRPC 쓰는 조직에 자연스러움
JSON Schema	✅ (`.json`)	사람이 읽기 좋음 · 도구 생태계 풍부	binary 비효율 · payload 크기 큼	사람 디버깅 빈번한 케이스
JSON (스키마 없음)	❌	진입 장벽 낮음	schema drift 위험 · 운영급 비추 (개인 추론)	빠른 PoC 외에는 비권장
String / ByteArray	❌	단순	도메인 의미 0	메타·로그 wrapper 가 아니면 비추

→ 본 조직 default 후보: Avro + Schema Registry (Confluent 표준). 단, 이미 Protobuf 쓰는 도메인이 있다면 Protobuf 도 허용 — (미정)

7. Connect를 통한 DB 적재

Sun, 10 May 2026 00:00:00 +0900

prd.log.system.v1 토픽의 시스템 로그를 Kafka Connect JDBC Sink로 PostgreSQL에 적재하는 실습.
별도 Consumer 서비스 없이 Connect만으로 처리하는 설정과 동작을 단계별로 구성한다.
개념 일반론은 Connect 개념, Q&A는 DB Sink 시나리오, 라이선스 이슈는 Connect 라이선스.

1. 전체 흐름#

order-service (Producer)
 │ SystemLogEvent (JSON)
 ▼
Kafka Broker — prd.log.system.v1
 │
 ▼
Kafka Connect Worker
 │
 ├── [1] Consumer.poll() ←── max.poll.records, fetch.min.bytes, fetch.max.wait.ms
 │
 ├── [2] SMT Pipeline
 │ ├── rename: camelCase → snake_case
 │ └── drop: context 필드 제거
 │
 └── [3] JDBC Sink
 └── batch INSERT (batch.size 개씩 묶어 1 SQL 문장으로)
 │
 ▼
 PostgreSQL — system_log 테이블

2. 커넥터 설정 전체 (`system-log-sink.json`)#

{
 "name": "system-log-sink",
 "config": {
 "connector.class": "io.aiven.connect.jdbc.JdbcSinkConnector",
 "tasks.max": "1",
 "topics": "prd.log.system.v1",
 "connection.url": "${env:DB_URL}",
 "connection.user": "${env:DB_USER}",
 "connection.password": "${env:DB_PASSWORD}",

 "insert.mode": "insert",
 "auto.create": "false",
 "auto.evolve": "false",
 "table.name.format": "system_log",
 "pk.mode": "none",

 "value.converter": "org.apache.kafka.connect.json.JsonConverter",
 "value.converter.schemas.enable": "false",

 "batch.size": "10",
 "consumer.override.max.poll.records": "10",
 "consumer.override.fetch.min.bytes": "1024",
 "consumer.override.fetch.max.wait.ms": "1000",

 "transforms": "rename,drop",
 "transforms.rename.type": "org.apache.kafka.connect.transforms.ReplaceField$Value",
 "transforms.rename.renames": "eventId:event_id,aggregateId:aggregate_id,serviceId:service_id,occurredAt:occurred_at",
 "transforms.drop.type": "org.apache.kafka.connect.transforms.ReplaceField$Value",
 "transforms.drop.exclude": "context"
 }
}

3. 필드별 설명#

3.1. 기본 식별#

필드	값	설명
`name`	`system-log-sink`	Connect 내 커넥터 고유 이름. REST API `/connectors/{name}` 으로 조회·관리
`connector.class`	`io.aiven.connect.jdbc.JdbcSinkConnector`	사용할 커넥터 구현체. Aiven JDBC Sink (Apache 2.0). 라이선스 이슈 참고
`tasks.max`	`1`	병렬 처리 task 수. 1로 고정한 이유: 여러 task 쓰면 각 task가 독립 batch 가져가므로 batch 크기가 분산됨. 로그 적재는 순서보다 batch 효율이 중요하므로 단일 task로 묶음 처리
`topics`	`prd.log.system.v1`	이 커넥터가 소비할 Kafka 토픽. 여러 개면 콤마 구분

3.2. DB 연결#

필드	값	설명
`connection.url`	`${env:DB_URL}`	JDBC URL. `${env:VAR}` 형식으로 Connect Worker의 환경변수에서 주입. 하드코딩 금지
`connection.user`	`${env:DB_USER}`	DB 사용자
`connection.password`	`${env:DB_PASSWORD}`	DB 패스워드

Connect Worker의 connect-distributed.properties에서 config.providers=env,file 설정이 필요.

Home on San Kim의 위키

1. 스케줄러 조사

1. 핵심 요구사항#

2. 선택지별 분석#

2-1. @Scheduled + ShedLock#

1. 초기설계

1. batch-common 실제 패키지 구조#

2. 의존성#

Kafka 통합 테스트 — auto-offset-reset 미설정 시 메시지 유실

1. 문제#

2. 원인#

1. Colima — Mac Docker 환경 설정

1. 엔터프라이즈 환경에서 Colima를 쓰는 이유#

Docker Desktop 라이선스 제한#

“CLI만 쓰면 괜찮지 않나?”#

1. Gradle 기초 개념

1. 핵심 구성 요소#

2. 주요 블록#

plugins {}#

1. SNAPSHOT vs Release

1. 개념 비교#

2. Nexus 레포 구조#

2. Groovy DSL vs Kotlin DSL (.kts)

1. 핵심 차이#

2. 문법 비교#

플러그인 선언#

의존성 선언#

태스크 정의#

3. Kotlin DSL의 실질적 이득#

IDE 자동완성#

8. Kafka UI — 토픽·메시지·모니터링

1. 실행#

docker-compose#

멀티 클러스터#

1. ArgoCD 개념

1. GitOps — 정의·배경·역사

1. 정의 (gitops.tech 인용)#

1. 설계v1 - GitOps

1. 목표#

1. Connect 개념

1. Connect 개념#

1.1. Connect 란 무엇인가#

1. 카프카 개요

1. 카프카 핵심#

1.1. 분산환경에서 메시지 처리 철학(Message Delivery Semantics)#

2. 실전 예제 설계

1. 예제 개요#

2. 배치에서의 응답 방식#

Kafka 통합 테스트 — 컨테이너 종료 후 JVM hang

1. 문제#

2. 원인#

2. build.gradle.kts vs settings.gradle.kts

1. 평가 순서#

2. settings.gradle.kts#

역할#

예시 (멀티모듈 프로젝트)#

2. 설계v2 - Connect 적용

1. 리포 구성 (2개)#

2. Kafka 설정 — Hard vs Soft 구분#

Hard 설정 (변경 불가 — 공통팀만 통제)#

2. 모니터링

1. 모니터링이 답해야 할 질문#

1. 버전 정리 — 4.0과 그 이전의 차이

1. 마일스톤 한눈에#

3. Gradle Version Catalog

1. 도입 전 — 기존 버전 관리 방식들#

방법 A: 문자열 하드코딩#

방법 B: val 변수로 추출#

3. 설계v3 - Connect 제외

1. 모듈 위치 (멀티모듈 구성)#

2. 패키지 트리#

3. 핵심 클래스#

SystemLogConsumer#

SystemLog (JPA 엔티티)#

4. Kafka → DB 흐름#

5. Kafka Connect와의 비교#

6. 테스트 전략#

SystemLogFlowTest (통합 테스트)#

3. Topic 설계

1. Confluent 가 권장하는 4가지 구성 요소#

2-1. `@Scheduled` + ShedLock#

`plugins {}`#

방법 B: `val` 변수로 추출#

1. 핵심 개념 — Redis `SET NX`#

2. 커넥터 설정 전체 (`system-log-sink.json`)#