GW LABS

읽은 글을 기억으로: 서버비 0원의 온디바이스 AI 퀴즈 앱 'Blank.' 개발기

GeonWoo Kim — Mon, 23 Feb 2026 21:21:33 +0900

우리는 매일 수많은 아티클과 뉴스레터를 읽습니다. 하지만 다음 날이면 내용이 가물가물해지곤 합니다. ‘스크랩만 해두고 다시 보지 않는 글들을 강제로 복습하게 만들 순 없을까?’ 이 작은 고민에서 출발한 앱, Blank.의 개발 과정을 공유합니다. Blank는 링크만 넣으면 AI가 핵심을 파악해 빈칸 채우기(Cloze Test) 문제를 만들어주는 안드로이드 앱입니다.

1. 왜 서버가 아니라 기기 내부(On-device)를 선택했나

개인화된 학습 도구를 만들 때 가장 큰 고민은 두 가지였습니다. 첫째는 트래픽에 비례해 증가하는 유지보수 비용(서버비)이었고, 둘째는 사용자가 어떤 글을 읽는지에 대한 프라이버시 문제였습니다. 이를 해결하기 위해 서버 기반의 API 대신 기기 내부에서 직접 AI를 구동하는 방식을 택했습니다.

온디바이스 LLM (On-device LLM)

클라우드 서버를 거치지 않고, 스마트폰 기기 내부의 연산 자원(AP)만으로 구동되는 소형 인공지능 모델(이 프로젝트에서는 Google Gemma 3 사용)입니다.
외부로 데이터를 전송하지 않아 사용자의 프라이버시를 완벽히 보호하고, 개발자의 서버 유지 비용을 0원으로 만들기 위해 쓰입니다.
데이터 보안이 민감한 메모 앱이거나, 비행기 모드 같은 오프라인 환경에서도 핵심 AI 기능이 동작해야 할 때 사용합니다.
디자이너 관점 비교: 피그마(Figma)가 서버에 접속해야만 쓸 수 있는 클라우드 기반이라면, 온디바이스는 포토샵이나 일러스트레이터처럼 내 컴퓨터의 리소스를 직접 써서 오프라인에서도 돌아가는 독립적인 작업 환경과 같습니다.

2. 출시의 기쁨, 그리고 예상치 못한 암초

최초 버전을 완성한 뒤 긱뉴스(GeekNews)에 앱을 공개했고, 5일 만에 87대의 기기에서 다운로드되는 의미 있는 성과를 얻었습니다. 하지만 한 유저분의 뼈아픈 피드백이 도착했습니다.

"나무위키의 특정 인물 링크를 넣었더니, 7문제 중 5문제의 정답이 모두 그 인물 이름이었습니다."

앱의 핵심 경험을 해치는 치명적인 문제였습니다. 문서의 빈도수에 의존하다 보니 AI가 가장 많이 등장하는 단어에만 꽂히는 과적합(Overfitting) 현상이 발생한 것입니다.

3. 문제 해결 과정: AI의 고집 꺾기

처음에는 프롬프트에 "이미 나온 단어는 쓰지 마세요"라고 지시하거나, 중복된 정답이 나오면 다시 생성하게 만드는 재시도(Retry) 로직을 고려했습니다. 하지만 모바일 환경에서 수 초가 걸리는 추론을 여러 번 반복하는 것은 치명적인 UX 저하를 낳습니다. 속도를 희생하지 않으면서 확실한 통제 수단이 필요했습니다.

텍스트 치환 (Input Substitution)

AI에게 문장을 분석하라고 넘기기 직전, 이미 정답으로 출제된 단어들을 코드 레벨에서 원문으로부터 강제로 가려버리는(OOO 등으로 변경) 전처리 기법입니다.
AI가 기존 정답 단어 자체를 아예 읽지 못하게 만들어 중복 추출을 원천 차단하고, 무거운 추론 과정을 단 1회로 끝내어 앱의 반응 속도를 방어하기 위해 쓰입니다.
모바일 환경처럼 연산 비용이 비싸서 호출 횟수를 1회로 통제하면서 100% 확실하고 다양한 결과를 얻어야 할 때 사용합니다.
작업자에게 "파란색은 빼고 그려주세요"라고 말로 지시하는 것(프롬프트)은 무의식적으로 파란색을 쓸 위험이 남습니다. 텍스트 치환은 애초에 팔레트에서 파란색 물감을 빼앗은 뒤 시안을 요구하는 것과 같습니다. 오류 가능성을 시스템적으로 차단합니다.

이 방식을 통해 퀴즈 생성 속도를 늦추지 않으면서 정답의 다양성을 확보할 수 있었습니다.

4. 다음 스텝을 향해

급한 불은 껐지만, 아직 전체 퀴즈 생성 속도를 더 끌어올려야 하는 과제가 남아있습니다. 텍스트의 유사도를 모두 계산하는 무거운 TextRank 알고리즘을 걷어내고, 문단 단위로 빠르게 핵심을 짚어내는 새로운 추출 로직을 도입할 예정입니다.

읽은 것을 온전한 내 지식으로 만드는 경험, Blank.가 계속 만들어가겠습니다.

Google Play Store에서 Blank. 다운로드

MySQL InnoDB: 백엔드 개발자를 위한 필수 가이드

GeonWoo Kim — Mon, 29 Sep 2025 08:14:16 +0900

MySQL은 전 세계적으로 가장 많이 사용되는 오픈소스 데이터베이스 중 하나이며, 그 중심에는 InnoDB 스토리지 엔진이 있습니다. InnoDB는 단순히 데이터를 저장하는 엔진을 넘어, 성능, 안정성, 확장성 측면에서 MySQL을 지탱하는 핵심 요소입니다. 이번 글에서는 백엔드 개발자라면 반드시 이해해야 할 MySQL InnoDB의 특징과 성능 튜닝 포인트를 정리해 보겠습니다.

InnoDB의 주요 특징

1. 트랜잭션 지원 (ACID 보장)

InnoDB는 ACID(Atomicity, Consistency, Isolation, Durability) 특성을 충실히 지원합니다.
이는 금융 서비스나 전자상거래처럼 데이터 무결성이 중요한 시스템에서 필수적인 기능입니다.

-- 트랜잭션 예제
START TRANSACTION;

UPDATE accounts SET balance = balance - 100 WHERE id = 1;
UPDATE accounts SET balance = balance + 100 WHERE id = 2;

COMMIT;

위 예제에서 두 개의 UPDATE가 모두 성공해야 최종 COMMIT이 이루어집니다. 실패 시 ROLLBACK으로 데이터 무결성이 보장됩니다.

2. 클러스터형 인덱스 (Clustered Index)

InnoDB는 Primary Key를 기준으로 데이터를 물리적으로 정렬하는 클러스터형 인덱스를 사용합니다.
따라서 Primary Key를 잘 설계하는 것이 성능에 큰 영향을 줍니다.

장점: Primary Key 기반 조회 속도가 매우 빠름
단점: 잘못된 PK 설계 시 데이터 재배치 비용이 증가
```
- 효율적인 PK 설계 예시
  CREATE TABLE orders (
  order_id BIGINT AUTO_INCREMENT PRIMARY KEY,
  user_id BIGINT NOT NULL,
  created_at DATETIME NOT NULL,
  INDEX (user_id),
  INDEX (created_at)
  ) ENGINE=InnoDB;

3. 외래 키(Foreign Key) 지원

MyISAM과 달리, InnoDB는 외래 키 제약조건을 지원합니다. 이는 데이터 무결성을 DB 레벨에서 보장할 수 있게 해줍니다.

-- 외래 키 제약조건 예시
CREATE TABLE users (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(100) NOT NULL
) ENGINE=InnoDB;

CREATE TABLE posts (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    user_id BIGINT,
    content TEXT,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
) ENGINE=InnoDB;

MySQL 성능 튜닝과 InnoDB

1. InnoDB Buffer Pool 최적화

InnoDB의 핵심은 Buffer Pool입니다. 이는 메모리에 데이터와 인덱스를 캐싱하여 디스크 I/O를 줄여줍니다.
대규모 트래픽 환경에서는 innodb_buffer_pool_size를 서버 메모리의 60~70% 수준으로 설정하는 것이 일반적입니다.

# my.cnf 설정 예시
[mysqld]
innodb_buffer_pool_size = 8G
innodb_log_file_size = 1G
innodb_flush_log_at_trx_commit = 1

2. 트랜잭션 격리 수준 조정

InnoDB는 4가지 트랜잭션 격리 수준을 지원합니다.
기본값은 REPEATABLE READ이지만, 서비스 특성에 맞게 조정할 수 있습니다.

-- 현재 세션에서 격리 수준 변경
SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED;

READ COMMITTED: 대부분의 웹 서비스에 적합, 잠금 경합 줄임
REPEATABLE READ: 기본값, 팬텀 리드 방지
SERIALIZABLE: 가장 강력하지만 성능 저하

백엔드 개발자가 알아야 할 InnoDB 핵심 포인트

PK 설계 중요성: 자동 증가 값이나 짧은 정수형 PK 권장
Buffer Pool 튜닝: 성능의 70% 이상을 좌우
트랜잭션 이해: 단순한 쿼리 작성이 아니라, 데이터 무결성을 보장하는 로직 설계 필요
Deadlock 처리: InnoDB는 자동 Deadlock 감지를 지원하므로, 애플리케이션 레벨에서 재시도 로직을 구현해야 함

# Python 예시: Deadlock 발생 시 재시도 로직
import MySQLdb
import time

def execute_with_retry(cursor, query, params=()):
    for attempt in range(3):
        try:
            cursor.execute(query, params)
            return
        except MySQLdb.OperationalError as e:
            if e.args[0] == 1213:  # Deadlock
                time.sleep(0.5)
            else:
                raise

결론

InnoDB는 단순한 스토리지 엔진이 아니라, MySQL의 성능과 안정성을 좌우하는 핵심 기술입니다.
백엔드 개발자는 트랜잭션 관리, PK 설계, Buffer Pool 튜닝 같은 부분을 이해하고 적용해야 실제 서비스 환경에서 안정적이고 빠른 데이터베이스를 운영할 수 있습니다.

요약: InnoDB를 제대로 이해하면, MySQL의 잠재력을 최대한 끌어낼 수 있습니다.

AWS DynamoDB Deep Dive: Key-Value DB와 NoSQL 모델링 완벽 이해

GeonWoo Kim — Sun, 7 Sep 2025 09:05:02 +0900

AWS DynamoDB Deep Dive: Key-Value DB와 NoSQL 모델링 완벽 이해

서론

AWS DynamoDB는 완전 관리형(fully managed) NoSQL 데이터베이스 서비스로, Key-Value 및 Document 모델을 지원하면서도 초당 수백만 건의 요청을 처리할 수 있는 확장성을 제공합니다.
많은 기업이 DynamoDB를 선택하는 이유는 서버 관리 부담을 줄이고, 고성능 애플리케이션을 안정적으로 운영할 수 있기 때문입니다. 이번 글에서는 DynamoDB의 특징, 기본 사용법, 데이터 모델링 전략, 그리고 RDBMS와의 차이점을 심도 있게 다루겠습니다.

본론

1. DynamoDB의 주요 특징

완전 관리형: 서버 인프라, 스케일링, 보안, 백업을 AWS가 관리
Key-Value + Document 저장 모델: 단순 키-값 조회부터 JSON 기반 복잡한 구조까지 지원
자동 확장성: 온디맨드(On-Demand) 또는 프로비저닝(Provisioned) 용량 모드 선택 가능
고가용성: 다중 AZ(Availability Zone)에 자동 데이터 복제
서버리스 통합: AWS Lambda, API Gateway와 쉽게 연동되어 실시간 애플리케이션 구축에 최적화

2. DynamoDB 기본 사용법

DynamoDB는 테이블(table), 아이템(item), 속성(attribute) 구조를 기반으로 동작합니다.
기본 키(primary key)는 두 가지 방식으로 정의할 수 있습니다:

단일 파티션 키 (Partition Key Only)
→ 단순 Key-Value 조회용
복합 키 (Partition Key + Sort Key)
→ 동일 파티션 키 내에서 정렬된 데이터 관리 가능

예제: 테이블 생성 (AWS CLI)

aws dynamodb create-table \
    --table-name Orders \
    --attribute-definitions \
        AttributeName=OrderId,AttributeType=S \
        AttributeName=CreatedAt,AttributeType=N \
    --key-schema \
        AttributeName=OrderId,KeyType=HASH \
        AttributeName=CreatedAt,KeyType=RANGE \
    --provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5

예제: 데이터 삽입 (Python Boto3)

import boto3
from datetime import datetime

dynamodb = boto3.resource('dynamodb')
table = dynamodb.Table('Orders')

response = table.put_item(
   Item={
        'OrderId': 'ORD1234',
        'CreatedAt': int(datetime.now().timestamp()),
        'CustomerName': '홍길동',
        'TotalAmount': 35000
    }
)
print("PutItem succeeded:", response)

예제: 데이터 조회 (Python Boto3)

response = table.get_item(
    Key={
        'OrderId': 'ORD1234',
        'CreatedAt': 1694001123
    }
)
print(response['Item'])

3. DynamoDB 데이터 모델링 전략

DynamoDB는 RDBMS와 달리 정규화보다 액세스 패턴 중심 설계가 핵심입니다.

단일 테이블 설계 (Single-Table Design)
- 여러 엔터티를 하나의 테이블에 저장하고, 파티션 키/정렬 키 조합으로 액세스 패턴을 관리
Secondary Index 활용
- GSI(Global Secondary Index): 파티션 키 및 정렬 키를 새롭게 정의해 보조 조회 지원
- LSI(Local Secondary Index): 동일 파티션 키 내에서 다른 정렬 키로 조회 가능
핫 파티션 방지
- 키 분포가 특정 값에 치우치지 않도록 설계 필요

예제: GSI 생성 (AWS CLI)

aws dynamodb update-table \
    --table-name Orders \
    --attribute-definitions AttributeName=CustomerName,AttributeType=S \
    --global-secondary-index-updates \
        "[{\"Create\":{\"IndexName\":\"CustomerNameIndex\",\"KeySchema\":[{\"AttributeName\":\"CustomerName\",\"KeyType\":\"HASH\"}],\"Projection\":{\"ProjectionType\":\"ALL\"},\"ProvisionedThroughput\":{\"ReadCapacityUnits\":5,\"WriteCapacityUnits\":5}}}]"

4. DynamoDB와 RDBMS의 차이점

구분	DynamoDB	RDBMS
데이터 모델	Key-Value, Document	테이블, 행(Row), 열(Column)
스키마	스키마리스 (유연)	엄격한 스키마
확장성	수평적 확장 (샤딩 자동화)	수직적 확장 위주
트랜잭션	제한적 지원 (ACID 일부)	완전한 ACID 보장
설계 방식	액세스 패턴 중심	정규화 중심
사용 사례	IoT, 로그 처리, 세션 관리	ERP, 회계, 관계형 데이터 관리

결론

이번 포스팅에서는 AWS DynamoDB의 특징, 기본 사용법, 데이터 모델링 전략, 그리고 RDBMS와의 차이점을 살펴보았습니다.
핵심은 DynamoDB는 스키마리스 구조와 수평 확장성 덕분에 고성능 분산 애플리케이션에 최적화되어 있으며, 전통적인 RDBMS와는 완전히 다른 설계 사고방식이 필요하다는 점입니다.

이 글을 통해 독자분들은 DynamoDB를 단순한 NoSQL 서비스가 아닌, 실무에 최적화된 강력한 데이터베이스로 이해할 수 있습니다.

Gemma3 270M으로 배우는 sLLM 파인튜닝과 Edge Device 서빙 전략

GeonWoo Kim — Tue, 2 Sep 2025 08:53:37 +0900

서론

최근 LLM(Large Language Model)의 경량화 버전인 sLLM(Small Language Model) 이 빠르게 주목받고 있습니다. 거대한 모델을 직접 서빙하기 어려운 환경에서는 sLLM과 같은 소형 모델을 적절히 파인튜닝해 활용하는 것이 매우 유효한 전략입니다. 본 포스팅에서는 Gemma3 270M 모델을 활용하여 LoRA 기반 파인튜닝을 진행하고, 학습된 PyTorch 모델을 TensorFlow Lite 변환 후 Mediapipe 기반 Edge Device 서빙까지 이어지는 전체 워크플로우를 정리합니다.

이 글은 실무 환경에서 sLLM을 파인튜닝하거나 모바일·엣지 디바이스에 배포하려는 개발자에게 최적화된 가이드를 제공합니다.

본론

1. Gemma3 270M과 sLLM 파인튜닝

Gemma3 270M은 Google이 공개한 소형 언어 모델로, 경량·저비용·실시간 응답성이라는 특징을 가집니다. 하지만 특정 도메인 데이터에 맞게 활용하려면 파인튜닝이 필수적입니다.

가장 널리 쓰이는 접근은 LoRA(Low-Rank Adaptation) 를 적용하는 방식입니다. LoRA는 전체 파라미터를 학습하지 않고 일부 저차원 행렬만 업데이트하기 때문에, 적은 리소스로도 높은 성능 향상을 기대할 수 있습니다.

LoRA Config 예시

from peft import LoraConfig

lora_config = LoraConfig(
    r=8,                      # 랭크
    lora_alpha=16,            # LoRA scaling
    target_modules=["q_proj", "v_proj"],  # 적용할 레이어
    lora_dropout=0.05,        # 드롭아웃
    bias="none",
    task_type="CAUSAL_LM"
)

이 설정은 Gemma3 270M 같은 소형 모델에서 적절한 학습/메모리 균형을 제공합니다.

파인튜닝 예제

from transformers import AutoModelForCausalLM, AutoTokenizer, TrainingArguments, Trainer

model_name = "google/gemma-3-270m"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name)

# 데이터 준비
train_dataset = ...

# 학습 설정
training_args = TrainingArguments(
    output_dir="./outputs",
    per_device_train_batch_size=16,
    gradient_accumulation_steps=2,
    learning_rate=2e-4,
    num_train_epochs=3,
    fp16=True,
    logging_steps=50,
    save_steps=500,
    save_total_limit=2,
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
)

trainer.train()

2. Torch 모델을 TensorFlow Lite 변환

학습이 완료된 모델을 Edge Device에 배포하기 위해서는 TFLite 변환이 필요합니다.

변환 절차

PyTorch → ONNX
ONNX → TensorFlow SavedModel
SavedModel → TFLite

코드 예제

import torch

# 1. Torch -> ONNX
dummy_input = torch.randint(0, 100, (1, 128))  # 시퀀스 입력
torch.onnx.export(model, dummy_input, "gemma3.onnx", input_names=["input_ids"], output_names=["logits"])

# 2. ONNX -> TensorFlow (onnx_tf 활용)
!onnx-tf convert -i gemma3.onnx -o ./gemma3_tf

# 3. TensorFlow -> TFLite
import tensorflow as tf

converter = tf.lite.TFLiteConverter.from_saved_model("./gemma3_tf")
converter.optimizations = [tf.lite.Optimize.DEFAULT]  # 양자화 가능
tflite_model = converter.convert()

with open("gemma3_270m.tflite", "wb") as f:
    f.write(tflite_model)

3. Mediapipe 기반 Edge Device 서빙

변환된 .tflite 모델은 Mediapipe Tasks API를 활용하면 모바일 환경에서 효율적으로 서빙할 수 있습니다.

Python 예제

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
TextEmbedder = mp.tasks.text.TextEmbedder
TextEmbedderOptions = mp.tasks.text.TextEmbedderOptions

options = TextEmbedderOptions(
    base_options=BaseOptions(model_asset_path="gemma3_270m.tflite")
)

with TextEmbedder.create_from_options(options) as embedder:
    result = embedder.embed("sLLM 활용 예제입니다.")
    print(result)

Mediapipe는 GPU 가속, 멀티 플랫폼(Android, iOS, Web) 지원이 가능하기 때문에 실제 서비스에서 경량 AI 모델을 배포할 때 강력한 선택지가 됩니다.

결론

이번 포스팅에서는 Gemma3 270M sLLM을 LoRA로 파인튜닝하고, 학습된 모델을 TFLite 변환 후 Mediapipe로 서빙하는 전체 과정을 살펴보았습니다.

핵심은 작은 모델도 적절한 파인튜닝과 최적화 파이프라인을 거치면, 모바일과 Edge 환경에서도 충분히 실용적인 AI 서비스를 구현할 수 있다는 점입니다.

이 과정을 따라가면 저비용·고효율의 맞춤형 sLLM 서비스를 누구나 구축할 수 있습니다.

개인 프로젝트 WordADay 출시 후기: 바이브 코딩과 Flutter로 만든 앱, 그리고 PlayStore 등록까지

GeonWoo Kim — Wed, 27 Aug 2025 20:47:25 +0900

개발자로서 개인 프로젝트를 완성해 실제로 Google PlayStore에 출시하는 경험은 값진 자산이 됩니다. 이번 포스팅에서는 제가 진행한 WordADay 프로젝트를 소개하고, 개발 과정에서 활용한 바이브 코딩(Vibe Coding) 방식과 Flutter UI 구현, 마지막으로 Google PlayStore 등록 시 유의할 점을 공유하고자 합니다.

WordADay 앱 바로가기: Google PlayStore 다운로드

WordADay 프로젝트와 바이브 코딩 접근법

개인 프로젝트 동기와 목표

WordADay는 매일 새로운 영어 단어를 제공하는 간단한 학습 앱입니다.
개인적으로 “매일 반복적으로 학습할 수 있는 작은 습관 앱”을 만들어 보고 싶었고, Flutter를 기반으로 빠르게 MVP를 개발했습니다.

여기서 저는 바이브 코딩(Vibe Coding) 방식을 적용했습니다.

정해진 설계 문서를 따르기보다는, “느낌과 직관”을 우선시하여 UI와 기능을 즉시 구현
즉각적인 실행과 피드백을 통해 사용자 경험을 빠르게 조정

이 방식은 특히 사이드 프로젝트에서 동기부여를 유지하고, 빠른 출시로 이어지는 데 유효했습니다.

Flutter UI: 바이브 코딩으로 빠르게 만들기

Flutter의 가장 큰 장점은 핫 리로드(Hot Reload) 기능을 통한 빠른 UI 반복입니다.
WordADay UI는 최소한의 코드로 심플하게 구성했으며, 핵심은 “단어 표시 → 뜻 → 추가 학습 버튼”의 단순한 흐름입니다.

예를 들어, WordADay의 기본 카드 UI는 아래와 같은 방식으로 구현했습니다. 실제 UI 코드는 아니나, 아래와 같은 작은 UI 코드들은 지속적으로 AI로 만들면서 개선했습니다.

import 'package:flutter/material.dart';

class WordCard extends StatelessWidget {
  final String word;
  final String meaning;

  const WordCard({required this.word, required this.meaning, super.key});

  @override
  Widget build(BuildContext context) {
    return Card(
      shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(16)),
      elevation: 4,
      margin: const EdgeInsets.all(16),
      child: Padding(
        padding: const EdgeInsets.all(24),
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            Text(word,
                style: Theme.of(context).textTheme.headlineMedium),
            const SizedBox(height: 12),
            Text(meaning,
                style: Theme.of(context).textTheme.bodyLarge),
            const SizedBox(height: 16),
            ElevatedButton(
              onPressed: () {
                // TODO: 추가 학습 페이지 연결
              },
              child: const Text("Learn More"),
            ),
          ],
        ),
      ),
    );
  }
}

이처럼 작은 단위 UI 위젯을 바이브 코딩으로 빠르게 만들어 나가면, 전체 앱의 뼈대를 짧은 시간 안에 완성할 수 있습니다.

Google PlayStore 등록 시 유의할 점

WordADay를 배포하면서, PlayStore 등록 과정에서 다음과 같은 포인트를 반드시 체크해야 했습니다.

앱 서명(App Signing)

Google Play App Signing을 활성화하면 배포 및 업데이트 관리가 훨씬 안정적입니다.

앱 콘텐츠 정책 준수

학습 앱이라 하더라도 개인정보 처리방침(Privacy Policy) URL은 필수
아동 보호, 광고 정책 관련 체크리스트를 반드시 확인

앱 설명과 SEO 최적화

설명 문구에 핵심 키워드 삽입: 영어 단어, 학습, WordADay, 개인 프로젝트, Flutter
스크린샷은 실제 사용성을 보여주는 형태로 준비

테스트 및 검증

내부 테스트 트랙 → 클로즈드 테스트 → 프로덕션 순으로 진행
실제 기기에서 UI/UX 흐름을 검증한 뒤 출시

결론: 개인 프로젝트에서 출시까지

이번 WordADay 앱은 바이브 코딩으로 직관적인 Flutter UI 개발 → 빠른 MVP 완성 → Google PlayStore 배포라는 과정을 거쳐 탄생했습니다.

요약하자면,

바이브 코딩은 사이드 프로젝트 동기부여와 속도를 높여줍니다.
Flutter UI는 빠르게 시각적 결과물을 얻는 데 최적화되어 있습니다.
PlayStore 등록은 개발뿐 아니라 정책과 마케팅 측면까지 고려해야 합니다.

독자 여러분도 작은 개인 프로젝트를 실제로 출시해보는 경험을 통해 개발자로서의 성장을 체감할 수 있습니다.

XGBoost 회귀 완전 정복: RMSE, MAE부터 Tweedie와 Gamma까지 최적 Objective 선택법

GeonWoo Kim — Mon, 25 Aug 2025 10:00:34 +0900

서론

XGBoost는 분류 문제뿐 아니라 회귀 문제에서도 강력한 성능을 발휘하는 알고리즘입니다. 특히 비선형 데이터, 결측치 처리, 대용량 데이터셋에 효과적이라는 장점이 있습니다. 그러나 회귀 문제에서는 단순히 reg:squarederror 같은 기본 Objective만 사용하는 경우가 많습니다. 실제로 데이터의 분포와 목적에 맞춰 Objective를 선택하고, 적절한 하이퍼파라미터를 조정하면 모델의 성능을 극대화할 수 있습니다.

이번 글에서는 XGBoost 회귀(Objective function) 활용법, RMSE와 MAE의 차이, Tweedie, Gamma 분포 회귀 적용법, 그리고 주요 하이퍼파라미터 튜닝 방법을 정리하겠습니다.

본론

1. XGBoost 회귀 Objective와 평가 지표 선택

XGBoost는 다양한 회귀용 Objective를 제공합니다. 데이터 분포와 목적에 맞게 선택해야 합니다.

reg:squarederror
- 기본값. 평균제곱오차(MSE)를 최소화.
- RMSE(Root Mean Squared Error) 지표와 궁합이 좋음.
- 예측값이 정규분포적 특성을 가질 때 적합.
reg:squaredlogerror
- 로그 스케일 오차 최소화.
- target 값이 지수적 성장 형태(예: 매출액, 가격)일 때 유용.
- 예측값이 음수가 되지 않는다는 점을 고려해야 함.
reg:gamma
- 양수 실수값(보험료, 대기 시간, 수익 등)에 적합.
- 분포가 오른쪽 꼬리가 긴 형태(skewed distribution)일 때 추천.
reg:tweedie
- Tweedie 분포 기반 회귀.
- 0 값이 다수 존재하면서 동시에 양수 연속값도 있는 경우 유용 (예: 보험 청구 건수, 날씨 데이터 강수량).
- tweedie_variance_power 하이퍼파라미터로 분포 형태 제어 가능:
  - 1 < power < 2 → 포아송+감마 혼합
  - power = 1 → 포아송 근사
  - power = 2 → 감마 근사

평가 지표 선택

RMSE (Root Mean Squared Error)
- 큰 오차에 민감 → 이상치 영향 반영 필요할 때 사용.
MAE (Mean Absolute Error)
- 이상치에 둔감 → 예측값 분포가 고르게 퍼져 있고 극단값이 문제되지 않을 때 사용.
Poisson Deviance / Tweedie Deviance
- reg:tweedie, reg:gamma 모델에서 활용 가능.

2. 회귀 학습에서 중요한 하이퍼파라미터

회귀 문제에서 성능을 좌우하는 주요 하이퍼파라미터는 다음과 같습니다.

학습률(eta)
- 기본값: 0.3
- 너무 크면 과적합, 너무 작으면 학습이 느려짐. 일반적으로 0.01~0.1 권장.
트리 깊이(max_depth)
- 모델 복잡도를 조절.
- 깊을수록 비선형 패턴을 잘 잡지만 과적합 위험 증가.
정규화 파라미터(lambda, alpha)
- L2(lambda), L1(alpha) 정규화 적용.
- 다중공선성이나 잡음을 줄이는 데 효과적.
max_delta_step (특히 reg:logistic, reg:gamma, reg:tweedie에서 중요)
- 모델의 수렴 안정성을 높이는 역할.
- 포아송/감마 계열 회귀에서는 1~10 범위에서 조정.
tweedie_variance_power
- reg:tweedie 전용.
- 1.1~1.9 범위에서 탐색 → 데이터 분포에 맞게 최적화.

3. 예제 코드: 다양한 회귀 Objective 적용

아래는 사이킷런 API 기반의 XGBoost 회귀 예제입니다.

import xgboost as xgb
from sklearn.datasets import make_regression
from sklearn.model_selection import train_test_split
from sklearn.metrics import mean_squared_error, mean_absolute_error

# 예시 데이터 생성
X, y = make_regression(n_samples=5000, n_features=20, noise=0.3, random_state=42)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

# XGBoost 회귀 모델 (Tweedie objective 적용)
params = {
    "objective": "reg:tweedie",
    "tweedie_variance_power": 1.5,
    "learning_rate": 0.05,
    "max_depth": 6,
    "n_estimators": 300,
    "eval_metric": "mae"
}

model = xgb.XGBRegressor(**params)
model.fit(X_train, y_train)

# 예측
y_pred = model.predict(X_test)

# 평가
rmse = mean_squared_error(y_test, y_pred, squared=False)
mae = mean_absolute_error(y_test, y_pred)

print(f"RMSE: {rmse:.4f}, MAE: {mae:.4f}")

결론

XGBoost 회귀에서 성능을 극대화하려면 데이터의 분포와 특성에 맞는 Objective를 선택하는 것이 중요합니다. RMSE와 MAE를 적절히 비교하며 평가 지표를 선택하고, reg:gamma, reg:tweedie 같은 특수 목적 Objective를 활용하면 일반적인 reg:squarederror보다 훨씬 나은 성능을 얻을 수 있습니다.

정리하면, XGBoost 회귀의 핵심은 올바른 Objective 선택과 하이퍼파라미터 최적화에 있다는 점입니다.

파이썬 병렬처리: 멀티프로세싱으로 CPU 코어를 100% 활용하는 방법

GeonWoo Kim — Wed, 20 Aug 2025 16:39:43 +0900

서론: 파이썬, 느리다는 편견을 깨다

파이썬은 쉽고 빠르게 코드를 작성할 수 있어 많은 사랑을 받고 있지만, "느리다"는 오명을 종종 듣곤 합니다. 이는 파이썬의 GIL(Global Interpreter Lock) 때문인데요. GIL은 한 번에 하나의 스레드만 파이썬 바이트코드를 실행할 수 있도록 허용하는 메커니즘으로, 멀티코어 환경에서 스레드를 여러 개 사용해도 실질적인 병렬 처리가 어렵게 만듭니다.

하지만 데이터 처리, 웹 스크래핑, 대규모 연산과 같은 작업에서는 이러한 한계가 병목 현상을 유발합니다. 그래서 우리는 이 병목 현상을 극복하고 파이썬의 성능을 극대화할 수 있는 병렬처리 기법에 대해 알아볼 필요가 있습니다. 이번 포스팅에서는 파이썬에서 병렬 처리를 구현하는 대표적인 방법인 멀티프로세싱(Multiprocessing)을 중심으로, 멀티쓰레딩(Multithreading)과 비교하고, 나아가 데이터 처리의 필수 라이브러리인 판다스(Pandas)를 병렬 처리하는 실용적인 방법까지 심도 있게 다뤄보겠습니다.

본론: 파이썬 병렬처리, 제대로 이해하기

1. 멀티쓰레딩 vs. 멀티프로세싱: GIL의 한계를 넘어서

파이썬에서 동시성을 다루는 대표적인 두 가지 방법은 멀티쓰레딩과 멀티프로세싱입니다. 이 둘의 가장 큰 차이점은 GIL의 적용 여부입니다.

멀티쓰레딩 (Multithreading): 하나의 프로세스 내에서 여러 스레드를 생성하여 작업을 분할합니다. 스레드는 메모리를 공유하기 때문에 데이터 접근이 용이하지만, GIL 때문에 CPU를 많이 사용하는 연산 작업(CPU-bound tasks)에서는 진정한 병렬 처리가 불가능합니다. 주로 네트워크 요청이나 파일 입출력과 같은 I/O-bound 작업에 적합합니다.
멀티프로세싱 (Multiprocessing): 여러 개의 독립적인 프로세스를 생성하여 작업을 수행합니다. 각 프로세스는 별도의 메모리 공간을 가지므로 GIL의 영향을 받지 않고, 여러 CPU 코어를 동시에 활용할 수 있습니다. 따라서 대규모 연산이나 복잡한 계산 등 CPU-bound 작업에 매우 효과적입니다.

간단한 예제 코드를 통해 두 기법의 차이를 직관적으로 살펴보겠습니다.

import time
import multiprocessing
import threading

def cpu_bound_task():
    # 간단한 CPU-bound 작업 (루프를 돌며 계산)
    count = 0
    for _ in range(10**8):
        count += 1

def run_with_multiprocessing():
    start = time.time()
    processes = []
    for _ in range(4): # 4개의 프로세스 생성
        p = multiprocessing.Process(target=cpu_bound_task)
        processes.append(p)
        p.start()

    for p in processes:
        p.join() # 프로세스가 종료될 때까지 기다림
    print(f"멀티프로세싱 소요 시간: {time.time() - start:.2f}초")

def run_with_threading():
    start = time.time()
    threads = []
    for _ in range(4): # 4개의 스레드 생성
        t = threading.Thread(target=cpu_bound_task)
        threads.append(t)
        t.start()

    for t in threads:
        t.join() # 스레드가 종료될 때까지 기다림
    print(f"멀티쓰레딩 소요 시간: {time.time() - start:.2f}초")

if __name__ == '__main__':
    run_with_multiprocessing()
    run_with_threading()

이 코드를 실행하면 멀티프로세싱이 멀티쓰레딩보다 훨씬 빠르게 작업을 완료하는 것을 확인할 수 있습니다.

2. 판다스(Pandas) 병렬처리: 대용량 데이터프레임 가공하기

데이터 분석가와 개발자에게 판다스는 필수적인 라이브러리입니다. 하지만 apply()나 map() 함수로 대용량 데이터프레임을 처리할 때, 단일 코어만 사용해 시간이 오래 걸리는 경우가 많습니다. 이때 pandarallel 라이브러리를 사용하면 판다스의 연산을 간단하게 병렬 처리할 수 있습니다.

먼저 pandarallel을 설치합니다.

pip install pandarallel

사용법은 매우 간단합니다. 초기화 후 기존 apply 함수 자리에 .parallel_apply()를 사용하기만 하면 됩니다.

import pandas as pd
from pandarallel import pandarallel

# pandarallel 초기화
pandarallel.initialize(nb_workers=4) # 사용할 코어 수 지정

# 예제 데이터프레임 생성
df_size = 10**6
df = pd.DataFrame({
    'a': range(df_size),
    'b': range(df_size)
})

# 복잡한 연산 함수 정의
def complex_operation(row):
    return row['a'] * row['b'] + 100

# 병렬 처리로 데이터프레임 연산
start_parallel = time.time()
df['result_parallel'] = df.parallel_apply(complex_operation, axis=1)
print(f"Pandarallel 병렬 처리 소요 시간: {time.time() - start_parallel:.2f}초")

# 일반적인 판다스 apply 연산
start_serial = time.time()
df['result_serial'] = df.apply(complex_operation, axis=1)
print(f"Pandas 일반 처리 소요 시간: {time.time() - start_serial:.2f}초")

대용량 데이터프레임에서 parallel_apply를 사용하면 일반 apply 대비 연산 속도가 크게 향상되는 것을 확인할 수 있습니다.

결론: 파이썬의 무한한 가능성을 열다

파이썬의 GIL은 단일 스레드 환경에서 메모리 관리를 효율적으로 해주는 장점도 있지만, 멀티코어 시대에 성능의 제약이 되는 것도 사실입니다. 하지만 이번 포스팅에서 살펴본 멀티프로세싱과 pandarallel과 같은 전문 라이브러리를 활용하면 이러한 한계를 극복하고 파이썬의 진정한 병렬 처리 능력을 끌어낼 수 있습니다.

이러한 기법들은 단순한 코드 최적화를 넘어, 여러분이 다루는 대규모 데이터와 복잡한 연산 작업의 처리 시간을 획기적으로 단축시켜 개발 생산성과 시스템 효율을 동시에 높여줄 것입니다.

Spring Rest API 캐싱전략 완벽 가이드: @Cacheable과 CacheManager 활용법

GeonWoo Kim — Mon, 18 Aug 2025 15:55:55 +0900

Spring Rest API 캐싱전략 완벽 가이드: @Cacheable과 CacheManager 활용법

서론

Rest API 서버를 운영하다 보면 가장 큰 고민 중 하나는 성능과 응답 속도입니다. 특히 조회 요청이 빈번한 API의 경우, 매번 DB를 조회하는 것은 서버 부담을 크게 증가시킵니다. 이를 효율적으로 해결하는 방법이 바로 캐싱(Caching)입니다.
Spring은 @Cacheable과 CacheManager를 통해 강력하면서도 유연한 캐싱 기능을 제공하고 있으며, 상황에 맞는 캐싱 전략을 적용하면 성능 최적화 효과를 극대화할 수 있습니다.

이번 포스팅에서는 Spring Rest API 캐싱전략, CacheManager 사용법, @Cacheable 활용법을 중심으로 실무 적용 방법을 정리하겠습니다.

본론

1. Spring Rest API 캐싱전략

Spring에서 캐싱은 크게 다음과 같은 전략으로 나눌 수 있습니다.

읽기 중심 API 캐싱: 자주 조회되지만 데이터 변경이 드문 API 응답을 캐싱.
조건부 캐싱: 특정 조건(예: 파라미터 값, 사용자 권한)에 따라 캐싱 여부 결정.
TTL(Time-to-Live) 전략: 데이터 유효기간을 설정하여 일정 시간 후 자동으로 캐시 무효화.
분산 캐싱: Redis, Hazelcast 등 외부 캐시 서버를 사용하여 다중 서버 환경에서도 일관된 캐시 유지.

캐싱 전략 선택 시 고려해야 할 요소는 다음과 같습니다.

데이터의 변경 주기
실시간성이 중요한지 여부
API 호출 빈도
인프라 구성(단일 서버 vs 다중 서버)

2. CacheManager 사용법

Spring은 CacheManager를 통해 다양한 캐시 구현체(EhCache, Redis, Caffeine 등)를 추상화합니다.

예제: Caffeine Cache 설정

import com.github.benmanes.caffeine.cache.Caffeine;
import org.springframework.cache.CacheManager;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.cache.caffeine.CaffeineCacheManager;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.concurrent.TimeUnit;

@Configuration
@EnableCaching
public class CacheConfig {

    @Bean
    public CacheManager cacheManager() {
        CaffeineCacheManager cacheManager = new CaffeineCacheManager("users", "products");
        cacheManager.setCaffeine(
                Caffeine.newBuilder()
                        .expireAfterWrite(10, TimeUnit.MINUTES)
                        .maximumSize(1000)
        );
        return cacheManager;
    }
}

위 코드에서는 Caffeine 캐시를 사용하며, users, products 캐시 영역을 정의했습니다. TTL은 10분, 최대 캐시 사이즈는 1000개로 설정되어 있습니다.

3. @Cacheable 사용법

@Cacheable은 메서드 실행 결과를 캐싱하고, 동일한 파라미터로 호출 시 캐시된 결과를 반환합니다.

기본 사용법

import org.springframework.cache.annotation.Cacheable;
import org.springframework.stereotype.Service;

@Service
public class UserService {

    @Cacheable(value = "users", key = "#userId")
    public User getUserById(Long userId) {
        simulateSlowService();
        return new User(userId, "User_" + userId);
    }

    private void simulateSlowService() {
        try {
            Thread.sleep(3000); // DB 조회 대기 시간 가정
        } catch (InterruptedException e) {
            throw new IllegalStateException(e);
        }
    }
}

주요 속성

value: 캐시 이름 지정 (CacheManager에서 관리)
key: 캐시 키 정의 (SpEL 사용 가능)
condition: 조건부 캐싱 여부 지정
unless: 결과에 따라 캐싱 제외

조건부 캐싱 예시

@Cacheable(value = "products", key = "#id", condition = "#id > 10")
public Product getProduct(Long id) {
    return new Product(id, "Product_" + id);
}

→ ID가 10보다 큰 경우에만 캐싱.

결론

Spring Rest API에서 캐싱은 단순한 성능 최적화 이상의 의미를 가집니다. 캐싱 전략을 올바르게 적용하면 DB 부하 감소, 응답 속도 향상, 서비스 안정성 강화라는 세 마리 토끼를 동시에 잡을 수 있습니다.

정리하자면,

CacheManager로 다양한 캐시 구현체를 통합 관리할 수 있고,
@Cacheable을 통해 선언형 캐싱을 손쉽게 적용할 수 있으며,
상황별 캐싱 전략(TTL, 조건부 캐싱, 분산 캐싱)을 병행하면 실무에서 강력한 성능 최적화를 이끌어낼 수 있습니다.

효율적인 캐싱 전략은 API 성능을 한 단계 끌어올리는 핵심 무기입니다.

Spring Batch 사용법: 대용량 데이터 처리를 위한 실무 가이드

GeonWoo Kim — Sat, 16 Aug 2025 14:23:22 +0900

Spring Batch 사용법: 대용량 데이터 처리를 위한 실무 가이드

서론

대규모 데이터 처리 작업은 단순히 코드 몇 줄로 해결할 수 있는 문제가 아닙니다. 안정성, 트랜잭션 관리, 스케줄링, 장애 복구 등 고려해야 할 요소가 많습니다. Spring Batch는 이러한 요구사항을 충족하기 위해 설계된 프레임워크로, 반복적이고 대량의 데이터 처리를 안정적으로 지원합니다.
본 포스팅에서는 Spring Batch의 핵심 개념, 설정 방법, 그리고 실무에서 주의해야 할 사항을 다루어, 개발자가 바로 활용할 수 있는 지식을 제공합니다.

본론

1. Spring Batch의 핵심 개념

Spring Batch는 크게 세 가지 개념으로 나눌 수 있습니다.

Job
- 배치 작업의 최상위 단위
- 하나의 Job은 여러 개의 Step으로 구성
Step
- Job을 구성하는 개별 처리 단계
- 일반적으로 읽기(Read) → 처리(Processing) → 쓰기(Write) 구조를 가짐
ItemReader / ItemProcessor / ItemWriter
- ItemReader: 데이터 소스로부터 데이터를 읽어옴 (예: DB, CSV, API)
- ItemProcessor: 읽어온 데이터를 가공 및 변환
- ItemWriter: 가공된 데이터를 목적지에 저장

즉, Spring Batch는 대량의 데이터를 작은 단위로 나누어 안정적으로 처리하는 구조를 제공합니다.

2. Spring Batch 기본 설정

Spring Batch 프로젝트를 시작하기 위해서는 Spring Boot + Spring Batch Starter 의존성을 추가합니다.

Maven 의존성

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-batch</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
</dependency>

기본 Job & Step 구성

@Configuration
@EnableBatchProcessing
public class BatchConfig {

    @Bean
    public Job exampleJob(JobRepository jobRepository, Step exampleStep) {
        return new JobBuilder("exampleJob", jobRepository)
                .start(exampleStep)
                .build();
    }

    @Bean
    public Step exampleStep(JobRepository jobRepository, PlatformTransactionManager transactionManager) {
        return new StepBuilder("exampleStep", jobRepository)
                .<String, String>chunk(10, transactionManager)
                .reader(exampleReader())
                .processor(exampleProcessor())
                .writer(exampleWriter())
                .build();
    }

    @Bean
    public ItemReader<String> exampleReader() {
        return new ListItemReader<>(List.of("A", "B", "C"));
    }

    @Bean
    public ItemProcessor<String, String> exampleProcessor() {
        return item -> item.toLowerCase();
    }

    @Bean
    public ItemWriter<String> exampleWriter() {
        return items -> items.forEach(System.out::println);
    }
}

위 코드는 간단한 예시로, 문자열 리스트 ["A", "B", "C"]를 읽어 소문자로 변환 후 출력합니다. 실제 환경에서는 DB, CSV, API 연동 등을 Reader/Writer에 적용할 수 있습니다.

3. Spring Batch 사용 시 유의사항

Spring Batch를 실무에서 사용할 때는 다음과 같은 포인트를 반드시 고려해야 합니다.

트랜잭션 관리

각 Step은 기본적으로 트랜잭션 단위로 동작합니다.
Chunk 크기(chunk-size)에 따라 롤백 단위가 달라지므로, 데이터 일관성을 고려해야 합니다.

성능 최적화

대규모 데이터의 경우 멀티 스레드 Step 또는 파티셔닝 전략을 활용하면 처리 속도를 높일 수 있습니다.
대용량 Batch는 Reader/Writer에서 I/O 최적화가 중요합니다.

재시작 전략

Spring Batch는 실패한 Job을 중단된 위치부터 재시작할 수 있습니다.
이를 위해 JobRepository(DB 테이블)에 실행 이력이 저장되며, 프로덕션 환경에서는 H2 대신 MySQL, PostgreSQL 같은 RDBMS를 권장합니다.

운영 모니터링

Job 실행 로그, Step별 처리 건수, 에러 내역 등을 수집/모니터링하는 체계를 구축해야 장애 대응이 수월합니다.

결론

Spring Batch는 대량 데이터 처리를 안정적이고 유연하게 지원하는 강력한 프레임워크입니다.
본 포스팅에서는 Spring Batch의 핵심 개념, 기본 설정 방법, 실무 적용 시 주의사항을 살펴보았습니다.

요약: Spring Batch를 올바르게 이해하고 활용하면, 대규모 데이터 처리 업무를 안정적이고 효율적으로 수행할 수 있습니다.

Spring Kafka 완벽 가이드: KafkaTemplate와 @KafkaListener, 재시도 및 Dead Letter Queue 활용법

GeonWoo Kim — Fri, 15 Aug 2025 09:05:49 +0900

Spring Kafka 완벽 가이드: KafkaTemplate와 @KafkaListener, 재시도 및 Dead Letter Queue 활용법

서론

Apache Kafka는 대규모 실시간 데이터 스트리밍과 비동기 메시징을 처리하는 데 최적화된 분산 이벤트 스트리밍 플랫폼입니다.
Spring Kafka는 이러한 Kafka의 기능을 Spring 환경에 자연스럽게 통합하여 개발자가 간결한 코드로 안정적이고 확장 가능한 메시지 기반 애플리케이션을 만들 수 있도록 지원합니다.

이 글에서는 Spring Kafka의 핵심 개념, KafkaTemplate 사용법, @KafkaListener 활용법과 주의사항, 그리고 재시도 로직 및 Dead Letter Queue(DLQ) 적용 방법을 실무 중심으로 정리합니다.

본론

1. Spring Kafka 핵심 개념

Spring Kafka의 주요 컴포넌트는 다음과 같습니다.

KafkaTemplate
Kafka 프로듀서 역할. 메시지를 전송하고 결과를 비동기/동기로 받을 수 있음.
@KafkaListener
Kafka 토픽을 구독하고 메시지를 처리하는 어노테이션 기반 컨슈머.
Listener Container
메시지 리스너 실행 환경을 관리하며 스레드, 오프셋 커밋, 재시도 정책 등을 제어.
ErrorHandler / SeekToCurrentErrorHandler
메시지 처리 실패 시 재시도 및 DLQ 라우팅 설정 가능.

기본 의존성 예시

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

2. KafkaTemplate 사용법

KafkaTemplate은 메시지를 Kafka로 전송하는 핵심 클래스입니다.

프로듀서 설정

@Configuration
public class KafkaProducerConfig {

    @Bean
    public ProducerFactory<String, String> producerFactory() {
        Map<String, Object> config = new HashMap<>();
        config.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
        config.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class);
        config.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class);
        return new DefaultKafkaProducerFactory<>(config);
    }

    @Bean
    public KafkaTemplate<String, String> kafkaTemplate() {
        return new KafkaTemplate<>(producerFactory());
    }
}

메세지 전송

@Service
public class KafkaProducerService {

    private final KafkaTemplate<String, String> kafkaTemplate;

    public KafkaProducerService(KafkaTemplate<String, String> kafkaTemplate) {
        this.kafkaTemplate = kafkaTemplate;
    }

    public void send(String topic, String message) {
        kafkaTemplate.send(topic, message)
            .addCallback(
                success -> System.out.println("전송 성공: " + success.getRecordMetadata()),
                failure -> System.err.println("전송 실패: " + failure.getMessage())
            );
    }
}

@KafkaListener 사용법과 주의사항

@KafkaListener는 Kafka 메시지 소비를 단순화합니다.

컨슈머 설정

@Configuration
public class KafkaConsumerConfig {

    @Bean
    public ConsumerFactory<String, String> consumerFactory() {
        Map<String, Object> config = new HashMap<>();
        config.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
        config.put(ConsumerConfig.GROUP_ID_CONFIG, "my-group");
        config.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class);
        config.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class);
        return new DefaultKafkaConsumerFactory<>(config);
    }

    @Bean
    public ConcurrentKafkaListenerContainerFactory<String, String> kafkaListenerContainerFactory() {
        ConcurrentKafkaListenerContainerFactory<String, String> factory =
            new ConcurrentKafkaListenerContainerFactory<>();
        factory.setConsumerFactory(consumerFactory());
        return factory;
    }
}

메세지 소비

@Service
public class KafkaConsumerService {

    @KafkaListener(topics = "test-topic", groupId = "my-group")
    public void consume(String message) {
        System.out.println("수신 메시지: " + message);
    }
}

주의사항

groupId 필수: 같은 groupId를 사용하는 컨슈머끼리는 메시지를 파티션 단위로 분배 처리.
파티션 수 고려: 병렬 컨슈머 수는 파티션 수 이상이 되어도 추가 컨슈머는 대기 상태.
에러 처리 필수: 예외 발생 시 무한 재시도 방지를 위해 재시도 및 DLQ 설정 필요.
오프셋 관리 전략: auto-commit 또는 수동 커밋 전략을 요구사항에 맞게 선택.

4. 재시도 로직과 Dead Letter Queue 적용

메시지 처리 중 오류가 발생하면 무한 재시도를 피하기 위해 재시도 횟수 제한과 DLQ를 설정하는 것이 권장됩니다.

재시도 & DLQ 설정 예시

@Configuration
public class KafkaErrorHandlerConfig {

    @Bean
    public ConcurrentKafkaListenerContainerFactory<String, String> kafkaListenerContainerFactory() {
        ConcurrentKafkaListenerContainerFactory<String, String> factory =
            new ConcurrentKafkaListenerContainerFactory<>();
        factory.setConsumerFactory(consumerFactory());

        // SeekToCurrentErrorHandler: 재시도 후 DLQ로 전송
        DeadLetterPublishingRecoverer recoverer =
            new DeadLetterPublishingRecoverer(kafkaTemplate(), (record, ex) -> 
                new TopicPartition(record.topic() + ".DLT", record.partition()));

        factory.setErrorHandler(new SeekToCurrentErrorHandler(recoverer, 3)); // 최대 3회 재시도
        return factory;
    }

    @Bean
    public ProducerFactory<String, String> producerFactory() {
        Map<String, Object> config = new HashMap<>();
        config.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
        config.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class);
        config.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class);
        return new DefaultKafkaProducerFactory<>(config);
    }

    @Bean
    public KafkaTemplate<String, String> kafkaTemplate() {
        return new KafkaTemplate<>(producerFactory());
    }
}

Dead Letter Queue 운영 팁

.DLT 접미사를 사용해 DLQ 토픽 이름을 명확하게 구분.
DLQ 데이터를 주기적으로 모니터링하여 장애 원인을 분석.
필요 시 DLQ 메시지를 재처리하는 별도 컨슈머 운영.

결론

Spring Kafka는 복잡한 Kafka API를 추상화하여 개발자가 간결하게 메시지 기반 애플리케이션을 개발할 수 있도록 돕습니다.
KafkaTemplate과 @KafkaListener를 올바르게 조합하고, 재시도 및 DLQ 설정을 적용하면 안정적인 이벤트 스트리밍 아키텍처를 구축할 수 있습니다.

요약:
Spring Kafka를 이해하고 재시도·DLQ 패턴을 적용하면, 실무에서 안정적이고 예측 가능한 메시징 시스템을 구현할 수 있습니다.