시작은 진짜 단순했다

비 오는 날 밤. 갑자기 천둥이 엄청 크게 쳤다.

"와 진짜 크다... 나만 들은 건가? 다른 사람들도 들었나?"

트위터에서 "천둥" 검색하면 반응은 나온다. 근데 우리 동네 사람인지 모르겠고, 실시간도 아니고, 그냥 검색 결과일 뿐이다.

같은 동네에서, 같은 순간을, 같이 경험하고 있다는 걸 실시간으로 볼 수 있으면?

그래서 만들었다. Hear That? — 천둥이 치면 같은 동네 사람들의 반응을 실시간으로 보는 웹앱.

라이브: https://hear-that.vercel.app GitHub: https://github.com/moonjun1/hear-that

어떤 앱인지

• 천둥이 치면 이모지(⚡😱🙉😂🌧️)로 바로 반응
• 같은 동네(~9km) 사람들의 반응이 실시간으로 피드에 뜸
• 지도에서 번개 위치를 실시간으로 보여줌 (기상청 낙뢰 API 연동)
• "Thunder Wave" — 번개 지점에서 소리가 퍼져나가는 동심원 애니메이션 (343m/s 실제 음속)
• 지역 채팅 — 같은 동네 사람들끼리 대화
• 당근마켓처럼 줌아웃하면 숫자로 묶이고, 줌인하면 개별 이모지로 펼쳐지는 클러스터링

만든 과정 — AI랑 같이 만들었다

이 프로젝트는 gstack + Claude Code로 만들었다. 솔직히 말하면, 코드의 대부분은 AI가 짰다. 내가 한 건 "뭘 만들지" 결정하고, "이거 이상한데?" 피드백 주고, "다음 이거 해" 지시한 것.

gstack이 뭔데?

gstack은 Garry Tan이 만든 오픈소스 AI 빌더 프레임워크다. Claude Code 위에서 돌아가는 스킬 시스템인데, /office-hours로 아이디어 브레인스토밍하고, /qa로 QA 테스트하고, /design-review로 디자인 리뷰하고, /ship으로 배포하는 식이다.

타임라인

4월 5일 밤 11시 — "천둥이 치는데 다른 사람 반응이 궁금하다"고 Claude에게 말함

11시 30분 — /office-hours 스킬로 아이디어 정리. "Hear That?"이라는 이름이 정해짐. 디자인 문서가 나옴.

12시 — GitHub repo 생성, 이슈 17개, 마일스톤 7개가 자동으로 세팅됨

12시 30분 — Day 1 코드 완성. Next.js + Supabase + Mapbox 세팅, 핵심 컴포넌트 13개.

새벽 1시 — Day 2-7 코드 전부 완성. PR 8개 머지. Vercel 배포.

새벽 2시 — 실제 기상청 API로 번개 데이터가 들어오기 시작. 실제로 충남 쪽에 번개가 치고 있었다.

4월 6일 — QA, 디자인 리뷰, 모바일 최적화. 버그 수정 25건. PR 20개 추가.

총: 하루 반 만에 52커밋, 29파일, 2,492줄, PR 28개.

기술 스택

왜 이 스택?

Supabase를 고른 이유 — 실시간 WebSocket이 핵심이었다. 누가 이모지를 탭하면 같은 동네 사람 피드에 즉시 떠야 한다. Supabase Realtime이 Postgres Changes를 WebSocket으로 브로드캐스트해준다. Firebase보다 SQL 쿼리가 자유롭고, 무료 tier가 넉넉하다.

Mapbox를 고른 이유 — Thunder Wave 애니메이션. 번개 지점에서 동심원이 343m/s로 퍼져나가는 걸 canvas로 그려야 했다. WebGL custom layer가 가능한 건 Mapbox뿐이었다. 네이버 지도나 카카오맵은 오버레이만 가능해서 이 애니메이션이 안 된다.

H3를 고른 이유 — "같은 동네"를 정의하는 문제. 행정구역(구/동)으로 나누면 경계에 있는 사람들이 갈라진다. H3 육각형 그리드는 경계가 자연스럽고, resolution 5로 설정하면 반경 ~9km로 "우리 동네" 느낌이 딱 맞다.

재밌었던 기술 문제들

1. 기상청 API에서 진짜 번개 좌표가 나온다

기상청 낙뢰관측자료 API(getLgt)는 개별 낙뢰마다 WGS84 위도/경도를 소수점 6자리까지 준다. 정밀도가 약 0.1m. 10분 지연이지만 준실시간이다.

문제는 바다에서 친 번개도 나온다는 것. 위도 3338.6, 경도 125131.9로 한국 육지만 필터링했다.

2. 서버리스에서 메모리 캐시는 의미 없다

Vercel 서버리스 환경에서 let lastPollTime = 0 같은 메모리 변수는 인스턴스마다 다르다. 1분 캐시를 걸어도 다른 인스턴스에서는 캐시가 없다.

해결: 매 폴링마다 DB의 weather_events를 전부 지우고(RPC 함수) 새로 넣는 "delete all + insert fresh" 방식으로 바꿨다.

3. Supabase Realtime 구독이 React Strict Mode에서 깨진다

React 18+ strict mode는 useEffect를 두 번 실행한다. initialized.current ref로 막으면 첫 번째 마운트에서 true가 되고 두 번째(실제) 마운트에서 구독이 스킵된다.

해결: useEffect(deps: [neighbors]) — 위치가 세팅되면 구독 시작, cleanup에서 해제. ref 대신 React 라이프사이클을 따르도록.

4. Vercel env에 줄바꿈이 들어간다

echo "KEY" | vercel env add 하면 줄바꿈(\n)이 같이 들어간다. Supabase anon key URL에 %0A가 붙어서 WebSocket 연결이 실패했다.

해결: printf 'KEY'로 줄바꿈 없이 넣기.

gstack 스킬들이 실제로 도움이 됐나?

솔직히, 엄청 도움이 됐다.

/office-hours — 아이디어를 디자인 문서로 바꿔줬다. "천둥이 치면 반응 보고 싶다"를 테이블 스키마, API 설계, 7일 빌드 플랜까지 만들어줬다. 세컨드 오피니언으로 "Thunder Wave" 아이디어도 여기서 나왔다.

/qa — headless 브라우저로 전체 사이트를 테스트한다. WebGL이 안 되는 한계가 있었지만, 콘솔 에러, API 응답, viewport 경고 같은 건 잡아줬다.

/design-review — 소스 코드 기반으로 디자인 이슈 27건을 찾아줬다. "AI 슬롭" (큰 이모지를 디자인 요소로 쓰는 것) 같은 건 혼자서는 못 알아챘을 것 같다.

/grill-me — 이 블로그 글의 방향도 여기서 정했다. "목적이 뭐야?" 하나 물어보는 게 30분 고민보다 빠르다.

숫자로 보는 프로젝트

배운 것

1. AI는 "뭘 만들지"는 못 정한다. 코드는 잘 짜는데, "천둥 칠 때 반응이 보고 싶다"는 인간의 경험에서 나온다. AI는 실행자이지 발명가가 아니다.

2. "바로 만들어" 대신 "설계부터"가 맞다. /office-hours로 디자인 문서를 먼저 만들고 시작하니까, 중간에 방향을 잃지 않았다. 7일 플랜을 하루 반에 끝낸 것도 설계가 있어서 가능했다.

3. 사이드 프로젝트는 재미가 동력이다. "이거 돈 될까?" 생각하면 안 만든다. "천둥 치면 다른 사람 반응 궁금하다" 이 호기심 하나로 36시간을 버텼다.

4. Vercel + Supabase 무료 tier가 생각보다 넉넉하다. Supabase 무료 200 동시 접속, Vercel 무료 배포, Mapbox 월 50,000 로드, 기상청 일 10,000건. 사이드 프로젝트에는 충분하다.

한계와 다음 할 것

• 천둥이 안 치면 텅 비어있다 (해결: 과거 이벤트 히스토리)
• 사용자가 나밖에 없다 (해결: 공유해서 사람 모으기)
• 커스텀 도메인 없음 (hear-that.xyz 사려다 말았다)
• 푸시 알림 없음 (천둥 칠 때 알림)

마무리

천둥이 치는 밤, "다른 사람들도 들었나?" 궁금했을 뿐인데 앱이 하나 나왔다.

AI 시대에 사이드 프로젝트 만드는 건 진입 장벽이 거의 없다. 아이디어만 있으면 된다. 코드는 AI가 짜주고, 배포는 Vercel이 해주고, DB는 Supabase가 해준다.

중요한 건 "뭘 만들지" 결정하는 것. 그건 여전히 사람의 몫이다.

다음에 천둥이 치면, hear-that.vercel.app 열어봐. 같은 동네 사람들이 뭐라고 하는지 볼 수 있다.

태그: #사이드프로젝트 #Next.js #Supabase #Mapbox #기상청API #AI개발 #ClaudeCode #gstack #날씨앱 #실시간

Ruby on Rails로 마크다운 블로그 만들기

🤔 Ruby on Rails란 무엇인가?

Ruby on Rails(줄여서 Rails)는 Ruby 언어로 작성된 오픈소스 웹 애플리케이션 프레임워크입니다. 2004년 David Heinemeier Hansson이 만든 이 프레임워크는 "개발자의 행복"을 중시하며, 빠르고 효율적인 웹 개발을 가능하게 합니다.

핵심 철학

• Convention over Configuration (설정보다 관례): 복잡한 설정 파일 대신 표준 관례를 따름
• Don't Repeat Yourself (DRY): 코드 중복을 최소화
• REST(Representational State Transfer): RESTful한 설계 원칙 준수

💡 왜 Ruby on Rails를 선택했나?

✅ 장점들

1. 빠른 개발 속도

# 단 몇 줄로 CRUD가 완성됩니다
class PostsController < ApplicationController
  def index
    @posts = Post.published.recent
  end

  def show
    @post = Post.find(params[:id])
  end
end

2. 강력한 ORM (Active Record)

# SQL 없이도 복잡한 쿼리 작성 가능
Post.where(published: true)
    .where('created_at > ?', 1.week.ago)
    .order(created_at: :desc)

3. 풍부한 Gem 생태계

# Gemfile - 필요한 기능을 쉽게 추가
gem 'redcarpet'      # 마크다운 처리
gem 'rouge'          # 코드 하이라이팅
gem 'bootstrap', '~> 5.1'  # UI 프레임워크

4. MVC 패턴의 완벽한 구현

app/
├── controllers/     # 요청 처리 로직
├── models/         # 데이터 모델
├── views/          # 화면 표시
└── services/       # 비즈니스 로직 분리

⚠️ 단점들

1. 성능 이슈

• Ruby 자체가 상대적으로 느림
• 대용량 트래픽 처리에 한계

2. 메모리 사용량

• 다른 언어에 비해 메모리 사용량이 높음
• 서버 비용 증가 가능성

3. 학습 곡선

• Rails의 "마법" 같은 기능들이 초보자에게 혼란 야기
• Ruby 언어 자체도 함께 학습해야 함

📈 Ruby on Rails의 현재 위치

🔥 여전히 인기 있는 이유

1. 스타트업의 선택

   • 빠른 MVP(Minimum Viable Product) 개발
   • GitHub, Shopify, Airbnb 등이 Rails로 시작

2. 성숙한 생태계

   • 15년+ 의 안정성
   • 풍부한 문서와 커뮤니티

3. 최근 업데이트

   # Rails 7의 새로운 기능들
   - Hotwire: SPA 없이도 모던한 웹앱
   - Import Maps: JavaScript 번들링 간소화
   - CSS Bundling: 모던 CSS 워크플로우

📊 현재 사용 현황 (2024년 기준)

• Stack Overflow 설문조사: 웹 프레임워크 13위
• GitHub Stars: 50,000+ (꾸준한 성장)
• Job Market: 여전히 많은 Rails 개발자 구인

🛠️ 내가 구현한 마크다운 블로그

📁 프로젝트 구조

markdown_blog/
├── app/
│   ├── controllers/
│   │   ├── application_controller.rb
│   │   └── posts_controller.rb
│   ├── models/
│   │   ├── application_record.rb
│   │   └── post.rb
│   ├── services/
│   │   └── markdown_renderer.rb
│   └── views/
│       ├── layouts/
│       │   └── application.html.erb
│       └── posts/
│           ├── index.html.erb
│           ├── show.html.erb
│           ├── new.html.erb
│           ├── edit.html.erb
│           └── _form.html.erb
├── config/
│   ├── routes.rb
│   └── database.yml
└── db/
    └── migrate/
        └── 001_create_posts.rb

🎯 핵심 기능 구현

1. 마크다운 렌더링

# app/services/markdown_renderer.rb
class MarkdownRenderer
  def self.render(content)
    renderer = Redcarpet::Render::HTML.new(
      filter_html: true,
      hard_wrap: true,
      link_attributes: { target: '_blank' }
    )

    markdown = Redcarpet::Markdown.new(
      renderer,
      autolink: true,
      tables: true,
      fenced_code_blocks: true,
      strikethrough: true
    )

    markdown.render(content).html_safe
  end
end

2. 포스트 모델

# app/models/post.rb
class Post < ApplicationRecord
  validates :title, presence: true, length: { minimum: 1, maximum: 255 }
  validates :content, presence: true, length: { minimum: 1 }

  scope :published, -> { where(published: true) }
  scope :recent, -> { order(created_at: :desc) }

  def markdown_content
    MarkdownRenderer.render(content)
  end

  def reading_time
    words_per_minute = 200
    word_count = content.split.size
    (word_count / words_per_minute.to_f).ceil
  end

  def summary(limit = 150)
    stripped_content = content.gsub(/[#*`>-]/, '').strip
    truncated = stripped_content.length > limit ? 
                stripped_content[0...limit] + '...' : 
                stripped_content
    truncated
  end
end

3. 컨트롤러

# app/controllers/posts_controller.rb
class PostsController < ApplicationController
  before_action :find_post, only: [:show, :edit, :update, :destroy]

  def index
    @posts = Post.published.recent
  end

  def show
  end

  def new
    @post = Post.new
  end

  def create
    @post = Post.new(post_params)

    if @post.save
      redirect_to @post, notice: '포스트가 성공적으로 작성되었습니다.'
    else
      render :new
    end
  end

  private

  def find_post
    @post = Post.find(params[:id])
  end

  def post_params
    params.require(:post).permit(:title, :content, :published)
  end
end

🎨 UI/UX 특징

반응형 디자인

<!-- app/views/layouts/application.html.erb -->
<div class="container-fluid">
  <div class="row">
    <div class="col-lg-8 mx-auto">
      <main>
        <%= yield %>
      </main>
    </div>
  </div>
</div>

실시간 미리보기

<!-- app/views/posts/_form.html.erb -->
<div class="row">
  <div class="col-md-6">
    <%= form.text_area :content, class: "form-control", 
                       rows: 20, 
                       placeholder: "마크다운으로 작성하세요..." %>
  </div>
  <div class="col-md-6">
    <div class="markdown-preview border p-3">
      <!-- JavaScript로 실시간 미리보기 구현 -->
    </div>
  </div>
</div>

완성된 기능들

1. CRUD 완전 구현: 포스트 생성, 읽기, 수정, 삭제
2. 마크다운 처리: Redcarpet + Rouge로 완벽한 문법 지원
3. 상태 관리: 초안/발행 시스템
4. 반응형 UI: Bootstrap 5 기반 모바일 친화적 디자인
5. 코드 하이라이팅: 다양한 프로그래밍 언어 지원
6. 자동 기능: 읽기 시간 계산, 요약문 생성

실행 방법

# 1. 의존성 설치
bundle install

# 2. 데이터베이스 설정
rails db:create
rails db:migrate
rails db:seed

# 3. 서버 실행
rails server

# 4. 브라우저 접속
http://localhost:3000

Ruby on Rails의 미래

발전 방향

1. 성능 개선: Ruby 3.0+의 성능 향상
2. 모던 웹: Hotwire로 SPA 없는 리치 웹앱
3. API 모드: Rails API + React/Vue 조합 증가
4. 컨테이너화: Docker, Kubernetes 지원 강화

개인적인 생각

Rails를 선택한 이유는 단순합니다. 빠르게 아이디어를 실현할 수 있기 때문입니다.

몇 시간 만에 완전히 작동하는 블로그 시스템을 만들 수 있었고, 코드도 읽기 쉽고 유지보수하기 좋습니다. 비록 성능상 한계는 있지만, 개인 프로젝트나 중소규모 서비스에는 여전히 최고의 선택 중 하나라고 생각합니다.

결론

Ruby on Rails는:

• ✅ 빠른 개발이 필요한 프로젝트에 최적
• ✅ 스타트업이나 MVP 개발에 탁월
• ✅ 개발자 경험을 중시하는 팀에 적합
• ⚠️ 대용량 트래픽 처리에는 추가 고려 필요
• ⚠️ 성능이 최우선인 프로젝트는 다른 선택 고려

2024년 현재도 많은 개발자들이 Rails를 선택하는 이유는 명확합니다. 복잡한 설정 없이 비즈니스 로직에 집중할 수 있고, 풍부한 생태계와 커뮤니티가 뒷받침하고 있기 때문입니다.

앞으로도 Rails는 웹 개발의 좋은 선택지 중 하나로 남을 것 같습니다. 특히 빠른 프로토타이핑과 개발 생산성을 중시하는 환경에서는 여전히 강력한 도구입니다.

🎯 학습 총괄

이 문서는 Spring Batch 학습의 최종 단계로, 실무에서 필요한 고급 활용법과 노하우를 종합적으로 다룹니다.

🚀 고급 아키텍처 패턴

1. 마이크로서비스 환경에서의 배치

/**
 * 분산 배치 시스템 아키�ecture
 */
@Configuration
@EnableScheduling
public class DistributedBatchConfig {

    /**
     * 배치 작업 분산 처리를 위한 Message Queue 기반 아키텍처
     */
    @Bean
    public Job distributedProcessingJob() {
        return new JobBuilder("distributedProcessingJob", jobRepository)
            .start(dataPartitionStep())        // 1. 데이터 분할
            .next(messagePublishStep())        // 2. 메시지 큐에 작업 발행
            .next(resultAggregationStep())     // 3. 결과 수집 및 집계
            .build();
    }

    /**
     * Kafka를 통한 배치 작업 분산
     */
    @KafkaListener(topics = "batch-work-queue")
    public void processBatchWork(@Payload BatchWorkMessage message) {
        try {
            // 분산된 배치 작업 처리
            JobParameters params = new JobParametersBuilder()
                .addString("workId", message.getWorkId())
                .addString("dataRange", message.getDataRange())
                .toJobParameters();

            jobLauncher.run(workerBatchJob, params);

            // 완료 메시지 발행
            kafkaTemplate.send("batch-completion-topic", 
                new BatchCompletionMessage(message.getWorkId(), "SUCCESS"));

        } catch (Exception e) {
            // 실패 처리 및 재시도 로직
            handleDistributedBatchFailure(message, e);
        }
    }
}

2. 이벤트 기반 배치 시스템

/**
 * 도메인 이벤트 기반 배치 처리
 */
@Component
public class EventDrivenBatchManager {

    /**
     * 주문 완료 이벤트 발생 시 자동 배치 실행
     */
    @EventListener
    @Async
    public void handleOrderCompletedEvent(OrderCompletedEvent event) {
        // 주문 완료 후 1시간 뒤 배송 준비 배치 실행
        scheduleDelayedBatch("shipping-preparation-job", 
                           Duration.ofHours(1), 
                           Map.of("orderId", event.getOrderId()));
    }

    /**
     * 재고 부족 이벤트 발생 시 긴급 배치 실행
     */
    @EventListener
    public void handleLowStockEvent(LowStockEvent event) {
        // 즉시 재고 보충 요청 배치 실행
        executeImmediateBatch("stock-replenishment-job", 
                            Map.of("productId", event.getProductId(),
                                   "urgentLevel", "HIGH"));
    }

    private void scheduleDelayedBatch(String jobName, Duration delay, Map<String, Object> params) {
        // Spring의 TaskScheduler를 사용한 지연 실행
        taskScheduler.schedule(() -> {
            try {
                JobParameters jobParams = createJobParameters(params);
                jobLauncher.run(getJob(jobName), jobParams);
            } catch (Exception e) {
                log.error("Scheduled batch execution failed: {}", jobName, e);
                // 실패 시 재시도 로직 또는 알림 발송
            }
        }, Instant.now().plus(delay));
    }
}

3. 조건부 배치 체인

/**
 * 복잡한 비즈니스 로직을 위한 조건부 배치 체인
 */
@Configuration
public class ConditionalBatchChainConfig {

    /**
     * 비즈니스 규칙에 따른 동적 배치 플로우
     */
    @Bean
    public Job smartProcessingJob() {
        return new JobBuilder("smartProcessingJob", jobRepository)
            .start(dataAnalysisStep())
            .next(businessRuleDecider())

            // 고객 등급별 분기
            .from(businessRuleDecider()).on("VIP_CUSTOMERS")
                .to(vipCustomerProcessingFlow())
            .from(businessRuleDecider()).on("REGULAR_CUSTOMERS")
                .to(regularCustomerProcessingFlow())
            .from(businessRuleDecider()).on("NEW_CUSTOMERS")
                .to(newCustomerOnboardingFlow())

            // 데이터 볼륨별 분기
            .from(businessRuleDecider()).on("LARGE_VOLUME")
                .to(parallelProcessingFlow())
            .from(businessRuleDecider()).on("SMALL_VOLUME")
                .to(sequentialProcessingStep())

            // 최종 집계
            .from(vipCustomerProcessingFlow()).on("*").to(finalAggregationStep())
            .from(regularCustomerProcessingFlow()).on("*").to(finalAggregationStep())
            .from(newCustomerOnboardingFlow()).on("*").to(finalAggregationStep())
            .from(sequentialProcessingStep()).on("*").to(finalAggregationStep())

            .build();
    }

    /**
     * 비즈니스 규칙 결정자
     */
    @Bean
    public JobExecutionDecider businessRuleDecider() {
        return (jobExecution, stepExecution) -> {

            // 데이터 분석 결과 조회
            ExecutionContext context = stepExecution.getExecutionContext();
            int totalRecords = context.getInt("totalRecords", 0);
            String customerSegment = context.getString("primarySegment", "REGULAR");
            boolean isEndOfMonth = isEndOfMonth();
            boolean isHighTrafficPeriod = isHighTrafficPeriod();

            // 복합 조건 평가
            if (isEndOfMonth && "VIP".equals(customerSegment)) {
                return new FlowExecutionStatus("VIP_CUSTOMERS");
            }

            if (totalRecords > 100000 || isHighTrafficPeriod) {
                return new FlowExecutionStatus("LARGE_VOLUME");
            }

            if ("NEW".equals(customerSegment)) {
                return new FlowExecutionStatus("NEW_CUSTOMERS");
            }

            return new FlowExecutionStatus("REGULAR_CUSTOMERS");
        };
    }
}

💡 실무 성능 최적화 기법

1. 동적 청크 크기 조정

/**
 * 런타임 성능에 따른 동적 청크 크기 조정
 */
@Component
public class AdaptiveChunkSizeManager {

    private final AtomicInteger currentChunkSize = new AtomicInteger(100);
    private final MovingAverage processingTimeAvg = new MovingAverage(10);
    private final MovingAverage memoryUsageAvg = new MovingAverage(5);

    /**
     * 성능 메트릭 기반 청크 크기 자동 조정
     */
    public int getOptimalChunkSize() {
        double avgProcessingTime = processingTimeAvg.getAverage();
        double avgMemoryUsage = memoryUsageAvg.getAverage();
        int current = currentChunkSize.get();

        // 메모리 사용률이 높으면 청크 크기 감소
        if (avgMemoryUsage > 0.8) {
            int newSize = Math.max(10, (int) (current * 0.8));
            currentChunkSize.set(newSize);
            log.info("Reducing chunk size due to high memory usage: {} -> {}", current, newSize);
            return newSize;
        }

        // 처리 시간이 목표보다 길면 청크 크기 감소
        if (avgProcessingTime > 5000) { // 5초 초과
            int newSize = Math.max(10, (int) (current * 0.9));
            currentChunkSize.set(newSize);
            log.info("Reducing chunk size due to slow processing: {} -> {}", current, newSize);
            return newSize;
        }

        // 성능이 좋으면 청크 크기 증가 시도
        if (avgProcessingTime < 1000 && avgMemoryUsage < 0.6) {
            int newSize = Math.min(1000, (int) (current * 1.2));
            currentChunkSize.set(newSize);
            log.info("Increasing chunk size due to good performance: {} -> {}", current, newSize);
            return newSize;
        }

        return current;
    }

    /**
     * 성능 메트릭 업데이트
     */
    public void updateMetrics(long processingTime, double memoryUsage) {
        processingTimeAvg.add(processingTime);
        memoryUsageAvg.add(memoryUsage);
    }
}

/**
 * 동적 청크 크기를 사용하는 Step
 */
@Bean
@JobScope
public Step adaptiveStep() {
    return new StepBuilder("adaptiveStep", jobRepository)
        .<InputData, OutputData>chunk(adaptiveChunkSizeManager::getOptimalChunkSize, transactionManager)
        .reader(reader())
        .processor(performanceAwareProcessor())
        .writer(writer())
        .listener(new ChunkPerformanceListener(adaptiveChunkSizeManager))
        .build();
}

2. 지능형 배치 스케줄링

/**
 * 시스템 부하와 비즈니스 우선순위를 고려한 스마트 스케줄링
 */
@Component
@EnableScheduling
public class IntelligentBatchScheduler {

    private final PriorityQueue<ScheduledBatch> batchQueue = new PriorityQueue<>(
        Comparator.comparing(ScheduledBatch::getPriority).reversed()
            .thenComparing(ScheduledBatch::getScheduledTime)
    );

    /**
     * 시스템 리소스 상태 기반 배치 실행 결정
     */
    @Scheduled(fixedDelay = 30000) // 30초마다 체크
    public void executeScheduledBatches() {
        SystemResourceInfo resources = getSystemResources();

        // 시스템 부하가 높으면 중요한 배치만 실행
        if (resources.getCpuUsage() > 80 || resources.getMemoryUsage() > 85) {
            log.warn("High system load detected. Only critical batches will run.");
            executeCriticalBatchesOnly();
            return;
        }

        // 비즈니스 시간대별 실행 정책
        LocalTime now = LocalTime.now();
        if (isBusinessHours(now)) {
            // 업무시간: 가벼운 배치만 실행
            executeLeightweightBatches(resources);
        } else {
            // 야간/주말: 모든 배치 실행 가능
            executeAllPendingBatches(resources);
        }
    }

    /**
     * 동적 우선순위 계산
     */
    private int calculateDynamicPriority(BatchJobInfo jobInfo) {
        int basePriority = jobInfo.getBasePriority();

        // SLA 데드라인 접근도
        Duration timeToDeadline = Duration.between(LocalDateTime.now(), jobInfo.getDeadline());
        if (timeToDeadline.toHours() < 2) {
            basePriority += 50; // 급상승
        } else if (timeToDeadline.toHours() < 6) {
            basePriority += 20;
        }

        // 재시도 횟수에 따른 우선순위 감소
        basePriority -= (jobInfo.getRetryCount() * 5);

        // 데이터 의존성 체크
        if (hasWaitingDependentJobs(jobInfo)) {
            basePriority += 30;
        }

        return Math.max(0, basePriority);
    }

    /**
     * 스마트 리소스 할당
     */
    private ExecutionPlan createExecutionPlan(List<ScheduledBatch> batches, SystemResourceInfo resources) {
        ExecutionPlan plan = new ExecutionPlan();

        // 메모리 집약적 vs CPU 집약적 배치 분류
        List<ScheduledBatch> memoryIntensive = batches.stream()
            .filter(b -> b.getResourceProfile().isMemoryIntensive())
            .toList();

        List<ScheduledBatch> cpuIntensive = batches.stream()
            .filter(b -> b.getResourceProfile().isCpuIntensive())
            .toList();

        // 리소스별 최적 스케줄링
        if (resources.getMemoryUsage() < 60) {
            plan.addParallelExecution(memoryIntensive, 2); // 메모리 충분하면 병렬 실행
        } else {
            plan.addSequentialExecution(memoryIntensive); // 순차 실행
        }

        if (resources.getCpuUsage() < 50) {
            plan.addParallelExecution(cpuIntensive, 4); // CPU 여유롭면 높은 병렬도
        } else {
            plan.addParallelExecution(cpuIntensive, 2); // 제한된 병렬도
        }

        return plan;
    }
}

3. 메모리 최적화 ItemReader

/**
 * 대용량 데이터 처리를 위한 메모리 효율적 ItemReader
 */
public class OptimizedLargeDataReader implements ItemReader<DataRecord> {

    private final DataSource dataSource;
    private final String query;
    private final int fetchSize;
    private Connection connection;
    private PreparedStatement statement;
    private ResultSet resultSet;
    private boolean initialized = false;

    public OptimizedLargeDataReader(DataSource dataSource, String query, int fetchSize) {
        this.dataSource = dataSource;
        this.query = query;
        this.fetchSize = fetchSize;
    }

    @Override
    public DataRecord read() throws Exception {
        if (!initialized) {
            initialize();
        }

        if (resultSet.next()) {
            return mapResultSetToRecord(resultSet);
        } else {
            // 메모리 해제
            closeResources();
            return null;
        }
    }

    private void initialize() throws SQLException {
        connection = dataSource.getConnection();

        // 메모리 효율성을 위한 설정
        connection.setAutoCommit(false);
        statement = connection.prepareStatement(query, 
                                              ResultSet.TYPE_FORWARD_ONLY, 
                                              ResultSet.CONCUR_READ_ONLY);

        // MySQL/PostgreSQL 스트리밍 설정
        statement.setFetchSize(fetchSize);
        if (connection.getMetaData().getDriverName().contains("mysql")) {
            statement.setFetchSize(Integer.MIN_VALUE); // MySQL streaming
        }

        resultSet = statement.executeQuery();
        initialized = true;

        log.info("Initialized streaming reader with fetch size: {}", fetchSize);
    }

    /**
     * 메모리 사용량 모니터링
     */
    @PreDestroy
    public void monitorMemoryUsage() {
        Runtime runtime = Runtime.getRuntime();
        long usedMemory = runtime.totalMemory() - runtime.freeMemory();
        long maxMemory = runtime.maxMemory();
        double usagePercentage = (double) usedMemory / maxMemory * 100;

        if (usagePercentage > 85) {
            log.warn("High memory usage detected: {:.1f}%. Consider reducing fetch size.", usagePercentage);

            // 가비지 컬렉션 힌트
            runtime.gc();
        }
    }
}

🛡️ 프로덕션 운영 베스트 프랙티스

1. 배치 보안 강화

/**
 * 엔터프라이즈급 배치 보안 설정
 */
@Configuration
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class BatchSecurityConfig {

    /**
     * 배치 실행 권한 제어
     */
    @Bean
    public JobOperatorSecurityWrapper secureJobOperator(JobOperator jobOperator) {
        return new JobOperatorSecurityWrapper(jobOperator);
    }

    /**
     * 데이터 암호화를 위한 ItemProcessor
     */
    @Bean
    public ItemProcessor<SensitiveData, SensitiveData> encryptionProcessor() {
        return item -> {
            // 민감한 데이터 암호화
            if (item.containsSensitiveInformation()) {
                item.setEncryptedData(encryptionService.encrypt(item.getSensitiveData()));
                item.clearPlainTextData(); // 원본 데이터 삭제
            }

            // 데이터 마스킹 (로그용)
            item.setMaskedData(maskingService.maskSensitiveFields(item));

            return item;
        };
    }

    /**
     * 감사 로그 기록
     */
    @Component
    public class BatchAuditLogger implements JobExecutionListener {

        @Override
        public void beforeJob(JobExecution jobExecution) {
            auditService.logBatchStart(
                jobExecution.getJobInstance().getJobName(),
                SecurityContextHolder.getContext().getAuthentication().getName(),
                extractSensitiveParameters(jobExecution.getJobParameters())
            );
        }

        @Override
        public void afterJob(JobExecution jobExecution) {
            auditService.logBatchCompletion(
                jobExecution.getId(),
                jobExecution.getStatus(),
                calculateDataAccessSummary(jobExecution)
            );
        }

        private DataAccessSummary calculateDataAccessSummary(JobExecution jobExecution) {
            return jobExecution.getStepExecutions().stream()
                .collect(DataAccessSummary.collector());
        }
    }
}

2. 배치 성능 프로파일링

/**
 * 실시간 배치 성능 프로파일링 시스템
 */
@Component
public class BatchPerformanceProfiler {

    private final MeterRegistry meterRegistry;
    private final Map<String, Timer.Sample> activeTimers = new ConcurrentHashMap<>();

    /**
     * 상세 성능 메트릭 수집
     */
    @EventListener
    public void handleStepStart(StepExecutionEvent event) {
        String stepName = event.getStepExecution().getStepName();

        // 타이머 시작
        Timer.Sample sample = Timer.start(meterRegistry);
        activeTimers.put(stepName, sample);

        // 메모리 스냅샷
        recordMemorySnapshot(stepName + ".start");

        // CPU 사용률 모니터링 시작
        startCpuMonitoring(stepName);
    }

    @EventListener
    public void handleStepEnd(StepExecutionEvent event) {
        String stepName = event.getStepExecution().getStepName();
        StepExecution execution = event.getStepExecution();

        // 타이머 종료
        Timer.Sample sample = activeTimers.remove(stepName);
        if (sample != null) {
            sample.stop(Timer.builder("batch.step.duration")
                .tag("step", stepName)
                .tag("status", execution.getStatus().toString())
                .register(meterRegistry));
        }

        // 처리량 메트릭
        recordThroughputMetrics(stepName, execution);

        // 메모리 사용량 변화
        recordMemorySnapshot(stepName + ".end");

        // 성능 분석 리포트 생성
        generatePerformanceReport(stepName, execution);
    }

    /**
     * 실시간 성능 분석 및 알림
     */
    private void generatePerformanceReport(String stepName, StepExecution execution) {
        PerformanceReport report = PerformanceReport.builder()
            .stepName(stepName)
            .duration(calculateDuration(execution))
            .throughput(calculateThroughput(execution))
            .memoryUsed(calculateMemoryDelta(stepName))
            .errorRate(calculateErrorRate(execution))
            .build();

        // 성능 임계값 체크
        if (report.getThroughput() < getExpectedThroughput(stepName) * 0.8) {
            alertService.sendPerformanceAlert(
                "Low throughput detected in step: " + stepName,
                report
            );
        }

        // 성능 히스토리 저장
        performanceHistoryService.save(report);
    }

    /**
     * 성능 트렌드 분석
     */
    @Scheduled(fixedRate = 300000) // 5분마다
    public void analyzePerfomanceTrends() {
        List<PerformanceReport> recentReports = 
            performanceHistoryService.getRecentReports(Duration.ofHours(1));

        for (String stepName : getActiveStepNames()) {
            List<PerformanceReport> stepReports = recentReports.stream()
                .filter(r -> r.getStepName().equals(stepName))
                .sorted(Comparator.comparing(PerformanceReport::getTimestamp))
                .toList();

            if (stepReports.size() < 3) continue;

            // 성능 저하 트렌드 탐지
            if (isPerformanceDegrading(stepReports)) {
                alertService.sendTrendAlert(
                    "Performance degradation trend detected in step: " + stepName,
                    calculateTrendAnalysis(stepReports)
                );
            }
        }
    }
}

3. 고급 데이터 검증 시스템

/**
 * 엔터프라이즈급 데이터 품질 보장 시스템
 */
@Component
public class DataQualityManager {

    /**
     * 다층 데이터 검증 체계
     */
    public class MultiLevelValidationProcessor implements ItemProcessor<RawData, ValidatedData> {

        private final List<DataValidator> validators;
        private final DataQualityReporter reporter;

        @Override
        public ValidatedData process(RawData item) throws Exception {
            ValidationContext context = new ValidationContext(item);

            // 1단계: 기본 스키마 검증
            ValidationResult schemaResult = validateSchema(item, context);
            if (!schemaResult.isValid()) {
                reporter.recordValidationFailure("SCHEMA", item, schemaResult.getErrors());
                return null; // 스키마 오류는 처리 불가
            }

            // 2단계: 비즈니스 규칙 검증
            ValidationResult businessResult = validateBusinessRules(item, context);
            if (!businessResult.isValid()) {
                // 비즈니스 규칙 위반은 quarantine으로 분류
                return createQuarantineRecord(item, businessResult.getErrors());
            }

            // 3단계: 데이터 일관성 검증
            ValidationResult consistencyResult = validateDataConsistency(item, context);
            if (!consistencyResult.isValid()) {
                // 일관성 문제는 수정 시도
                item = attemptDataCorrection(item, consistencyResult.getErrors());
            }

            // 4단계: 품질 점수 계산
            double qualityScore = calculateQualityScore(item, context);

            ValidatedData result = new ValidatedData(item);
            result.setQualityScore(qualityScore);
            result.setValidationTimestamp(LocalDateTime.now());

            // 품질 메트릭 기록
            reporter.recordQualityMetrics(result);

            return result;
        }

        /**
         * AI/ML 기반 데이터 품질 예측
         */
        private double predictDataQuality(RawData item) {
            // 머신러닝 모델을 사용한 품질 예측
            return qualityPredictionModel.predict(
                extractQualityFeatures(item)
            );
        }
    }

    /**
     * 실시간 데이터 품질 대시보드
     */
    @RestController
    @RequestMapping("/api/data-quality")
    public class DataQualityController {

        @GetMapping("/dashboard")
        public DataQualityDashboard getQualityDashboard() {
            return DataQualityDashboard.builder()
                .overallQualityScore(calculateOverallQualityScore())
                .qualityTrends(getQualityTrends(Duration.ofDays(7)))
                .topQualityIssues(getTopQualityIssues(10))
                .qualityByDataSource(getQualityByDataSource())
                .qualityImprovement(getQualityImprovementSuggestions())
                .build();
        }

        @GetMapping("/quality-rules")
        public List<DataQualityRule> getActiveQualityRules() {
            return dataQualityRuleManager.getActiveRules();
        }

        @PostMapping("/quality-rules")
        public ResponseEntity<DataQualityRule> createQualityRule(@RequestBody DataQualityRule rule) {
            DataQualityRule created = dataQualityRuleManager.createRule(rule);
            return ResponseEntity.ok(created);
        }
    }
}

📈 비즈니스 가치 극대화

1. 배치 ROI 측정 시스템

/**
 * 배치 시스템의 비즈니스 가치 측정
 */
@Service
public class BatchBusinessValueCalculator {

    /**
     * 배치 시스템 ROI 계산
     */
    public BatchROIReport calculateBatchROI(String jobName, Period period) {

        // 1. 비용 계산
        BatchCostInfo costs = calculateBatchCosts(jobName, period);

        // 2. 효익 계산
        BatchBenefitInfo benefits = calculateBatchBenefits(jobName, period);

        // 3. ROI 계산
        double roi = (benefits.getTotalValue() - costs.getTotalCost()) / costs.getTotalCost() * 100;

        return BatchROIReport.builder()
            .jobName(jobName)
            .period(period)
            .totalCosts(costs)
            .totalBenefits(benefits)
            .roi(roi)
            .paybackPeriod(calculatePaybackPeriod(costs, benefits))
            .recommendations(generateOptimizationRecommendations(costs, benefits))
            .build();
    }

    private BatchBenefitInfo calculateBatchBenefits(String jobName, Period period) {
        return BatchBenefitInfo.builder()
            // 자동화로 인한 인력 절약
            .laborCostSaving(calculateLaborCostSaving(jobName, period))
            // 처리 시간 단축으로 인한 기회비용 절약
            .timeSaving(calculateTimeSavingValue(jobName, period))
            // 오류 감소로 인한 비용 절약
            .errorReductionValue(calculateErrorReductionValue(jobName, period))
            // 고객 만족도 향상 가치
            .customerSatisfactionValue(calculateCustomerSatisfactionValue(jobName, period))
            // 컴플라이언스 준수 가치
            .complianceValue(calculateComplianceValue(jobName, period))
            .build();
    }

    /**
     * 배치 성능과 비즈니스 KPI 연결
     */
    public BusinessImpactAnalysis analyzeBatchBusinessImpact(String jobName) {

        // 배치 성능 메트릭 수집
        BatchPerformanceMetrics performance = getRecentPerformanceMetrics(jobName);

        // 비즈니스 KPI와의 상관관계 분석
        List<KPICorrelation> correlations = analyzeKPICorrelations(jobName, performance);

        // 개선 기회 식별
        List<ImprovementOpportunity> opportunities = identifyImprovementOpportunities(correlations);

        return BusinessImpactAnalysis.builder()
            .jobName(jobName)
            .performanceMetrics(performance)
            .kpiCorrelations(correlations)
            .improvementOpportunities(opportunities)
            .estimatedBusinessImpact(calculateEstimatedImpact(opportunities))
            .build();
    }
}

2. 지속적 개선 시스템

/**
 * 배치 시스템 지속적 개선 자동화
 */
@Component
public class ContinuousImprovementEngine {

    /**
     * A/B 테스트 기반 배치 최적화
     */
    @Scheduled(cron = "0 0 2 * * SUN") // 매주 일요일 새벽 2시
    public void runWeeklyOptimizationExperiments() {

        List<String> jobNames = getActiveJobNames();

        for (String jobName : jobNames) {
            // 현재 성능 베이스라인 설정
            PerformanceBaseline baseline = establishPerformanceBaseline(jobName);

            // 최적화 실험 후보 생성
            List<OptimizationExperiment> experiments = generateOptimizationExperiments(jobName, baseline);

            for (OptimizationExperiment experiment : experiments) {
                // 실험 환경에서 테스트 실행
                ExperimentResult result = runOptimizationExperiment(experiment);

                // 결과 분석
                if (result.isSignificantImprovement()) {
                    // 프로덕션 적용 제안
                    proposeProductionDeployment(experiment, result);
                }

                // 실험 결과 저장
                optimizationHistoryService.save(experiment, result);
            }
        }
    }

    /**
     * 머신러닝 기반 성능 예측 및 최적화
     */
    public class MLBasedOptimizer {

        private final MachineLearningModel performancePredictionModel;
        private final MachineLearningModel configurationOptimizationModel;

        /**
         * 성능 예측 기반 사전 최적화
         */
        public void predictiveOptimization(String jobName) {

            // 과거 성능 데이터 수집
            List<PerformanceRecord> historicalData = getHistoricalPerformance(jobName, Duration.ofDays(90));

            // 미래 워크로드 예측
            WorkloadForecast forecast = predictFutureWorkload(jobName, Duration.ofDays(7));

            // 최적 설정 예측
            BatchConfiguration optimalConfig = configurationOptimizationModel.predict(
                OptimizationInput.builder()
                    .historicalPerformance(historicalData)
                    .forecastedWorkload(forecast)
                    .systemConstraints(getCurrentSystemConstraints())
                    .businessRequirements(getBusinessRequirements(jobName))
                    .build()
            );

            // 예측된 최적 설정 적용 제안
            if (isSignificantConfigurationChange(optimalConfig)) {
                proposeConfigurationChange(jobName, optimalConfig);
            }
        }
    }
}

🎓 Spring Batch 학습 로드맵 완성

실력 수준별 체크리스트

🔰 초급 (Beginner)

• Spring Batch 기본 개념 이해 (Job, Step, ItemReader/Processor/Writer)
• 간단한 CSV → DB 배치 구현
• H2 데이터베이스로 로컬 테스트 환경 구축
• 기본적인 에러 처리 (Skip, Retry) 이해
• 배치 메타데이터 테이블 이해

🎯 중급 (Intermediate)

• 복잡한 비즈니스 로직이 포함된 ItemProcessor 구현
• 데이터베이스 간 데이터 이관 배치 작성
• 조건부 Step 실행 및 Flow 제어
• 멀티스레드 처리 구현
• 배치 스케줄링 및 모니터링 시스템 구축
• 단위 테스트 및 통합 테스트 작성

🚀 고급 (Advanced)

• 파티셔닝을 통한 대용량 데이터 분산 처리
• 복잡한 에러 처리 정책 및 재시작 메커니즘 구현
• 성능 최적화 및 튜닝
• 마이크로서비스 환경에서의 분산 배치 시스템
• 실시간 모니터링 및 알림 시스템
• 보안 및 감사 로깅 구현

🏆 전문가 (Expert)

• 엔터프라이즈급 배치 아키텍처 설계
• AI/ML 기반 배치 최적화 시스템 구축
• 클라우드 네이티브 배치 시스템 설계
• 배치 시스템 ROI 측정 및 비즈니스 가치 분석
• 지속적 개선 및 자동화 시스템 구축
• 팀 리딩 및 기술 멘토링

실무 프로젝트 추천 순서

1. 개인 프로젝트: 간단한 데이터 ETL 배치
2. 팀 프로젝트: 회사 내부 데이터 처리 자동화
3. 서비스 프로젝트: 고객 대상 배치 기반 서비스
4. 플랫폼 프로젝트: 범용 배치 플랫폼 구축
5. 오픈소스 기여: Spring Batch 생태계 기여

🎯 마무리 및 실무 조언

🔑 핵심 원칙

1. 단순함 추구: 복잡한 배치보다는 이해하기 쉬운 배치
2. 점진적 개선: 처음부터 완벽하려 하지 말고 단계적 발전
3. 모니터링 우선: 배치 상태를 항상 파악할 수 있도록 구성
4. 에러 대응: 실패는 당연한 것, 복구 가능한 시스템 설계
5. 문서화: 배치 로직과 운영 가이드 필수 작성

💡 실무 성공 팁

• 작게 시작하기: 큰 배치를 여러 개의 작은 배치로 분할
• 테스트 환경 구축: 프로덕션과 동일한 테스트 환경 필수
• 성능 측정: 처음부터 성능 메트릭 수집 체계 구축
• 장애 대응 계획: 배치 실패 시 대응 절차 미리 수립
• 지속적 학습: Spring Batch 커뮤니티 및 최신 동향 팔로우

🎉 축하합니다! Spring Batch의 모든 핵심 개념과 실무 활용법을 마스터했습니다.

이제 여러분은 엔터프라이즈급 배치 시스템을 설계하고 구현할 수 있는 전문가가 되었습니다.

지속적인 실습과 실무 적용을 통해 더욱 발전하시기 바랍니다! 🚀

🎯 학습 목표

• 배치 실행 중 발생하는 다양한 에러 상황 처리
• Skip, Retry, Restart 정책 구현
• 배치 실행 상태 모니터링 및 알림 시스템 구축
• 실무에서 필요한 로깅 및 추적 기능 구현

🚨 에러 처리 전략

에러 유형별 처리 방법

[Reader 에러]           [Processor 에러]        [Writer 에러]
     ↓                      ↓                    ↓
- 파일 없음/읽기 실패       - 데이터 검증 실패       - DB 연결 실패
- 네트워크 연결 실패       - 외부 API 호출 실패     - 제약조건 위반
- 권한 없음              - 메모리 부족           - 트랜잭션 충돌
     ↓                      ↓                    ↓
[재시도] or [건너뛰기]    [건너뛰기] or [중단]    [재시도] or [중단]

1. 고급 Skip 정책 구현

package com.example.batchtutorial.policy;

import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.core.step.skip.SkipLimitExceededException;
import org.springframework.batch.core.step.skip.SkipPolicy;
import org.springframework.dao.DataIntegrityViolationException;
import org.springframework.web.client.ResourceAccessException;

import java.sql.SQLException;
import java.util.HashMap;
import java.util.Map;

/**
 * 에러 유형별 차등 Skip 정책
 */
@Slf4j
public class SmartSkipPolicy implements SkipPolicy {

    private final Map<Class<? extends Throwable>, Integer> skipLimits;
    private final Map<Class<? extends Throwable>, Integer> currentCounts;

    public SmartSkipPolicy() {
        this.skipLimits = new HashMap<>();
        this.currentCounts = new HashMap<>();

        // 에러 유형별 Skip 한도 설정
        skipLimits.put(ValidationException.class, 50);              // 검증 오류: 50개까지
        skipLimits.put(DataIntegrityViolationException.class, 10);  // DB 제약조건: 10개까지
        skipLimits.put(ResourceAccessException.class, 5);           // 네트워크 오류: 5개까지
        skipLimits.put(SQLException.class, 3);                      // SQL 오류: 3개까지
    }

    @Override
    public boolean shouldSkip(Throwable exception, int skipCount) throws SkipLimitExceededException {

        Class<? extends Throwable> exceptionClass = exception.getClass();

        // 에러 유형별 카운터 증가
        currentCounts.put(exceptionClass, currentCounts.getOrDefault(exceptionClass, 0) + 1);

        // 해당 에러 유형의 Skip 한도 확인
        Integer limit = skipLimits.get(exceptionClass);
        if (limit == null) {
            log.error("Unknown exception type, not skipping: {}", exceptionClass.getSimpleName());
            return false;  // 알 수 없는 에러는 Skip 하지 않음
        }

        Integer currentCount = currentCounts.get(exceptionClass);

        if (currentCount <= limit) {
            log.warn("Skipping exception #{} of type {}: {} (limit: {})", 
                    currentCount, exceptionClass.getSimpleName(), exception.getMessage(), limit);
            return true;
        } else {
            log.error("Skip limit exceeded for {}: {} > {}", 
                    exceptionClass.getSimpleName(), currentCount, limit);
            throw new SkipLimitExceededException(limit, exception);
        }
    }

    /**
     * Skip 통계 정보 반환
     */
    public Map<String, Integer> getSkipStatistics() {
        Map<String, Integer> stats = new HashMap<>();
        currentCounts.forEach((clazz, count) -> 
            stats.put(clazz.getSimpleName(), count)
        );
        return stats;
    }
}

2. 지능적 Retry 정책 구현

package com.example.batchtutorial.policy;

import lombok.extern.slf4j.Slf4j;
import org.springframework.dao.TransientDataAccessException;
import org.springframework.retry.RetryContext;
import org.springframework.retry.policy.RetryPolicy;
import org.springframework.web.client.ResourceAccessException;

import java.net.ConnectException;
import java.net.SocketTimeoutException;
import java.time.Duration;
import java.time.LocalDateTime;
import java.util.HashMap;
import java.util.Map;

/**
 * 에러 유형별 차등 Retry 정책
 */
@Slf4j
public class SmartRetryPolicy implements RetryPolicy {

    private final Map<Class<? extends Throwable>, Integer> retryLimits;
    private final Map<Class<? extends Throwable>, Duration> backoffIntervals;

    public SmartRetryPolicy() {
        this.retryLimits = new HashMap<>();
        this.backoffIntervals = new HashMap<>();

        // 에러 유형별 재시도 설정
        retryLimits.put(ConnectException.class, 5);                    // 연결 오류: 5회
        retryLimits.put(SocketTimeoutException.class, 3);              // 타임아웃: 3회
        retryLimits.put(ResourceAccessException.class, 4);             // 리소스 접근: 4회
        retryLimits.put(TransientDataAccessException.class, 3);        // DB 일시 오류: 3회

        // 백오프 간격 설정
        backoffIntervals.put(ConnectException.class, Duration.ofSeconds(2));
        backoffIntervals.put(SocketTimeoutException.class, Duration.ofSeconds(5));
        backoffIntervals.put(ResourceAccessException.class, Duration.ofSeconds(3));
        backoffIntervals.put(TransientDataAccessException.class, Duration.ofSeconds(1));
    }

    @Override
    public boolean canRetry(RetryContext context) {
        Throwable lastThrowable = context.getLastThrowable();
        if (lastThrowable == null) {
            return true;
        }

        Class<? extends Throwable> exceptionClass = lastThrowable.getClass();
        Integer limit = retryLimits.get(exceptionClass);

        if (limit == null) {
            log.debug("No retry policy for exception type: {}", exceptionClass.getSimpleName());
            return false;  // 재시도 정책이 없는 에러는 재시도 안함
        }

        int attemptCount = context.getRetryCount();
        boolean canRetry = attemptCount < limit;

        if (canRetry) {
            Duration backoff = backoffIntervals.get(exceptionClass);
            if (backoff != null && attemptCount > 0) {
                log.info("Retrying in {} seconds... (attempt {} of {})", 
                        backoff.getSeconds(), attemptCount + 1, limit);

                try {
                    Thread.sleep(backoff.toMillis());
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                }
            }

            log.warn("Retrying operation (attempt {} of {}) for error: {}", 
                    attemptCount + 1, limit, lastThrowable.getMessage());
        } else {
            log.error("Retry limit exceeded for {}: {} attempts", 
                    exceptionClass.getSimpleName(), limit);
        }

        return canRetry;
    }

    @Override
    public RetryContext open(RetryContext parent) {
        return new RetryContext() {
            private int count = 0;
            private Throwable lastThrowable;
            private final LocalDateTime startTime = LocalDateTime.now();

            @Override
            public boolean isExhaustedOnly() {
                return false;
            }

            @Override
            public Throwable getLastThrowable() {
                return lastThrowable;
            }

            @Override
            public int getRetryCount() {
                return count;
            }

            @Override
            public void registerThrowable(Throwable throwable) {
                this.lastThrowable = throwable;
                this.count++;
            }

            @Override
            public void setAttribute(String name, Object value) {
                // 필요한 경우 속성 저장 구현
            }

            @Override
            public Object getAttribute(String name) {
                return null;
            }
        };
    }

    @Override
    public void close(RetryContext context) {
        if (context.getRetryCount() > 0) {
            log.info("Retry operation completed after {} attempts", context.getRetryCount());
        }
    }
}

3. 포괄적 에러 처리 Step 설정

package com.example.batchtutorial.config;

import com.example.batchtutorial.exception.ValidationException;
import com.example.batchtutorial.policy.SmartRetryPolicy;
import com.example.batchtutorial.policy.SmartSkipPolicy;
import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.core.Job;
import org.springframework.batch.core.Step;
import org.springframework.batch.core.job.builder.JobBuilder;
import org.springframework.batch.core.repository.JobRepository;
import org.springframework.batch.core.step.builder.StepBuilder;
import org.springframework.batch.item.ItemProcessor;
import org.springframework.batch.item.ItemReader;
import org.springframework.batch.item.ItemWriter;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.dao.DataIntegrityViolationException;
import org.springframework.dao.TransientDataAccessException;
import org.springframework.transaction.PlatformTransactionManager;
import org.springframework.web.client.ResourceAccessException;

import java.net.ConnectException;
import java.net.SocketTimeoutException;

/**
 * 포괄적 에러 처리가 적용된 배치 설정
 */
@Slf4j
@Configuration
public class ErrorHandlingBatchConfig {

    @Autowired
    private JobRepository jobRepository;

    @Autowired
    private PlatformTransactionManager transactionManager;

    /**
     * 에러 처리가 강화된 Job
     */
    @Bean
    public Job resilientJob(Step resilientStep) {
        return new JobBuilder("resilientJob", jobRepository)
                .start(resilientStep)
                .build();
    }

    /**
     * 포괄적 에러 처리 Step
     */
    @Bean
    public Step resilientStep(ItemReader<Object> reader,
                             ItemProcessor<Object, Object> processor,
                             ItemWriter<Object> writer) {
        return new StepBuilder("resilientStep", jobRepository)
                .<Object, Object>chunk(50, transactionManager)
                .reader(reader)
                .processor(processor)
                .writer(writer)

                // Fault Tolerance 활성화
                .faultTolerant()

                // Skip 정책 설정
                .skipPolicy(new SmartSkipPolicy())
                .skip(ValidationException.class)
                .skip(DataIntegrityViolationException.class)
                .skip(ResourceAccessException.class)

                // Retry 정책 설정
                .retryPolicy(new SmartRetryPolicy())
                .retry(ConnectException.class)
                .retry(SocketTimeoutException.class)
                .retry(TransientDataAccessException.class)

                // 치명적 예외 (Skip/Retry 하지 않음)
                .noSkip(OutOfMemoryError.class)
                .noSkip(StackOverflowError.class)
                .noRetry(OutOfMemoryError.class)

                // 리스너 등록
                .listener(errorHandlingStepListener())
                .listener(new DetailedSkipListener())

                build();
    }

    @Bean
    public ErrorHandlingStepListener errorHandlingStepListener() {
        return new ErrorHandlingStepListener();
    }
}

🔄 배치 재시작 기능

1. 재시작 가능한 Job 설정

package com.example.batchtutorial.config;

import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.core.Job;
import org.springframework.batch.core.Step;
import org.springframework.batch.core.job.builder.JobBuilder;
import org.springframework.batch.core.job.flow.FlowExecutionStatus;
import org.springframework.batch.core.job.flow.JobExecutionDecider;
import org.springframework.batch.core.repository.JobRepository;
import org.springframework.batch.core.step.builder.StepBuilder;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.transaction.PlatformTransactionManager;

/**
 * 재시작 가능한 배치 Job 설정
 */
@Slf4j
@Configuration
public class RestartableBatchConfig {

    @Autowired
    private JobRepository jobRepository;

    @Autowired
    private PlatformTransactionManager transactionManager;

    /**
     * 재시작 가능한 Job
     */
    @Bean
    public Job restartableJob(Step dataProcessingStep, 
                             Step dataValidationStep,
                             Step dataCleanupStep,
                             JobExecutionDecider restartDecider) {
        return new JobBuilder("restartableJob", jobRepository)
                .start(dataProcessingStep)
                .next(restartDecider)
                .from(restartDecider).on("RESTART_NEEDED").to(dataValidationStep)
                .from(restartDecider).on("CONTINUE").to(dataCleanupStep)
                .build();
    }

    /**
     * 데이터 처리 Step (재시작 지점 추적)
     */
    @Bean
    public Step dataProcessingStep(ItemReader<Object> reader,
                                  ItemProcessor<Object, Object> processor,
                                  ItemWriter<Object> writer) {
        return new StepBuilder("dataProcessingStep", jobRepository)
                .<Object, Object>chunk(100, transactionManager)
                .reader(reader)
                .processor(processor)
                .writer(writer)

                // 재시작을 위한 상태 저장 활성화
                .allowStartIfComplete(false)  // 완료된 Step은 재시작하지 않음

                // 재시작 지점 추적
                .listener(new RestartPointTrackingListener())

                build();
    }

    /**
     * 재시작 결정자
     */
    @Bean
    public JobExecutionDecider restartDecider() {
        return (jobExecution, stepExecution) -> {

            // 이전 실행에서 실패했는지 확인
            if (stepExecution != null && stepExecution.getExitStatus().getExitCode().equals("FAILED")) {
                log.info("Previous execution failed, restart needed");
                return new FlowExecutionStatus("RESTART_NEEDED");
            }

            // Step 실행 통계 확인
            if (stepExecution != null && stepExecution.getSkipCount() > 10) {
                log.warn("High skip count detected: {}, validation needed", stepExecution.getSkipCount());
                return new FlowExecutionStatus("RESTART_NEEDED");
            }

            return new FlowExecutionStatus("CONTINUE");
        };
    }
}

2. 재시작 지점 추적 리스너

package com.example.batchtutorial.listener;

import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.core.*;
import org.springframework.batch.core.listener.StepExecutionListenerSupport;
import org.springframework.batch.item.ExecutionContext;

import java.time.LocalDateTime;

/**
 * 재시작 지점을 추적하는 리스너
 */
@Slf4j
public class RestartPointTrackingListener extends StepExecutionListenerSupport {

    private static final String LAST_PROCESSED_ID = "last.processed.id";
    private static final String RESTART_COUNT = "restart.count";
    private static final String LAST_RESTART_TIME = "last.restart.time";

    @Override
    public void beforeStep(StepExecution stepExecution) {
        ExecutionContext executionContext = stepExecution.getExecutionContext();

        // 재시작 횟수 증가
        int restartCount = executionContext.getInt(RESTART_COUNT, 0);
        if (stepExecution.getJobExecution().getJobInstance().getVersion() > 0) {
            restartCount++;
            executionContext.putInt(RESTART_COUNT, restartCount);
            executionContext.putString(LAST_RESTART_TIME, LocalDateTime.now().toString());

            log.info("🔄 Job restarted {} times. Last restart: {}", 
                    restartCount, LocalDateTime.now());
        }

        // 마지막 처리 지점 복원
        Long lastProcessedId = executionContext.getLong(LAST_PROCESSED_ID, 0L);
        if (lastProcessedId > 0) {
            log.info("📍 Resuming from last processed ID: {}", lastProcessedId);
        }
    }

    @Override
    public ExitStatus afterStep(StepExecution stepExecution) {
        ExecutionContext executionContext = stepExecution.getExecutionContext();

        // 처리 통계 저장
        executionContext.putLong("final.read.count", stepExecution.getReadCount());
        executionContext.putLong("final.write.count", stepExecution.getWriteCount());
        executionContext.putLong("final.skip.count", stepExecution.getSkipCount());

        // 재시작이 필요한 조건 확인
        if (stepExecution.getSkipCount() > 50) {
            log.warn("⚠️ High skip count: {}. Step marked for review", stepExecution.getSkipCount());
            return new ExitStatus("FAILED", "High skip count requires review");
        }

        if (stepExecution.getWriteCount() == 0) {
            log.warn("⚠️ No items written. Possible data source issue");
            return new ExitStatus("FAILED", "No data processed");
        }

        log.info("✅ Step completed successfully. Read: {}, Write: {}, Skip: {}", 
                stepExecution.getReadCount(), 
                stepExecution.getWriteCount(), 
                stepExecution.getSkipCount());

        return stepExecution.getExitStatus();
    }

    /**
     * 현재 처리 지점 업데이트 (ItemWriter에서 호출)
     */
    public static void updateLastProcessedId(ExecutionContext context, Long id) {
        context.putLong(LAST_PROCESSED_ID, id);
    }
}

📊 실시간 배치 모니터링

1. 배치 상태 모니터링 서비스

package com.example.batchtutorial.service;

import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.core.*;
import org.springframework.batch.core.explore.JobExplorer;
import org.springframework.batch.core.launch.JobOperator;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.time.Duration;
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.util.*;
import java.util.stream.Collectors;

/**
 * 배치 모니터링 서비스
 */
@Slf4j
@Service
public class BatchMonitoringService {

    @Autowired
    private JobExplorer jobExplorer;

    @Autowired
    private JobOperator jobOperator;

    /**
     * 실행 중인 배치 목록 조회
     */
    public List<BatchExecutionInfo> getRunningBatches() {
        List<BatchExecutionInfo> runningBatches = new ArrayList<>();

        Set<Long> runningExecutions = jobOperator.getRunningExecutions("*");

        for (Long executionId : runningExecutions) {
            JobExecution jobExecution = jobExplorer.getJobExecution(executionId);
            if (jobExecution != null) {
                BatchExecutionInfo info = createBatchInfo(jobExecution);
                runningBatches.add(info);
            }
        }

        return runningBatches;
    }

    /**
     * 최근 배치 실행 이력 조회
     */
    public List<BatchExecutionInfo> getRecentBatchHistory(int count) {
        List<String> jobNames = jobExplorer.getJobNames();
        List<BatchExecutionInfo> recentExecutions = new ArrayList<>();

        for (String jobName : jobNames) {
            List<JobInstance> jobInstances = jobExplorer.getJobInstances(jobName, 0, count);

            for (JobInstance instance : jobInstances) {
                List<JobExecution> executions = jobExplorer.getJobExecutions(instance);
                for (JobExecution execution : executions) {
                    BatchExecutionInfo info = createBatchInfo(execution);
                    recentExecutions.add(info);
                }
            }
        }

        // 최근 실행 순으로 정렬
        return recentExecutions.stream()
                .sorted((a, b) -> b.getStartTime().compareTo(a.getStartTime()))
                .limit(count)
                .collect(Collectors.toList());
    }

    /**
     * 특정 Job의 상세 정보 조회
     */
    public DetailedBatchInfo getBatchDetails(Long executionId) {
        JobExecution jobExecution = jobExplorer.getJobExecution(executionId);
        if (jobExecution == null) {
            return null;
        }

        DetailedBatchInfo details = new DetailedBatchInfo();
        details.setJobExecution(jobExecution);

        // Step별 상세 정보
        Collection<StepExecution> stepExecutions = jobExecution.getStepExecutions();
        List<StepExecutionInfo> stepInfos = new ArrayList<>();

        for (StepExecution stepExecution : stepExecutions) {
            StepExecutionInfo stepInfo = createStepInfo(stepExecution);
            stepInfos.add(stepInfo);
        }

        details.setStepExecutions(stepInfos);
        details.setOverallStatistics(calculateOverallStatistics(stepExecutions));

        return details;
    }

    /**
     * 배치 실행 중단
     */
    public boolean stopBatch(Long executionId) {
        try {
            boolean stopped = jobOperator.stop(executionId);
            if (stopped) {
                log.info("🛑 Batch execution {} stopped successfully", executionId);
            } else {
                log.warn("⚠️ Failed to stop batch execution {}", executionId);
            }
            return stopped;
        } catch (Exception e) {
            log.error("❌ Error stopping batch execution {}: {}", executionId, e.getMessage());
            return false;
        }
    }

    /**
     * 배치 재시작
     */
    public Long restartBatch(Long executionId) {
        try {
            Long newExecutionId = jobOperator.restart(executionId);
            log.info("🔄 Batch execution {} restarted as {}", executionId, newExecutionId);
            return newExecutionId;
        } catch (Exception e) {
            log.error("❌ Error restarting batch execution {}: {}", executionId, e.getMessage());
            return null;
        }
    }

    /**
     * 시스템 상태 체크
     */
    public SystemHealthInfo getSystemHealth() {
        SystemHealthInfo health = new SystemHealthInfo();

        // 메모리 사용량
        Runtime runtime = Runtime.getRuntime();
        long maxMemory = runtime.maxMemory();
        long usedMemory = runtime.totalMemory() - runtime.freeMemory();
        health.setMemoryUsage((double) usedMemory / maxMemory * 100);

        // 실행 중인 배치 개수
        health.setRunningBatchCount(getRunningBatches().size());

        // 최근 실패한 배치 개수
        List<BatchExecutionInfo> recentBatches = getRecentBatchHistory(50);
        long failedCount = recentBatches.stream()
                .filter(batch -> "FAILED".equals(batch.getStatus()))
                .count();
        health.setRecentFailureCount(failedCount);

        // 전체 상태 결정
        if (health.getMemoryUsage() > 90 || failedCount > 5) {
            health.setOverallStatus("CRITICAL");
        } else if (health.getMemoryUsage() > 70 || failedCount > 2) {
            health.setOverallStatus("WARNING");
        } else {
            health.setOverallStatus("HEALTHY");
        }

        return health;
    }

    // 헬퍼 메서드들
    private BatchExecutionInfo createBatchInfo(JobExecution jobExecution) {
        BatchExecutionInfo info = new BatchExecutionInfo();
        info.setExecutionId(jobExecution.getId());
        info.setJobName(jobExecution.getJobInstance().getJobName());
        info.setStatus(jobExecution.getStatus().toString());
        info.setStartTime(LocalDateTime.ofInstant(jobExecution.getStartTime().toInstant(), ZoneId.systemDefault()));

        if (jobExecution.getEndTime() != null) {
            info.setEndTime(LocalDateTime.ofInstant(jobExecution.getEndTime().toInstant(), ZoneId.systemDefault()));
            info.setDuration(Duration.between(info.getStartTime(), info.getEndTime()));
        }

        // 진행률 계산
        Collection<StepExecution> stepExecutions = jobExecution.getStepExecutions();
        if (!stepExecutions.isEmpty()) {
            long totalRead = stepExecutions.stream().mapToLong(StepExecution::getReadCount).sum();
            long totalWrite = stepExecutions.stream().mapToLong(StepExecution::getWriteCount).sum();

            info.setTotalReadCount(totalRead);
            info.setTotalWriteCount(totalWrite);
            info.setProgress(totalRead > 0 ? (double) totalWrite / totalRead * 100 : 0);
        }

        return info;
    }

    private StepExecutionInfo createStepInfo(StepExecution stepExecution) {
        StepExecutionInfo info = new StepExecutionInfo();
        info.setStepName(stepExecution.getStepName());
        info.setStatus(stepExecution.getStatus().toString());
        info.setReadCount(stepExecution.getReadCount());
        info.setWriteCount(stepExecution.getWriteCount());
        info.setSkipCount(stepExecution.getSkipCount());
        info.setCommitCount(stepExecution.getCommitCount());

        if (stepExecution.getStartTime() != null && stepExecution.getEndTime() != null) {
            LocalDateTime start = LocalDateTime.ofInstant(stepExecution.getStartTime().toInstant(), ZoneId.systemDefault());
            LocalDateTime end = LocalDateTime.ofInstant(stepExecution.getEndTime().toInstant(), ZoneId.systemDefault());
            info.setDuration(Duration.between(start, end));

            // 처리 속도 계산
            long durationSeconds = info.getDuration().getSeconds();
            if (durationSeconds > 0) {
                info.setThroughput((double) stepExecution.getWriteCount() / durationSeconds);
            }
        }

        return info;
    }

    private Map<String, Object> calculateOverallStatistics(Collection<StepExecution> stepExecutions) {
        Map<String, Object> stats = new HashMap<>();

        long totalRead = stepExecutions.stream().mapToLong(StepExecution::getReadCount).sum();
        long totalWrite = stepExecutions.stream().mapToLong(StepExecution::getWriteCount).sum();
        long totalSkip = stepExecutions.stream().mapToLong(StepExecution::getSkipCount).sum();

        stats.put("totalRead", totalRead);
        stats.put("totalWrite", totalWrite);
        stats.put("totalSkip", totalSkip);
        stats.put("successRate", totalRead > 0 ? (double) totalWrite / totalRead * 100 : 0);

        return stats;
    }
}

// 데이터 클래스들
@Data
class BatchExecutionInfo {
    private Long executionId;
    private String jobName;
    private String status;
    private LocalDateTime startTime;
    private LocalDateTime endTime;
    private Duration duration;
    private Long totalReadCount;
    private Long totalWriteCount;
    private Double progress;
}

@Data
class DetailedBatchInfo {
    private JobExecution jobExecution;
    private List<StepExecutionInfo> stepExecutions;
    private Map<String, Object> overallStatistics;
}

@Data
class StepExecutionInfo {
    private String stepName;
    private String status;
    private int readCount;
    private int writeCount;
    private int skipCount;
    private int commitCount;
    private Duration duration;
    private Double throughput;
}

@Data
class SystemHealthInfo {
    private String overallStatus;
    private Double memoryUsage;
    private Integer runningBatchCount;
    private Long recentFailureCount;
    private LocalDateTime checkedAt = LocalDateTime.now();
}

2. 배치 모니터링 REST API

package com.example.batchtutorial.controller;

import com.example.batchtutorial.service.BatchMonitoringService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;
import java.util.Map;

/**
 * 배치 모니터링 REST API
 */
@Slf4j
@RestController
@RequestMapping("/api/batch")
public class BatchMonitoringController {

    @Autowired
    private BatchMonitoringService monitoringService;

    /**
     * 실행 중인 배치 목록
     */
    @GetMapping("/running")
    public List<BatchExecutionInfo> getRunningBatches() {
        return monitoringService.getRunningBatches();
    }

    /**
     * 최근 배치 실행 이력
     */
    @GetMapping("/history")
    public List<BatchExecutionInfo> getBatchHistory(
            @RequestParam(defaultValue = "20") int count) {
        return monitoringService.getRecentBatchHistory(count);
    }

    /**
     * 특정 배치 상세 정보
     */
    @GetMapping("/{executionId}")
    public ResponseEntity<DetailedBatchInfo> getBatchDetails(@PathVariable Long executionId) {
        DetailedBatchInfo details = monitoringService.getBatchDetails(executionId);
        if (details != null) {
            return ResponseEntity.ok(details);
        } else {
            return ResponseEntity.notFound().build();
        }
    }

    /**
     * 배치 중단
     */
    @PostMapping("/{executionId}/stop")
    public ResponseEntity<Map<String, Object>> stopBatch(@PathVariable Long executionId) {
        boolean stopped = monitoringService.stopBatch(executionId);
        return ResponseEntity.ok(Map.of(
            "success", stopped,
            "message", stopped ? "Batch stopped successfully" : "Failed to stop batch"
        ));
    }

    /**
     * 배치 재시작
     */
    @PostMapping("/{executionId}/restart")
    public ResponseEntity<Map<String, Object>> restartBatch(@PathVariable Long executionId) {
        Long newExecutionId = monitoringService.restartBatch(executionId);
        if (newExecutionId != null) {
            return ResponseEntity.ok(Map.of(
                "success", true,
                "newExecutionId", newExecutionId,
                "message", "Batch restarted successfully"
            ));
        } else {
            return ResponseEntity.ok(Map.of(
                "success", false,
                "message", "Failed to restart batch"
            ));
        }
    }

    /**
     * 시스템 상태 체크
     */
    @GetMapping("/health")
    public SystemHealthInfo getSystemHealth() {
        return monitoringService.getSystemHealth();
    }

    /**
     * 배치 통계 대시보드
     */
    @GetMapping("/dashboard")
    public Map<String, Object> getDashboardData() {
        List<BatchExecutionInfo> runningBatches = monitoringService.getRunningBatches();
        List<BatchExecutionInfo> recentHistory = monitoringService.getRecentBatchHistory(100);
        SystemHealthInfo health = monitoringService.getSystemHealth();

        // 성공률 계산
        long totalBatches = recentHistory.size();
        long successfulBatches = recentHistory.stream()
                .filter(batch -> "COMPLETED".equals(batch.getStatus()))
                .count();

        double successRate = totalBatches > 0 ? (double) successfulBatches / totalBatches * 100 : 0;

        return Map.of(
            "runningBatches", runningBatches,
            "recentHistory", recentHistory.stream().limit(10).toList(),
            "systemHealth", health,
            "statistics", Map.of(
                "totalBatches", totalBatches,
                "successfulBatches", successfulBatches,
                "successRate", successRate
            )
        );
    }
}

3. 실시간 알림 시스템

package com.example.batchtutorial.notification;

import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.core.JobExecution;
import org.springframework.batch.core.JobExecutionListener;
import org.springframework.batch.core.StepExecution;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

import java.time.Duration;
import java.time.LocalDateTime;
import java.time.ZoneId;

/**
 * 배치 실행 결과에 따른 알림 발송
 */
@Slf4j
@Component
public class BatchNotificationService implements JobExecutionListener {

    @Value("${batch.notification.email.enabled:true}")
    private boolean emailNotificationEnabled;

    @Value("${batch.notification.slack.enabled:false}")
    private boolean slackNotificationEnabled;

    @Value("${batch.notification.threshold.duration:300}")  // 5분
    private long longRunningThresholdSeconds;

    @Override
    public void beforeJob(JobExecution jobExecution) {
        String jobName = jobExecution.getJobInstance().getJobName();
        log.info("📧 Job started notification: {}", jobName);

        if (emailNotificationEnabled) {
            sendJobStartNotification(jobName);
        }
    }

    @Override
    public void afterJob(JobExecution jobExecution) {
        String jobName = jobExecution.getJobInstance().getJobName();
        String status = jobExecution.getExitStatus().getExitCode();

        LocalDateTime startTime = LocalDateTime.ofInstant(
                jobExecution.getStartTime().toInstant(), ZoneId.systemDefault());
        LocalDateTime endTime = LocalDateTime.ofInstant(
                jobExecution.getEndTime().toInstant(), ZoneId.systemDefault());
        Duration duration = Duration.between(startTime, endTime);

        // 실행 통계 수집
        JobExecutionSummary summary = createExecutionSummary(jobExecution, duration);

        // 상태에 따른 알림 발송
        switch (status) {
            case "COMPLETED" -> handleSuccessfulCompletion(summary);
            case "FAILED" -> handleFailure(summary);
            case "STOPPED" -> handleStopped(summary);
            default -> handleUnknownStatus(summary);
        }

        // 장시간 실행 알림
        if (duration.getSeconds() > longRunningThresholdSeconds) {
            sendLongRunningJobAlert(summary);
        }
    }

    private void handleSuccessfulCompletion(JobExecutionSummary summary) {
        log.info("✅ Job completed successfully: {}", summary.getJobName());

        if (emailNotificationEnabled) {
            sendSuccessNotification(summary);
        }

        if (slackNotificationEnabled) {
            sendSlackSuccessMessage(summary);
        }
    }

    private void handleFailure(JobExecutionSummary summary) {
        log.error("❌ Job failed: {}", summary.getJobName());

        // 실패 시 항상 알림 발송
        sendFailureNotification(summary);

        if (slackNotificationEnabled) {
            sendSlackFailureAlert(summary);
        }

        // 긴급 알림 (SMS, 전화 등) - 실제 구현 필요
        if (summary.isCritical()) {
            sendUrgentAlert(summary);
        }
    }

    private void handleStopped(JobExecutionSummary summary) {
        log.warn("🛑 Job was stopped: {}", summary.getJobName());
        sendJobStoppedNotification(summary);
    }

    private JobExecutionSummary createExecutionSummary(JobExecution jobExecution, Duration duration) {
        JobExecutionSummary summary = new JobExecutionSummary();
        summary.setJobName(jobExecution.getJobInstance().getJobName());
        summary.setExecutionId(jobExecution.getId());
        summary.setStatus(jobExecution.getExitStatus().getExitCode());
        summary.setDuration(duration);
        summary.setStartTime(LocalDateTime.ofInstant(
                jobExecution.getStartTime().toInstant(), ZoneId.systemDefault()));
        summary.setEndTime(LocalDateTime.ofInstant(
                jobExecution.getEndTime().toInstant(), ZoneId.systemDefault()));

        // Step 통계 수집
        long totalRead = 0, totalWrite = 0, totalSkip = 0;
        StringBuilder stepDetails = new StringBuilder();

        for (StepExecution step : jobExecution.getStepExecutions()) {
            totalRead += step.getReadCount();
            totalWrite += step.getWriteCount();
            totalSkip += step.getSkipCount();

            stepDetails.append(String.format(
                "- %s: Read=%d, Write=%d, Skip=%d%n", 
                step.getStepName(), step.getReadCount(), step.getWriteCount(), step.getSkipCount()
            ));
        }

        summary.setTotalRead(totalRead);
        summary.setTotalWrite(totalWrite);
        summary.setTotalSkip(totalSkip);
        summary.setStepDetails(stepDetails.toString());

        // 중요도 판단
        summary.setCritical(jobExecution.getJobInstance().getJobName().contains("CRITICAL") || 
                           totalSkip > 1000 || 
                           duration.getSeconds() > 3600); // 1시간 이상

        return summary;
    }

    private void sendSuccessNotification(JobExecutionSummary summary) {
        String subject = String.format("✅ Batch Job Completed: %s", summary.getJobName());
        String body = String.format("""
            Job: %s
            Status: COMPLETED
            Duration: %d minutes

            Statistics:
            - Read: %,d items
            - Write: %,d items
            - Skip: %,d items
            - Success Rate: %.2f%%

            Step Details:
            %s
            """, 
            summary.getJobName(),
            summary.getDuration().toMinutes(),
            summary.getTotalRead(),
            summary.getTotalWrite(),
            summary.getTotalSkip(),
            summary.getTotalRead() > 0 ? (double) summary.getTotalWrite() / summary.getTotalRead() * 100 : 0,
            summary.getStepDetails()
        );

        sendEmailNotification(subject, body);
    }

    private void sendFailureNotification(JobExecutionSummary summary) {
        String subject = String.format("❌ Batch Job FAILED: %s", summary.getJobName());
        String body = String.format("""
            🚨 BATCH JOB FAILURE ALERT 🚨

            Job: %s
            Status: FAILED
            Execution ID: %d
            Duration: %d minutes

            Failure occurred at: %s

            Statistics:
            - Read: %,d items
            - Write: %,d items  
            - Skip: %,d items

            Step Details:
            %s

            Please check the logs and take appropriate action.
            """,
            summary.getJobName(),
            summary.getExecutionId(),
            summary.getDuration().toMinutes(),
            summary.getEndTime(),
            summary.getTotalRead(),
            summary.getTotalWrite(),
            summary.getTotalSkip(),
            summary.getStepDetails()
        );

        sendEmailNotification(subject, body);
    }

    private void sendEmailNotification(String subject, String body) {
        // 실제 이메일 발송 구현
        log.info("📧 EMAIL NOTIFICATION: {}", subject);
        log.debug("Email body: {}", body);

        // JavaMailSender 등을 사용한 실제 이메일 발송 로직 구현
        // emailService.sendNotification(subject, body);
    }

    private void sendSlackSuccessMessage(JobExecutionSummary summary) {
        String message = String.format(
            "✅ Batch job `%s` completed successfully in %d minutes. Processed %,d items.",
            summary.getJobName(), summary.getDuration().toMinutes(), summary.getTotalWrite()
        );

        sendSlackMessage(message, "good");
    }

    private void sendSlackFailureAlert(JobExecutionSummary summary) {
        String message = String.format(
            "🚨 Batch job `%s` FAILED after %d minutes. Execution ID: %d. Please check immediately!",
            summary.getJobName(), summary.getDuration().toMinutes(), summary.getExecutionId()
        );

        sendSlackMessage(message, "danger");
    }

    private void sendSlackMessage(String message, String color) {
        // 실제 Slack API 호출 구현
        log.info("📱 SLACK NOTIFICATION ({}): {}", color, message);

        // Slack WebClient를 사용한 메시지 발송 로직 구현
        // slackService.sendMessage(message, color);
    }

    // 기타 알림 메서드들...
    private void sendJobStartNotification(String jobName) { /* 구현 */ }
    private void handleUnknownStatus(JobExecutionSummary summary) { /* 구현 */ }
    private void sendLongRunningJobAlert(JobExecutionSummary summary) { /* 구현 */ }
    private void sendJobStoppedNotification(JobExecutionSummary summary) { /* 구현 */ }
    private void sendUrgentAlert(JobExecutionSummary summary) { /* 구현 */ }
}

@Data
class JobExecutionSummary {
    private String jobName;
    private Long executionId;
    private String status;
    private Duration duration;
    private LocalDateTime startTime;
    private LocalDateTime endTime;
    private long totalRead;
    private long totalWrite;
    private long totalSkip;
    private String stepDetails;
    private boolean critical;
}

이제 프로덕션 환경에서 안정적으로 운영할 수 있는 완전한 에러 처리, 재시작, 모니터링 시스템이 구축되었습니다! 마지막 단계에서는 Spring Batch의 고급 활용법과 실무 팁을 학습하겠습니다.

🎯 학습 목표

• 대용량 데이터 처리를 위한 성능 최적화 기법 습득
• 멀티스레드와 병렬 처리 구현
• 파티셔닝(Partitioning)을 통한 분산 처리
• 메모리 최적화 및 성능 모니터링

📊 성능 최적화 전략 개요

성능 병목 지점 분석

[데이터 읽기] → [데이터 처리] → [데이터 쓰기]
     ↓              ↓              ↓
  I/O 병목        CPU 병목      I/O + 트랜잭션 병목
     ↓              ↓              ↓
  - 페이징        - 복잡한        - 배치 삽입
  - 인덱스         비즈니스 로직    - 트랜잭션 크기
  - 캐싱          - 변환 작업      - 커넥션 풀

최적화 기법들

1. 청크 크기 최적화: 메모리 vs 트랜잭션 오버헤드 균형
2. 멀티스레드 처리: CPU 활용도 극대화
3. 파티셔닝: 대용량 데이터 분할 처리
4. 비동기 처리: ItemProcessor에서 외부 API 호출 최적화
5. 데이터베이스 최적화: 인덱스, 배치 삽입, 커넥션 풀

🚀 멀티스레드 Step 구현

1. 기본 멀티스레드 설정

package com.example.batchtutorial.config;

import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.core.Job;
import org.springframework.batch.core.Step;
import org.springframework.batch.core.job.builder.JobBuilder;
import org.springframework.batch.core.repository.JobRepository;
import org.springframework.batch.core.step.builder.StepBuilder;
import org.springframework.batch.item.ItemProcessor;
import org.springframework.batch.item.ItemReader;
import org.springframework.batch.item.ItemWriter;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.task.TaskExecutor;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
import org.springframework.transaction.PlatformTransactionManager;

/**
 * 멀티스레드 배치 처리 설정
 */
@Slf4j
@Configuration
public class MultiThreadBatchConfig {

    @Autowired
    private JobRepository jobRepository;

    @Autowired
    private PlatformTransactionManager transactionManager;

    /**
     * 멀티스레드 배치용 TaskExecutor
     */
    @Bean
    public TaskExecutor batchTaskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(4);        // 기본 스레드 수
        executor.setMaxPoolSize(8);         // 최대 스레드 수
        executor.setQueueCapacity(100);     // 큐 용량
        executor.setThreadNamePrefix("batch-thread-");
        executor.setKeepAliveSeconds(60);   // 유휴 스레드 생존 시간
        executor.setWaitForTasksToCompleteOnShutdown(true);
        executor.setAwaitTerminationSeconds(60);
        executor.initialize();
        return executor;
    }

    /**
     * CPU 집약적 작업용 TaskExecutor
     */
    @Bean
    public TaskExecutor cpuIntensiveTaskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        // CPU 코어 수만큼 스레드 설정 (CPU 집약적 작업)
        int cpuCores = Runtime.getRuntime().availableProcessors();
        executor.setCorePoolSize(cpuCores);
        executor.setMaxPoolSize(cpuCores);
        executor.setQueueCapacity(50);
        executor.setThreadNamePrefix("cpu-batch-");
        executor.initialize();
        return executor;
    }

    /**
     * I/O 집약적 작업용 TaskExecutor
     */
    @Bean
    public TaskExecutor ioIntensiveTaskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        // I/O 대기 시간을 고려하여 더 많은 스레드 할당
        executor.setCorePoolSize(10);
        executor.setMaxPoolSize(20);
        executor.setQueueCapacity(200);
        executor.setThreadNamePrefix("io-batch-");
        executor.initialize();
        return executor;
    }

    /**
     * 멀티스레드 Step 설정
     */
    @Bean
    public Step multiThreadStep(ItemReader<Object> reader,
                               ItemProcessor<Object, Object> processor,
                               ItemWriter<Object> writer) {
        return new StepBuilder("multiThreadStep", jobRepository)
                .<Object, Object>chunk(100, transactionManager)  // 큰 청크 크기
                .reader(reader)
                .processor(processor)
                .writer(writer)
                .taskExecutor(batchTaskExecutor())       // TaskExecutor 설정
                .throttleLimit(4)                        // 동시 실행 스레드 제한
                .build();
    }
}

2. 스레드 세이프 ItemReader 구현

package com.example.batchtutorial.batch.reader;

import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.item.database.JdbcPagingItemReader;
import org.springframework.batch.item.database.PagingQueryProvider;
import org.springframework.batch.item.database.builder.JdbcPagingItemReaderBuilder;
import org.springframework.batch.item.database.support.SqlPagingQueryProviderFactoryBean;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.jdbc.core.BeanPropertyRowMapper;

import javax.sql.DataSource;

/**
 * 멀티스레드 환경에서 안전한 ItemReader 설정
 */
@Slf4j
@Configuration
public class ThreadSafeReaderConfig {

    @Autowired
    private DataSource dataSource;

    /**
     * 스레드 세이프한 JDBC Paging ItemReader
     * (JdbcPagingItemReader는 기본적으로 thread-safe)
     */
    @Bean
    public JdbcPagingItemReader<LargeDataDto> threadSafeReader() throws Exception {

        return new JdbcPagingItemReaderBuilder<LargeDataDto>()
                .name("threadSafeReader")
                .dataSource(dataSource)
                .queryProvider(createQueryProvider())
                .pageSize(1000)                    // 페이지 크기 증가
                .rowMapper(new BeanPropertyRowMapper<>(LargeDataDto.class))
                .saveState(false)                  // 멀티스레드에서는 상태 저장 비활성화
                .build();
    }

    /**
     * 페이징 쿼리 제공자 생성
     */
    private PagingQueryProvider createQueryProvider() throws Exception {
        SqlPagingQueryProviderFactoryBean factory = new SqlPagingQueryProviderFactoryBean();
        factory.setDataSource(dataSource);
        factory.setSelectClause("SELECT id, name, amount, created_at");
        factory.setFromClause("FROM large_data_table");
        factory.setWhereClause("WHERE status = 'ACTIVE'");
        factory.setSortKey("id");                  // 정렬 키 필수
        return factory.getObject();
    }
}

/**
 * 대용량 데이터 처리용 DTO
 */
@Data
@NoArgsConstructor
@AllArgsConstructor
class LargeDataDto {
    private Long id;
    private String name;
    private BigDecimal amount;
    private LocalDateTime createdAt;
}

3. 비동기 ItemProcessor 구현

package com.example.batchtutorial.batch.processor;

import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.item.ItemProcessor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;

import java.time.Duration;
import java.util.concurrent.CompletableFuture;

/**
 * 비동기 처리를 포함하는 ItemProcessor
 */
@Slf4j
@Configuration
public class AsyncProcessorConfig {

    @Autowired
    private WebClient webClient;

    /**
     * 외부 API 호출이 포함된 비동기 Processor
     */
    @Bean
    public ItemProcessor<LargeDataDto, ProcessedDataDto> asyncProcessor() {
        return new ItemProcessor<LargeDataDto, ProcessedDataDto>() {
            @Override
            public ProcessedDataDto process(LargeDataDto item) throws Exception {

                long startTime = System.currentTimeMillis();
                String threadName = Thread.currentThread().getName();

                log.debug("Processing item {} on thread {}", item.getId(), threadName);

                try {
                    // 1. 로컬 데이터 변환 (CPU 작업)
                    ProcessedDataDto result = transformData(item);

                    // 2. 외부 API 호출 (I/O 작업)
                    String enrichedData = callExternalApiAsync(item.getId()).get();
                    result.setEnrichedData(enrichedData);

                    // 3. 복잡한 계산 수행 (CPU 작업)
                    BigDecimal calculatedValue = performComplexCalculation(item.getAmount());
                    result.setCalculatedValue(calculatedValue);

                    long processingTime = System.currentTimeMillis() - startTime;
                    result.setProcessingTime(processingTime);

                    log.debug("Completed processing item {} in {}ms on thread {}", 
                            item.getId(), processingTime, threadName);

                    return result;

                } catch (Exception e) {
                    log.error("Failed to process item {} on thread {}: {}", 
                            item.getId(), threadName, e.getMessage());
                    throw e;
                }
            }
        };
    }

    /**
     * 데이터 변환 로직
     */
    private ProcessedDataDto transformData(LargeDataDto input) {
        ProcessedDataDto result = new ProcessedDataDto();
        result.setId(input.getId());
        result.setProcessedName(input.getName().toUpperCase());
        result.setOriginalAmount(input.getAmount());
        result.setProcessedAt(LocalDateTime.now());
        return result;
    }

    /**
     * 외부 API 비동기 호출
     */
    private CompletableFuture<String> callExternalApiAsync(Long id) {
        return webClient.get()
                .uri("/api/enrich/{id}", id)
                .retrieve()
                .bodyToMono(String.class)
                .timeout(Duration.ofSeconds(5))
                .toFuture();
    }

    /**
     * 복잡한 계산 수행 (CPU 집약적)
     */
    private BigDecimal performComplexCalculation(BigDecimal input) {
        // 복잡한 수학적 계산 시뮬레이션
        BigDecimal result = input;
        for (int i = 0; i < 1000; i++) {
            result = result.multiply(new BigDecimal("1.001"));
        }
        return result.setScale(2, RoundingMode.HALF_UP);
    }
}

/**
 * 처리된 데이터 DTO
 */
@Data
@NoArgsConstructor
@AllArgsConstructor
class ProcessedDataDto {
    private Long id;
    private String processedName;
    private BigDecimal originalAmount;
    private BigDecimal calculatedValue;
    private String enrichedData;
    private LocalDateTime processedAt;
    private Long processingTime;
}

🔀 파티셔닝(Partitioning) 구현

1. 파티셔닝 기본 설정

package com.example.batchtutorial.config;

import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.core.Job;
import org.springframework.batch.core.Step;
import org.springframework.batch.core.configuration.annotation.StepScope;
import org.springframework.batch.core.job.builder.JobBuilder;
import org.springframework.batch.core.partition.PartitionHandler;
import org.springframework.batch.core.partition.support.Partitioner;
import org.springframework.batch.core.partition.support.TaskExecutorPartitionHandler;
import org.springframework.batch.core.repository.JobRepository;
import org.springframework.batch.core.step.builder.StepBuilder;
import org.springframework.batch.item.ItemProcessor;
import org.springframework.batch.item.ItemReader;
import org.springframework.batch.item.ItemWriter;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.task.TaskExecutor;
import org.springframework.transaction.PlatformTransactionManager;

/**
 * 파티셔닝을 통한 분산 처리 설정
 */
@Slf4j
@Configuration
public class PartitioningBatchConfig {

    @Autowired
    private JobRepository jobRepository;

    @Autowired
    private PlatformTransactionManager transactionManager;

    /**
     * 파티셔닝 Job 설정
     */
    @Bean
    public Job partitioningJob(Step managerStep) {
        return new JobBuilder("partitioningJob", jobRepository)
                .start(managerStep)
                .build();
    }

    /**
     * 매니저 Step (파티션을 관리하는 Step)
     */
    @Bean
    public Step managerStep(Step workerStep, Partitioner customPartitioner, TaskExecutor taskExecutor) {
        return new StepBuilder("managerStep", jobRepository)
                .partitioner("workerStep", customPartitioner)
                .step(workerStep)
                .partitionHandler(partitionHandler(workerStep, taskExecutor))
                .build();
    }

    /**
     * 파티션 핸들러 설정
     */
    @Bean
    public PartitionHandler partitionHandler(Step workerStep, TaskExecutor taskExecutor) {
        TaskExecutorPartitionHandler handler = new TaskExecutorPartitionHandler();
        handler.setTaskExecutor(taskExecutor);
        handler.setStep(workerStep);
        handler.setGridSize(8);                    // 파티션 개수
        return handler;
    }

    /**
     * 워커 Step (실제 작업을 수행하는 Step)
     */
    @Bean
    public Step workerStep(ItemReader<LargeDataDto> partitionReader,
                          ItemProcessor<LargeDataDto, ProcessedDataDto> processor,
                          ItemWriter<ProcessedDataDto> writer) {
        return new StepBuilder("workerStep", jobRepository)
                .<LargeDataDto, ProcessedDataDto>chunk(500, transactionManager)
                .reader(partitionReader)
                .processor(processor)
                .writer(writer)
                .build();
    }

    /**
     * 커스텀 파티셔너 - 데이터 범위에 따라 분할
     */
    @Bean
    public Partitioner customPartitioner() {
        return new CustomRangePartitioner();
    }
}

2. 커스텀 파티셔너 구현

package com.example.batchtutorial.partition;

import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.core.partition.support.Partitioner;
import org.springframework.batch.item.ExecutionContext;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Component;

import java.util.HashMap;
import java.util.Map;

/**
 * ID 범위 기반 파티셔너
 */
@Slf4j
@Component
public class CustomRangePartitioner implements Partitioner {

    @Autowired
    private JdbcTemplate jdbcTemplate;

    @Override
    public Map<String, ExecutionContext> partition(int gridSize) {

        log.info("Creating {} partitions for data processing", gridSize);

        // 1. 전체 데이터 범위 조회
        Long minId = jdbcTemplate.queryForObject("SELECT MIN(id) FROM large_data_table WHERE status = 'ACTIVE'", Long.class);
        Long maxId = jdbcTemplate.queryForObject("SELECT MAX(id) FROM large_data_table WHERE status = 'ACTIVE'", Long.class);
        Long totalRecords = jdbcTemplate.queryForObject("SELECT COUNT(*) FROM large_data_table WHERE status = 'ACTIVE'", Long.class);

        if (minId == null || maxId == null || totalRecords == 0) {
            log.warn("No data found for partitioning");
            return new HashMap<>();
        }

        log.info("Total records: {}, ID range: {} - {}", totalRecords, minId, maxId);

        // 2. 파티션별 범위 계산
        long rangeSize = (maxId - minId + 1) / gridSize;
        Map<String, ExecutionContext> partitions = new HashMap<>();

        for (int i = 0; i < gridSize; i++) {
            ExecutionContext context = new ExecutionContext();

            long startId = minId + (i * rangeSize);
            long endId = (i == gridSize - 1) ? maxId : startId + rangeSize - 1;

            context.putLong("startId", startId);
            context.putLong("endId", endId);

            // 파티션별 예상 레코드 수 계산
            Long partitionRecordCount = jdbcTemplate.queryForObject(
                "SELECT COUNT(*) FROM large_data_table WHERE id BETWEEN ? AND ? AND status = 'ACTIVE'",
                Long.class, startId, endId
            );

            context.putLong("expectedRecords", partitionRecordCount);

            partitions.put("partition" + i, context);

            log.info("Partition {}: ID range {} - {}, expected records: {}", 
                    i, startId, endId, partitionRecordCount);
        }

        return partitions;
    }
}

3. 파티션용 StepScope ItemReader

package com.example.batchtutorial.batch.reader;

import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.core.configuration.annotation.StepScope;
import org.springframework.batch.item.database.JdbcPagingItemReader;
import org.springframework.batch.item.database.builder.JdbcPagingItemReaderBuilder;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.jdbc.core.BeanPropertyRowMapper;

import javax.sql.DataSource;
import java.util.HashMap;
import java.util.Map;

/**
 * 파티션별 데이터를 읽는 StepScope ItemReader
 */
@Slf4j
@Configuration
public class PartitionReaderConfig {

    @Autowired
    private DataSource dataSource;

    /**
     * 파티션 범위에 따라 데이터를 읽는 Reader
     */
    @Bean
    @StepScope
    public JdbcPagingItemReader<LargeDataDto> partitionReader(
            @Value("#{stepExecutionContext['startId']}") Long startId,
            @Value("#{stepExecutionContext['endId']}") Long endId,
            @Value("#{stepExecutionContext['expectedRecords']}") Long expectedRecords) {

        String threadName = Thread.currentThread().getName();
        log.info("Creating partition reader for range {} - {} (expected: {} records) on thread {}", 
                startId, endId, expectedRecords, threadName);

        Map<String, Object> parameters = new HashMap<>();
        parameters.put("startId", startId);
        parameters.put("endId", endId);

        return new JdbcPagingItemReaderBuilder<LargeDataDto>()
                .name("partitionReader")
                .dataSource(dataSource)
                .queryString("SELECT id, name, amount, created_at FROM large_data_table WHERE id BETWEEN :startId AND :endId AND status = 'ACTIVE'")
                .parameterValues(parameters)
                .pageSize(100)
                .rowMapper(new BeanPropertyRowMapper<>(LargeDataDto.class))
                .saveState(false)  // 파티셔닝에서는 상태 저장 비활성화
                .build();
    }
}

📈 성능 모니터링 및 측정

1. 배치 성능 모니터링 리스너

package com.example.batchtutorial.listener;

import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.core.JobExecution;
import org.springframework.batch.core.JobExecutionListener;
import org.springframework.batch.core.StepExecution;
import org.springframework.stereotype.Component;

import java.time.Duration;
import java.time.LocalDateTime;
import java.time.ZoneId;

/**
 * 배치 성능 모니터링 리스너
 */
@Slf4j
@Component
public class PerformanceMonitoringListener implements JobExecutionListener {

    @Override
    public void beforeJob(JobExecution jobExecution) {
        log.info("🚀 Job started: {} at {}", 
                jobExecution.getJobInstance().getJobName(),
                LocalDateTime.ofInstant(jobExecution.getStartTime().toInstant(), ZoneId.systemDefault()));

        // 시스템 리소스 모니터링
        Runtime runtime = Runtime.getRuntime();
        long maxMemory = runtime.maxMemory();
        long freeMemory = runtime.freeMemory();
        long totalMemory = runtime.totalMemory();

        log.info("💾 Memory status - Max: {}MB, Free: {}MB, Total: {}MB", 
                maxMemory / (1024 * 1024), 
                freeMemory / (1024 * 1024), 
                totalMemory / (1024 * 1024));

        log.info("🖥️ Available processors: {}", runtime.availableProcessors());
    }

    @Override
    public void afterJob(JobExecution jobExecution) {
        Duration duration = Duration.between(
                jobExecution.getStartTime().toInstant(),
                jobExecution.getEndTime().toInstant()
        );

        log.info("✅ Job completed: {} in {} seconds", 
                jobExecution.getJobInstance().getJobName(),
                duration.getSeconds());

        // Step별 성능 통계
        logStepStatistics(jobExecution);

        // 전체 성능 통계
        logOverallPerformance(jobExecution, duration);

        // 메모리 사용량 최종 확인
        logFinalMemoryUsage();
    }

    private void logStepStatistics(JobExecution jobExecution) {
        log.info("📊 Step Performance Statistics:");

        for (StepExecution stepExecution : jobExecution.getStepExecutions()) {
            Duration stepDuration = Duration.between(
                    stepExecution.getStartTime().toInstant(),
                    stepExecution.getEndTime().toInstant()
            );

            long readCount = stepExecution.getReadCount();
            long writeCount = stepExecution.getWriteCount();
            long skipCount = stepExecution.getSkipCount();

            double readThroughput = readCount / (double) stepDuration.getSeconds();
            double writeThroughput = writeCount / (double) stepDuration.getSeconds();

            log.info("  📋 Step: {}", stepExecution.getStepName());
            log.info("    ⏱️ Duration: {} seconds", stepDuration.getSeconds());
            log.info("    📖 Read: {} items ({:.2f} items/sec)", readCount, readThroughput);
            log.info("    ✏️ Write: {} items ({:.2f} items/sec)", writeCount, writeThroughput);
            log.info("    ⚠️ Skip: {} items", skipCount);

            if (stepExecution.getCommitCount() > 0) {
                double avgChunkSize = (double) writeCount / stepExecution.getCommitCount();
                log.info("    🔄 Commits: {} (avg chunk size: {:.1f})", 
                        stepExecution.getCommitCount(), avgChunkSize);
            }
        }
    }

    private void logOverallPerformance(JobExecution jobExecution, Duration duration) {
        long totalReadCount = jobExecution.getStepExecutions().stream()
                .mapToLong(StepExecution::getReadCount)
                .sum();

        long totalWriteCount = jobExecution.getStepExecutions().stream()
                .mapToLong(StepExecution::getWriteCount)
                .sum();

        double overallThroughput = totalWriteCount / (double) duration.getSeconds();

        log.info("🎯 Overall Performance:");
        log.info("  📖 Total Read: {} items", totalReadCount);
        log.info("  ✏️ Total Write: {} items", totalWriteCount);
        log.info("  ⚡ Overall Throughput: {:.2f} items/sec", overallThroughput);
        log.info("  📊 Success Rate: {:.2f}%", 
                (totalWriteCount / (double) totalReadCount) * 100);
    }

    private void logFinalMemoryUsage() {
        Runtime runtime = Runtime.getRuntime();
        runtime.gc(); // 가비지 컬렉션 수행

        long usedMemory = runtime.totalMemory() - runtime.freeMemory();
        long maxMemory = runtime.maxMemory();

        log.info("💾 Final Memory Usage: {}MB / {}MB ({:.1f}%)", 
                usedMemory / (1024 * 1024),
                maxMemory / (1024 * 1024),
                (usedMemory / (double) maxMemory) * 100);
    }
}

2. 성능 최적화된 ItemWriter

package com.example.batchtutorial.batch.writer;

import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.item.Chunk;
import org.springframework.batch.item.database.JdbcBatchItemWriter;
import org.springframework.batch.item.database.builder.JdbcBatchItemWriterBuilder;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.jdbc.core.namedparam.MapSqlParameterSource;

import javax.sql.DataSource;

/**
 * 고성능 배치 삽입을 위한 ItemWriter
 */
@Slf4j
@Configuration  
public class HighPerformanceWriterConfig {

    @Autowired
    private DataSource dataSource;

    /**
     * JDBC 배치 삽입 Writer
     */
    @Bean
    public JdbcBatchItemWriter<ProcessedDataDto> highPerformanceWriter() {
        return new JdbcBatchItemWriterBuilder<ProcessedDataDto>()
                .dataSource(dataSource)
                .sql("INSERT INTO processed_data (id, processed_name, original_amount, calculated_value, enriched_data, processed_at, processing_time) " +
                     "VALUES (:id, :processedName, :originalAmount, :calculatedValue, :enrichedData, :processedAt, :processingTime)")
                .beanMapped()
                .assertUpdates(false)  // 업데이트 확인 비활성화 (성능 향상)
                .build();
    }

    /**
     * 사용자 정의 배치 Writer (더 세밀한 제어)
     */
    @Bean
    public CustomBatchWriter customBatchWriter() {
        return new CustomBatchWriter(dataSource);
    }
}

/**
 * 커스텀 배치 Writer 구현
 */
@Slf4j
class CustomBatchWriter implements ItemWriter<ProcessedDataDto> {

    private final DataSource dataSource;
    private final JdbcTemplate jdbcTemplate;

    public CustomBatchWriter(DataSource dataSource) {
        this.dataSource = dataSource;
        this.jdbcTemplate = new JdbcTemplate(dataSource);
    }

    @Override
    public void write(Chunk<? extends ProcessedDataDto> chunk) throws Exception {
        List<? extends ProcessedDataDto> items = chunk.getItems();

        if (items.isEmpty()) {
            return;
        }

        long startTime = System.currentTimeMillis();
        String threadName = Thread.currentThread().getName();

        log.debug("Writing {} items on thread {}", items.size(), threadName);

        try {
            // 배치 삽입 준비
            String sql = "INSERT INTO processed_data " +
                        "(id, processed_name, original_amount, calculated_value, enriched_data, processed_at, processing_time) " +
                        "VALUES (?, ?, ?, ?, ?, ?, ?)";

            List<Object[]> batchArgs = items.stream()
                    .map(this::createBatchArgs)
                    .collect(Collectors.toList());

            // 배치 실행
            int[] results = jdbcTemplate.batchUpdate(sql, batchArgs);

            long executionTime = System.currentTimeMillis() - startTime;
            double throughput = items.size() / (executionTime / 1000.0);

            log.debug("Batch write completed - {} items in {}ms ({:.2f} items/sec) on thread {}", 
                    items.size(), executionTime, throughput, threadName);

            // 실패한 삽입 확인
            long failedInserts = Arrays.stream(results).filter(result -> result == 0).count();
            if (failedInserts > 0) {
                log.warn("⚠️ {} insertions failed out of {} on thread {}", 
                        failedInserts, items.size(), threadName);
            }

        } catch (Exception e) {
            log.error("❌ Batch write failed for {} items on thread {}: {}", 
                    items.size(), threadName, e.getMessage(), e);
            throw e;
        }
    }

    private Object[] createBatchArgs(ProcessedDataDto item) {
        return new Object[]{
            item.getId(),
            item.getProcessedName(),
            item.getOriginalAmount(),
            item.getCalculatedValue(),
            item.getEnrichedData(),
            item.getProcessedAt(),
            item.getProcessingTime()
        };
    }
}

🔧 성능 최적화 설정

1. 데이터베이스 커넥션 풀 최적화

# application-performance.properties

# HikariCP 설정 (고성능 커넥션 풀)
spring.datasource.hikari.maximum-pool-size=20
spring.datasource.hikari.minimum-idle=10
spring.datasource.hikari.idle-timeout=300000
spring.datasource.hikari.max-lifetime=600000
spring.datasource.hikari.connection-timeout=30000
spring.datasource.hikari.leak-detection-threshold=60000

# JPA/Hibernate 성능 최적화
spring.jpa.hibernate.jdbc.batch_size=25
spring.jpa.hibernate.order_inserts=true
spring.jpa.hibernate.order_updates=true
spring.jpa.hibernate.jdbc.batch_versioned_data=true

# Spring Batch 성능 설정
spring.batch.jdbc.isolation-level-for-create=READ_COMMITTED
spring.batch.jdbc.table-prefix=BATCH_

# 로깅 설정 (성능 모드)
logging.level.org.springframework.batch=INFO
logging.level.org.hibernate.SQL=WARN
logging.level.org.hibernate.type.descriptor.sql.BasicBinder=WARN

2. JVM 성능 튜닝 옵션

# 배치 애플리케이션 실행 시 권장 JVM 옵션
java -Xms2g -Xmx4g \
     -XX:+UseG1GC \
     -XX:MaxGCPauseMillis=200 \
     -XX:+UnlockExperimentalVMOptions \
     -XX:+UseStringDeduplication \
     -XX:+PrintGCDetails \
     -XX:+PrintGCTimeStamps \
     -Xloggc:gc.log \
     -jar batch-application.jar

📊 성능 테스트 및 벤치마크

성능 테스트 시나리오

package com.example.batchtutorial.test;

import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Test;
import org.springframework.batch.core.Job;
import org.springframework.batch.core.JobParameters;
import org.springframework.batch.core.JobParametersBuilder;
import org.springframework.batch.core.launch.JobLauncher;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.ActiveProfiles;

import java.time.Duration;
import java.time.Instant;

/**
 * 배치 성능 테스트
 */
@Slf4j
@SpringBootTest
@ActiveProfiles("performance")
class BatchPerformanceTest {

    @Autowired
    private JobLauncher jobLauncher;

    @Autowired
    private Job singleThreadJob;

    @Autowired
    private Job multiThreadJob;

    @Autowired
    private Job partitioningJob;

    @Test
    void compareBatchPerformance() throws Exception {

        // 1. 단일 스레드 성능 테스트
        Instant start = Instant.now();
        jobLauncher.run(singleThreadJob, createJobParameters("single"));
        Duration singleThreadTime = Duration.between(start, Instant.now());
        log.info("Single thread execution time: {} seconds", singleThreadTime.getSeconds());

        // 2. 멀티 스레드 성능 테스트
        start = Instant.now();
        jobLauncher.run(multiThreadJob, createJobParameters("multi"));
        Duration multiThreadTime = Duration.between(start, Instant.now());
        log.info("Multi thread execution time: {} seconds", multiThreadTime.getSeconds());

        // 3. 파티셔닝 성능 테스트
        start = Instant.now();
        jobLauncher.run(partitioningJob, createJobParameters("partition"));
        Duration partitioningTime = Duration.between(start, Instant.now());
        log.info("Partitioning execution time: {} seconds", partitioningTime.getSeconds());

        // 4. 성능 비교 결과
        log.info("Performance Comparison:");
        log.info("  Single Thread: {} seconds (baseline)", singleThreadTime.getSeconds());
        log.info("  Multi Thread: {} seconds ({}x faster)", 
                multiThreadTime.getSeconds(), 
                (double) singleThreadTime.getSeconds() / multiThreadTime.getSeconds());
        log.info("  Partitioning: {} seconds ({}x faster)", 
                partitioningTime.getSeconds(),
                (double) singleThreadTime.getSeconds() / partitioningTime.getSeconds());
    }

    private JobParameters createJobParameters(String suffix) {
        return new JobParametersBuilder()
                .addLong("timestamp", System.currentTimeMillis())
                .addString("testType", suffix)
                .toJobParameters();
    }
}

이제 대용량 데이터 처리를 위한 고성능 Spring Batch 시스템을 완전히 구현했습니다! 다음 단계에서는 실무에서 필요한 에러 처리와 모니터링 기능을 학습하겠습니다.

🎯 학습 목표

• ItemReader, ItemProcessor, ItemWriter 실전 구현
• CSV 파일을 읽어서 데이터베이스에 저장하는 완전한 배치 시스템 구축
• 청크 기반 처리 이해 및 최적화
• 데이터 검증 및 변환 로직 구현

📂 프로젝트 준비

1. 의존성 추가 (build.gradle)

dependencies {
    // 기존 의존성들...

    // CSV 처리를 위한 추가 의존성
    implementation 'org.springframework.batch:spring-batch-core'
    implementation 'org.springframework.boot:spring-boot-starter-batch'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'

    // 검증을 위한 의존성
    implementation 'org.springframework.boot:spring-boot-starter-validation'

    // 유틸리티
    implementation 'org.apache.commons:commons-csv:1.10.0'
}

2. 테스트 데이터 준비

CSV 파일 생성 (src/main/resources/data/employees.csv):

firstName,lastName,email,department,salary,hireDate
김,철수,kim.chulsoo@company.com,개발팀,5500000,2023-01-15
이,영희,lee.younghee@company.com,마케팅팀,4800000,2023-02-20
박,민수,park.minsoo@company.com,개발팀,6200000,2022-11-10
최,수진,choi.sujin@company.com,인사팀,5000000,2023-03-05
정,호영,jung.hoyoung@company.com,영업팀,4500000,2023-01-30
강,미영,kang.miyoung@company.com,개발팀,7000000,2022-08-15
윤,대호,yoon.daeho@company.com,기획팀,5800000,2023-02-10
송,지민,song.jimin@company.com,개발팀,5200000,2023-04-01
조,현우,cho.hyunwoo@company.com,마케팅팀,4700000,2023-01-25
한,서연,han.seoyeon@company.com,인사팀,5300000,2022-12-05

잘못된 데이터가 포함된 CSV (src/main/resources/data/employees-with-errors.csv):

firstName,lastName,email,department,salary,hireDate
김,철수,kim.chulsoo@company.com,개발팀,5500000,2023-01-15
이,영희,invalid-email,마케팅팀,4800000,2023-02-20
박,,park.minsoo@company.com,개발팀,6200000,2022-11-10
최,수진,choi.sujin@company.com,,5000000,2023-03-05
정,호영,jung.hoyoung@company.com,영업팀,-1000,2023-01-30
강,미영,kang.miyoung@company.com,개발팀,7000000,invalid-date

🏗️ 엔티티 및 DTO 클래스 구현

1. Employee 엔티티 클래스

package com.example.batchtutorial.entity;

import jakarta.persistence.*;
import jakarta.validation.constraints.*;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.LocalDateTime;

/**
 * 직원 정보를 저장하는 JPA 엔티티
 */
@Entity
@Table(name = "employees")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Employee {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(name = "first_name", nullable = false, length = 50)
    @NotBlank(message = "이름은 필수입니다")
    private String firstName;

    @Column(name = "last_name", nullable = false, length = 50)
    @NotBlank(message = "성은 필수입니다")
    private String lastName;

    @Column(name = "email", nullable = false, unique = true, length = 100)
    @Email(message = "올바른 이메일 형식이 아닙니다")
    @NotBlank(message = "이메일은 필수입니다")
    private String email;

    @Column(name = "department", nullable = false, length = 50)
    @NotBlank(message = "부서는 필수입니다")
    private String department;

    @Column(name = "salary", nullable = false, precision = 10, scale = 2)
    @DecimalMin(value = "0.0", message = "급여는 0보다 커야 합니다")
    @NotNull(message = "급여는 필수입니다")
    private BigDecimal salary;

    @Column(name = "hire_date", nullable = false)
    @NotNull(message = "입사일은 필수입니다")
    @PastOrPresent(message = "입사일은 현재 또는 과거 날짜여야 합니다")
    private LocalDate hireDate;

    @Column(name = "created_at")
    private LocalDateTime createdAt;

    @Column(name = "updated_at")
    private LocalDateTime updatedAt;

    // 생성/수정 시간 자동 설정
    @PrePersist
    protected void onCreate() {
        this.createdAt = LocalDateTime.now();
        this.updatedAt = LocalDateTime.now();
    }

    @PreUpdate
    protected void onUpdate() {
        this.updatedAt = LocalDateTime.now();
    }

    // 전체 이름 반환 헬퍼 메서드
    public String getFullName() {
        return firstName + " " + lastName;
    }
}

2. CSV 데이터용 DTO 클래스

package com.example.batchtutorial.dto;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
 * CSV 파일에서 읽어온 원시 데이터를 담는 DTO
 */
@Data
@NoArgsConstructor
@AllArgsConstructor
public class EmployeeCsvDto {

    private String firstName;
    private String lastName;
    private String email;
    private String department;
    private String salary;        // 문자열로 받아서 검증 후 변환
    private String hireDate;      // 문자열로 받아서 날짜 변환
}

3. Repository 인터페이스

package com.example.batchtutorial.repository;

import com.example.batchtutorial.entity.Employee;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.stereotype.Repository;

import java.math.BigDecimal;
import java.util.List;
import java.util.Optional;

@Repository
public interface EmployeeRepository extends JpaRepository<Employee, Long> {

    // 이메일로 직원 조회 (중복 체크용)
    Optional<Employee> findByEmail(String email);

    // 부서별 직원 목록 조회
    List<Employee> findByDepartmentOrderByLastNameAsc(String department);

    // 급여 범위로 직원 조회
    List<Employee> findBySalaryBetweenOrderBySalaryDesc(BigDecimal minSalary, BigDecimal maxSalary);

    // 부서별 평균 급여 계산
    @Query("SELECT e.department, AVG(e.salary) FROM Employee e GROUP BY e.department")
    List<Object[]> findAverageSalaryByDepartment();

    // 최근 입사자 조회
    @Query("SELECT e FROM Employee e ORDER BY e.hireDate DESC")
    List<Employee> findRecentHires();
}

🔧 배치 컴포넌트 구현

1. ItemReader - CSV 파일 읽기

package com.example.batchtutorial.batch;

import com.example.batchtutorial.dto.EmployeeCsvDto;
import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.item.file.FlatFileItemReader;
import org.springframework.batch.item.file.builder.FlatFileItemReaderBuilder;
import org.springframework.batch.item.file.mapping.BeanWrapperFieldSetMapper;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;

/**
 * CSV 파일을 읽는 ItemReader 설정
 */
@Slf4j
@Configuration
public class EmployeeItemReaderConfig {

    @Bean
    public FlatFileItemReader<EmployeeCsvDto> employeeCsvReader() {
        return new FlatFileItemReaderBuilder<EmployeeCsvDto>()
                .name("employeeCsvReader")
                .resource(new ClassPathResource("data/employees.csv"))
                .delimited()
                .delimiter(",")
                .names("firstName", "lastName", "email", "department", "salary", "hireDate")
                .linesToSkip(1)  // 첫 번째 라인(헤더) 스킵
                .fieldSetMapper(new BeanWrapperFieldSetMapper<EmployeeCsvDto>() {{
                    setTargetType(EmployeeCsvDto.class);
                }})
                .build();
    }

    /**
     * 에러가 있는 CSV 파일을 읽는 Reader (에러 처리 테스트용)
     */
    @Bean
    public FlatFileItemReader<EmployeeCsvDto> employeeCsvReaderWithErrors() {
        return new FlatFileItemReaderBuilder<EmployeeCsvDto>()
                .name("employeeCsvReaderWithErrors")
                .resource(new ClassPathResource("data/employees-with-errors.csv"))
                .delimited()
                .delimiter(",")
                .names("firstName", "lastName", "email", "department", "salary", "hireDate")
                .linesToSkip(1)
                .fieldSetMapper(new BeanWrapperFieldSetMapper<EmployeeCsvDto>() {{
                    setTargetType(EmployeeCsvDto.class);
                }})
                .build();
    }
}

2. ItemProcessor - 데이터 변환 및 검증

package com.example.batchtutorial.batch;

import com.example.batchtutorial.dto.EmployeeCsvDto;
import com.example.batchtutorial.entity.Employee;
import com.example.batchtutorial.exception.DataValidationException;
import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.item.ItemProcessor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.StringUtils;

import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.util.regex.Pattern;

/**
 * CSV 데이터를 Employee 엔티티로 변환하는 ItemProcessor
 */
@Slf4j
@Configuration
public class EmployeeItemProcessorConfig {

    private static final Pattern EMAIL_PATTERN = Pattern.compile(
            "^[A-Za-z0-9+_.-]+@([A-Za-z0-9.-]+\\.[A-Za-z]{2,})$"
    );

    private static final DateTimeFormatter DATE_FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd");

    @Bean
    public ItemProcessor<EmployeeCsvDto, Employee> employeeProcessor() {
        return new ItemProcessor<EmployeeCsvDto, Employee>() {
            @Override
            public Employee process(EmployeeCsvDto csvDto) throws Exception {

                log.debug("Processing employee: {} {}", csvDto.getFirstName(), csvDto.getLastName());

                try {
                    // 1. 기본 필드 검증
                    validateRequiredFields(csvDto);

                    // 2. Employee 엔티티 생성
                    Employee employee = new Employee();

                    // 3. 기본 정보 설정
                    employee.setFirstName(csvDto.getFirstName().trim());
                    employee.setLastName(csvDto.getLastName().trim());
                    employee.setDepartment(csvDto.getDepartment().trim());

                    // 4. 이메일 검증 및 설정
                    String email = validateAndProcessEmail(csvDto.getEmail());
                    employee.setEmail(email);

                    // 5. 급여 검증 및 설정
                    BigDecimal salary = validateAndProcessSalary(csvDto.getSalary());
                    employee.setSalary(salary);

                    // 6. 입사일 검증 및 설정
                    LocalDate hireDate = validateAndProcessHireDate(csvDto.getHireDate());
                    employee.setHireDate(hireDate);

                    log.info("Successfully processed employee: {}", employee.getFullName());
                    return employee;

                } catch (DataValidationException e) {
                    log.warn("Validation failed for employee {}: {}", 
                            csvDto.getFirstName() + " " + csvDto.getLastName(), e.getMessage());
                    return null;  // null 반환 시 해당 아이템은 writer로 전달되지 않음

                } catch (Exception e) {
                    log.error("Unexpected error processing employee {}: {}", 
                            csvDto.getFirstName() + " " + csvDto.getLastName(), e.getMessage());
                    throw e;  // 예상치 못한 오류는 재발생시켜 배치 중단
                }
            }
        };
    }

    /**
     * 필수 필드 검증
     */
    private void validateRequiredFields(EmployeeCsvDto csvDto) throws DataValidationException {
        if (!StringUtils.hasText(csvDto.getFirstName())) {
            throw new DataValidationException("이름이 비어있습니다");
        }
        if (!StringUtils.hasText(csvDto.getLastName())) {
            throw new DataValidationException("성이 비어있습니다");
        }
        if (!StringUtils.hasText(csvDto.getEmail())) {
            throw new DataValidationException("이메일이 비어있습니다");
        }
        if (!StringUtils.hasText(csvDto.getDepartment())) {
            throw new DataValidationException("부서가 비어있습니다");
        }
        if (!StringUtils.hasText(csvDto.getSalary())) {
            throw new DataValidationException("급여가 비어있습니다");
        }
        if (!StringUtils.hasText(csvDto.getHireDate())) {
            throw new DataValidationException("입사일이 비어있습니다");
        }
    }

    /**
     * 이메일 검증 및 처리
     */
    private String validateAndProcessEmail(String email) throws DataValidationException {
        String processedEmail = email.trim().toLowerCase();

        if (!EMAIL_PATTERN.matcher(processedEmail).matches()) {
            throw new DataValidationException("올바른 이메일 형식이 아닙니다: " + email);
        }

        return processedEmail;
    }

    /**
     * 급여 검증 및 처리
     */
    private BigDecimal validateAndProcessSalary(String salaryStr) throws DataValidationException {
        try {
            BigDecimal salary = new BigDecimal(salaryStr.trim());

            if (salary.compareTo(BigDecimal.ZERO) <= 0) {
                throw new DataValidationException("급여는 0보다 커야 합니다: " + salaryStr);
            }

            if (salary.compareTo(new BigDecimal("100000000")) > 0) {
                throw new DataValidationException("급여가 너무 큽니다: " + salaryStr);
            }

            return salary;

        } catch (NumberFormatException e) {
            throw new DataValidationException("급여 형식이 올바르지 않습니다: " + salaryStr);
        }
    }

    /**
     * 입사일 검증 및 처리
     */
    private LocalDate validateAndProcessHireDate(String hireDateStr) throws DataValidationException {
        try {
            LocalDate hireDate = LocalDate.parse(hireDateStr.trim(), DATE_FORMATTER);

            // 입사일이 미래날짜인지 확인
            if (hireDate.isAfter(LocalDate.now())) {
                throw new DataValidationException("입사일은 현재 날짜보다 미래일 수 없습니다: " + hireDateStr);
            }

            // 입사일이 너무 과거인지 확인 (예: 회사 설립일 이전)
            LocalDate companyFoundedDate = LocalDate.of(2000, 1, 1);
            if (hireDate.isBefore(companyFoundedDate)) {
                throw new DataValidationException("입사일이 회사 설립일보다 이전입니다: " + hireDateStr);
            }

            return hireDate;

        } catch (DateTimeParseException e) {
            throw new DataValidationException("입사일 형식이 올바르지 않습니다 (yyyy-MM-dd): " + hireDateStr);
        }
    }
}

3. 커스텀 예외 클래스

package com.example.batchtutorial.exception;

/**
 * 데이터 검증 실패 시 발생하는 예외
 */
public class DataValidationException extends Exception {

    public DataValidationException(String message) {
        super(message);
    }

    public DataValidationException(String message, Throwable cause) {
        super(message, cause);
    }
}

4. ItemWriter - 데이터베이스 저장

package com.example.batchtutorial.batch;

import com.example.batchtutorial.entity.Employee;
import com.example.batchtutorial.repository.EmployeeRepository;
import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.item.Chunk;
import org.springframework.batch.item.ItemWriter;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.math.BigDecimal;
import java.util.List;

/**
 * Employee 엔티티를 데이터베이스에 저장하는 ItemWriter
 */
@Slf4j
@Configuration
public class EmployeeItemWriterConfig {

    @Autowired
    private EmployeeRepository employeeRepository;

    @Bean
    public ItemWriter<Employee> employeeWriter() {
        return new ItemWriter<Employee>() {
            @Override
            public void write(Chunk<? extends Employee> chunk) throws Exception {

                List<? extends Employee> employees = chunk.getItems();
                log.info("Writing {} employees to database", employees.size());

                // 통계 정보 수집
                int savedCount = 0;
                int duplicateCount = 0;
                BigDecimal totalSalary = BigDecimal.ZERO;

                for (Employee employee : employees) {
                    try {
                        // 중복 이메일 체크
                        if (employeeRepository.findByEmail(employee.getEmail()).isPresent()) {
                            log.warn("Duplicate email found, skipping: {}", employee.getEmail());
                            duplicateCount++;
                            continue;
                        }

                        // 직원 저장
                        Employee savedEmployee = employeeRepository.save(employee);
                        savedCount++;
                        totalSalary = totalSalary.add(savedEmployee.getSalary());

                        log.debug("Saved employee: {} (ID: {})", 
                                savedEmployee.getFullName(), savedEmployee.getId());

                    } catch (Exception e) {
                        log.error("Failed to save employee: {}", employee.getFullName(), e);
                        throw e;
                    }
                }

                // 청크 처리 결과 로깅
                log.info("Chunk processing completed - Saved: {}, Duplicates: {}, Total Salary: {}", 
                        savedCount, duplicateCount, totalSalary);

                if (savedCount == 0 && duplicateCount > 0) {
                    log.warn("All employees in this chunk were duplicates");
                }
            }
        };
    }
}

🔧 배치 Job 설정

메인 배치 설정 클래스

package com.example.batchtutorial.config;

import com.example.batchtutorial.dto.EmployeeCsvDto;
import com.example.batchtutorial.entity.Employee;
import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.core.Job;
import org.springframework.batch.core.Step;
import org.springframework.batch.core.job.builder.JobBuilder;
import org.springframework.batch.core.launch.support.RunIdIncrementer;
import org.springframework.batch.core.repository.JobRepository;
import org.springframework.batch.core.step.builder.StepBuilder;
import org.springframework.batch.item.ItemProcessor;
import org.springframework.batch.item.ItemReader;
import org.springframework.batch.item.ItemWriter;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.transaction.PlatformTransactionManager;

/**
 * 직원 CSV 파일 처리 배치 Job 설정
 */
@Slf4j
@Configuration
public class EmployeeBatchConfig {

    @Autowired
    private JobRepository jobRepository;

    @Autowired
    private PlatformTransactionManager transactionManager;

    /**
     * 직원 데이터 처리 Job
     */
    @Bean
    public Job importEmployeeJob(Step importEmployeeStep) {
        return new JobBuilder("importEmployeeJob", jobRepository)
                .incrementer(new RunIdIncrementer())  // 매번 새로운 JobInstance 생성
                .flow(importEmployeeStep)
                .end()
                .build();
    }

    /**
     * 직원 데이터 처리 Step (정상 데이터)
     */
    @Bean
    public Step importEmployeeStep(
            @Qualifier("employeeCsvReader") ItemReader<EmployeeCsvDto> reader,
            ItemProcessor<EmployeeCsvDto, Employee> processor,
            ItemWriter<Employee> writer) {

        return new StepBuilder("importEmployeeStep", jobRepository)
                .<EmployeeCsvDto, Employee>chunk(3, transactionManager)  // 청크 크기 3
                .reader(reader)
                .processor(processor)
                .writer(writer)
                .build();
    }

    /**
     * 에러 처리가 포함된 Job (실습용)
     */
    @Bean
    public Job importEmployeeWithErrorHandlingJob(Step importEmployeeWithErrorHandlingStep) {
        return new JobBuilder("importEmployeeWithErrorHandlingJob", jobRepository)
                .incrementer(new RunIdIncrementer())
                .flow(importEmployeeWithErrorHandlingStep)
                .end()
                .build();
    }

    /**
     * 에러 처리가 포함된 Step
     */
    @Bean
    public Step importEmployeeWithErrorHandlingStep(
            @Qualifier("employeeCsvReaderWithErrors") ItemReader<EmployeeCsvDto> reader,
            ItemProcessor<EmployeeCsvDto, Employee> processor,
            ItemWriter<Employee> writer) {

        return new StepBuilder("importEmployeeWithErrorHandlingStep", jobRepository)
                .<EmployeeCsvDto, Employee>chunk(5, transactionManager)
                .reader(reader)
                .processor(processor)
                .writer(writer)
                // 에러 처리 설정
                .faultTolerant()
                .skipLimit(10)                                    // 최대 10개 아이템 스킵 허용
                .skip(Exception.class)                            // 모든 예외에 대해 스킵 처리
                .listener(employeeSkipListener())                 // 스킵 리스너 등록
                .build();
    }

    /**
     * 스킵된 아이템 로깅을 위한 리스너
     */
    @Bean
    public EmployeeSkipListener employeeSkipListener() {
        return new EmployeeSkipListener();
    }
}

스킵 리스너 구현

package com.example.batchtutorial.config;

import com.example.batchtutorial.dto.EmployeeCsvDto;
import com.example.batchtutorial.entity.Employee;
import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.core.listener.SkipListenerSupport;
import org.springframework.stereotype.Component;

/**
 * 스킵된 아이템에 대한 로깅을 처리하는 리스너
 */
@Slf4j
@Component
public class EmployeeSkipListener extends SkipListenerSupport<EmployeeCsvDto, Employee> {

    @Override
    public void onSkipInRead(Throwable t) {
        log.error("❌ Skip occurred in Reader: {}", t.getMessage());
    }

    @Override
    public void onSkipInProcess(EmployeeCsvDto item, Throwable t) {
        log.error("❌ Skip occurred in Processor for item [{}]: {}", 
                item.getFirstName() + " " + item.getLastName(), t.getMessage());
    }

    @Override
    public void onSkipInWrite(Employee item, Throwable t) {
        log.error("❌ Skip occurred in Writer for item [{}]: {}", 
                item.getFullName(), t.getMessage());
    }
}

🎮 배치 실행 컨트롤러

컨트롤러 클래스 확장

package com.example.batchtutorial.controller;

import com.example.batchtutorial.entity.Employee;
import com.example.batchtutorial.repository.EmployeeRepository;
import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.core.Job;
import org.springframework.batch.core.JobParameters;
import org.springframework.batch.core.JobParametersBuilder;
import org.springframework.batch.core.launch.JobLauncher;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.web.bind.annotation.*;

import java.math.BigDecimal;
import java.util.List;
import java.util.Map;

@Slf4j
@RestController
@RequestMapping("/batch")
public class EmployeeBatchController {

    @Autowired
    private JobLauncher jobLauncher;

    @Autowired
    @Qualifier("importEmployeeJob")
    private Job importEmployeeJob;

    @Autowired
    @Qualifier("importEmployeeWithErrorHandlingJob")
    private Job importEmployeeWithErrorHandlingJob;

    @Autowired
    private EmployeeRepository employeeRepository;

    /**
     * 정상 직원 데이터 배치 실행
     */
    @PostMapping("/employees")
    public String runEmployeeBatch() {
        try {
            JobParameters jobParameters = new JobParametersBuilder()
                    .addLong("timestamp", System.currentTimeMillis())
                    .toJobParameters();

            var jobExecution = jobLauncher.run(importEmployeeJob, jobParameters);

            return String.format(
                "✅ 직원 데이터 배치가 실행되었습니다! " +
                "Job ID: %d, 상태: %s", 
                jobExecution.getId(), 
                jobExecution.getStatus()
            );

        } catch (Exception e) {
            log.error("직원 배치 실행 중 오류 발생", e);
            return "❌ 배치 실행 실패: " + e.getMessage();
        }
    }

    /**
     * 에러 처리 포함 배치 실행
     */
    @PostMapping("/employees-with-errors")
    public String runEmployeeBatchWithErrors() {
        try {
            JobParameters jobParameters = new JobParametersBuilder()
                    .addLong("timestamp", System.currentTimeMillis())
                    .toJobParameters();

            var jobExecution = jobLauncher.run(importEmployeeWithErrorHandlingJob, jobParameters);

            return String.format(
                "✅ 에러 처리 포함 직원 배치가 실행되었습니다! " +
                "Job ID: %d, 상태: %s", 
                jobExecution.getId(), 
                jobExecution.getStatus()
            );

        } catch (Exception e) {
            log.error("에러 처리 배치 실행 중 오류 발생", e);
            return "❌ 배치 실행 실패: " + e.getMessage();
        }
    }

    /**
     * 저장된 직원 데이터 조회
     */
    @GetMapping("/employees")
    public List<Employee> getAllEmployees() {
        return employeeRepository.findAll();
    }

    /**
     * 부서별 통계 조회
     */
    @GetMapping("/employees/statistics")
    public Map<String, Object> getEmployeeStatistics() {
        List<Employee> allEmployees = employeeRepository.findAll();

        long totalCount = allEmployees.size();
        BigDecimal totalSalary = allEmployees.stream()
                .map(Employee::getSalary)
                .reduce(BigDecimal.ZERO, BigDecimal::add);

        BigDecimal averageSalary = totalCount > 0 ? 
                totalSalary.divide(BigDecimal.valueOf(totalCount), 2, BigDecimal.ROUND_HALF_UP) : 
                BigDecimal.ZERO;

        // 부서별 직원 수
        Map<String, Long> departmentCounts = allEmployees.stream()
                .collect(java.util.stream.Collectors.groupingBy(
                    Employee::getDepartment,
                    java.util.stream.Collectors.counting()
                ));

        return Map.of(
            "totalEmployees", totalCount,
            "totalSalary", totalSalary,
            "averageSalary", averageSalary,
            "departmentCounts", departmentCounts
        );
    }

    /**
     * 데이터 초기화 (테스트용)
     */
    @DeleteMapping("/employees")
    public String clearEmployeeData() {
        long deletedCount = employeeRepository.count();
        employeeRepository.deleteAll();
        return String.format("✅ %d개의 직원 데이터가 삭제되었습니다.", deletedCount);
    }
}

🧪 테스트 실행

1. 애플리케이션 실행

./gradlew bootRun

2. 배치 실행 테스트

# 정상 데이터 배치 실행
curl -X POST http://localhost:8080/batch/employees

# 에러 데이터 포함 배치 실행
curl -X POST http://localhost:8080/batch/employees-with-errors

# 직원 데이터 조회
curl http://localhost:8080/batch/employees

# 통계 정보 조회
curl http://localhost:8080/batch/employees/statistics

# 데이터 초기화
curl -X DELETE http://localhost:8080/batch/employees

3. 실행 결과 확인

// GET /batch/employees/statistics 응답 예시
{
  "totalEmployees": 8,
  "totalSalary": 44500000,
  "averageSalary": 5562500.00,
  "departmentCounts": {
    "개발팀": 4,
    "마케팅팀": 2,
    "인사팀": 2
  }
}

✅ 학습 체크포인트

완료해야 할 작업들:

• Employee 엔티티 및 Repository 구현
• CSV 파일 ItemReader 설정
• 데이터 검증 및 변환 ItemProcessor 구현
• 데이터베이스 저장 ItemWriter 구현
• 청크 기반 배치 Job 설정
• 에러 처리 및 스킵 로직 구현
• 배치 실행 및 결과 확인
• 통계 정보 조회 API 테스트

확인 질문:

1. 청크 크기를 3으로 설정한 이유는?
2. ItemProcessor에서 null을 반환하면 어떻게 되나요?
3. 스킵과 재시도의 차이점은 무엇인가요?
4. 왜 DTO와 Entity를 분리했나요?

🎉 축하합니다! 실제 CSV 파일을 처리하는 완전한 배치 시스템을 구현했습니다. 다음 단계에서는 더 고급 기능들을 학습해보겠습니다!

🎯 학습 목표

• Spring Batch 개발 환경 완전 구축
• 가장 간단한 Hello World 배치 작성
• 배치 실행 및 결과 확인
• 메타데이터 테이블 이해

🛠️ 개발 환경 설정

1. 필수 소프트웨어 설치

Java Development Kit (JDK 17+)

# Windows (Chocolatey 사용)
choco install openjdk17

# macOS (Homebrew 사용)
brew install openjdk@17

# Linux (Ubuntu)
sudo apt-get install openjdk-17-jdk

# 설치 확인
java -version
javac -version

IntelliJ IDEA 또는 Eclipse

# IntelliJ IDEA Community Edition (무료)
# https://www.jetbrains.com/idea/download/

# Eclipse IDE for Enterprise Java Developers
# https://www.eclipse.org/downloads/

Gradle 또는 Maven

# Gradle 설치 (권장)
# Windows
choco install gradle

# macOS
brew install gradle

# Linux
sudo apt-get install gradle

# 설치 확인
gradle -version

2. Spring Boot 프로젝트 생성

Spring Initializr 사용

1. 웹 브라우저에서 https://start.spring.io/ 접속

2. 프로젝트 설정:

   Project: Gradle Project
   Language: Java
   Spring Boot: 3.2.x (안정 버전)
   Group: com.example
   Artifact: batch-tutorial
   Name: batch-tutorial
   Description: Spring Batch Tutorial Project
   Package name: com.example.batchtutorial
   Packaging: Jar
   Java: 17

3. Dependencies 추가:

   • Spring Batch
   • Spring Boot DevTools
   • H2 Database
   • Spring Data JPA
   • Spring Web (웹 UI용)

4. GENERATE 클릭 후 다운로드

프로젝트 구조 확인

batch-tutorial/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/batchtutorial/
│   │   │       └── BatchTutorialApplication.java
│   │   └── resources/
│   │       └── application.properties
│   └── test/
│       └── java/
│           └── com/example/batchtutorial/
│               └── BatchTutorialApplicationTests.java
├── build.gradle
└── gradlew (Unix용 실행 스크립트)

3. 의존성 설정 확인 및 수정

build.gradle 파일 내용:

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.0'
    id 'io.spring.dependency-management' version '1.1.4'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    sourceCompatibility = '17'
}

configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories {
    mavenCentral()
}

dependencies {
    // Spring Batch 핵심
    implementation 'org.springframework.boot:spring-boot-starter-batch'

    // 데이터베이스
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    runtimeOnly 'com.h2database:h2'

    // 웹 (모니터링용)
    implementation 'org.springframework.boot:spring-boot-starter-web'

    // 개발 편의
    developmentOnly 'org.springframework.boot:spring-boot-devtools'

    // 로깅 및 유틸리티
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'

    // 테스트
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'org.springframework.batch:spring-batch-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

4. 기본 설정 파일 구성

application.properties 설정:

# 애플리케이션 기본 설정
server.port=8080
spring.application.name=batch-tutorial

# H2 데이터베이스 설정
spring.datasource.url=jdbc:h2:mem:batchdb
spring.datasource.username=sa
spring.datasource.password=
spring.datasource.driver-class-name=org.h2.Driver

# H2 콘솔 활성화 (개발용)
spring.h2.console.enabled=true
spring.h2.console.path=/h2-console

# JPA/Hibernate 설정
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect
spring.jpa.hibernate.ddl-auto=create-drop
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

# Spring Batch 설정
spring.batch.job.enabled=false
spring.batch.jdbc.initialize-schema=always

# 로깅 설정
logging.level.org.springframework.batch=DEBUG
logging.level.com.example.batchtutorial=DEBUG

🏃‍♂️ 첫 번째 배치 작성

1. Hello World 배치 구현

메인 애플리케이션 클래스:

package com.example.batchtutorial;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class BatchTutorialApplication {

    public static void main(String[] args) {
        SpringApplication.run(BatchTutorialApplication.class, args);
    }
}

첫 번째 배치 설정 클래스:

package com.example.batchtutorial.config;

import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.core.Job;
import org.springframework.batch.core.Step;
import org.springframework.batch.core.job.builder.JobBuilder;
import org.springframework.batch.core.repository.JobRepository;
import org.springframework.batch.core.step.builder.StepBuilder;
import org.springframework.batch.core.step.tasklet.Tasklet;
import org.springframework.batch.repeat.RepeatStatus;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.transaction.PlatformTransactionManager;

@Slf4j
@Configuration
public class HelloWorldBatchConfig {

    @Autowired
    private JobRepository jobRepository;

    @Autowired
    private PlatformTransactionManager transactionManager;

    /**
     * Hello World Job 정의
     */
    @Bean
    public Job helloWorldJob(Step helloWorldStep) {
        return new JobBuilder("helloWorldJob", jobRepository)
                .start(helloWorldStep)
                .build();
    }

    /**
     * Hello World Step 정의 - Tasklet 방식
     */
    @Bean
    public Step helloWorldStep() {
        return new StepBuilder("helloWorldStep", jobRepository)
                .tasklet(helloWorldTasklet(), transactionManager)
                .build();
    }

    /**
     * 실제 작업을 수행하는 Tasklet
     */
    @Bean
    public Tasklet helloWorldTasklet() {
        return (contribution, chunkContext) -> {
            log.info("===========================================");
            log.info("🎉 Hello, Spring Batch World!");
            log.info("🚀 첫 번째 배치가 성공적으로 실행되었습니다!");
            log.info("⏰ 실행 시간: {}", java.time.LocalDateTime.now());
            log.info("===========================================");

            return RepeatStatus.FINISHED;
        };
    }
}

2. 배치 실행을 위한 컨트롤러 추가

웹 컨트롤러 클래스:

package com.example.batchtutorial.controller;

import lombok.extern.slf4j.Slf4j;
import org.springframework.batch.core.Job;
import org.springframework.batch.core.JobParameters;
import org.springframework.batch.core.JobParametersBuilder;
import org.springframework.batch.core.launch.JobLauncher;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Slf4j
@RestController
@RequestMapping("/batch")
public class BatchController {

    @Autowired
    private JobLauncher jobLauncher;

    @Autowired
    private Job helloWorldJob;

    /**
     * 배치 수동 실행 엔드포인트
     */
    @PostMapping("/hello")
    public String runHelloWorldBatch() {
        try {
            // 매번 다른 파라미터로 실행 (중복 실행 방지)
            JobParameters jobParameters = new JobParametersBuilder()
                    .addLong("timestamp", System.currentTimeMillis())
                    .toJobParameters();

            var jobExecution = jobLauncher.run(helloWorldJob, jobParameters);

            return String.format(
                "배치가 실행되었습니다! " +
                "Job ID: %d, 상태: %s", 
                jobExecution.getId(), 
                jobExecution.getStatus()
            );

        } catch (Exception e) {
            log.error("배치 실행 중 오류 발생", e);
            return "배치 실행 실패: " + e.getMessage();
        }
    }

    /**
     * 간단한 상태 확인 페이지
     */
    @GetMapping("/status")
    public String getStatus() {
        return "Spring Batch Tutorial 애플리케이션이 실행 중입니다! " +
               "POST /batch/hello 로 배치를 실행하세요.";
    }
}

3. 간단한 웹 페이지 추가 (선택사항)

HTML 템플릿 (src/main/resources/static/index.html):

<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Spring Batch Tutorial</title>
    <style>
        body { 
            font-family: Arial, sans-serif; 
            max-width: 800px; 
            margin: 50px auto; 
            padding: 20px; 
        }
        .container { 
            text-align: center; 
            background: #f5f5f5; 
            padding: 30px; 
            border-radius: 10px; 
        }
        button { 
            background: #007bff; 
            color: white; 
            border: none; 
            padding: 15px 30px; 
            font-size: 16px; 
            border-radius: 5px; 
            cursor: pointer; 
            margin: 10px;
        }
        button:hover { background: #0056b3; }
        .result { 
            margin-top: 20px; 
            padding: 15px; 
            background: white; 
            border-radius: 5px; 
            border-left: 4px solid #007bff;
        }
    </style>
</head>
<body>
    <div class="container">
        <h1>🚀 Spring Batch Tutorial</h1>
        <p>첫 번째 Spring Batch 프로젝트에 오신 것을 환영합니다!</p>

        <button onclick="runBatch()">📤 Hello World 배치 실행</button>
        <button onclick="openH2Console()">🗄️ H2 데이터베이스 콘솔</button>

        <div id="result" class="result" style="display: none;">
            <h3>실행 결과:</h3>
            <p id="resultText"></p>
        </div>
    </div>

    <script>
        function runBatch() {
            const button = event.target;
            button.disabled = true;
            button.innerHTML = '⏳ 실행 중...';

            fetch('/batch/hello', { method: 'POST' })
                .then(response => response.text())
                .then(data => {
                    document.getElementById('result').style.display = 'block';
                    document.getElementById('resultText').textContent = data;
                    button.disabled = false;
                    button.innerHTML = '📤 Hello World 배치 실행';
                })
                .catch(error => {
                    alert('오류 발생: ' + error);
                    button.disabled = false;
                    button.innerHTML = '📤 Hello World 배치 실행';
                });
        }

        function openH2Console() {
            window.open('/h2-console', '_blank');
        }
    </script>
</body>
</html>

🏃‍♂️ 프로젝트 실행 및 테스트

1. 애플리케이션 빌드 및 실행

터미널에서 실행:

# 프로젝트 디렉토리로 이동
cd batch-tutorial

# Gradle로 빌드 및 실행
./gradlew bootRun

# Windows에서는
gradlew.bat bootRun

실행 로그 확인:

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v3.2.0)

2024-08-27 10:30:15.123  INFO --- [main] c.e.b.BatchTutorialApplication : Starting BatchTutorialApplication
2024-08-27 10:30:16.456  INFO --- [main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 8080 (http)
2024-08-27 10:30:16.789  INFO --- [main] c.e.b.BatchTutorialApplication : Started BatchTutorialApplication in 2.345 seconds

2. 배치 실행 테스트

방법 1: 웹 브라우저 사용

1. http://localhost:8080 접속
2. "Hello World 배치 실행" 버튼 클릭
3. 실행 결과 확인

방법 2: cURL 명령어 사용

# 배치 실행
curl -X POST http://localhost:8080/batch/hello

# 응답 예시:
# 배치가 실행되었습니다! Job ID: 1, 상태: COMPLETED

방법 3: IDE에서 직접 실행

// 테스트 클래스 작성
@SpringBootTest
class HelloWorldBatchTest {

    @Autowired
    private JobLauncher jobLauncher;

    @Autowired
    private Job helloWorldJob;

    @Test
    void testHelloWorldBatch() throws Exception {
        JobParameters jobParameters = new JobParametersBuilder()
                .addLong("timestamp", System.currentTimeMillis())
                .toJobParameters();

        JobExecution jobExecution = jobLauncher.run(helloWorldJob, jobParameters);

        assertEquals(BatchStatus.COMPLETED, jobExecution.getStatus());
    }
}

3. 실행 결과 확인

콘솔 로그:

2024-08-27 10:35:22.123  INFO --- [http-nio-8080-exec-1] c.e.b.config.HelloWorldBatchConfig : ===========================================
2024-08-27 10:35:22.124  INFO --- [http-nio-8080-exec-1] c.e.b.config.HelloWorldBatchConfig : 🎉 Hello, Spring Batch World!
2024-08-27 10:35:22.124  INFO --- [http-nio-8080-exec-1] c.e.b.config.HelloWorldBatchConfig : 🚀 첫 번째 배치가 성공적으로 실행되었습니다!
2024-08-27 10:35:22.125  INFO --- [http-nio-8080-exec-1] c.e.b.config.HelloWorldBatchConfig : ⏰ 실행 시간: 2024-08-27T10:35:22.124
2024-08-27 10:35:22.125  INFO --- [http-nio-8080-exec-1] c.e.b.config.HelloWorldBatchConfig : ===========================================

📊 메타데이터 테이블 확인

1. H2 콘솔 접속

1. http://localhost:8080/h2-console 접속
2. JDBC URL: jdbc:h2:mem:batchdb
3. 사용자명: sa
4. 비밀번호: (비워두기)
5. Connect 클릭

2. Spring Batch 메타데이터 테이블들

주요 테이블 구조:

-- Job 인스턴스 정보
SELECT * FROM BATCH_JOB_INSTANCE;

-- Job 실행 정보
SELECT 
    JOB_EXECUTION_ID,
    JOB_INSTANCE_ID,
    CREATE_TIME,
    START_TIME,
    END_TIME,
    STATUS,
    EXIT_CODE
FROM BATCH_JOB_EXECUTION;

-- Step 실행 정보
SELECT 
    STEP_EXECUTION_ID,
    JOB_EXECUTION_ID,
    STEP_NAME,
    STATUS,
    READ_COUNT,
    WRITE_COUNT,
    COMMIT_COUNT,
    START_TIME,
    END_TIME
FROM BATCH_STEP_EXECUTION;

-- Job 파라미터
SELECT * FROM BATCH_JOB_EXECUTION_PARAMS;

실행 결과 예시:

BATCH_JOB_EXECUTION 테이블:
JOB_EXECUTION_ID | JOB_INSTANCE_ID | STATUS    | START_TIME          | END_TIME
1                | 1               | COMPLETED | 2024-08-27 10:35:22 | 2024-08-27 10:35:22

BATCH_STEP_EXECUTION 테이블:
STEP_EXECUTION_ID | JOB_EXECUTION_ID | STEP_NAME        | STATUS    | COMMIT_COUNT
1                 | 1                | helloWorldStep   | COMPLETED | 1

✅ 학습 체크포인트

완료해야 할 작업들:

• Java 17+ 설치 및 확인
• IDE (IntelliJ 또는 Eclipse) 설치
• Spring Boot 프로젝트 생성
• 의존성 설정 확인
• Hello World 배치 구현
• 웹 컨트롤러 작성
• 애플리케이션 실행 성공
• 배치 실행 및 로그 확인
• H2 콘솔에서 메타데이터 테이블 확인

확인 질문:

1. JobRepository의 역할은 무엇인가요?
2. Tasklet과 Chunk 방식의 차이점은?
3. JobParameters가 왜 필요한가요?
4. 배치 실행 상태는 어디에 저장되나요?

다음 단계 준비:

• ItemReader, ItemProcessor, ItemWriter 개념 학습
• 실제 데이터(CSV 파일) 처리 배치 구현
• 에러 처리 및 재시작 기능

🎉 축하합니다! 첫 번째 Spring Batch 프로젝트를 성공적으로 완성했습니다. 이제 다음 단계로 넘어가서 더 실용적인 배치를 만들어보겠습니다.

🎯 Spring Batch란?

Spring Batch는 대용량 데이터 처리를 위한 경량급, 포괄적인 배치 프레임워크입니다. 엔터프라이즈 환경에서 일상적으로 필요한 견고한 배치 애플리케이션 개발을 가능하게 합니다.

핵심 특징

• ✅ 트랜잭션 관리: 대용량 데이터 처리 시 안전한 트랜잭션 보장
• ✅ 청크 기반 처리: 메모리 효율적인 대용량 데이터 처리
• ✅ 재시작/재시도: 실패 지점부터 재시작 가능
• ✅ 스케일링: 멀티스레드, 병렬처리, 원격처리 지원
• ✅ 모니터링: 실행 상태 추적 및 관리

🏗️ Spring Batch 아키텍처

전체 구조도

JobLauncher ──┐
              ├─► Job ──┐
JobRepository ──┘      ├─► Step1 ──┐
                       │           ├─► ItemReader
                       │           ├─► ItemProcessor  
                       │           └─► ItemWriter
                       └─► Step2 ──┐
                                   ├─► ItemReader
                                   ├─► ItemProcessor
                                   └─► ItemWriter

핵심 컴포넌트 상세

1. Job (작업)

Job은 전체 배치 프로세스를 캡슐화한 엔티티입니다.

@Bean
public Job myBatchJob(Step step1, Step step2) {
    return new JobBuilder("myBatchJob", jobRepository)
        .start(step1)        // 첫 번째 Step
        .next(step2)         // 두 번째 Step
        .build();
}

// 조건부 실행 예시
@Bean
public Job conditionalJob(Step step1, Step step2, Step step3) {
    return new JobBuilder("conditionalJob", jobRepository)
        .start(step1)
        .on("FAILED").to(step3)      // step1 실패 시 step3 실행
        .from(step1).on("*").to(step2)  // step1 성공 시 step2 실행
        .build().build();
}

Job의 주요 속성:

• JobInstance: Job의 논리적 실행 단위
• JobExecution: Job의 물리적 실행 시도
• JobParameters: Job 실행 시 전달되는 파라미터

2. Step (단계)

Step은 Job 내에서 독립적이고 순차적인 단계를 나타냅니다.

@Bean
public Step processDataStep(ItemReader<InputData> reader,
                           ItemProcessor<InputData, OutputData> processor,
                           ItemWriter<OutputData> writer) {
    return new StepBuilder("processDataStep", jobRepository)
        .<InputData, OutputData>chunk(1000, transactionManager)  // 1000개씩 처리
        .reader(reader)
        .processor(processor)
        .writer(writer)
        .build();
}

Step의 두 가지 유형:

Chunk-oriented Step (청크 지향)

// 청크 기반 처리 - 가장 일반적
.chunk(chunkSize, transactionManager)
.reader(itemReader)      // 데이터 읽기
.processor(itemProcessor) // 데이터 처리 (선택사항)
.writer(itemWriter)      // 데이터 쓰기

Tasklet-based Step (태스크릿 기반)

// 단순 태스크 실행 - 파일 삭제, 정리 작업 등
@Bean
public Step cleanupStep() {
    return new StepBuilder("cleanupStep", jobRepository)
        .tasklet(new Tasklet() {
            @Override
            public RepeatStatus execute(StepContribution contribution,
                                       ChunkContext chunkContext) {
                // 정리 작업 수행
                cleanupTempFiles();
                return RepeatStatus.FINISHED;
            }
        }, transactionManager)
        .build();
}

3. ItemReader (데이터 읽기)

다양한 소스에서 데이터를 읽어오는 인터페이스

public interface ItemReader<T> {
    T read() throws Exception, UnexpectedInputException, ParseException;
}

주요 구현체들:

파일 읽기 (CSV, TXT)

@Bean
public FlatFileItemReader<Person> csvReader() {
    return new FlatFileItemReaderBuilder<Person>()
        .name("csvReader")
        .resource(new ClassPathResource("input.csv"))
        .delimited()
        .delimiter(",")
        .names("firstName", "lastName", "email", "age")
        .fieldSetMapper(new BeanWrapperFieldSetMapper<Person>() {{
            setTargetType(Person.class);
        }})
        .linesToSkip(1)  // 헤더 행 스킵
        .build();
}

데이터베이스 읽기 (JPA)

@Bean
public JpaPagingItemReader<Customer> databaseReader() {
    return new JpaPagingItemReaderBuilder<Customer>()
        .name("customerReader")
        .entityManagerFactory(entityManagerFactory)
        .queryString("SELECT c FROM Customer c WHERE c.active = true")
        .pageSize(100)  // 페이지당 100개
        .build();
}

데이터베이스 읽기 (JDBC)

@Bean
public JdbcCursorItemReader<Person> jdbcReader() {
    return new JdbcCursorItemReaderBuilder<Person>()
        .name("jdbcReader")
        .dataSource(dataSource)
        .sql("SELECT first_name, last_name, email FROM person WHERE active = 1")
        .rowMapper(new BeanPropertyRowMapper<>(Person.class))
        .build();
}

JSON 파일 읽기

@Bean
public JsonItemReader<Person> jsonReader() {
    return new JsonItemReaderBuilder<Person>()
        .name("jsonReader")
        .resource(new ClassPathResource("input.json"))
        .jsonObjectReader(new JacksonJsonObjectReader<>(Person.class))
        .build();
}

XML 파일 읽기

@Bean
public StaxEventItemReader<Person> xmlReader() {
    return new StaxEventItemReaderBuilder<Person>()
        .name("xmlReader")
        .resource(new ClassPathResource("input.xml"))
        .addFragmentRootElements("person")
        .unmarshaller(personUnmarshaller())
        .build();
}

4. ItemProcessor (데이터 처리)

읽어온 데이터를 비즈니스 로직에 따라 변환하는 인터페이스

public interface ItemProcessor<I, O> {
    O process(I item) throws Exception;
}

실제 구현 예시:

단순 변환

@Bean
public ItemProcessor<Person, Person> validatingProcessor() {
    return new ItemProcessor<Person, Person>() {
        @Override
        public Person process(Person person) throws Exception {
            // 데이터 검증
            if (person.getEmail() == null || !person.getEmail().contains("@")) {
                return null;  // null 반환 시 해당 아이템은 writer로 전달되지 않음
            }

            // 데이터 변환
            person.setFirstName(person.getFirstName().toUpperCase());
            person.setLastName(person.getLastName().toUpperCase());

            return person;
        }
    };
}

복합 프로세서 (여러 프로세서 연결)

@Bean
public CompositeItemProcessor<Person, Person> compositeProcessor() {
    List<ItemProcessor<?, ?>> processors = new ArrayList<>();
    processors.add(validationProcessor());
    processors.add(transformationProcessor());
    processors.add(enrichmentProcessor());

    CompositeItemProcessor<Person, Person> processor = new CompositeItemProcessor<>();
    processor.setDelegates(processors);
    return processor;
}

외부 API 호출 프로세서

@Bean
public ItemProcessor<String, WeatherData> apiCallProcessor() {
    return cityName -> {
        try {
            // 외부 API 호출
            WeatherApiResponse response = webClient.get()
                .uri("/weather?q=" + cityName)
                .retrieve()
                .bodyToMono(WeatherApiResponse.class)
                .timeout(Duration.ofSeconds(5))  // 5초 타임아웃
                .block();

            // 응답을 엔티티로 변환
            return convertToWeatherData(response, cityName);

        } catch (Exception e) {
            log.error("API call failed for city: {}", cityName, e);
            return null;  // 실패 시 null 반환
        }
    };
}

5. ItemWriter (데이터 쓰기)

처리된 데이터를 최종 목적지에 저장하는 인터페이스

public interface ItemWriter<T> {
    void write(List<? extends T> items) throws Exception;
}

주요 구현체들:

파일 쓰기

@Bean
public FlatFileItemWriter<Person> csvWriter() {
    return new FlatFileItemWriterBuilder<Person>()
        .name("csvWriter")
        .resource(new FileSystemResource("output.csv"))
        .delimited()
        .delimiter(",")
        .names("firstName", "lastName", "email")
        .headerCallback(writer -> writer.write("FirstName,LastName,Email"))  // 헤더
        .build();
}

데이터베이스 쓰기 (JPA)

@Bean
public JpaItemWriter<Customer> jpaWriter() {
    JpaItemWriter<Customer> writer = new JpaItemWriter<>();
    writer.setEntityManagerFactory(entityManagerFactory);
    return writer;
}

데이터베이스 쓰기 (JDBC)

@Bean
public JdbcBatchItemWriter<Person> jdbcWriter() {
    return new JdbcBatchItemWriterBuilder<Person>()
        .dataSource(dataSource)
        .sql("INSERT INTO person (first_name, last_name, email) VALUES (:firstName, :lastName, :email)")
        .beanMapped()  // Bean 속성을 SQL 파라미터로 매핑
        .build();
}

복합 Writer (여러 Writer에 동시 저장)

@Bean
public CompositeItemWriter<Person> compositeWriter() {
    List<ItemWriter<? super Person>> writers = new ArrayList<>();
    writers.add(databaseWriter());
    writers.add(fileWriter());
    writers.add(emailNotificationWriter());

    CompositeItemWriter<Person> writer = new CompositeItemWriter<>();
    writer.setDelegates(writers);
    return writer;
}

🔄 청크 기반 처리의 이해

청크 처리 과정

[Reader] ──► Item1 ──┐
[Reader] ──► Item2 ──┤
[Reader] ──► Item3 ──┤ Chunk (Size=3)
                     ├──► [Processor] ──► ProcessedChunk ──► [Writer]
                     │                                      │
                     └──► Transaction Commit ◄──────────────┘

청크 크기 결정 기준

// 작은 청크 크기 (10-100)
.chunk(50, transactionManager)
// 장점: 빠른 피드백, 적은 메모리 사용, 롤백 범위 최소화
// 단점: 트랜잭션 오버헤드 증가

// 큰 청크 크기 (1000-10000)
.chunk(5000, transactionManager)
// 장점: 높은 처리 성능, 트랜잭션 오버헤드 감소
// 단점: 메모리 사용량 증가, 롤백 시 재처리 데이터 많음

청크 처리 최적화 팁

@Bean
public Step optimizedStep() {
    return new StepBuilder("optimizedStep", jobRepository)
        .<InputData, OutputData>chunk(1000, transactionManager)
        .reader(reader())
        .processor(processor())
        .writer(writer())

        // 성능 최적화 설정
        .faultTolerant()
        .skipLimit(100)                    // 최대 100개 아이템 스킵 허용
        .skip(ValidationException.class)   // 특정 예외는 스킵
        .retryLimit(3)                     // 최대 3번 재시도
        .retry(TransientException.class)   // 일시적 예외는 재시도

        // 멀티스레드 처리
        .taskExecutor(taskExecutor())
        .throttleLimit(4)                  // 동시 실행 스레드 수

        build();
}

💾 메타데이터 관리

JobRepository

Spring Batch는 실행 중인 Job의 상태 정보를 JobRepository에 저장합니다.

-- 주요 메타데이터 테이블들
BATCH_JOB_INSTANCE        -- Job 인스턴스 정보
BATCH_JOB_EXECUTION       -- Job 실행 정보  
BATCH_JOB_EXECUTION_PARAMS -- Job 파라미터
BATCH_STEP_EXECUTION      -- Step 실행 정보
BATCH_STEP_EXECUTION_CONTEXT -- Step 실행 컨텍스트

JobParameters 사용법

// JobParameters 생성
JobParameters jobParameters = new JobParametersBuilder()
    .addString("inputFile", "/path/to/input.csv")
    .addLong("timestamp", System.currentTimeMillis())
    .addDate("processDate", new Date())
    .toJobParameters();

// Job 실행
JobExecution execution = jobLauncher.run(job, jobParameters);

🚨 에러 처리 전략

1. Skip (건너뛰기)

@Bean
public Step skipStep() {
    return new StepBuilder("skipStep", jobRepository)
        .<String, String>chunk(10, transactionManager)
        .reader(reader())
        .processor(processor())
        .writer(writer())
        .faultTolerant()
        .skip(ValidationException.class)     // ValidationException 발생 시 스킵
        .skip(DataAccessException.class)     // DB 접근 오류 시 스킵
        .skipLimit(100)                      // 최대 100개까지 스킵 허용
        .skipPolicy(customSkipPolicy())      // 커스텀 스킵 정책
        .build();
}

2. Retry (재시도)

@Bean
public Step retryStep() {
    return new StepBuilder("retryStep", jobRepository)
        .<String, String>chunk(10, transactionManager)
        .reader(reader())
        .processor(processor())
        .writer(writer())
        .faultTolerant()
        .retry(ConnectException.class)       // 연결 오류 시 재시도
        .retry(TimeoutException.class)       // 타임아웃 시 재시도
        .retryLimit(3)                       // 최대 3번 재시도
        .retryPolicy(customRetryPolicy())    // 커스텀 재시도 정책
        .build();
}

3. 커스텀 예외 처리

@Component
public class CustomSkipPolicy implements SkipPolicy {

    private static final Logger logger = LoggerFactory.getLogger(CustomSkipPolicy.class);

    @Override
    public boolean shouldSkip(Throwable exception, int skipCount) throws SkipLimitExceededException {

        if (exception instanceof ValidationException) {
            logger.warn("Validation error occurred. Skipping item. Skip count: {}", skipCount);
            return skipCount < 50;  // ValidationException은 50개까지 스킵
        }

        if (exception instanceof DataAccessException) {
            logger.error("Database error occurred. Skipping item. Skip count: {}", skipCount);
            return skipCount < 10;  // DB 오류는 10개까지만 스킵
        }

        return false;  // 다른 예외는 스킵하지 않음
    }
}

🎯 실전 예제: 완전한 배치 시스템

고객 데이터 처리 배치

@Configuration
@EnableBatchProcessing
public class CustomerProcessingBatchConfig {

    @Bean
    public Job customerProcessingJob() {
        return new JobBuilder("customerProcessingJob", jobRepository)
            .start(readCustomersStep())          // 1. 고객 데이터 읽기
            .next(validateCustomersStep())       // 2. 데이터 검증
            .next(enrichCustomersStep())         // 3. 데이터 보강
            .next(calculateScoreStep())          // 4. 점수 계산
            .next(sendNotificationStep())        // 5. 알림 발송
            .next(cleanupStep())                 // 6. 정리 작업
            .build();
    }

    // Step 1: 고객 데이터 읽기
    @Bean
    public Step readCustomersStep() {
        return new StepBuilder("readCustomersStep", jobRepository)
            .<CustomerCsv, Customer>chunk(500, transactionManager)
            .reader(customerCsvReader())
            .processor(csvToCustomerProcessor())
            .writer(customerDatabaseWriter())
            .build();
    }

    // Step 2: 데이터 검증
    @Bean
    public Step validateCustomersStep() {
        return new StepBuilder("validateCustomersStep", jobRepository)
            .<Customer, Customer>chunk(1000, transactionManager)
            .reader(customerDatabaseReader())
            .processor(validationProcessor())
            .writer(validatedCustomerWriter())
            .faultTolerant()
            .skip(ValidationException.class)
            .skipLimit(100)
            .listener(validationSkipListener())
            .build();
    }

    // Step 3: 외부 API를 통한 데이터 보강
    @Bean
    public Step enrichCustomersStep() {
        return new StepBuilder("enrichCustomersStep", jobRepository)
            .<Customer, Customer>chunk(100, transactionManager)
            .reader(validatedCustomerReader())
            .processor(enrichmentProcessor())
            .writer(enrichedCustomerWriter())
            .faultTolerant()
            .retry(ConnectException.class)
            .retryLimit(3)
            .taskExecutor(taskExecutor())
            .throttleLimit(5)  // API 호출 제한
            .build();
    }
}

이제 Spring Batch의 모든 기본 개념을 이해했습니다! 다음 단계에서는 실제로 배치를 어떻게 구현하고 운영하는지 더 자세히 알아보겠습니다.

🎯 학습 목표

이 문서는 현재 Spring Batch 시스템을 어떻게 공부하고, 어떻게 확장할 수 있는지 상세하게 안내합니다.

📚 코드 분석을 통한 학습 방법

1. 핵심 클래스 분석 순서

1단계: 기본 구조 이해

// 1. 메인 애플리케이션 클래스 분석
SpringBatchApplication.java
→ @SpringBootApplication 어노테이션의 의미
→ main() 메서드의 역할
→ Spring Boot 자동 설정 메커니즘

// 2. 설정 클래스 분석
BatchConfig.java, WeatherBatchConfig.java
→ @Configuration 어노테이션
→ @Bean 메서드들의 의존성 주입
→ Job, Step, ItemReader/Processor/Writer 관계

2단계: 배치 컴포넌트 상세 분석

Job 분석 (작업 단위):

@Bean
public Job importUserJob(Step step1) {
    return new JobBuilder("importUserJob", jobRepository)
            .start(step1)  // 시작 Step 지정
            .build();
}

// 학습 포인트:
// - Job은 여러 Step을 포함할 수 있음
// - JobRepository는 배치 실행 메타데이터 관리
// - JobBuilder 패턴 사용법

Step 분석 (처리 단계):

@Bean
public Step step1(ItemReader<Person> reader,
                  ItemProcessor<Person, Person> processor,
                  ItemWriter<Person> writer) {
    return new StepBuilder("step1", jobRepository)
            .<Person, Person>chunk(3, transactionManager)  // 청크 크기 = 3
            .reader(reader)      // 데이터 읽기
            .processor(processor) // 데이터 처리
            .writer(writer)      // 데이터 쓰기
            .build();
}

// 학습 포인트:
// - 청크 기반 처리: 3개씩 묶어서 트랜잭션 처리
// - Reader → Processor → Writer 파이프라인
// - 각 컴포넌트의 독립성과 재사용성

3단계: 각 컴포넌트 심화 분석

ItemReader 분석:

// CSV 파일 읽기
@Bean
public FlatFileItemReader<Person> reader() {
    return new FlatFileItemReaderBuilder<Person>()
            .name("personItemReader")
            .resource(new ClassPathResource("sample-data.csv"))
            .delimited()  // CSV 구분자 설정
            .names(new String[]{"firstName", "lastName", "email"})
            .fieldSetMapper(new BeanWrapperFieldSetMapper<Person>() {{
                setTargetType(Person.class);  // 매핑 대상 클래스
            }})
            .build();
}

// 학습 해볼 점:
// 1. 다른 데이터 소스는? (Database, JSON, XML)
// 2. 파일 경로 동적 설정 방법은?
// 3. 에러 발생 시 처리 방법은?

ItemProcessor 분석:

// 날씨 데이터 처리 예시
@Bean
public ItemProcessor<String, WeatherData> weatherProcessor() {
    return cityCode -> {
        try {
            // 1. 외부 API 호출
            WeatherApiResponse response = weatherApiService
                .getCurrentWeather(cityCode).block();

            // 2. 데이터 변환
            WeatherData weatherData = convertToWeatherData(response, cityCode);

            // 3. 비즈니스 로직 (이상 기후 탐지)
            detectAbnormalWeather(weatherData);

            return weatherData;
        } catch (Exception e) {
            log.error("Processing failed for {}: {}", cityCode, e.getMessage());
            return null;  // null 반환 시 해당 아이템 스킵
        }
    };
}

// 학습 해볼 점:
// 1. 복잡한 변환 로직 구현 방법
// 2. 외부 API 호출 시 에러 처리
// 3. 조건부 처리 (특정 조건에서만 처리)
// 4. 병렬 처리를 위한 멀티스레드 적용

2. 실전 코드 실습 방법

디버깅을 통한 학습:

// 1. IDE에서 브레이크포인트 설정
@Bean
public ItemProcessor<Person, Person> processor() {
    return (item) -> {
        // ↓ 여기에 브레이크포인트 설정
        log.info("Processing person: {}", item);

        // 데이터 변환 로직 실행 과정 관찰
        String upperFirstName = item.getFirstName().toUpperCase();
        item.setFirstName(upperFirstName);

        return item;  // ← 반환값 확인
    };
}

로그 분석:

# 애플리케이션 실행 후 로그 확인
./gradlew bootRun

# 주요 확인 포인트:
# - Job 실행 시작/종료 로그
# - Step 실행 과정
# - 청크 단위 처리 로그
# - 에러 발생 시 스택 트레이스

🛠️ 시스템 확장 방법

1. 새로운 배치 Job 추가

예시: 주식 데이터 배치 추가

@Configuration
public class StockBatchConfig {

    @Autowired
    private JobRepository jobRepository;

    @Autowired
    private PlatformTransactionManager transactionManager;

    // 1. 새로운 Job 정의
    @Bean
    public Job collectStockDataJob(Step stockCollectionStep) {
        return new JobBuilder("collectStockDataJob", jobRepository)
                .start(stockCollectionStep)
                .build();
    }

    // 2. Step 정의
    @Bean
    public Step stockCollectionStep() {
        return new StepBuilder("stockCollectionStep", jobRepository)
                .<String, StockData>chunk(5, transactionManager)
                .reader(stockSymbolReader())      // 주식 심볼 리더
                .processor(stockDataProcessor())   // 주식 API 호출
                .writer(stockDataWriter())        // DB 저장
                .build();
    }

    // 3. 주식 심볼 읽기
    @Bean
    public ItemReader<String> stockSymbolReader() {
        List<String> symbols = List.of("AAPL", "GOOGL", "MSFT", "AMZN");

        return new ItemReader<String>() {
            private int index = 0;

            @Override
            public String read() {
                if (index < symbols.size()) {
                    return symbols.get(index++);
                }
                return null;
            }
        };
    }

    // 4. 주식 데이터 처리
    @Bean
    public ItemProcessor<String, StockData> stockDataProcessor() {
        return symbol -> {
            // Yahoo Finance API 또는 Alpha Vantage API 호출
            // JSON 응답을 StockData 엔티티로 변환
            return stockApiService.getStockData(symbol);
        };
    }

    // 5. DB 저장
    @Bean
    public ItemWriter<StockData> stockDataWriter() {
        return chunk -> {
            List<? extends StockData> stockDataList = chunk.getItems();
            stockDataRepository.saveAll(stockDataList);
        };
    }
}

필요한 추가 클래스들:

// StockData 엔티티
@Entity
@Table(name = "stock_data")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class StockData {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String symbol;       // 주식 심볼
    private String companyName;  // 회사명
    private Double currentPrice; // 현재 가격
    private Double openPrice;    // 시가
    private Double highPrice;    // 고가
    private Double lowPrice;     // 저가
    private Long volume;         // 거래량
    private LocalDateTime collectedAt;
}

// StockDataRepository
@Repository
public interface StockDataRepository extends JpaRepository<StockData, Long> {
    List<StockData> findBySymbolOrderByCollectedAtDesc(String symbol);
    List<StockData> findTop10ByOrderByCollectedAtDesc();
}

// StockApiService
@Service
public class StockApiService {

    private final WebClient webClient;

    public StockApiService() {
        this.webClient = WebClient.builder()
            .baseUrl("https://api.example.com/stock")
            .build();
    }

    public StockData getStockData(String symbol) {
        // 실제 API 호출 로직 구현
        return webClient.get()
            .uri("/quote/{symbol}", symbol)
            .retrieve()
            .bodyToMono(StockData.class)
            .block();
    }
}

2. 스케줄링 추가

Cron 표현식으로 자동 실행:

@Component
@EnableScheduling
public class BatchScheduler {

    @Autowired
    private JobLauncher jobLauncher;

    @Autowired
    private Job collectWeatherDataJob;

    @Autowired
    private Job collectStockDataJob;

    // 매시간 정각에 날씨 데이터 수집
    @Scheduled(cron = "0 0 * * * *")
    public void runWeatherBatch() {
        try {
            JobParameters params = new JobParametersBuilder()
                .addLong("time", System.currentTimeMillis())
                .toJobParameters();

            jobLauncher.run(collectWeatherDataJob, params);
        } catch (Exception e) {
            log.error("Weather batch scheduling failed", e);
        }
    }

    // 평일 오전 9시에 주식 데이터 수집
    @Scheduled(cron = "0 0 9 * * MON-FRI")
    public void runStockBatch() {
        try {
            JobParameters params = new JobParametersBuilder()
                .addLong("time", System.currentTimeMillis())
                .toJobParameters();

            jobLauncher.run(collectStockDataJob, params);
        } catch (Exception e) {
            log.error("Stock batch scheduling failed", e);
        }
    }
}

3. 에러 처리 및 재시도 로직 추가

재시도 정책 설정:

@Bean
public Step resilientWeatherStep() {
    return new StepBuilder("resilientWeatherStep", jobRepository)
            .<String, WeatherData>chunk(3, transactionManager)
            .reader(cityReader())
            .processor(weatherProcessor())
            .writer(weatherWriter())
            // 재시도 설정
            .faultTolerant()
            .retry(Exception.class)        // 모든 예외에 대해 재시도
            .retryLimit(3)                 // 최대 3번 재시도
            // 특정 예외는 건너뛰기
            .skip(IllegalArgumentException.class)
            .skipLimit(5)                  // 최대 5개까지 건너뛰기
            .build();
}

실패한 아이템 별도 처리:

@Bean
public Step stepWithFailureHandling() {
    return new StepBuilder("stepWithFailureHandling", jobRepository)
            .<String, WeatherData>chunk(3, transactionManager)
            .reader(cityReader())
            .processor(weatherProcessor())
            .writer(weatherWriter())
            .faultTolerant()
            // 실패한 아이템을 별도 파일로 저장
            .skipListener(new SkipListener<String, WeatherData>() {
                @Override
                public void onSkipInProcessing(String item, Throwable t) {
                    log.error("Skipped processing for city: {}, Error: {}", 
                        item, t.getMessage());
                    // 실패 로그를 파일이나 별도 테이블에 저장
                    saveFailedItem(item, t.getMessage());
                }
            })
            .build();
}

4. 성능 최적화

멀티스레드 처리:

@Bean
public Step parallelWeatherStep() {
    return new StepBuilder("parallelWeatherStep", jobRepository)
            .<String, WeatherData>chunk(3, transactionManager)
            .reader(cityReader())
            .processor(weatherProcessor())
            .writer(weatherWriter())
            // 멀티스레드 설정
            .taskExecutor(taskExecutor())
            .throttleLimit(4)  // 동시 실행 스레드 수
            .build();
}

@Bean
public TaskExecutor taskExecutor() {
    ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
    executor.setCorePoolSize(4);
    executor.setMaxPoolSize(8);
    executor.setQueueCapacity(25);
    executor.setThreadNamePrefix("batch-thread-");
    executor.initialize();
    return executor;
}

파티션 처리 (대용량 데이터):

@Bean
public Step partitionStep() {
    return new StepBuilder("partitionStep", jobRepository)
            .partitioner("slaveStep", partitioner())
            .step(slaveStep())
            .gridSize(4)  // 4개 파티션으로 분할
            .taskExecutor(taskExecutor())
            .build();
}

@Bean
public Partitioner partitioner() {
    return new Partitioner() {
        @Override
        public Map<String, ExecutionContext> partition(int gridSize) {
            Map<String, ExecutionContext> result = new HashMap<>();

            // 도시 목록을 4개 그룹으로 분할
            List<String> cities = List.of("Seoul", "Busan", "Incheon", 
                                         "Daegu", "Daejeon", "Gwangju", 
                                         "Ulsan", "Suwon");

            int partitionSize = cities.size() / gridSize;

            for (int i = 0; i < gridSize; i++) {
                ExecutionContext context = new ExecutionContext();
                int start = i * partitionSize;
                int end = (i == gridSize - 1) ? cities.size() : (i + 1) * partitionSize;

                context.put("cities", cities.subList(start, end));
                result.put("partition" + i, context);
            }

            return result;
        }
    };
}

🔍 고급 학습 방향

1. Spring Batch Admin 연동

• 배치 작업 모니터링 웹 UI
• 실행 이력 및 상태 관리
• 실패한 Job 재시작 기능

2. 메시지 큐 연동 (RabbitMQ, Kafka)

// Kafka를 통한 배치 트리거
@KafkaListener(topics = "weather-batch-trigger")
public void handleBatchTrigger(String message) {
    // 메시지 수신 시 배치 실행
    jobLauncher.run(collectWeatherDataJob, createJobParameters());
}

3. 클라우드 환경 배포

• AWS Batch, Google Cloud Dataflow
• Kubernetes CronJob
• Docker 컨테이너화

4. 데이터베이스 최적화

// 대용량 처리를 위한 JPA 배치 설정
@Bean
public JpaItemWriter<WeatherData> optimizedWriter() {
    JpaItemWriter<WeatherData> writer = new JpaItemWriter<>();
    writer.setEntityManagerFactory(entityManagerFactory);
    // 배치 삽입 최적화
    return writer;
}

📖 추천 학습 리소스

공식 문서:

• Spring Batch Reference Documentation
• Spring Boot Batch 가이드

실습 프로젝트 아이디어:

1. 로그 파일 분석 배치: 웹 서버 로그 파싱 및 통계 생성
2. 데이터 마이그레이션 배치: Legacy 시스템에서 신규 시스템으로 데이터 이전
3. 리포트 생성 배치: 일간/주간/월간 리포트 자동 생성
4. 데이터 정제 배치: 중복 데이터 제거, 데이터 품질 향상

이 가이드를 통해 현재 시스템을 완전히 이해하고 자신만의 배치 시스템으로 확장할 수 있습니다.

🚀 시스템 시작하기

1. 애플리케이션 실행

# 프로젝트 디렉토리에서
./gradlew bootRun

# 또는 Windows에서
gradlew.bat bootRun

2. 접속 정보

• 메인 페이지: http://localhost:8080
• 날씨 대시보드: http://localhost:8080/weather/dashboard
• H2 콘솔: http://localhost:8080/h2-console

3. H2 데이터베이스 접속 정보

JDBC URL: jdbc:h2:mem:testdb
사용자명: sa
비밀번호: (비워두세요)

📋 CSV 배치 시스템 사용법

1. 웹 UI를 통한 실행

메인 페이지에서:

1. http://localhost:8080 접속
2. "📤 CSV 배치 실행" 버튼 클릭
3. 확인 대화상자에서 "확인" 클릭
4. 배치 실행 결과 확인

// 실행 버튼 JavaScript 코드
function runBatch(button) {
    if(confirm('배치 작업을 실행하시겠습니까?')) {
        button.disabled = true;
        button.innerHTML = '⏳ 실행 중...';

        fetch('/run-batch', { method: 'POST' })
        .then(response => response.text())
        .then(data => {
            alert(data);  // 실행 결과 표시
            button.disabled = false;
            button.innerHTML = '📤 배치 실행';
        });
    }
}

2. REST API를 통한 실행

POST 요청으로 직접 실행:

curl -X POST http://localhost:8080/run-batch

응답 예시:

{
  "message": "배치가 성공적으로 완료되었습니다!",
  "jobExecutionId": 1,
  "status": "COMPLETED"
}

3. 처리되는 데이터 확인

CSV 파일 내용 (sample-data.csv):

firstName,lastName,email
김,철수,kim.chulsoo@example.com
이,영희,lee.younghee@example.com
박,민수,park.minsoo@example.com
최,수지,choi.suji@example.com
정,재호,jung.jaeho@example.com

저장된 데이터 확인:

1. 웹 UI: "📊 저장된 사용자 데이터" 버튼 클릭
2. REST API: GET http://localhost:8080/persons
3. H2 콘솔: SELECT * FROM PERSON;

🌦️ 날씨 배치 시스템 사용법

1. 날씨 대시보드 접속

대시보드 메인 화면:

1. http://localhost:8080/weather/dashboard 접속
2. 실시간 날씨 데이터 현황 확인
3. 통계 카드에서 전체 수집 데이터 수, 모니터링 도시 수, 이상 기후 감지 수 확인

2. 날씨 데이터 수집 실행

웹 UI를 통한 실행:

<!-- 대시보드에서 -->
<button onclick="collectWeatherData()" class="btn btn-primary">
    🌍 날씨 데이터 수집
</button>

1. "🌍 날씨 데이터 수집" 버튼 클릭
2. 배치 실행 확인 (약 10-15초 소요)
3. 자동 페이지 새로고침 (3초 후)
4. 업데이트된 날씨 데이터 확인

REST API를 통한 실행:

curl -X POST http://localhost:8080/weather/collect

3. 수집 대상 도시

전국 주요 8개 도시:

List<String> cities = List.of(
    "Seoul",    // 서울
    "Busan",    // 부산
    "Incheon",  // 인천
    "Daegu",    // 대구
    "Daejeon",  // 대전
    "Gwangju",  // 광주
    "Ulsan",    // 울산
    "Suwon"     // 수원
);

4. 수집되는 날씨 정보

기본 날씨 데이터:

• 온도 정보: 현재 온도, 체감 온도, 최고/최저 온도
• 기상 상태: 날씨 상태 (맑음, 흐림, 비 등), 상세 설명
• 대기 정보: 습도, 기압, 가시거리
• 바람 정보: 풍속, 풍향
• 강수 정보: 강수량, 적설량 (1시간 단위)

추가 분석 데이터:

• 수집 시간: 데이터 수집 시각
• 온도 변화량: 전날 동시간 대비 온도 차이
• 이상 기후 여부: 20도 이상 온도 변화 시 true

5. 실시간 데이터 모니터링

대시보드 섹션별 기능:

📊 통계 카드:

<div class="stats-grid">
    <div class="stat-card">
        <h3>전체 수집 데이터</h3>
        <div class="value">1,234</div>
    </div>
    <div class="stat-card">
        <h3>모니터링 도시</h3>
        <div class="value">8</div>
    </div>
    <div class="stat-card">
        <h3>이상 기후 감지</h3>
        <div class="value">2</div>
    </div>
</div>

🌤️ 도시별 현재 날씨:

• 각 도시의 최신 날씨 정보
• 온도, 날씨 상태, 수집 시간
• 전날 대비 온도 변화량 표시

🌡️ 온도 순위:

• 현재 온도 기준 도시별 순위
• 습도, 체감 온도 추가 정보

⚠️ 이상 기후 알림:

• 전날 대비 20도 이상 변화한 지역
• 급격한 온도 변화 감지 시 자동 표시

🔧 API 엔드포인트 가이드

CSV 배치 관련 API

1. 배치 실행

POST /run-batch
Content-Type: application/json

Response:
{
  "message": "배치가 성공적으로 완료되었습니다!",
  "jobExecutionId": 1,
  "status": "COMPLETED"
}

2. 저장된 사용자 데이터 조회

GET /persons

Response:
[
  {
    "id": 1,
    "firstName": "김",
    "lastName": "철수",
    "email": "kim.chulsoo@example.com"
  },
  ...
]

날씨 배치 관련 API

1. 날씨 데이터 수집 실행

POST /weather/collect

Response: "날씨 데이터 수집 배치가 시작되었습니다. 상태: STARTED"

2. 전체 날씨 데이터 조회

GET /weather/data

Response:
[
  {
    "id": 1,
    "cityCode": "Seoul",
    "cityName": "서울",
    "temperature": 15.5,
    "humidity": 65,
    "weatherMain": "Clear",
    "collectedAt": "2025-08-27T14:30:00",
    "isAbnormal": false,
    "temperatureChange": 2.1
  },
  ...
]

3. 도시별 최신 날씨 조회

GET /weather/current

Response: [최신 날씨 데이터만]

4. 이상 기후 데이터 조회

GET /weather/abnormal

Response: [이상 기후로 감지된 데이터만]

5. 날씨 통계 조회

GET /weather/statistics

Response:
{
  "todayRecords": 24,
  "averageTemperature": 18.5,
  "maxTemperature": 25.2,
  "minTemperature": 12.1,
  "abnormalCount": 1
}

🛠️ 데이터베이스 직접 조회

H2 콘솔 사용법

1. 콘솔 접속:

1. http://localhost:8080/h2-console 접속
2. JDBC URL: jdbc:h2:mem:testdb 입력
3. 사용자명: sa, 비밀번호: 빈값
4. "Connect" 클릭

2. 유용한 SQL 쿼리:

전체 사용자 데이터 조회:

SELECT * FROM PERSON;

날씨 데이터 조회:

-- 최신 날씨 데이터
SELECT city_name, temperature, weather_main, collected_at 
FROM WEATHER_DATA 
ORDER BY collected_at DESC 
LIMIT 10;

-- 이상 기후 데이터
SELECT city_name, temperature, temperature_change, collected_at
FROM WEATHER_DATA 
WHERE is_abnormal = true
ORDER BY collected_at DESC;

-- 도시별 평균 온도
SELECT city_name, AVG(temperature) as avg_temp, COUNT(*) as records
FROM WEATHER_DATA 
GROUP BY city_name;

⚠️ 주의사항 및 문제 해결

1. API 키 설정 확인

# .env 파일 확인
cat .env

# 출력 예시:
# WEATHER_API_KEY=4336a7df2186cc57454035002475e06a

2. 포트 충돌 해결

# 8080 포트 사용 중인 프로세스 확인
netstat -ano | findstr :8080

# 프로세스 종료 (Windows)
taskkill /F /PID [프로세스ID]

3. 배치 실행 실패 시

• 로그 확인: 콘솔 출력에서 ERROR 레벨 메시지 확인
• API 키 유효성 확인
• 인터넷 연결 상태 확인
• H2 데이터베이스 연결 상태 확인

4. 일반적인 에러 해결

"API 키가 설정되지 않았습니다" 에러:

# .env 파일 생성 또는 수정
echo "WEATHER_API_KEY=4336a7df2186cc57454035002475e06a" > .env

"포트 8080이 이미 사용 중" 에러:

1. 다른 프로세스 종료
2. 또는 application.properties에서 포트 변경:

   server.port=8081

이제 시스템을 완전히 활용할 수 있습니다. 다음 문서에서는 이 시스템을 어떻게 공부하고 확장할 수 있는지 알아보겠습니다.

📋 프로젝트 개요

이 Spring Batch 프로젝트는 CSV 파일 처리와 실시간 날씨 데이터 수집 두 가지 배치 시스템을 포함합니다.

springBatch/
├── src/main/java/com/springbatch/
│   ├── SpringBatchApplication.java       # 메인 애플리케이션
│   ├── config/                          # 설정 클래스들
│   │   ├── BatchConfig.java             # CSV 배치 설정
│   │   └── WeatherBatchConfig.java      # 날씨 배치 설정
│   ├── controller/                      # 웹 컨트롤러
│   │   ├── BatchController.java         # 배치 실행 컨트롤러
│   │   └── WeatherController.java       # 날씨 API 컨트롤러
│   ├── entity/                          # JPA 엔티티
│   │   ├── Person.java                  # 사용자 엔티티
│   │   └── WeatherData.java             # 날씨 데이터 엔티티
│   ├── dto/                             # 데이터 전송 객체
│   │   └── WeatherApiResponse.java      # 날씨 API 응답 DTO
│   ├── repository/                      # 데이터 접근 계층
│   │   ├── PersonRepository.java        # 사용자 데이터 리포지토리
│   │   └── WeatherDataRepository.java   # 날씨 데이터 리포지토리
│   └── service/                         # 비즈니스 로직
│       └── WeatherApiService.java       # 날씨 API 서비스
├── src/main/resources/
│   ├── templates/                       # Thymeleaf 템플릿
│   │   ├── index.html                   # 메인 페이지
│   │   └── weather-dashboard.html       # 날씨 대시보드
│   ├── application.properties           # 애플리케이션 설정
│   └── sample-data.csv                 # 샘플 CSV 데이터
├── .env                                # 환경 변수 (API 키)
└── build.gradle                        # Gradle 빌드 설정

🏗️ 아키텍처 구성요소

1. CSV 배치 시스템 (BatchConfig.java)

@Configuration
public class BatchConfig {

    // Job: 전체 배치 작업 정의
    @Bean
    public Job importUserJob(Step step1) {
        return new JobBuilder("importUserJob", jobRepository)
                .start(step1)
                .build();
    }

    // Step: 실제 처리 단계
    @Bean
    public Step step1(ItemReader<Person> reader,
                      ItemProcessor<Person, Person> processor,
                      ItemWriter<Person> writer) {
        return new StepBuilder("step1", jobRepository)
                .<Person, Person>chunk(3, transactionManager)
                .reader(reader)      // CSV 파일 읽기
                .processor(processor) // 데이터 변환/검증
                .writer(writer)      // 데이터베이스 저장
                .build();
    }
}

처리 흐름:

1. ItemReader: sample-data.csv 파일에서 사용자 데이터 읽기
2. ItemProcessor: 데이터 검증 및 변환 (이메일 형식 체크 등)
3. ItemWriter: H2 데이터베이스에 Person 엔티티로 저장

2. 날씨 배치 시스템 (WeatherBatchConfig.java)

@Configuration
public class WeatherBatchConfig {

    // 날씨 데이터 수집 Job
    @Bean
    public Job collectWeatherDataJob(Step weatherCollectionStep) {
        return new JobBuilder("collectWeatherDataJob", jobRepository)
                .start(weatherCollectionStep)
                .build();
    }

    // 날씨 데이터 처리 Step
    @Bean
    public Step weatherCollectionStep(ItemReader<String> cityReader,
                                     ItemProcessor<String, WeatherData> weatherProcessor,
                                     ItemWriter<WeatherData> weatherWriter) {
        return new StepBuilder("weatherCollectionStep", jobRepository)
                .<String, WeatherData>chunk(3, transactionManager)
                .reader(cityReader)      // 도시 목록 생성
                .processor(weatherProcessor) // API 호출 및 데이터 변환
                .writer(weatherWriter)   // 데이터베이스 저장
                .build();
    }
}

처리 흐름:

1. ItemReader: 전국 주요 8개 도시 목록 생성 (Seoul, Busan, Incheon 등)
2. ItemProcessor: 각 도시별 OpenWeatherMap API 호출 → WeatherData 엔티티 변환
3. ItemWriter: H2 데이터베이스에 날씨 데이터 저장
4. 이상 기후 탐지: 전날 대비 온도 변화량 계산 (20도 이상 차이 시 이상 기후로 판정)

🛠️ 기술 스택

Core Technologies

• Spring Boot 3.5.5: 애플리케이션 프레임워크
• Spring Batch 5.x: 배치 처리 프레임워크
• Java 17: 프로그래밍 언어
• Gradle: 빌드 도구

Data & Persistence

• H2 Database: 인메모리 데이터베이스
• Spring Data JPA: 데이터 접근 계층
• Hibernate: ORM 프레임워크

Web & API

• Spring WebFlux: 비동기 REST 클라이언트 (WebClient)
• Thymeleaf: 서버사이드 템플릿 엔진
• Spring Web MVC: 웹 컨트롤러

External APIs

• OpenWeatherMap API: 실시간 날씨 데이터
• API Key: 환경변수로 관리 (.env 파일)

📊 데이터 모델

Person Entity (사용자 데이터)

@Entity
@Table(name = "person")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Person {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(name = "first_name")
    private String firstName;

    @Column(name = "last_name") 
    private String lastName;

    private String email;
}

WeatherData Entity (날씨 데이터)

@Entity
@Table(name = "weather_data")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class WeatherData {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String cityCode;           // 도시 코드

    @Column(nullable = false)
    private String cityName;           // 도시명 (한국어)

    @Column(nullable = false)
    private Double temperature;        // 현재 온도

    private Double feelsLike;          // 체감 온도
    private Double tempMin;            // 최저 온도
    private Double tempMax;            // 최고 온도
    private Integer humidity;          // 습도
    private Integer pressure;          // 기압
    private Double windSpeed;          // 풍속
    private Integer windDirection;     // 풍향
    private Integer cloudiness;        // 구름량
    private Double rainfall;           // 강수량 (1시간)
    private Double snowfall;           // 적설량 (1시간)
    private Integer visibility;        // 가시거리

    private String weatherMain;        // 날씨 상태 (Rain, Clear 등)
    private String weatherDescription; // 날씨 설명

    @Column(nullable = false)
    private LocalDateTime collectedAt; // 데이터 수집 시간

    private LocalDateTime weatherTime; // 날씨 관측 시간

    // 이상 기후 탐지 필드
    private Boolean isAbnormal = false;     // 이상 기후 여부
    private Double temperatureChange;       // 전날 대비 온도 변화량
}

🔄 배치 실행 흐름

1. CSV 배치 실행

사용자 요청 → BatchController.runJob() 
→ JobLauncher.run(importUserJob) 
→ Step1 실행 
→ CSV 파일 읽기 → 데이터 처리 → DB 저장

2. 날씨 배치 실행

사용자 요청 → WeatherController.collectWeatherData()
→ JobLauncher.run(collectWeatherDataJob)
→ WeatherCollectionStep 실행
→ 도시 목록 생성 → API 호출 → 데이터 변환 → 이상기후 탐지 → DB 저장

🎯 핵심 특징

1. 청크 기반 처리

• 대량 데이터를 3개씩 묶어서 처리 (메모리 효율성)
• 트랜잭션 단위로 커밋

2. 이상 기후 탐지 알고리즘

private void detectAbnormalWeather(WeatherData currentData) {
    // 전날 동일 시간대 데이터 조회
    var yesterdayDataList = weatherDataRepository
        .findByCityCodeAndCollectedAtBetweenOrderByCollectedAtDesc(
            currentData.getCityCode(), yesterdayStart, yesterdayEnd);

    if (!yesterdayDataList.isEmpty()) {
        WeatherData yesterdayData = yesterdayDataList.get(0);
        double temperatureChange = currentData.getTemperature() - yesterdayData.getTemperature();

        // 전날 대비 20도 이상 변화 시 이상 기후로 판단
        if (Math.abs(temperatureChange) >= 20.0) {
            currentData.setIsAbnormal(true);
        }
    }
}

3. 외부 API 연동

• WebClient를 사용한 비동기 HTTP 통신
• 환경변수 기반 API 키 관리
• 에러 핸들링 및 로깅

4. 웹 대시보드

• Thymeleaf 템플릿 기반 실시간 데이터 시각화
• 반응형 디자인
• AJAX 기반 배치 실행

🔐 보안 및 설정

환경 변수 관리 (.env)

WEATHER_API_KEY=4336a7df2186cc57454035002475e06a

애플리케이션 설정 (application.properties)

# H2 Database
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.username=sa
spring.datasource.password=
spring.h2.console.enabled=true

# JPA
spring.jpa.hibernate.ddl-auto=create-drop
spring.jpa.show-sql=true

# Batch
spring.batch.job.enabled=false

📈 성능 및 모니터링

로깅 시스템

• Slf4j + Logback 기반 로깅
• 배치 실행 상태 및 에러 추적
• API 호출 결과 모니터링

메트릭스

• 배치 실행 시간
• API 응답 시간
• 데이터 처리량
• 이상 기후 감지 건수

이 구조를 기반으로 다양한 배치 시스템을 확장할 수 있으며, 각 컴포넌트는 독립적으로 테스트 및 운영 가능합니다.

"이론으로만 알던 MSA를 실제로 구현해보니 생각보다 복잡했지만, 그만큼 배운 것도 많았습니다."

안녕하세요! 오늘은 Spring Boot와 React를 사용해서 완전한 마이크로서비스 아키텍처(MSA) 시스템을 구현한 경험을 공유해보려 합니다. 단순한 Hello World가 아닌, 실제 상용 서비스 수준의 전자상거래 시스템을 만들어봤어요.

🎯 완성된 시스템 미리보기

회원가입 → 상품등록 → 장바구니 → 주문 → JWT 인증까지, 완전한 비즈니스 플로우를 가진 시스템입니다.

🤔 왜 MSA를 선택했을까?

모놀리식 아키텍처의 한계

전통적인 모놀리식 구조에서는 한 부분의 변경이 전체 시스템에 영향을 미치는 문제가 있었습니다.

모놀리식 구조의 문제점:
❌ 부분 배포 불가 → 전체 시스템 재배포 필요
❌ 기술 스택 고정 → 서비스별 최적 기술 선택 불가
❌ 확장성 제한 → 전체 시스템 스케일업만 가능
❌ 장애 전파 → 한 모듈 장애가 전체 시스템 다운

MSA가 제공하는 장점

🔥 핵심 장점들:

1. 독립적인 배포와 확장

   • 각 서비스를 개별적으로 배포/확장 가능
   • 트래픽이 많은 서비스만 스케일 아웃

2. 기술적 다양성

   • 서비스별로 최적의 기술 스택 선택
   • User Service는 Spring Boot, Notification Service는 Node.js 등

3. 장애 격리

   • 한 서비스의 장애가 다른 서비스에 영향 없음
   • Circuit Breaker 패턴으로 장애 전파 방지

4. 팀 독립성

   • 서비스별로 팀이 독립적으로 개발
   • API 계약만 지키면 내부 구현은 자유

🏗️ 시스템 아키텍처 설계

전체 시스템 구조

graph TD
    A[React Frontend :3000] --> B[API Gateway :8080]
    B --> C[Eureka Server :8761]

    B --> D[User Service :8081]
    B --> E[Product Service :8082]  
    B --> F[Order Service :8083]

    F --> E[Product Service via OpenFeign]

    D --> G[H2 DB - users]
    E --> H[H2 DB - products]
    F --> I[H2 DB - orders]

핵심 구성 요소

선택한 기술 스택

백엔드:

• Java 17 (LTS 안정성)
• Gradle 8.10 (멀티모듈 빌드)
• Spring Boot 3.2 (최신 안정 버전)
• Spring Cloud Gateway (비동기 API 게이트웨이)
• Netflix Eureka (서비스 발견)
• OpenFeign (선언적 HTTP 클라이언트)

프론트엔드:

• React 18 (최신 Hook 기반)
• Axios (HTTP 클라이언트)

🛠️ 단계별 구현 과정

1단계: 프로젝트 기반 구조 설정

가장 중요한 것은 올바른 멀티모듈 Gradle 구조를 만드는 것이었습니다.

settings.gradle

rootProject.name = 'msa-system'

include 'eureka-server'
include 'api-gateway'
include 'user-service'
include 'product-service'
include 'order-service'

루트 build.gradle

plugins {
    id 'org.springframework.boot' version '3.2.0' apply false
    id 'io.spring.dependency-management' version '1.1.4' apply false
}

subprojects {
    apply plugin: 'java'
    apply plugin: 'org.springframework.boot'
    apply plugin: 'io.spring.dependency-management'

    java {
        toolchain {
            languageVersion = JavaLanguageVersion.of(17)
        }
    }

    // 🔥 핵심: @PathVariable 파라미터 인식을 위한 설정
    tasks.withType(JavaCompile) {
        options.compilerArgs += ['-parameters']
    }
}

💡 중요한 포인트: -parameters 옵션이 없으면 DELETE API에서 500 에러가 발생합니다!

2단계: 서비스 발견 시스템 (Eureka Server)

MSA의 핵심인 서비스 발견 시스템부터 구축했습니다.

EurekaServerApplication.java

@SpringBootApplication
@EnableEurekaServer  // 이 한 줄로 Eureka 서버 완성!
public class EurekaServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(EurekaServerApplication.class, args);
    }
}

application.yml

server:
  port: 8761

eureka:
  client:
    register-with-eureka: false  # 자기 자신은 등록하지 않음
    fetch-registry: false
  server:
    enable-self-preservation: false  # 개발환경용 설정

결과: http://localhost:8761 에서 아름다운 Eureka 대시보드 완성!

3단계: 핵심 비즈니스 서비스들

User Service - JWT 인증 시스템

가장 까다로웠던 부분입니다. 단순 CRUD가 아닌 완전한 JWT 인증 시스템을 구현했어요.

@Component
public class JwtTokenProvider {

    private final String secretKey = "mySecretKeyForJwtTokenGenerationAndValidation1234567890";
    private final long validityInMilliseconds = 86400000; // 24시간

    public String createToken(User user) {
        Claims claims = Jwts.claims().setSubject(user.getUsername());
        claims.put("userId", user.getId());
        claims.put("username", user.getUsername());
        claims.put("role", user.getRole().toString());

        Date now = new Date();
        Date validity = new Date(now.getTime() + validityInMilliseconds);

        return Jwts.builder()
                .setClaims(claims)
                .setIssuedAt(now)
                .setExpiration(validity)
                .signWith(key, SignatureAlgorithm.HS256)
                .compact();
    }
}

Product Service - 재고 관리 시스템

단순한 CRUD를 넘어서 실시간 재고 관리까지 구현했습니다.

@Entity
public class Product {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;
    private Double price;
    private Integer stock;  // 🔥 재고 관리의 핵심
    private String category;
}

Order Service - 서비스 간 통신

가장 복잡한 서비스입니다. OpenFeign을 사용한 서비스 간 통신과 트랜잭션 처리를 구현했어요.

@FeignClient(name = "product-service")
public interface ProductClient {
    @GetMapping("/products/{id}")
    ProductResponse getProduct(@PathVariable Long id);

    @PutMapping("/products/{id}/stock")
    void updateStock(@PathVariable Long id, @RequestBody Integer stock);
}

주문 처리 로직:

@Service
@Transactional
public class OrderService {

    public Order createOrder(OrderRequest orderRequest) {
        // 1. 상품 정보 조회 (다른 마이크로서비스 호출!)
        ProductResponse product = productClient.getProduct(productId);

        // 2. 재고 확인
        if (product.getStock() < quantity) {
            throw new RuntimeException("재고 부족!");
        }

        // 3. 재고 차감 (다른 마이크로서비스 업데이트!)
        productClient.updateStock(productId, product.getStock() - quantity);

        // 4. 주문 생성
        return orderRepository.save(order);
    }
}

4단계: API Gateway - 단일 진입점

모든 요청을 받아서 적절한 서비스로 라우팅하는 관문 역할입니다.

application.yml

spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: lb://user-service  # 로드밸런서 사용!
          predicates:
            - Path=/users/**

        - id: product-service
          uri: lb://product-service
          predicates:
            - Path=/products/**

        - id: order-service
          uri: lb://order-service
          predicates:
            - Path=/orders/**

      # 🔥 CORS 문제 해결
      globalcors:
        cors-configurations:
          '[/**]':
            allowed-origins: "*"
            allowed-methods: "*"
            allowed-headers: "*"

JWT 인증 필터

API Gateway에서 모든 요청을 가로채서 JWT 검증을 수행합니다.

@Component
public class JwtAuthenticationFilter extends AbstractGatewayFilterFactory<JwtAuthenticationFilter.Config> {

    @Override
    public GatewayFilter apply(Config config) {
        return (exchange, chain) -> {
            ServerHttpRequest request = exchange.getRequest();

            // 인증이 필요 없는 경로들
            if (isPublicPath(request.getURI().getPath())) {
                return chain.filter(exchange);
            }

            // JWT 토큰 검증
            String authHeader = request.getHeaders().getFirst(HttpHeaders.AUTHORIZATION);
            if (authHeader == null || !authHeader.startsWith("Bearer ")) {
                return onError(exchange, "Invalid Authorization header");
            }

            String token = authHeader.substring(7);
            if (!jwtUtil.validateToken(token)) {
                return onError(exchange, "Invalid JWT token");
            }

            // 검증 성공시 사용자 정보를 헤더에 추가
            Long userId = jwtUtil.getUserIdFromToken(token);
            ServerHttpRequest modifiedRequest = exchange.getRequest()
                    .mutate()
                    .header("X-User-Id", userId.toString())
                    .build();

            return chain.filter(exchange.mutate().request(modifiedRequest).build());
        };
    }
}

5단계: React 프론트엔드 - 사용자 경험

탭 기반의 직관적인 UI로 모든 기능을 쉽게 사용할 수 있게 했습니다.

핵심 상태 관리

function App() {
  const [activeTab, setActiveTab] = useState('users');
  const [users, setUsers] = useState([]);
  const [products, setProducts] = useState([]);
  const [cart, setCart] = useState([]);
  const [orders, setOrders] = useState([]);
}

실시간 장바구니 시스템

const addToCart = (product) => {
  const existingItem = cart.find(item => item.id === product.id);
  if (existingItem) {
    setCart(cart.map(item => 
      item.id === product.id 
        ? { ...item, quantity: item.quantity + 1 }
        : item
    ));
  } else {
    setCart([...cart, { ...product, quantity: 1 }]);
  }
  setMessage(`${product.name}이(가) 장바구니에 추가되었습니다!`);
};

주문 생성 및 재고 연동

const createOrder = async () => {
  const orderRequest = {
    userId: users[0].id,
    items: cart.map(item => ({
      productId: item.id,
      quantity: item.quantity
    }))
  };

  await axios.post('/orders', orderRequest);
  setCart([]);
  setMessage('주문이 성공적으로 생성되었습니다!');
  fetchOrders(); // 주문 목록 새로고침
};

🔥 핵심 기술적 해결책들

1. JSON 순환 참조 문제

문제: Order ↔ OrderItem 양방향 참조로 인한 StackOverflowError

// 해결책: Jackson 어노테이션 사용
@Entity
public class Order {
    @OneToMany(mappedBy = "order")
    @JsonManagedReference  // 부모에서 자식 직렬화
    private List<OrderItem> orderItems;
}

@Entity 
public class OrderItem {
    @ManyToOne
    @JsonBackReference  // 자식에서 부모 직렬화 제외
    private Order order;
}

2. @PathVariable 파라미터 인식 실패

문제: DELETE API에서 500 에러 발생

// 해결책: 컴파일 시 파라미터 정보 포함
tasks.withType(JavaCompile) {
    options.compilerArgs += ['-parameters']
}

3. 서비스 간 통신 최적화

OpenFeign 사용으로 선언적 HTTP 클라이언트 구현:

@FeignClient(name = "product-service")
public interface ProductClient {
    @GetMapping("/products/{id}")
    ProductResponse getProduct(@PathVariable Long id);
}

// 사용법이 정말 간단!
ProductResponse product = productClient.getProduct(1L);

4. CORS 문제 완전 해결

API Gateway에서 중앙화된 CORS 설정:

spring:
  cloud:
    gateway:
      globalcors:
        cors-configurations:
          '[/**]':
            allowed-origins: "*"
            allowed-methods: "*" 
            allowed-headers: "*"

🚀 완성된 기능들

✅ 완전한 비즈니스 플로우

1. 👤 사용자 관리: 회원가입, 로그인, JWT 토큰 발급
2. 📦 상품 관리: CRUD, 재고 관리, 카테고리 검색
3. 🛒 장바구니: 실시간 추가/삭제, 수량 조절
4. 📋 주문 처리: 자동 재고 차감, 트랜잭션 처리
5. 🔐 보안: JWT 기반 인증, API Gateway 필터

✅ MSA 핵심 패턴 구현

• 서비스 발견 패턴 (Eureka)
• API 게이트웨이 패턴 (Spring Cloud Gateway)
• 서비스 간 통신 패턴 (OpenFeign)
• 데이터베이스 per 서비스 (각 서비스별 독립 DB)

✅ 사용자 경험

• 직관적인 탭 기반 UI
• 실시간 피드백 (성공/실패 메시지)
• 반응형 디자인 (모바일 지원)

🎯 실제 테스트 시나리오

전체 플로우 테스트

1. 사용자 등록 → "홍길동" 회원가입
2. 상품 등록 → "iPhone 15" (가격: 1,200,000원, 재고: 10개)
3. 장바구니 추가 → iPhone 15 * 2개 담기
4. 주문 생성 → 총 2,400,000원 주문
5. 재고 확인 → iPhone 15 재고가 8개로 자동 차감!
6. 주문 조회 → 생성된 주문 정보 확인

API 테스트 (Postman)

# 사용자 생성
POST http://localhost:8080/users
{
  "name": "홍길동",
  "email": "hong@test.com",
  "phone": "010-1234-5678"
}

# 상품 생성  
POST http://localhost:8080/products
{
  "name": "iPhone 15",
  "description": "최신 아이폰",
  "price": 1200000,
  "stock": 10,
  "category": "전자제품"
}

# 주문 생성 (서비스 간 통신 테스트)
POST http://localhost:8080/orders
{
  "userId": 1,
  "items": [
    {
      "productId": 1,
      "quantity": 2
    }
  ]
}

📈 성능 및 확장성

로드밸런싱 테스트

# 서비스 인스턴스 복제 테스트
docker-compose up -d --scale user-service=3 --scale product-service=2

장애 격리 테스트

• Product Service 중단 → Order Service에서 Circuit Breaker 작동
• User Service 중단 → 인증이 필요 없는 상품 조회는 정상 작동

🔮 향후 확장 계획

현재 시스템은 완전한 MSA의 기초를 다졌습니다. 다음 단계로는:

고급 MSA 패턴 적용

• Circuit Breaker (Resilience4j)
• 분산 추적 (Sleuth + Zipkin)
• 중앙화 로깅 (ELK Stack)
• 메시지 큐 (RabbitMQ, Kafka)

클라우드 네이티브 전환

• Kubernetes 배포
• Istio 서비스 메시 적용
• Prometheus + Grafana 모니터링

DevOps 파이프라인

• Jenkins CI/CD 구축
• Docker 컨테이너화 완료
• Helm Chart 배포 자동화

💡 학습 포인트와 조언

1. 단계적 접근의 중요성

처음부터 모든 기능을 만들려 하지 마세요. 저는 이런 순서로 진행했습니다:

1. 단일 서비스로 시작 → 2. Eureka 추가 → 3. 서비스 분리 → 4. Gateway 추가

2. 로그를 꼼꼼히 확인하자

MSA에서는 여러 서비스 간의 상호작용이 복잡합니다. 문제 발생 시 각 서비스의 로그를 모두 확인해야 해요.

3. 독립 테스트 먼저

각 서비스를 독립적으로 먼저 테스트한 후에 통합 테스트를 진행하세요.

4. 문서화는 필수

해결한 문제들을 반드시 문서로 기록하세요. 같은 문제를 다시 겪지 않기 위해서죠.

📚 참고 자료

• Spring Cloud 공식 문서
• Netflix Eureka 가이드
• OpenFeign 사용법

🎉 마무리

이번 MSA 구현 프로젝트를 통해 정말 많은 것을 배웠습니다. 단순한 Hello World 수준을 넘어서 실제 서비스 수준의 기능을 구현할 수 있었고, MSA의 장점과 복잡성을 모두 경험해볼 수 있었어요.

가장 인상적이었던 부분:

• 서비스 간 통신이 이렇게 간단할 수 있다니! (OpenFeign 덕분)
• JWT 인증을 API Gateway에서 중앙화 처리하는 것의 편리함
• React와 Spring Boot의 완벽한 조합

앞으로 MSA를 시작하려는 분들께:

• 작게 시작해서 점진적으로 확장하세요
• 각 단계별로 충분히 테스트하고 넘어가세요
• 문제를 겪는 것은 자연스러운 과정입니다. 포기하지 마세요!

완전한 소스 코드는 GitHub에서 확인하실 수 있습니다. 질문이나 피드백은 언제든 환영입니다! 🚀

이 글이 도움이 되셨다면 좋아요와 댓글 부탁드려요! 여러분의 MSA 구현 경험도 궁금합니다. 🙌

🔰 스레드풀이 뭔가요?

스레드(Thread)란?

스레드는 프로그램이 동시에 여러 일을 처리할 수 있게 해주는 작업 단위입니다.

• 음식점에서 요리사 1명 = 스레드 1개라고 생각하면 됩니다
• 요리사가 1명이면 주문을 하나씩만 처리 가능 (동기)
• 요리사가 여러 명이면 여러 주문을 동시에 처리 가능 (비동기)

스레드풀(ThreadPool)이란?

스레드풀은 미리 준비해둔 스레드들의 집합입니다.

음식점 비유:
┌─────────────────────────────────────┐
│        주방 (스레드풀)               │
│                                     │
│ 👨‍🍳 👨‍🍳 👨‍🍳 (요리사 = 스레드)      │
│                                     │
│ 📋 📋 📋 (대기 주문 = 큐)           │
└─────────────────────────────────────┘

- 기본 요리사 2명 (corePoolSize = 2)
- 바쁠 때 최대 10명까지 (maxPoolSize = 10)
- 주문 50개까지 대기 가능 (queueCapacity = 50)

왜 스레드풀을 사용하나요?

1. 효율성: 스레드 생성/삭제 비용 절약
2. 안정성: 시스템 리소스 보호 (무한정 스레드 생성 방지)
3. 제어: 동시 실행 작업 수 제한

개요

DungeonTalk 백엔드는 도메인별 분리된 스레드풀을 사용하여 비동기 작업을 처리합니다.

핵심 개념 (실제 예시로 이해하기)

1. 매칭 전용 스레드풀

🎮 게임 매칭 상황:
유저A: "게임 매칭해주세요!"
유저B: "저도 매칭해주세요!" 
AI게임: "AI 턴 처리해주세요!"

👨‍🍳 매칭 전용 주방(스레드풀):
- 요리사 2~10명이 이런 요청들만 처리
- 게임 관련 작업에만 집중

2. Heartbeat 전용 스케줄러

💓 WebSocket 연결 유지:
"클라이언트야, 살아있니?" (매 30초마다)
"네, 살아있어요!" 

👨‍🍳 Heartbeat 전용 직원:
- 요리사 2명이 연결 확인만 담당  
- 게임 처리와 완전 분리

3. 장애 격리 (진짜 중요한 개념!)

❌ 만약 스레드풀을 분리하지 않았다면:
매칭 처리가 너무 느림 → 모든 스레드 점유 → WebSocket 연결 끊김 😱

✅ 스레드풀 분리 후:
매칭 처리가 느림 → 매칭용 스레드만 느림 → WebSocket은 정상 작동 😊

왜 이렇게 설계했나?

1. 안정성: 매칭 처리가 느려져도 WebSocket 연결은 유지됨
2. 확장성: 부하가 높은 기능만 독립적으로 스케일업 가능
3. 모니터링: 도메인별 성능 추적 및 문제 파악 용이

전체 아키텍처 다이어그램

┌─────────────────────────────────────────────────────────────────┐
│                    DungeonTalk Backend                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────────┐    ┌──────────────────┐                  │
│  │   Web Layer      │    │   WebSocket      │                  │
│  │  (Controllers)   │    │    Layer         │                  │
│  └─────────┬────────┘    └─────────┬────────┘                  │
│            │                       │                           │
│            ▼                       ▼                           │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                 Service Layer                               │ │
│  │                                                             │ │
│  │  ┌─────────────────┐       ┌────────────────────────────┐   │ │
│  │  │ MatchingService │       │   AiGameFlowService        │   │ │
│  │  │                 │       │                            │   │ │
│  │  │ @Async(         │       │ @Async(                    │   │ │
│  │  │ "matchingTask   │       │ "matchingTaskExecutor")    │   │ │
│  │  │ Executor")      │       │                            │   │ │
│  │  └─────────┬───────┘       └────────────┬───────────────┘   │ │
│  └────────────┼──────────────────────────────┼─────────────────┘ │
│               │                              │                   │
│               ▼                              ▼                   │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                Thread Pool Layer                            │ │
│  │                                                             │ │
│  │  ┌──────────────────────────────────────────────────────┐   │ │
│  │  │          matchingTaskExecutor                        │   │ │
│  │  │  ┌─────────────────────────────────────────────────┐ │   │ │
│  │  │  │ ThreadPoolTaskExecutor Configuration            │ │   │ │
│  │  │  │                                                 │ │   │ │
│  │  │  │ • Core Threads: 2                              │ │   │ │
│  │  │  │ • Max Threads: 10                              │ │   │ │
│  │  │  │ • Queue: 50                                    │ │   │ │
│  │  │  │ • KeepAlive: 60s                               │ │   │ │
│  │  │  │ • Name: "Matching-Async-"                      │ │   │ │
│  │  │  │                                                 │ │   │ │
│  │  │  │ RejectedExecutionHandler:                       │ │   │ │
│  │  │  │ └─► Fallback to Main Thread                    │ │   │ │
│  │  │  └─────────────────────────────────────────────────┘ │   │ │
│  │  └──────────────────────────────────────────────────────┘   │ │
│  │                                                             │ │
│  │  ┌──────────────────────────────────────────────────────┐   │ │
│  │  │           stompTaskScheduler                         │   │ │
│  │  │  ┌─────────────────────────────────────────────────┐ │   │ │
│  │  │  │ ThreadPoolTaskScheduler Configuration           │ │   │ │
│  │  │  │                                                 │ │   │ │
│  │  │  │ • Pool Size: 2                                 │ │   │ │
│  │  │  │ • Name: "stomp-heartbeat-"                     │ │   │ │
│  │  │  │ • RemoveOnCancel: true                         │ │   │ │
│  │  │  │                                                 │ │   │ │
│  │  │  │ Purpose: STOMP Heartbeat Only                  │ │   │ │
│  │  │  └─────────────────────────────────────────────────┘ │   │ │
│  │  └──────────────────────────────────────────────────────┘   │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

🚀 스레드 실행 흐름 (따라가보기)

🤔 초보자 질문: "사용자가 매칭 버튼을 누르면 뭐가 일어나요?"

매칭과 AI 턴 처리는 같은 스레드풀을 공유하여 리소스를 효율적으로 사용합니다.
WebSocket Heartbeat는 별도 스케줄러로 실시간 연결을 안정적으로 유지합니다.

단계별 실행 과정

1. 매칭 처리 흐름 (실제 상황)

🎮 사용자: "매칭해주세요!" 클릭
      │
      ▼ HTTP 요청 전송
┌─────────────┐    
│ Controller  │ ──── "어? 매칭 요청이 왔네!" 
└─────────────┘           
      │                          
      ▼ MatchingService 호출
┌──────────────────┐
│ MatchingService  │ ──── "@Async로 비동기 처리해야지!"
└─────────┬────────┘      
          │ @Async("matchingTaskExecutor")
          ▼ 스레드풀로 작업 위임
┌─────────────────────────┐
│  matchingTaskExecutor   │ ── "매칭 전용 주방이야!"
│                         │
│ 👨‍🍳 👨‍🍳 (T1)(T2)        │ ── "지금 2명 대기중"  
│                         │
│ 📋📋📋 Queue(50개 대기가능) │ ── "주문 대기열"
└─────────────────────────┘
          │
          ▼ 실제 매칭 작업 수행
┌─────────────────────────┐
│    매칭 처리 로직        │
│  • Redis에서 대기자 찾기 │ ── "다른 플레이어 있나?"
│  • 유저 상태 업데이트    │ ── "매칭중 상태로 변경"  
│  • 게임방 생성          │ ── "방 만들어서 입장!"
└─────────────────────────┘

💡 핵심 포인트: Controller는 바로 응답하고, 실제 매칭은 백그라운드에서 처리!

2. AI 게임 턴 처리 흐름

Game Event
      │
      ▼
┌──────────────┐   Event   ┌───────────────────┐
│ EventListener│ ────────► │ AiGameFlowService │
└──────────────┘           └─────────┬─────────┘
                                     │ @Async("matchingTaskExecutor")
                                     ▼
                           ┌─────────────────────────┐
                           │  matchingTaskExecutor   │ (Same pool)
                           │                         │
                           │ ┌─────┐ ┌─────┐ ┌─────┐ │
                           │ │ T1  │ │ T2  │ │ ... │ │
                           │ └─────┘ └─────┘ └─────┘ │
                           └─────────────────────────┘
                                     │
                                     ▼
                           ┌─────────────────────────┐
                           │   AI Turn Processing    │
                           │  • AI API Call          │
                           │  • Response Processing  │
                           │  • WebSocket Message    │
                           └─────────────────────────┘

3. WebSocket Heartbeat 흐름

WebSocket Connection
         │
         ▼
┌─────────────────┐     ┌────────────────────┐
│ WebSocketConfig │────►│ SimpleBroker       │
└─────────────────┘     └─────────┬──────────┘
                                  │ setTaskScheduler(stompTaskScheduler)
                                  ▼
                        ┌─────────────────────────┐
                        │   stompTaskScheduler    │
                        │                         │
                        │ ┌─────┐ ┌─────┐         │
                        │ │ HB1 │ │ HB2 │         │
                        │ └─────┘ └─────┘         │
                        │                         │
                        │ Heartbeat: 30s interval │
                        └─────────────────────────┘
                                  │
                                  ▼
                        ┌─────────────────────────┐
                        │  Client ←→ Server       │
                        │   Heartbeat Messages    │
                        └─────────────────────────┘

스레드풀 분리 전략

핵심 아이디어: "관심사 분리"

• 매칭 도메인: 사용자 매칭, AI 게임 처리 → 비즈니스 로직 중심
• 인프라 레이어: WebSocket 연결 유지 → 기술적 요구사항 중심

도메인별 격리

┌─────────────────────────────────────────────────────────────┐
│                     Thread Pool 분리 전략                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐  │
│  │   Matching      │  │   WebSocket     │  │   Future    │  │
│  │   Domain        │  │   Infrastructure│  │  Extension  │  │
│  │                 │  │                 │  │             │  │
│  │ matchingTask    │  │ stompTask       │  │ aiChatTask  │  │
│  │ Executor        │  │ Scheduler       │  │ Executor    │  │
│  │                 │  │                 │  │ (Planned)   │  │
│  │ • 매칭 처리      │  │ • Heartbeat     │  │ • AI 채팅    │  │
│  │ • AI 게임 턴     │  │ • Connection    │  │ • 응답 생성  │  │
│  │                 │  │   Management    │  │             │  │
│  └─────────────────┘  └─────────────────┘  └─────────────┘  │
│                                                             │
│  장점:                                                       │
│  • 도메인별 성능 최적화                                        │
│  • 장애 격리                                                │
│  • 독립적 모니터링                                           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

설정 관리 구조

설정의 흐름: YAML → Properties → Bean 생성

스프링의 @ConfigurationProperties를 활용해 타입 안전한 설정 관리를 구현했습니다.

Configuration 계층

application.yml
      │
      ▼
┌─────────────────────────────────────────────┐
│          MatchingProperties                 │
│                                             │
│ @ConfigurationProperties                    │
│ (prefix = "app.matching")                   │
│                                             │
│ ┌─────────────────────────────────────────┐ │
│ │        ThreadPool                       │ │
│ │                                         │ │
│ │ • corePoolSize: 2                      │ │
│ │ • maxPoolSize: 10                      │ │
│ │ • queueCapacity: 50                    │ │
│ │ • keepAliveSeconds: 60                 │ │
│ └─────────────────────────────────────────┘ │
└──────────────┬──────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────┐
│        MatchingAsyncConfig                  │
│                                             │
│ @Configuration                              │
│ @EnableAsync                                │
│                                             │
│ ┌─────────────────────────────────────────┐ │
│ │   @Bean("matchingTaskExecutor")         │ │
│ │                                         │ │
│ │   ThreadPoolTaskExecutor 생성           │ │
│ │   • Properties 값 주입                  │ │
│ │   • RejectedExecutionHandler 설정       │ │
│ │   • 로깅 및 초기화                       │ │
│ └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

성능 특성 및 튜닝 포인트

🎯 설정값 쉽게 이해하기 (음식점 비유)

현재 설정값의 근거

🏪 던전톡 매칭 전용 주방:

👨‍🍳👨‍🍳 기본 요리사 2명 (Core Pool Size = 2)
→ "평상시에는 이 정도면 충분해!"

👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳 최대 10명 (Max Pool Size = 10)  
→ "점심시간처럼 바쁠 때는 임시 직원까지 동원!"

📋📋📋📋📋...(50개) 주문 대기판 (Queue Capacity = 50)
→ "주문이 몰려도 50개까지는 대기 가능!"

🚨 주방이 가득 찬다면? (RejectedExecutionHandler)
→ "사장님이 직접 요리하기!" (메인 스레드에서 처리)

왜 이 숫자들을 선택했을까요?

• Core 2개: 매칭은 보통 몇 초 내 처리. CPU 과부하 방지
• Max 10개: 서버 메모리를 너무 많이 쓰면 안 되니까!
• Queue 50개: 동시접속자 급증해도 버틸 수 있게
• Fallback: 절대 매칭 요청을 버리지 않겠다는 의지!

스레드풀 크기 결정 기준

┌─────────────────────────────────────────────────────────────────┐
│                     튜닝 매트릭스                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ Core Threads (2) ←────┐                                         │
│                       │                                         │
│ • CPU 집약적 작업 고려  │    ┌─── Queue Capacity (50)           │
│ • 기본 처리량 확보     │    │                                   │
│                       │    │   • 버스트 트래픽 대응             │
│                       ▼    ▼   • 메모리 사용량 제한             │
│                                                                 │
│            ┌─────────────────────────────┐                      │
│            │    Thread Pool Behavior     │                      │
│            │                             │                      │
│            │ Low Load:  Core만 활성       │                      │
│            │ Med Load:  Queue 활용        │                      │
│            │ High Load: Max까지 확장      │                      │
│            │ Overflow:  Main Thread      │                      │
│            └─────────────────────────────┘                      │
│                       │    ▲                                    │
│                       │    │                                    │
│                       ▼    └─── Max Threads (10)               │
│                                                                 │
│ Keep Alive (60s) ────────────────┐                             │
│                                  │                             │
│ • 유휴 스레드 정리               │                             │
│ • 메모리 효율성                   │                             │
│                                  ▼                             │
└─────────────────────────────────────────────────────────────────┘

모니터링 포인트

현재 구현된 모니터링

• 초기화 로그: 스레드풀 설정값 확인
• 거부 로그: 스레드풀 포화 상태 감지
• 스레드 이름: 로그에서 어느 풀의 스레드인지 식별 가능

로그 기반 모니터링

Application Startup
         │
         ▼
┌─────────────────────────────────────────┐
│ "매칭 전용 스레드 풀 초기화 완료:         │
│  core=2, max=10, queue=50"             │
└─────────────────────────────────────────┘
         │
         ▼ (Runtime)
┌─────────────────────────────────────────┐
│ "매칭 처리 스레드 풀이 가득 참.          │
│  요청 거부됨"                           │
└─────────────────────────────────────────┘
         │
         ▼ (메트릭 수집 가능 지점)
┌─────────────────────────────────────────┐
│ • Active Thread Count                   │
│ • Queue Size                           │
│ • Completed Task Count                 │
│ • Rejected Task Count                  │
└─────────────────────────────────────────┘

TRPG 게임 백엔드를 개발하면서 매번 기능을 추가할 때마다 이런 생각이 들었습니다.

"이 코드 바꿔도 다른 기능 안 망가질까?"
"MongoDB 연동이 제대로 되는지 어떻게 확인하지?"
"서비스 로직이 복잡해지는데 테스트는 어떻게 하지?"

그래서 테스트 코드를 시작하기로 했습니다. 하지만 막상 시작하려니...

어디서부터 시작해야 할지 모르겠더라고요.

테스트 전략: DTO → Repository → Service

초보자인 저는 간단한 것부터 시작하기로 했습니다.

1단계: DTO 테스트 (워밍업)

@Test
@DisplayName("Builder로 객체 생성 테스트")
void builderCreatesObject() {
    // given
    String memberId = "user-12345";
    WorldType worldType = WorldType.FANTASY;

    // when
    AiServiceRequest result = AiServiceRequest.builder()
            .memberId(memberId)
            .worldType(worldType)
            .build();

    // then
    assertThat(result).isNotNull();
    assertThat(result.getMemberId()).isEqualTo(memberId);
    assertThat(result.getWorldType()).isEqualTo(worldType);
}

@Test
@DisplayName("JSON 직렬화/역직렬화 테스트")
void serializeToJson() throws Exception {
    // given
    AiServiceRequest request = AiServiceRequest.builder()
            .memberId("test-user")
            .worldType(WorldType.FANTASY)
            .build();

    // when
    String json = objectMapper.writeValueAsString(request);
    AiServiceRequest result = objectMapper.readValue(json, AiServiceRequest.class);

    // then
    assertThat(json).contains("\"memberId\":\"test-user\"");
    assertThat(result.getMemberId()).isEqualTo("test-user");
}

왜 DTO부터했을까?

• 로직이 단순해서 실패할 확률이 낮음
• JSON 직렬화/역직렬화 확인 가능
• 테스트 작성 패턴에 익숙해질 수 있음
• given-when-then 패턴 연습하기 좋음
• 제일 중요한 것은 ai 테스트 코드에 대해 설명해줘 했는데 dto를 제일 먼저 알려주었다..

2단계: Repository 테스트 (TestContainers와의 첫 만남)

진짜 도전은 Repository 테스트였습니다. Mock vs 실제 DB를 놓고 고민했는데...

"MongoDB 연동이 제대로 되는지 확인하려면 실제 DB를 써야겠다!"

그래서 TestContainers를 선택했습니다. 실제로 켜진 모습도 확인이 가능합니다

@Testcontainers
@DataMongoTest
@ActiveProfiles("test")
class AiGameMessageRepositoryTest {

    @Container
    static MongoDBContainer mongo = new MongoDBContainer("mongo:7.0");

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.data.mongodb.uri", mongo::getReplicaSetUrl);
    }

    @Autowired
    AiGameMessageRepository repository;

    @Test
    @DisplayName("메시지 저장 후 조회 테스트")
    void saveAndFindMessage() {
        // given
        AiGameMessage message = AiGameMessage.builder()
                .aiGameRoomId("room-123")
                .content("테스트 메시지")
                .messageType(AiMessageType.USER)
                .turnNumber(1)
                .messageOrder(1)
                .createdAt(Instant.now())
                .build();

        // when
        AiGameMessage saved = repository.save(message);
        Optional<AiGameMessage> found = repository.findById(saved.getId());

        // then
        assertThat(found).isPresent();
        assertThat(found.get().getContent()).isEqualTo("테스트 메시지");
        assertThat(found.get().getMessageType()).isEqualTo(AiMessageType.USER);
    }

    @Test
    @DisplayName("룸별 메시지 조회 테스트")
    void findByAiGameRoomIdOrderByCreatedAt() {
        // given
        String roomId = "room-456";

        AiGameMessage message1 = createTestMessage(roomId, "첫 번째 메시지", 1);
        AiGameMessage message2 = createTestMessage(roomId, "두 번째 메시지", 2);

        repository.saveAll(List.of(message1, message2));

        // when
        List<AiGameMessage> messages = repository.findByAiGameRoomIdOrderByCreatedAt(roomId);

        // then
        assertThat(messages).hasSize(2);
        assertThat(messages.get(0).getContent()).isEqualTo("첫 번째 메시지");
        assertThat(messages.get(1).getContent()).isEqualTo("두 번째 메시지");
    }
}

TestContainers의 장점:

• ✅ 실제 MongoDB 환경에서 테스트
• ✅ 로컬 DB 설정 불필요
• ✅ CI/CD에서도 동일한 환경 보장
• ✅ 실제 DB 쿼리 동작 확인 가능

삽질했던 부분:

• ❌ MongoDB 인증 설정 때문에 한참 헤맸음
• ❌ @DynamicPropertySource 없이 했다가 connection 실패
• ❌ 컨테이너 시작 시간 때문에 테스트가 느려짐
• ❌ TestContainers 버전 호환성 문제

3단계: Service 테스트 (Mockito의 위력)

Service 테스트는 다른 접근이 필요했습니다. 모든 의존성을 실제로 띄우기엔 너무 무거워서 Mock을 사용했습니다.

@ExtendWith(MockitoExtension.class)
class AiGameMessageServiceTest {

    @Mock
    AiGameMessageRepository aiGameMessageRepository;

    @Mock
    RedisPublisher redisPublisher;

    @Mock
    ProfanityFilterService profanityFilterService;

    @Mock
    AiGameValidator aiGameValidator;

    @InjectMocks
    AiGameMessageService aiGameMessageService;

    @Test
    @DisplayName("AI 메시지 저장 성공 테스트")
    void saveAiMessage_success() {
        // given
        AiMessageSaveRequest request = AiMessageSaveRequest.builder()
                .aiGameRoomId("room-123")
                .gameId("game-456")
                .content("AI 응답 메시지")
                .turnNumber(1)
                .build();

        // Mock: getNextMessageOrder 결과
        given(aiGameMessageRepository.findMaxMessageOrderByTurn("room-123", 1))
                .willReturn(Collections.emptyList());

        // Mock: 저장된 메시지 반환
        AiGameMessage savedMessage = AiGameMessage.builder()
                .id("saved-id")
                .aiGameRoomId("room-123")
                .gameId("game-456")
                .content("AI 응답 메시지")
                .messageType(AiMessageType.AI)
                .turnNumber(1)
                .messageOrder(1)
                .createdAt(Instant.now())
                .build();

        given(aiGameMessageRepository.save(any(AiGameMessage.class)))
                .willReturn(savedMessage);

        // when
        AiGameMessageDto result = aiGameMessageService.saveAiMessage(request);

        // then
        assertThat(result).isNotNull();
        assertThat(result.getContent()).isEqualTo("AI 응답 메시지");
        assertThat(result.getMessageType()).isEqualTo(AiMessageType.AI);
        assertThat(result.getTurnNumber()).isEqualTo(1);

        // Mock 호출 검증
        then(aiGameValidator).should().validateGameRoom("room-123");
        then(aiGameMessageRepository).should().save(any(AiGameMessage.class));
    }

    @Test
    @DisplayName("메시지 순서 계산 테스트")
    void messageOrder_test() {
        // given - 첫 번째 메시지인 경우
        AiMessageSaveRequest request = AiMessageSaveRequest.builder()
                .aiGameRoomId("room-123")
                .content("첫 번째 메시지")
                .turnNumber(1)
                .build();

        // Mock: 기존 메시지가 없는 경우
        given(aiGameMessageRepository.findMaxMessageOrderByTurn("room-123", 1))
                .willReturn(Collections.emptyList());

        AiGameMessage savedMessage = AiGameMessage.builder()
                .id("saved-id")
                .messageOrder(1) // 첫 번째 메시지이므로 1
                .turnNumber(1)
                .content("첫 번째 메시지")
                .messageType(AiMessageType.AI)
                .createdAt(Instant.now())
                .build();

        given(aiGameMessageRepository.save(any(AiGameMessage.class)))
                .willReturn(savedMessage);

        // when
        AiGameMessageDto result = aiGameMessageService.saveAiMessage(request);

        // then
        assertThat(result.getMessageOrder()).isEqualTo(1);
        then(aiGameMessageRepository).should().findMaxMessageOrderByTurn("room-123", 1);
    }
}

🚧 삽질 경험담 (진짜 겪은 일들)

1. MongoDB 인증 문제

# 이렇게 설정했다가 계속 실패
spring.data.mongodb.username=${SPRING_DATA_MONGODB_USERNAME}
spring.data.mongodb.password=${SPRING_DATA_MONGODB_PASSWORD}

# 이렇게 주석 처리해서 해결
#spring.data.mongodb.username=${SPRING_DATA_MONGODB_USERNAME}
#spring.data.mongodb.password=${SPRING_DATA_MONGODB_PASSWORD}

교훈: 로컬 환경과 테스트 환경 설정을 다르게 가져가자!

2. Mockito UnnecessaryStubbingException

// 🚫 이렇게 하면 에러 발생
@BeforeEach
void setUp() {
    given(mockService.someMethod()).willReturn(value); // 사용되지 않음
}

// ✅ 해결: 실제 사용되는 테스트에서만 Mock 설정
@Test
void testMethod() {
    given(mockService.someMethod()).willReturn(value); // 실제 사용됨
    // ... 테스트 로직
}

3. 필드명 틀린 실수

// 🚫 테스트에서는 이렇게 호출했는데
assertThat(result.getQueuePosition()).isEqualTo(6); 

// 🚫 실제로는 이런 메서드명이었음
public int getCurrentPosition() { ... }

// ✅ 해결
assertThat(result.getCurrentPosition()).isEqualTo(6);

교훈: IDE의 자동완성을 믿자! 타이핑하지 말고 자동완성 쓰자.

4. NullPointerException 지옥

// 🚫 이렇게 하면 NPE 발생
@Mock
SomeService someService; // Mock 생성만 하고

@Test
void test() {
    // Mock 설정 없이 바로 사용
    service.doSomething(); // NPE 발생!
}

// ✅ 해결: 필요한 모든 Mock 설정
@Test
void test() {
    given(someService.method()).willReturn(value);
    given(anotherService.method()).willReturn(value);
    // 모든 의존성 Mock 설정 후 테스트
}

🎯 도메인별 테스트 전략

AiChat 도메인: 실제 DB 중심

// Repository: TestContainers로 실제 MongoDB 테스트
@Testcontainers
@DataMongoTest
class AiGameMessageRepositoryTest { ... }

// Service: Mockito로 비즈니스 로직만 집중
@ExtendWith(MockitoExtension.class)
class AiGameMessageServiceTest { ... }

선택 이유: 시간 필드 변경(LocalDateTime → Instant) 등 데이터 정합성이 중요

Matching 도메인: Mock 중심

// QueueManager: Redis Mock으로 큐 로직 테스트
@Mock StringRedisTemplate redisTemplate;
@Mock ListOperations<String, String> listOperations;

// Service: WebSocket, Redis 등 외부 의존성 많음
@Mock MatchingQueueManager queueManager;
@Mock MatchingWebSocketService webSocketService;

선택 이유: 비즈니스 로직보다는 연동 로직이 중심

Room 도메인: Factory 패턴 테스트

// Factory: 실제 구현체들로 패턴 동작 확인
@Test
void getService_ai_success() {
    given(aiRoomService.getSupportedRoomType()).willReturn(RoomType.AI_GAME);

    RoomServiceFactory factory = new RoomServiceFactory(roomServices);
    RoomService result = factory.getService(RoomType.AI_GAME);

    assertThat(result).isEqualTo(aiRoomService);
}

선택 이유: 패턴 자체의 동작이 중요

💡 초보자를 위한 실전 팁

1. 테스트 작성 순서

DTO → Repository → Service → Controller

• DTO: 가장 간단, 실패할 확률 낮음
• Repository: 실제 DB 연동 확인
• Service: 비즈니스 로직 검증
• Controller: API 전체 흐름 테스트

2. TestContainers vs Mock 선택 기준

3. Mock 설정 꿀팁

// ✅ 좋은 예: 테스트별로 필요한 Mock만 설정
@Test
void specificTest() {
    // 이 테스트에 필요한 Mock만 설정
    given(mockA.method()).willReturn(value);

    // 테스트 실행
    // 검증
}

// ✅ 공통 Mock은 @BeforeEach에서
@BeforeEach
void setUp() {
    // 모든 테스트에서 공통으로 사용하는 Mock
    given(commonMock.method()).willReturn(commonValue);
}

4. 테스트 실패시 디버깅 체크리스트

1. 에러 메시지 꼼꼼히 읽기

   • NullPointerException → Mock 설정 확인
   • AssertionError → 예상값과 실제값 비교

2. Mock 설정 확인

   • given() 설정이 실제 호출과 일치하는지
   • 모든 필요한 의존성이 Mock되었는지

3. 메서드명 확인

   • 테스트의 메서드명과 실제 메서드명 일치 확인
   • IDE 자동완성 활용하기

4. given-when-then 순서 점검

   • given: 조건 설정이 완료되었는지
   • when: 실제 동작이 올바른지
   • then: 검증 로직이 정확한지

5. 테스트 데이터 관리

// ✅ 테스트 데이터 생성 메서드 활용
private AiGameMessage createTestMessage(String roomId, String content, int order) {
    return AiGameMessage.builder()
            .aiGameRoomId(roomId)
            .content(content)
            .messageOrder(order)
            .messageType(AiMessageType.USER)
            .createdAt(Instant.now())
            .build();
}

// ✅ 상수로 테스트 데이터 관리
private static final String TEST_ROOM_ID = "test-room-123";
private static final String TEST_USER_ID = "test-user-456";

테스트 코드 작성 후 느낀 점

좋은 점

1. 리팩토링 두려움 해소

   // LocalDateTime → Instant 변경도 안심하고 진행
   private LocalDateTime createdAt; // Before
   private Instant createdAt;       // After

   테스트가 있으니까 변경해도 바로 확인 가능!

2. 버그 발견 속도 향상

   // 필드명 틀린 것도 테스트에서 먼저 발견
   assertThat(result.getQueuePosition()).isEqualTo(6); // 컴파일 에러로 바로 발견!

3. 코드 이해도 증가

   • 테스트 작성하면서 기존 코드 흐름 파악
   • "이 메서드가 뭘 하는 거지?"에서 "이 메서드는 이렇게 동작하는구나!"

4. 자신감 향상

   • 기능 추가할 때 "혹시 뭔가 깨지지 않을까?" → "테스트 돌려보면 되지!"

아쉬운 점

1. 초기 설정 시간

   • TestContainers, Mock 설정 러닝커브
   • 처음엔 테스트 작성이 기능 구현보다 오래 걸림

2. 테스트 유지보수

   • 기능 변경시 테스트도 함께 수정 필요
   • 하지만 이것도 코드 품질 향상에 도움

3. 완벽한 테스트의 부담

   • "모든 케이스를 다 테스트해야 하나?" 하는 강박
   • → 중요한 것부터 차근차근하면 됨!

실제 테스트 실행 결과

> Task :test

AiServiceRequestTest > Builder로 객체 생성 테스트 PASSED
AiServiceRequestTest > JSON 직렬화 테스트 PASSED
AiServiceRequestTest > JSON 역직렬화 테스트 PASSED

AiGameMessageRepositoryTest > 메시지 저장 후 조회 테스트 PASSED
AiGameMessageRepositoryTest > 룸별 메시지 조회 테스트 PASSED
AiGameMessageRepositoryTest > 턴별 최대 메시지 순서 조회 테스트 PASSED

AiGameMessageServiceTest > AI 메시지 저장 성공 테스트 PASSED
AiGameMessageServiceTest > 메시지 순서 계산 테스트 PASSED

MatchingQueueManagerTest > 큐에 사용자 추가 성공 테스트 PASSED
MatchingQueueManagerTest > 큐에서 사용자 제거 성공 테스트 PASSED
MatchingQueueManagerTest > 큐 크기 조회 테스트 PASSED

MatchingServiceTest > 매칭 참가 성공 테스트 PASSED
MatchingServiceTest > 매칭 취소 성공 테스트 PASSED

RoomServiceFactoryTest > AI 룸 서비스 조회 성공 테스트 PASSED
RoomServiceFactoryTest > null 입력시 예외 발생 테스트 PASSED

BUILD SUCCESSFUL in 8s

18개 테스트 모두 통과!

다음 목표

1. Controller 테스트 도전

@WebMvcTest(AiGameRoomController.class)
class AiGameRoomControllerTest {

    @Autowired
    MockMvc mockMvc;

    @MockBean
    AiGameRoomService aiGameRoomService;

    @Test
    void createRoom_success() throws Exception {
        // MockMvc로 API 테스트
        mockMvc.perform(post("/api/ai/rooms")
                .contentType(MediaType.APPLICATION_JSON)
                .content(requestJson))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.roomName").value("테스트 룸"));
    }
}

2. 통합 테스트 시도

@SpringBootTest
@Testcontainers
class AiGameIntegrationTest {
    // 전체 애플리케이션 컨텍스트로 테스트
}

3. 테스트 커버리지 측정

// build.gradle에 JaCoCo 플러그인 추가
plugins {
    id 'jacoco'
}

jacoco {
    toolVersion = "0.8.8"
}

4. 주사위 기능 TDD로 개발

// 테스트 먼저 작성
@Test
void rollDice_d20_returnsRandomValue() {
    // given
    DiceType diceType = DiceType.D20;

    // when
    DiceResult result = diceService.roll(diceType);

    // then
    assertThat(result.getValue()).isBetween(1, 20);
}

// 그 다음 구현
public class DiceService {
    public DiceResult roll(DiceType diceType) {
        // 구현
    }
}

마무리

테스트 코드 초보자였던 제가 3개 도메인 테스트를 완주하면서 배운 가장 중요한 것:

완벽하지 않아도 시작하자!

DTO 테스트 하나부터 시작해서 점점 늘려가다 보니 어느새 Repository, Service 테스트까지 작성하게 되었습니다.

테스트 코드를 망설이고 있는 분들께

• "테스트 코드 어려울 것 같아" → DTO 테스트부터 시작해보세요
• "설정이 복잡할 것 같아" → @Test 하나부터 만들어보세요
• "시간이 오래 걸릴 것 같아" → 하루에 테스트 하나씩만 추가해보세요
• "뭘 테스트해야 할지 모르겠어" → 가장 자주 사용하는 메서드부터

테스트 코드의 진짜 가치

테스트 코드를 작성하면서 깨달은 것은 버그 방지보다도 개발자의 자신감이 가장 큰 수확이었습니다.

• "이 코드 바꿔도 될까?" → "테스트 돌려보면 알 수 있지!"
• "리팩토링하고 싶은데 무서워" → "테스트가 있으니까 안심하고 해보자!"
• "이 기능이 제대로 동작할까?" → "테스트로 확인했으니까 괜찮아!"

실제 프로젝트: GitHub - DungeonTalk Backend
테스트 코드 위치: src/test/java/org/com/dungeontalk/domain/

참고 자료

• Spring Boot Testing Guide
• TestContainers Documentation
• Mockito Documentation
• AssertJ Documentation

이 글이 테스트 코드 작성을 망설이고 있는 분들에게 도움이 되었으면 좋겠습니다! 궁금한 점이 있으시면 댓글로 언제든 물어보세요! 🙋‍♂️

DungeonTalk 실시간 매칭에서 Race Condition을 완벽히 해결한 Redis + Lua 스크립트 활용법

들어가며

실시간 게임 매칭 시스템을 구축할 때 가장 까다로운 부분 중 하나가 동시성 제어입니다. 여러 사용자가 동시에 매칭 큐에 참여하고, 적절한 인원이 모이면 즉시 게임을 시작해야 하는데, 이 과정에서 Race Condition이 발생하기 쉽습니다.

DungeonTalk에서는 Redis List를 활용한 큐 시스템에 Lua 스크립트를 도입해 이 문제를 완벽히 해결했습니다. 이번 포스팅에서는 그 과정과 노하우를 상세히 공유합니다.

문제 상황: Java 코드만으론 한계가 있었다

기존 매칭 로직의 문제점

처음에는 Java에서 Redis 명령어를 여러 번 호출하는 방식으로 구현했습니다:

// 💥 문제가 있는 기존 코드
@Service
public class MatchingQueueManager {

    @Autowired
    private RedisTemplate<String, String> redisTemplate;

    public List<String> extractUsersForMatching(String queueKey) {
        // 1️⃣ 큐 크기 확인
        Long queueSize = redisTemplate.opsForList().size(queueKey);

        if (queueSize < 3) {
            return Collections.emptyList();
        }

        // 2️⃣ 사용자 3명 추출
        List<String> matchedUsers = new ArrayList<>();
        for (int i = 0; i < 3; i++) {
            String user = redisTemplate.opsForList().rightPop(queueKey);
            if (user != null) {
                matchedUsers.add(user);
            }
        }

        return matchedUsers;
    }
}

발생한 문제들

1. Race Condition 발생

# 동시에 2개 스레드가 실행될 때
Thread-1: LLEN queue:world1 → 4명 (3명 이상이므로 매칭 진행)
Thread-2: LLEN queue:world1 → 4명 (3명 이상이므로 매칭 진행)
Thread-1: RPOP queue:world1 → user1
Thread-2: RPOP queue:world1 → user2  
Thread-1: RPOP queue:world1 → user3
Thread-2: RPOP queue:world1 → user4
Thread-1: RPOP queue:world1 → null (큐 빔!)
Thread-2: RPOP queue:world1 → null (큐 빔!)

# 결과: Thread-1은 [user1, user3, null], Thread-2는 [user2, user4, null]
# 💥 둘 다 3명이 모이지 않아서 매칭 실패!

2. 네트워크 지연으로 인한 성능 저하

• Redis 명령어를 4번 개별 호출 → 네트워크 왕복 4회
• 평균 매칭 시간: 3-5초

3. 부분 실패 시 데이터 정합성 문제

• 일부 사용자만 큐에서 제거되고 매칭은 실패하는 경우 발생

해결책: Lua 스크립트로 원자성 보장

Lua 스크립트를 선택한 이유

Redis + Lua의 핵심 장점:

• 원자성(Atomicity): 스크립트 전체가 하나의 트랜잭션으로 실행
• 성능: 네트워크 왕복 1회만 필요
• 일관성: 중간에 다른 명령어가 끼어들 수 없음

핵심 Lua 스크립트 구현

-- extractUsers.lua
-- 매칭 큐에서 정확히 3명을 원자적으로 추출하는 스크립트

local queueKey = KEYS[1]           -- 큐 키 (예: "queue:world1")
local requiredCount = tonumber(ARGV[1]) or 3  -- 필요한 인원수 (기본값: 3)

-- 🔍 현재 큐 크기 확인
local queueSize = redis.call('LLEN', queueKey)

-- ⚠️ 인원이 부족하면 즉시 종료
if queueSize < requiredCount then
    return {
        success = false,
        message = "인원 부족",
        currentCount = queueSize,
        requiredCount = requiredCount
    }
end

-- ✅ 필요한 인원만큼 사용자 추출
local extractedUsers = {}
for i = 1, requiredCount do
    local user = redis.call('RPOP', queueKey)
    if user then
        table.insert(extractedUsers, user)
    else
        -- 이론적으로는 발생할 수 없지만 안전장치
        return {
            success = false,
            message = "추출 중 오류 발생",
            extractedUsers = extractedUsers
        }
    end
end

-- 📊 추출 후 상태 정보
local remainingCount = redis.call('LLEN', queueKey)

return {
    success = true,
    extractedUsers = extractedUsers,
    remainingCount = remainingCount,
    timestamp = redis.call('TIME')[1]  -- Unix timestamp
}

대기열 추가를 위한 Lua 스크립트

-- addToQueue.lua  
-- 중복 방지와 함께 사용자를 큐에 안전하게 추가

local queueKey = KEYS[1]        -- 큐 키
local userDataKey = KEYS[2]     -- 사용자 데이터 키 (Hash)
local userId = ARGV[1]          -- 사용자 ID
local userData = ARGV[2]        -- 사용자 데이터 (JSON)
local ttlSeconds = tonumber(ARGV[3]) or 3600  -- TTL (기본값: 1시간)

-- 🔍 이미 큐에 있는지 확인 (중복 방지)
local existingPosition = redis.call('LPOS', queueKey, userId)
if existingPosition then
    return {
        success = false,
        message = "이미 큐에 대기 중입니다",
        position = existingPosition + 1,  -- 1부터 시작하는 위치
        queueSize = redis.call('LLEN', queueKey)
    }
end

-- ➕ 큐에 사용자 추가 (FIFO를 위해 LPUSH 사용)
redis.call('LPUSH', queueKey, userId)

-- 💾 사용자 데이터 저장 (매칭 시 필요한 정보)
redis.call('HSET', userDataKey, userId, userData)

-- ⏰ TTL 설정 (메모리 누수 방지)
redis.call('EXPIRE', queueKey, ttlSeconds)
redis.call('EXPIRE', userDataKey, ttlSeconds)

-- 📊 현재 상태 반환
local currentPosition = redis.call('LLEN', queueKey)
local queueSize = currentPosition

return {
    success = true,
    message = "큐에 추가되었습니다",
    position = currentPosition,
    queueSize = queueSize,
    estimatedWaitTime = math.ceil(queueSize / 3) * 30  -- 추정 대기 시간 (초)
}

큐에서 제거를 위한 Lua 스크립트

-- removeFromQueue.lua
-- 사용자가 매칭 취소 시 큐에서 안전하게 제거

local queueKey = KEYS[1]
local userDataKey = KEYS[2]  
local userId = ARGV[1]

-- 🔍 큐에서 사용자 찾기
local position = redis.call('LPOS', queueKey, userId)
if not position then
    return {
        success = false,
        message = "큐에서 찾을 수 없습니다"
    }
end

-- ➖ 큐에서 제거 (LREM: 값으로 제거)
local removedCount = redis.call('LREM', queueKey, 1, userId)

-- 🗑️ 사용자 데이터도 제거
redis.call('HDEL', userDataKey, userId)

-- 📊 제거 후 상태
local remainingSize = redis.call('LLEN', queueKey)

return {
    success = removedCount > 0,
    message = removedCount > 0 and "큐에서 제거되었습니다" or "제거 실패",
    previousPosition = position + 1,
    remainingQueueSize = remainingSize
}

Java에서 Lua 스크립트 실행

RedisScript 빈 설정

@Configuration
public class RedisScriptConfig {

    /**
     * 사용자 추출 스크립트 빈
     */
    @Bean
    public RedisScript<Map> extractUsersScript() {
        DefaultRedisScript<Map> script = new DefaultRedisScript<>();
        script.setScriptSource(new ResourceScriptSource(
            new ClassPathResource("lua/extractUsers.lua")
        ));
        script.setResultType(Map.class);
        return script;
    }

    /**
     * 큐 추가 스크립트 빈  
     */
    @Bean
    public RedisScript<Map> addToQueueScript() {
        DefaultRedisScript<Map> script = new DefaultRedisScript<>();
        script.setScriptSource(new ResourceScriptSource(
            new ClassPathResource("lua/addToQueue.lua")
        ));
        script.setResultType(Map.class);
        return script;
    }

    /**
     * 큐 제거 스크립트 빈
     */
    @Bean
    public RedisScript<Map> removeFromQueueScript() {
        DefaultRedisScript<Map> script = new DefaultRedisScript<>();
        script.setScriptSource(new ResourceScriptSource(
            new ClassPathResource("lua/removeFromQueue.lua")
        ));
        script.setResultType(Map.class);
        return script;
    }
}

매칭 큐 매니저 서비스

@Service
@Slf4j
public class MatchingQueueManager {

    private final RedisTemplate<String, String> redisTemplate;
    private final RedisScript<Map> extractUsersScript;
    private final RedisScript<Map> addToQueueScript;
    private final RedisScript<Map> removeFromQueueScript;

    private static final String QUEUE_KEY_PREFIX = "queue:";
    private static final String USER_DATA_KEY_PREFIX = "queue_data:";

    public MatchingQueueManager(RedisTemplate<String, String> redisTemplate,
                               RedisScript<Map> extractUsersScript,
                               RedisScript<Map> addToQueueScript,
                               RedisScript<Map> removeFromQueueScript) {
        this.redisTemplate = redisTemplate;
        this.extractUsersScript = extractUsersScript;
        this.addToQueueScript = addToQueueScript;
        this.removeFromQueueScript = removeFromQueueScript;
    }

    /**
     * 매칭을 위한 사용자 추출 (원자적)
     */
    public MatchingResult extractUsersForMatching(WorldType worldType, int requiredCount) {
        String queueKey = QUEUE_KEY_PREFIX + worldType.name().toLowerCase();

        try {
            // 🚀 Lua 스크립트 실행 (원자적)
            Map<String, Object> result = redisTemplate.execute(
                extractUsersScript,
                Collections.singletonList(queueKey),
                String.valueOf(requiredCount)
            );

            return parseMatchingResult(result, worldType);

        } catch (Exception e) {
            log.error("매칭 추출 중 오류 발생: worldType={}, requiredCount={}", 
                     worldType, requiredCount, e);
            return MatchingResult.failure("매칭 처리 중 오류 발생");
        }
    }

    /**
     * 큐에 사용자 추가
     */
    public QueueAddResult addToQueue(MatchingRequest request) {
        String queueKey = QUEUE_KEY_PREFIX + request.getWorldType().name().toLowerCase();
        String userDataKey = USER_DATA_KEY_PREFIX + request.getWorldType().name().toLowerCase();

        try {
            // 📝 사용자 데이터를 JSON으로 직렬화
            String userData = objectMapper.writeValueAsString(request);

            // 🚀 Lua 스크립트 실행
            Map<String, Object> result = redisTemplate.execute(
                addToQueueScript,
                Arrays.asList(queueKey, userDataKey),
                request.getMemberId(),
                userData,
                "3600"  // 1시간 TTL
            );

            return parseQueueAddResult(result);

        } catch (Exception e) {
            log.error("큐 추가 중 오류 발생: memberId={}, worldType={}", 
                     request.getMemberId(), request.getWorldType(), e);
            return QueueAddResult.failure("큐 추가 중 오류 발생");
        }
    }

    /**
     * 큐에서 사용자 제거
     */
    public QueueRemoveResult removeFromQueue(String memberId, WorldType worldType) {
        String queueKey = QUEUE_KEY_PREFIX + worldType.name().toLowerCase();
        String userDataKey = USER_DATA_KEY_PREFIX + worldType.name().toLowerCase();

        try {
            // 🚀 Lua 스크립트 실행
            Map<String, Object> result = redisTemplate.execute(
                removeFromQueueScript,
                Arrays.asList(queueKey, userDataKey),
                memberId
            );

            return parseQueueRemoveResult(result);

        } catch (Exception e) {
            log.error("큐 제거 중 오류 발생: memberId={}, worldType={}", 
                     memberId, worldType, e);
            return QueueRemoveResult.failure("큐 제거 중 오류 발생");
        }
    }

    // === 결과 파싱 메서드들 ===

    private MatchingResult parseMatchingResult(Map<String, Object> result, WorldType worldType) {
        Boolean success = (Boolean) result.get("success");

        if (!success) {
            String message = (String) result.get("message");
            Integer currentCount = (Integer) result.get("currentCount");
            Integer requiredCount = (Integer) result.get("requiredCount");

            log.info("매칭 실패: worldType={}, 현재={}, 필요={}, 사유={}", 
                    worldType, currentCount, requiredCount, message);

            return MatchingResult.waiting(currentCount, requiredCount, message);
        }

        // 성공한 경우
        List<String> extractedUsers = (List<String>) result.get("extractedUsers");
        Integer remainingCount = (Integer) result.get("remainingCount");
        String timestamp = (String) result.get("timestamp");

        log.info("✅ 매칭 성공: worldType={}, 추출된사용자={}, 남은인원={}", 
                worldType, extractedUsers.size(), remainingCount);

        return MatchingResult.success(extractedUsers, remainingCount, timestamp);
    }

    private QueueAddResult parseQueueAddResult(Map<String, Object> result) {
        Boolean success = (Boolean) result.get("success");
        String message = (String) result.get("message");
        Integer position = (Integer) result.get("position");
        Integer queueSize = (Integer) result.get("queueSize");
        Integer estimatedWaitTime = (Integer) result.get("estimatedWaitTime");

        return QueueAddResult.builder()
                .success(success)
                .message(message)
                .position(position)
                .queueSize(queueSize)
                .estimatedWaitTime(estimatedWaitTime)
                .build();
    }

    private QueueRemoveResult parseQueueRemoveResult(Map<String, Object> result) {
        Boolean success = (Boolean) result.get("success");
        String message = (String) result.get("message");
        Integer remainingSize = (Integer) result.get("remainingQueueSize");

        return QueueRemoveResult.builder()
                .success(success)
                .message(message)
                .remainingQueueSize(remainingSize)
                .build();
    }
}

실제 매칭 프로세스 플로우

1. 사용자 큐 참여

@PostMapping("/matching/join")
public RsData<QueueAddResult> joinMatchingQueue(@Valid @RequestBody MatchingRequest request) {
    // 🔐 사용자 인증 확인
    String memberId = getCurrentMemberId();
    request.setMemberId(memberId);

    // ➕ 큐에 추가 (Lua 스크립트로 중복 확인 + 추가)
    QueueAddResult result = matchingQueueManager.addToQueue(request);

    if (result.isSuccess()) {
        // 📢 WebSocket으로 대기 상태 알림
        webSocketService.sendQueueStatusUpdate(memberId, result);

        log.info("큐 참여 성공: memberId={}, worldType={}, position={}", 
                memberId, request.getWorldType(), result.getPosition());
    }

    return RsData.of(result.isSuccess() ? "200" : "400", 
                    result.getMessage(), result);
}

2. 백그라운드 매칭 프로세서

@Component
@Slf4j
public class MatchingProcessor {

    private final MatchingQueueManager queueManager;
    private final GameSessionService gameSessionService;
    private final WebSocketService webSocketService;

    /**
     * 주기적으로 모든 월드 타입의 매칭 처리
     */
    @Scheduled(fixedDelay = 1000) // 1초마다 실행
    public void processMatching() {
        for (WorldType worldType : WorldType.values()) {
            try {
                processMatchingForWorld(worldType);
            } catch (Exception e) {
                log.error("매칭 처리 중 오류: worldType={}", worldType, e);
            }
        }
    }

    private void processMatchingForWorld(WorldType worldType) {
        // 🎯 3명 추출 시도 (Lua 스크립트로 원자적 처리)
        MatchingResult result = queueManager.extractUsersForMatching(worldType, 3);

        if (result.isSuccess()) {
            // ✅ 매칭 성공 → 게임 세션 생성
            List<String> participants = result.getExtractedUsers();

            log.info("🎮 매칭 성공: worldType={}, participants={}", worldType, participants);

            // 게임 세션 생성
            GameSession gameSession = gameSessionService.createGameSession(worldType, participants);

            // 📢 참여자들에게 매칭 완료 알림
            MatchingCompleteEvent event = MatchingCompleteEvent.builder()
                    .gameSessionId(gameSession.getId())
                    .worldType(worldType)
                    .participants(participants)
                    .roomIds(gameSession.getRoomIds())
                    .build();

            // WebSocket으로 각 참여자에게 알림
            participants.forEach(memberId -> {
                webSocketService.sendMatchingComplete(memberId, event);
            });

            // 📊 매칭 통계 업데이트
            matchingStatisticsService.recordSuccessfulMatch(worldType, participants.size());

        } else if (result.isWaiting()) {
            // ⏳ 대기 중 (인원 부족)
            log.debug("매칭 대기: worldType={}, 현재={}, 필요={}", 
                     worldType, result.getCurrentCount(), result.getRequiredCount());
        }
    }
}

3. 실시간 큐 상태 모니터링

@RestController
@RequestMapping("/v1/matching")
public class MatchingStatusController {

    private final MatchingQueueManager queueManager;

    /**
     * 특정 월드의 현재 큐 상태 조회
     */
    @GetMapping("/queue-status/{worldType}")
    public RsData<QueueStatusResponse> getQueueStatus(@PathVariable WorldType worldType) {
        try {
            QueueStatusResponse status = queueManager.getQueueStatus(worldType);
            return RsData.of("200", "큐 상태 조회 성공", status);
        } catch (Exception e) {
            log.error("큐 상태 조회 실패: worldType={}", worldType, e);
            return RsData.of("500", "큐 상태 조회 중 오류 발생", null);
        }
    }

    /**
     * 내 현재 대기 상태 조회
     */
    @GetMapping("/my-status") 
    public RsData<List<MyQueueStatusResponse>> getMyQueueStatus() {
        String memberId = getCurrentMemberId();

        List<MyQueueStatusResponse> myStatus = Arrays.stream(WorldType.values())
                .map(worldType -> queueManager.getMyQueueStatus(memberId, worldType))
                .filter(Objects::nonNull)
                .collect(Collectors.toList());

        return RsData.of("200", "내 대기 상태 조회 성공", myStatus);
    }
}

성능 개선 결과

Before vs After 비교

매칭 처리 시간:

Before (Java 다중 호출): 평균 3-5초, 최대 10초
After (Lua 스크립트):   평균 0.5초, 최대 1초
→ 80-90% 성능 향상

Race Condition 발생률:

Before: 동시 접속 50명 이상 시 15-20% 발생
After:  동시 접속 200명에서도 0% 발생
→ 완전 해결

네트워크 호출 수:

Before: 매칭 1회당 4-6번의 Redis 명령어 호출
After:  매칭 1회당 1번의 Lua 스크립트 호출
→ 75% 감소

실제 운영 지표

매칭 성공률:

• Before: 85-90% (Race Condition으로 인한 실패)
• After: 99.8% (네트워크 오류 등 외부 요인만 존재)

사용자 만족도:

• "매칭이 안 돼요" 불만: 90% 감소
• 평균 대기 시간 체감도: 70% 개선

안정성과 에러 처리

Lua 스크립트 에러 처리

-- 안전한 사용자 추출 (에러 처리 포함)
local function safeExtractUsers(queueKey, requiredCount)
    local success, result = pcall(function()
        local queueSize = redis.call('LLEN', queueKey)

        if queueSize < requiredCount then
            return {
                success = false,
                message = "인원 부족",
                currentCount = queueSize
            }
        end

        local extractedUsers = {}
        for i = 1, requiredCount do
            local user = redis.call('RPOP', queueKey)
            if not user then
                -- 예상치 못한 상황: 큐가 중간에 비어짐
                -- 이미 추출한 사용자들을 다시 큐에 넣기
                for j = 1, #extractedUsers do
                    redis.call('RPUSH', queueKey, extractedUsers[j])
                end

                return {
                    success = false,
                    message = "추출 중 오류 발생 (롤백 완료)",
                    extractedUsers = {}
                }
            end

            table.insert(extractedUsers, user)
        end

        return {
            success = true,
            extractedUsers = extractedUsers,
            remainingCount = redis.call('LLEN', queueKey)
        }
    end)

    if not success then
        return {
            success = false,
            message = "스크립트 실행 오류: " .. tostring(result)
        }
    end

    return result
end

-- 메인 로직에서 안전한 함수 사용
return safeExtractUsers(KEYS[1], tonumber(ARGV[1]) or 3)

Java에서의 Fallback 처리

public MatchingResult extractUsersForMatching(WorldType worldType, int requiredCount) {
    String queueKey = QUEUE_KEY_PREFIX + worldType.name().toLowerCase();

    try {
        // 1차 시도: Lua 스크립트 실행
        Map<String, Object> result = redisTemplate.execute(
            extractUsersScript,
            Collections.singletonList(queueKey),
            String.valueOf(requiredCount)
        );

        return parseMatchingResult(result, worldType);

    } catch (RedisConnectionFailureException e) {
        // Redis 연결 실패
        log.error("Redis 연결 실패, 매칭 서비스 일시 중단: worldType={}", worldType, e);
        return MatchingResult.failure("매칭 서비스 일시 중단, 잠시 후 다시 시도해주세요");

    } catch (RedisScriptException e) {
        // Lua 스크립트 실행 오류  
        log.error("Lua 스크립트 실행 오류: worldType={}, 스크립트 오류={}", worldType, e.getMessage(), e);

        // 2차 시도: 전통적인 Java 방식으로 fallback
        return extractUsersWithJavaFallback(queueKey, requiredCount, worldType);

    } catch (Exception e) {
        log.error("예상치 못한 오류: worldType={}", worldType, e);
        return MatchingResult.failure("매칭 처리 중 오류 발생");
    }
}

/**
 * Lua 스크립트 실패 시 Java로 fallback 처리
 * (성능은 떨어지지만 서비스 중단 방지)
 */
private MatchingResult extractUsersWithJavaFallback(String queueKey, int requiredCount, WorldType worldType) {
    try {
        log.warn("Java fallback 모드로 매칭 처리: worldType={}", worldType);

        // 분산 락을 이용해 동시성 제어
        String lockKey = "lock:matching:" + worldType.name();
        Boolean lockAcquired = redisTemplate.opsForValue()
                .setIfAbsent(lockKey, "1", Duration.ofSeconds(10));

        if (!lockAcquired) {
            return MatchingResult.waiting(0, requiredCount, "다른 매칭 처리 진행 중");
        }

        try {
            Long queueSize = redisTemplate.opsForList().size(queueKey);
            if (queueSize < requiredCount) {
                return MatchingResult.waiting(queueSize.intValue(), requiredCount, "인원 부족");
            }

            List<String> extractedUsers = new ArrayList<>();
            for (int i = 0; i < requiredCount; i++) {
                String user = redisTemplate.opsForList().rightPop(queueKey);
                if (user != null) {
                    extractedUsers.add(user);
                }
            }

            return MatchingResult.success(extractedUsers, 
                    Math.max(0, queueSize.intValue() - requiredCount), 
                    String.valueOf(System.currentTimeMillis() / 1000));

        } finally {
            // 락 해제
            redisTemplate.delete(lockKey);
        }

    } catch (Exception e) {
        log.error("Java fallback도 실패: worldType={}", worldType, e);
        return MatchingResult.failure("매칭 서비스 장애");
    }
}

운영 및 모니터링

Redis 메모리 관리

/**
 * 주기적으로 만료된 큐 데이터 정리
 */
@Scheduled(cron = "0 0 * * * *") // 매 시간마다 실행
public void cleanupExpiredQueueData() {
    for (WorldType worldType : WorldType.values()) {
        String queueKey = QUEUE_KEY_PREFIX + worldType.name().toLowerCase();
        String userDataKey = USER_DATA_KEY_PREFIX + worldType.name().toLowerCase();

        try {
            // TTL이 설정되지 않은 키들을 찾아서 TTL 설정
            Long queueTTL = redisTemplate.getExpire(queueKey);
            if (queueTTL == -1) { // TTL이 설정되지 않음
                redisTemplate.expire(queueKey, Duration.ofHours(1));
                log.warn("TTL 미설정 큐 발견하여 수정: queueKey={}", queueKey);
            }

            Long userDataTTL = redisTemplate.getExpire(userDataKey);
            if (userDataTTL == -1) {
                redisTemplate.expire(userDataKey, Duration.ofHours(1));  
                log.warn("TTL 미설정 사용자 데이터 발견하여 수정: userDataKey={}", userDataKey);
            }

        } catch (Exception e) {
            log.error("큐 데이터 정리 중 오류: worldType={}", worldType, e);
        }
    }
}

매칭 성능 모니터링

@Component
public class MatchingPerformanceMonitor {

    private final MeterRegistry meterRegistry;
    private final Counter matchingSuccessCounter;
    private final Counter matchingFailureCounter;
    private final Timer matchingProcessingTimer;

    public MatchingPerformanceMonitor(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
        this.matchingSuccessCounter = Counter.builder("matching.success")
                .description("매칭 성공 횟수")
                .register(meterRegistry);
        this.matchingFailureCounter = Counter.builder("matching.failure")
                .description("매칭 실패 횟수")
                .register(meterRegistry);
        this.matchingProcessingTimer = Timer.builder("matching.processing.time")
                .description("매칭 처리 시간")
                .register(meterRegistry);
    }

    public MatchingResult monitoredExtractUsers(WorldType worldType, int requiredCount) {
        return Timer.Sample.start(meterRegistry)
                .stop(matchingProcessingTimer.timer("world", worldType.name()))
                .recordCallable(() -> {
                    MatchingResult result = actualExtractUsers(worldType, requiredCount);

                    if (result.isSuccess()) {
                        matchingSuccessCounter.increment(
                            Tags.of("world", worldType.name())
                        );
                    } else {
                        matchingFailureCounter.increment(
                            Tags.of("world", worldType.name(), "reason", result.getMessage())
                        );
                    }

                    return result;
                });
    }
}

핵심 배운점과 팁

1. Lua 스크립트 작성 시 주의사항

-- ✅ 좋은 예: 명확한 변수명과 주석
local queueKey = KEYS[1]  -- 큐 식별자
local requiredCount = tonumber(ARGV[1]) or 3  -- 기본값 설정

-- ❌ 나쁜 예: 의미불명한 변수명
local k1 = KEYS[1]
local a1 = ARGV[1]

2. 에러 처리는 필수

-- 모든 Redis 명령어를 pcall로 감싸기
local success, result = pcall(function()
    return redis.call('LLEN', queueKey)
end)

if not success then
    return { success = false, message = "큐 조회 실패" }
end

3. 성능 최적화 팁

• 배치 처리: 여러 명령어를 하나의 스크립트로 묶기
• 조기 반환: 조건 확인 후 빠른 종료
• 메모리 효율: 불필요한 변수 선언 피하기

4. 테스트 방법

# Redis CLI에서 직접 스크립트 테스트
redis-cli --eval extractUsers.lua queue:world1 , 3

# 결과 예시
1) "success"
2) (integer) 1
3) "extractedUsers"  
4) 1) "user123"
   2) "user456" 
   3) "user789"

결론

Redis + Lua 스크립트 조합은 실시간 매칭 시스템의 동시성 문제를 완벽히 해결할 수 있는 강력한 도구입니다.

앞으로도 활용하고 싶은 영역:

• 분산 락 구현
• 실시간 순위 시스템
• 채팅방 메시지 처리
• 동적 설정 관리

Redis의 Lua 스크립트는 처음엔 낯설 수 있지만, 원자성이 필요한 모든 상황에서 게임 체인저가 될 수 있습니다. 특히 실시간 서비스나 동시성이 중요한 시스템이라면 꼭 고려해볼 만한 기술인 것 같습니다

Situation-Task-Action-Result 방식으로 정리한 1개월 개발 여정

개요

1개월간 DungeonTalk 백엔드 시스템을 개발하며 경험한 주요 상황들을 STAR 방식으로 정리했습니다. 각 상황에서 어떤 과제를 받았고, 어떻게 행동했으며, 어떤 결과를 얻었는지 구체적으로 기록하여 향후 개발에 참고할 수 있도록 했습니다.

STAR 회고 1: 멀티 데이터베이스 아키텍처 설계

Situation (상황)

• 시기: 프로젝트 초기
• 배경: AI 채팅, 매칭, 룸 관리 기능을 하나의 시스템에 구현해야 하는 상황
• 문제: 각 도메인마다 다른 데이터 특성 (관계형 데이터, 메시지 데이터, 캐시 데이터)
• 제약: Spring Boot 기반 단일 애플리케이션으로 구성해야 함

Task (과제)

• 주요 과제: 서로 다른 특성의 데이터를 효율적으로 저장하고 관리할 수 있는 아키텍처 설계
• 세부 요구사항:
  • 사용자 인증/권한은 관계형 데이터베이스 (PostgreSQL)
  • AI 게임 메시지는 도큐먼트 데이터베이스 (MongoDB)
  • 매칭 큐와 세션은 인메모리 데이터베이스 (Redis/Valkey)
• 성능 목표: 동시 접속자 100명 이상 지원

Action (행동)

1. 기술 스택 조사 및 선정:

   // PostgreSQL - JPA 설정
   @Entity
   public class Member {
       @Id @GeneratedValue
       private Long id;
       // 관계형 데이터 구조
   }
   
   // MongoDB - Document 설정  
   @Document(collection = "ai_game_messages")
   public class AiGameMessage {
       @Id private String id;
       // 비정형 메시지 데이터
   }
   
   // Redis - 캐시 설정
   @RedisHash("game_session")
   public class GameSession {
       @Id private String sessionId;
       // 휘발성 세션 데이터
   }

2. 데이터베이스별 설정 분리:

   # application.yml
   spring:
     datasource:
       url: jdbc:postgresql://localhost:5432/dungeondb
     data:
       mongodb:
         uri: mongodb://localhost:27017/dungeondb
     data:
       redis:
         host: localhost
         port: 6379

3. 트랜잭션 관리 전략 수립:

   • PostgreSQL: @Transactional 적용
   • MongoDB: 개별 도큐먼트 원자성 활용
   • Redis: Lua 스크립트로 원자성 보장

Result (결과)

• 성능 향상:
  • 메시지 조회 속도 70% 향상 (MongoDB 인덱싱)
  • 매칭 처리 시간 50% 단축 (Redis 인메모리 처리)
• 개발 생산성:
  • 각 도메인별 최적화된 데이터 모델링
  • 개발자간 데이터베이스 역할 분담 가능
• 확장성:
  • 새로운 기능 추가 시 적절한 DB 선택 가능
  • 각 DB별 독립적 스케일링 가능

STAR 회고 2: 동시 게임 시작 오류 해결

Situation (상황)

• 시기: QA 테스트 중
• 문제 발생: 매칭 완료 후 3명이 동시에 게임을 시작할 때 2명이 401 에러로 실패
• 영향도: 사용자 경험 저하, 매칭 시스템 전체 신뢰성 문제
• 로그 상황:

   게임방 상태가 잘못됨: roomId=..., status=ACTIVE, expected=CREATED
  JWT 인증[필터] 중 오류 발생: AiChatException

Task (과제)

• 주요 과제: 동시성 문제로 인한 게임 시작 실패 해결
• 기술적 요구사항:
  • Race Condition 해결
  • 모든 참여자가 정상적으로 게임 참여할 수 있도록 보장
• 제약사항: 기존 API 구조 유지, 성능 저하 최소화

Action (행동)

1. 문제 분석 및 원인 파악:

   // 문제가 된 기존 코드
   if (room.getStatus() != AiGameStatus.CREATED) {
       log.warn("🎮 게임방 상태가 잘못됨: roomId={}, status={}", roomId, room.getStatus());
       throw new AiChatException(ErrorCode.AI_GAME_ROOM_INVALID_STATE);
   }

2. 서버 측 방어적 프로그래밍 적용:

   // 개선된 코드
   if (room.getStatus() == AiGameStatus.ACTIVE) {
       log.info("🎮 게임방이 이미 활성화됨: roomId={}", roomId);
       return AiGameRoomResponse.fromEntity(room); // 성공으로 처리
   }
   
   if (room.getStatus() != AiGameStatus.CREATED) {
       log.warn("🎮 게임방 상태가 잘못됨: roomId={}, status={}", roomId, room.getStatus());
       throw new AiChatException(ErrorCode.AI_GAME_ROOM_INVALID_STATE);
   }

3. 클라이언트 측 중복 요청 방지:

   let gameSessionStarted = false;
   
   async function startGameSession(matchData) {
       if (gameSessionStarted) {
           console.log('🔄 게임 세션이 이미 시작됨, 중복 요청 무시');
           return;
       }
       gameSessionStarted = true;
       // ... 게임 시작 로직
   }

4. 상세한 로그 추가 및 모니터링 강화:

   log.info("🎮 게임 시작 요청: roomId={}, memberId={}, timestamp={}", 
            roomId, memberId, Instant.now());

Result (결과)

• 기능 개선:
  • 동시 게임 시작 성공률 100% 달성
  • 사용자 경험 크게 개선
• 안정성 향상:
  • Race Condition 완전 해결
  • 에러 로그 90% 감소
• 개발 역량 성장:
  • 동시성 프로그래밍 이해도 향상
  • 방어적 프로그래밍 습관 체득
• 운영 개선:
  • 문제 감지 시간 단축 (상세 로그)
  • 자동 복구 메커니즘 구축

STAR 회고 3: Redis 매칭 시스템 성능 최적화

Situation (상황)

• 시기: 매칭 시스템 구현 중
• 성능 문제: 매칭 처리 시간 평균 3-5초, 때로는 타임아웃 발생
• 사용자 피드백: "매칭이 너무 느려요", "매칭이 안 돼요"
• 시스템 상황: 동시 매칭 대기 사용자 50명 이상 시 성능 급격히 저하

Task (과제)

• 주요 과제: 매칭 처리 성능을 1초 이내로 단축
• 기술적 목표:
  • 공정한 매칭 알고리즘 유지
  • 동시성 문제 해결 (Race Condition 방지)
  • 확장 가능한 구조로 개선
• 제약사항: Redis 기반 구조 유지

Action (행동)

1. 기존 매칭 로직 분석:

   // 문제가 있던 기존 코드 (Java에서 여러 번 Redis 호출)
   List<String> queueUsers = redisTemplate.opsForList().range(QUEUE_KEY, 0, -1);
   if (queueUsers.size() >= 3) {
       String user1 = redisTemplate.opsForList().rightPop(QUEUE_KEY);
       String user2 = redisTemplate.opsForList().rightPop(QUEUE_KEY);
       String user3 = redisTemplate.opsForList().rightPop(QUEUE_KEY);
   }

2. Lua 스크립트로 원자적 처리 구현:

   -- extractUsers.lua
   local queueKey = KEYS[1]
   local queueSize = redis.call('LLEN', queueKey)
   
   if queueSize < 3 then
       return nil
   end
   
   local users = {}
   for i = 1, 3 do
       local user = redis.call('RPOP', queueKey)
       table.insert(users, user)
   end
   return users

3. Java에서 Lua 스크립트 실행:

   @Component
   public class MatchingQueueManager {
       private final RedisScript<List> extractUsersScript;
   
       public List<String> extractUsersForMatching(String queueKey) {
           List<String> result = redisTemplate.execute(
               extractUsersScript, 
               Collections.singletonList(queueKey)
           );
           return result != null ? result : Collections.emptyList();
       }
   }

4. TTL 기반 자동 정리 시스템 구현:

   // 매칭 데이터에 TTL 설정
   redisTemplate.expire(userKey, Duration.ofSeconds(3600)); // 1시간
   redisTemplate.expire(queueKey, Duration.ofSeconds(1800)); // 30분

Result (결과)

• 성능 대폭 개선:
  • 매칭 처리 시간 3-5초 → 0.5초 이내
  • 타임아웃 발생율 거의 0%
• 동시성 문제 완전 해결:
  • Race Condition 발생 0건
  • 중복 매칭/빠진 매칭 발생 0건
• 시스템 안정성 향상:
  • Redis 메모리 사용량 70% 감소 (TTL 적용)
  • 매칭 성공률 95% → 99.8%
• 사용자 만족도 향상:
  • 매칭 대기 시간 불만 90% 감소
  • 실시간 게임 참여 활발해짐

STAR 회고 4: Factory 패턴으로 통합 룸 시스템 구축

Situation (상황)

• 시기: 각 도메인 기능 완성 후 통합 단계
• 문제: AI 게임룸과 채팅룸이 서로 다른 API와 서비스로 분리됨
• 복잡성: 매칭 시스템에서 룸 생성 시 각각 다른 서비스 호출 필요
• 중복성: 비슷한 룸 관리 로직이 여러 곳에 산재

Task (과제)

• 주요 과제: 서로 다른 룸 타입을 하나의 통합 인터페이스로 관리
• 기술적 요구사항:
  • 기존 서비스 코드 수정 최소화
  • 새로운 룸 타입 추가 시 확장 용이성 보장
  • 일관된 API 제공
• 설계 목표: Factory와 Adapter 패턴 활용

Action (행동)

1. 통합 인터페이스 설계:

   public interface RoomService {
       RoomType getSupportedRoomType();
       UnifiedRoomResponse createRoom(UnifiedRoomRequest request);
       UnifiedRoomResponse getRoom(String roomId);
       void processMessage(UnifiedMessageRequest request);
       // ... 기타 공통 메서드
   }

2. Factory 패턴 구현:

   @Component
   public class RoomServiceFactory {
       private final List<RoomService> roomServices;
       private Map<RoomType, RoomService> serviceMap;
   
       public RoomService getService(RoomType roomType) {
           initializeServiceMap();
           RoomService service = serviceMap.get(roomType);
           if (service == null) {
               throw new IllegalArgumentException("지원하지 않는 룸 타입: " + roomType);
           }
           return service;
       }
   
       private void initializeServiceMap() {
           if (serviceMap == null) {
               serviceMap = roomServices.stream()
                   .collect(Collectors.toMap(
                       RoomService::getSupportedRoomType,
                       Function.identity()
                   ));
           }
       }
   }

3. Adapter 패턴으로 기존 서비스 연동:

   @Service
   public class AiGameRoomServiceAdapter implements RoomService {
       private final AiGameRoomService aiGameRoomService;
   
       @Override
       public RoomType getSupportedRoomType() {
           return RoomType.AI_GAME;
       }
   
       @Override
       public UnifiedRoomResponse createRoom(UnifiedRoomRequest request) {
           // UnifiedRoomRequest → AiGameRoomCreateRequest 변환
           AiGameRoomCreateRequest aiRequest = convertToAiRequest(request);
           AiGameRoomResponse aiResponse = aiGameRoomService.createAiGameRoom(aiRequest);
           // AiGameRoomResponse → UnifiedRoomResponse 변환
           return UnifiedRoomResponse.fromAiGameRoom(aiResponse);
       }
   }

4. 통합 API 컨트롤러 구현:

   @RestController
   @RequestMapping("/v1/rooms")
   public class UnifiedRoomController {
       private final UnifiedRoomService unifiedRoomService;
   
       @PostMapping
       public RsData<UnifiedRoomResponse> createRoom(@Valid @RequestBody UnifiedRoomRequest request) {
           return unifiedRoomService.createRoom(request);
       }
   
       @GetMapping("/{roomType}/{roomId}")
       public RsData<UnifiedRoomResponse> getRoom(@PathVariable String roomType, @PathVariable String roomId) {
           return unifiedRoomService.getRoom(roomType, roomId);
       }
   }

Result (결과)

• 코드 복잡도 대폭 감소:
  • API 엔드포인트 16개 → 8개 (50% 감소)
  • 매칭 시스템 룸 생성 코드 60% 단축
• 개발 생산성 향상:
  • 새 룸 타입 추가 시 개발 시간 70% 단축
  • 일관된 에러 처리로 디버깅 시간 단축
• 시스템 확장성 확보:
  • 새 룸 타입 추가 시 기존 코드 수정 불필요
  • Spring 자동 등록으로 설정 작업 최소화
• 설계 패턴 이해도 향상:
  • Factory 패턴의 실무 적용 경험
  • Adapter 패턴으로 레거시 코드 활용 방법 학습

STAR 회고 5: AI 서비스 타임아웃 문제 해결

Situation (상황)

• 시기: 개발 2개월차, AI 채팅 시스템 구현 중
• 문제: AI API 호출 시 평균 30-60초 소요, 종종 타임아웃 발생
• 사용자 반응: "AI가 응답을 안 해요", "게임이 멈췄어요"
• 시스템 영향: WebSocket 연결 끊김, 게임 진행 중단

Task (과제)

• 주요 과제: AI 응답 대기 시간으로 인한 사용자 경험 저하 해결
• 기술적 목표:
  • 사용자에게 진행 상황 실시간 알림
  • 타임아웃 시 적절한 fallback 처리
  • 전체 게임 흐름 유지
• 제약사항: 외부 AI 서비스 응답 속도 제어 불가

Action (행동)

1. 비동기 처리 구조로 변경:

   @Async("aiServiceTaskExecutor")
   public CompletableFuture<AiGameMessageResponse> processAiTurnAsync(String roomId, AiGenerateRequest request) {
       try {
           // WebSocket으로 처리 시작 알림
           webSocketService.sendProcessingStatus(roomId, "AI가 생각 중입니다...");
   
           // AI 서비스 호출
           AiResponseResult result = aiServiceClient.generateAiResponse(request);
   
           // 결과 처리 및 WebSocket 전송
           return CompletableFuture.completedFuture(processResult(result));
   
       } catch (Exception e) {
           // 에러 시 fallback 처리
           return CompletableFuture.completedFuture(createFallbackResponse());
       }
   }

2. 실시간 진행 상황 알림 시스템:

   // 처리 단계별 WebSocket 메시지 전송
   webSocketService.sendProcessingStatus(roomId, "AI 서비스에 요청을 전송했습니다... ⏳");
   // ... API 호출
   webSocketService.sendProcessingStatus(roomId, "AI가 답변을 생성하고 있습니다... 🤖");
   // ... 응답 처리
   webSocketService.sendProcessingStatus(roomId, "곧 AI 답변이 도착합니다... ✨");

3. 타임아웃 처리 및 Fallback 구현:

   @Value("${ai.service.timeout:45000}")
   private int aiServiceTimeout;
   
   public AiResponseResult generateAiResponse(AiGenerateRequest request) {
       try {
           return restTemplate.postForObject(aiServiceUrl, request, AiResponseResult.class);
       } catch (ResourceAccessException e) {
           if (e.getCause() instanceof SocketTimeoutException) {
               log.warn("AI 서비스 타임아웃 발생: roomId={}", request.getRoomId());
               return createTimeoutFallbackResponse();
           }
           throw e;
       }
   }
   
   private AiResponseResult createTimeoutFallbackResponse() {
       return AiResponseResult.builder()
           .content("AI가 잠시 생각에 빠져있네요. 다음 턴에 더 흥미로운 이야기를 들려드릴게요! 🎭")
           .build();
   }

4. 사용자 대기 경험 개선:

   // 클라이언트에서 처리 상태 시각화
   function showAiProcessingStatus(message) {
       const statusDiv = document.getElementById('ai-processing-status');
       statusDiv.innerHTML = `
           <div class="processing-indicator">
               <div class="spinner"></div>
               <span>${message}</span>
           </div>
       `;
   }

Result (결과)

• 사용자 경험 극적 개선:
  • "AI가 안 돼요" 불만 85% 감소
  • 게임 중단율 70% 감소
• 시스템 안정성 향상:
  • WebSocket 연결 끊김 90% 감소
  • 전체 게임 완주율 60% → 85% 향상
• 기술적 성장:
  • 비동기 프로그래밍 실무 적용 경험
  • 사용자 경험 중심의 기술 설계 능력 향상
• 운영 지표 개선:
  • AI 응답 실패율 15% → 2% 개선
  • 평균 게임 시간 20% 단축 (대기시간 체감 감소)

전체 프로젝트 STAR 종합 분석

주요 성과 지표

기술적 성과:

• 동시 접속자 처리 능력: 50명 → 200명 (400% 향상)
• 평균 응답 시간: 3-5초 → 1초 이내 (80% 개선)
• 시스템 안정성: 에러율 15% → 2% (87% 개선)

개발 생산성:

• API 엔드포인트 통합: 16개 → 8개 (50% 감소)
• 새 기능 개발 시간: 70% 단축
• 코드 중복도: 60% 감소

사용자 경험:

• 매칭 성공률: 95% → 99.8%
• 게임 완주율: 60% → 85%
• 사용자 만족도 관련 불만: 90% 감소

핵심 학습 내용

1. 동시성 프로그래밍: Race Condition 해결과 원자적 처리의 중요성
2. 설계 패턴 실무 적용: Factory, Adapter 패턴의 확장성과 유지보수성
3. 성능 최적화: 데이터베이스 선택과 캐싱 전략의 임팩트
4. 사용자 경험 중심 설계: 기술적 제약을 UX로 극복하는 방법
5. 운영 안정성: 로그, 모니터링, 에러 처리의 중요성

마무리

이번 STAR 방식 회고를 통해 단순히 "무엇을 했다"가 아닌 "어떤 상황에서, 어떤 과제를 받고, 어떻게 행동해서, 어떤 구체적인 결과를 얻었는지"를 명확히 정리할 수 있었습니다.

특히 각 상황에서 문제를 분석하고 → 해결책을 설계하고 → 구현하고 → 결과를 측정하는 일련의 과정을 체계적으로 수행했다는 것을 확인할 수 있었습니다.

앞으로도 이런 체계적인 문제 해결 접근법을 계속 발전시켜 나가며, 더 복잡하고 규모 있는 시스템을 구축해 나가고 싶습니다.

"기술은 문제를 해결하는 도구일 뿐, 진짜 중요한 건 문제를 정확히 파악하고 최적의 해결책을 찾는 능력이다."

1개월간의 개발 여정을 돌아보며 - 실패했던 것들, 성장한 것들, 그리고 솔직한 이야기들

시작하며

벌써 마지막 편이네요. 돌이켜보니 정말 많은 일들이 있었습니다.

처음에는 "AI 채팅 시스템이면 간단하겠지?"라고 생각했는데, 막상 해보니 실시간 통신, 동시성 제어, 외부 API 연동, 성능 최적화까지... 생각보다 훨씬 복잡한 시스템이였습니다

이번 편에서는 기술적인 내용보다는 개발 과정에서 진짜 느꼈던 것들을 솔직하게 공유해보려고 합니다.

"이게 왜 안 되지?" - 가장 고생한 순간들

1. 동시 접속 시 게임 시작 오류

상황: 매칭이 완료되어 3명이 동시에 게임을 시작하려 하는데, 한 명만 성공하고 나머지 두 명은 401 에러가 발생

처음 반응: "JWT 토큰 문제인가? 아니면 DB 문제인가?"

실제 원인: 게임방 상태를 CREATED에서 ACTIVE로 바꾸는 로직에서 동시성을 고려하지 않았음

// 문제가 된 코드
if (room.getStatus() != AiGameStatus.CREATED) {
    throw new AiChatException(ErrorCode.AI_GAME_ROOM_INVALID_STATE);
}

깨달은 점:

• "동시성? 그냥 이론일 줄 알았는데 진짜 일어나네"
• 로컬에서는 문제없던 게 서버에 올리면 터지는 무서운 경험
• 로그를 더 자세히 남겨야겠다는 생각

해결 후 기분:

// 이미 활성화된 게임방은 성공으로 처리하도록 수정
if (room.getStatus() == AiGameStatus.ACTIVE) {
    log.info(" 게임방이 이미 활성화됨");
    return AiGameRoomResponse.fromEntity(room);
}

"아, 이게 바로 '방어적 프로그래밍'이구나!"

2. AI 응답이 30초씩 걸리는 문제

상황: AI 서비스 호출이 평균 30-60초 소요. 사용자들이 "버그인가?"라고 생각할 정도

시도한 것들:

// 1. 타임아웃을 늘려보기
@Value("${ai.service.timeout:60000}")

// 2. 비동기로 처리하기
@Async("matchingTaskExecutor")
public void processAiTurn(String roomId, AiGenerateRequest request) {
    // ...
}

// 3. WebSocket으로 진행 상황 알리기
webSocketService.sendProcessingStatus(roomId, "AI가 생각 중입니다...");

깨달은 점:

• 외부 API 의존성이 이렇게 큰 영향을 미칠 줄 몰랐음
• 사용자 경험은 기술적 완성도와 별개라는 것
• "기다림"을 어떻게 표현하느냐가 중요함
• 실제로 ai 모델 속도가 너무 느린 문제가 있었습니다 딥시크 모델이 평균 26초 정도 걸려서 모델 변경을 고려하기도 했었지만 딥시크 모델이 가장 가격대비 성능이 좋아서 선택하게 되었습니다.

결론: AI가 느려도 사용자가 답답하지 않게 만드는 게 더 중요했음

3. Redis 메모리 부족으로 서비스 다운

상황: 매칭 시스템 테스트 중 Redis 메모리가 가득 차서 서비스 전체가 중단

원인: TTL 설정을 안 한 테스트 데이터들이 계속 쌓임

# Redis 메모리 사용량 확인했을 때의 충격
redis-cli info memory
used_memory_human:985.2M
maxmemory_human:1.0G

응급처치:

// 모든 매칭 관련 데이터에 TTL 추가
redisTemplate.expire(userKey, Duration.ofSeconds(3600));
redisTemplate.expire(sessionKey, Duration.ofSeconds(604800));

배운 점:

• "TTL을 안 설정하면 Redis는 쓰레기통"
• 개발할 때는 정리를 습관화해야 함
• 모니터링이 얼마나 중요한지 체감

"이건 정말 잘했다!" - 뿌듯했던 순간들

1. Factory 패턴으로 통합 룸 시스템 구현

처음 계획: AI 룸이랑 채팅룸을 따로따로 만들자

중간에 깨달음: "어? 이거 중복이 너무 많은데?"

최종 결과:

// 이 한 줄로 모든 룸 타입을 처리할 수 있게 됨
RoomService service = roomServiceFactory.getService(roomType);

뿌듯한 이유:

• 새로운 룸 타입 추가가 진짜 쉬워짐
• 매칭 시스템에서 룸 생성하는 코드가 절반으로 줄어듦
• "아, 이게 좋은 설계구나" 하는 느낌

2. Lua 스크립트로 원자적 매칭 처리

문제: 매칭 큐에서 3명을 뽑을 때 race condition 발생 가능

해결:

-- 이 스크립트 하나로 모든 동시성 문제 해결
local queueSize = redis.call('LLEN', queueKey)
if queueSize < 3 then
    return nil
end

local users = {}
for i = 1, 3 do
    local user = redis.call('RPOP', queueKey)
    table.insert(users, user)
end
return users

왜 뿌듯했나:

• Lua 스크립트는 처음 써봤는데 생각보다 강력함
• "원자성"이라는 개념을 코드로 구현해본 느낌
• Redis의 진짜 파워를 경험

3. WebSocket 실시간 알림 시스템

처음 WebSocket 연결됐을 때:

stompClient.connect(headers, function(frame) {
    console.log('Connected: ' + frame);
});

첫 메시지가 실시간으로 전달됐을 때: "와... 진짜 된다!"

지금 생각: 실시간 통신이 주는 사용자 경험의 임팩트가 생각보다 훨씬 큼

"이랬으면 더 좋았을 텐데" - 아쉬운 점들

1. 테스트 코드를 더 일찍 작성할걸

현실:

// 이런 테스트가 많았음
@Test
void createRoom() {
    // given
    // when
    // then - 일단 동작만 확인
    assertThat(result).isNotNull();
}

이랬으면 좋았을 것:

// 이런 테스트를 더 많이 작성했으면
@Test 
void createRoom_WhenAlreadyActive_ShouldReturnExistingRoom() {
    // 구체적인 시나리오 테스트
}

배운 점: 테스트는 나중에 하려면 더 어려워짐. 그냥 처음부터 습관화하자.

2. 에러 처리를 더 체계적으로

초기 에러 처리:

try {
    // 비즈니스 로직
} catch (Exception e) {
    log.error("에러 발생: {}", e.getMessage());
    throw new RuntimeException("처리 중 오류 발생");
}

지금 생각하는 이상적인 형태:

try {
    // 비즈니스 로직
} catch (AiServiceTimeoutException e) {
    log.warn("AI 서비스 타임아웃: roomId={}", roomId);
    return ErrorResponse.aiServiceUnavailable();
} catch (InvalidGameStateException e) {
    log.info("잘못된 게임 상태: roomId={}, status={}", roomId, e.getGameStatus());
    return ErrorResponse.invalidGameState(e.getGameStatus());
}

아쉬운 이유: 에러가 발생했을 때 원인을 찾기가 어려웠음

3. 성능 모니터링을 처음부터 구축할걸

현재 상황: 성능 문제가 생긴 후에야 "어디가 느린지 모르겠네?"

이랬으면 좋았을 것:

@Timed(name = "ai.response.time", description = "AI 응답 시간")
public AiResponseResult generateAiResponse(...) {
    // ...
}

배운 점: 모니터링은 문제가 생기기 전에 미리 준비해야 함

진짜 성장했다고 느끼는 부분들

1. "일단 돌아가게" → "제대로 돌아가게"

예전 코드:

// 일단 동작하면 OK
public String processMessage(String message) {
    return aiService.callApi(message).getResponse();
}

지금 코드:

// 예외 상황까지 고려
public RsData<AiGameMessageResponse> processMessage(UnifiedMessageRequest request) {
    try {
        // 입력 검증
        request.validateByRoomType();

        // 게임 상태 확인
        if (!aiGameStateService.canProcessMessage(request.getRoomId())) {
            return RsData.of("400", "현재 메시지를 처리할 수 없는 상태입니다", null);
        }

        // 실제 처리
        return processMessageInternal(request);

    } catch (ValidationException e) {
        return RsData.of("400", e.getMessage(), null);
    } catch (Exception e) {
        log.error("메시지 처리 중 예상치 못한 오류: roomId={}", request.getRoomId(), e);
        return RsData.of("500", "메시지 처리 중 오류가 발생했습니다", null);
    }
}

2. 로그에 대한 인식 변화

예전: 로그는 디버깅용

지금: 로그는 운영의 핵심

// 이제는 이런 로그를 자주 씀
log.info(" AI 게임 세션 시작: roomId={}, participants={}", roomId, participants);
log.warn(" AI 응답 처리 중 락 설정 실패 (이미 처리중): roomId={}", roomId);
log.error(" AI 서비스 연결 시간 초과: roomId={}, timeout={}ms", roomId, timeout);

느낀 점:

• 이모지 쓰니까 로그 보기가 훨씬 편함
• 구조화된 로그 (roomId, userId 등)가 진짜 도움됨
• 적절한 로그 레벨 구분이 중요

3. 설계 패턴을 "이해"에서 "활용"으로

Factory 패턴을 처음 적용했을 때:

// "이게 Factory 패턴이구나"
public RoomService getService(RoomType roomType) {
    switch (roomType) {
        case AI_GAME: return aiGameRoomServiceAdapter;
        case PLAYER_CHAT: return chatRoomServiceAdapter;
        default: throw new IllegalArgumentException("지원하지 않는 타입");
    }
}

지금의 Factory:

// "이렇게 하면 확장성이 좋겠구나"
private void initializeServiceMap() {
    serviceMap = roomServices.stream()
        .collect(Collectors.toMap(
            RoomService::getSupportedRoomType,
            Function.identity()
        ));
}

차이점: 패턴을 "알고 있음"에서 "왜 쓰는지 체감함"으로 변화

예상과 달랐던 재밌는 점들

1. MongoDB가 생각보다 편함

처음 생각: "NoSQL은 어려울 것 같은데..."

실제 경험:

// 스키마 자유도가 이렇게 좋을 줄이야
@Document(collection = "ai_game_messages")
public class AiGameMessage {
    // 필드 추가가 너무 간단함
    private String newField; // 그냥 추가하면 끝
}

인상깊었던 점:

• JSON과 자연스럽게 연결됨
• 복잡한 중첩 구조도 쉽게 저장
• 인덱스 설정만 잘하면 성능도 좋음

2. Redis가 단순한 캐시 그 이상

처음 생각: "Redis = 빠른 메모리 저장소"

실제 활용:

• 분산 락: setIfAbsent()
• Pub/Sub: 실시간 메시징
• TTL: 자동 데이터 정리
• List: 매칭 큐 구현
• Hash: 복잡한 데이터 구조 저장

깨달음: "Redis는 완전 다목적 도구구나"

3. WebSocket이 HTTP와 완전 다른 세계

HTTP 사고방식:

• 요청 → 응답
• 상태없음 (Stateless)
• 단방향

WebSocket 사고방식:

• 지속적 연결
• 상태 관리 필요
• 양방향 통신

인상깊었던 차이:

// HTTP: 간단명료
@GetMapping("/api/rooms/{id}")
public RoomResponse getRoom(@PathVariable String id) {
    return roomService.getRoom(id);
}

// WebSocket: 연결 상태, 세션 관리 등 고려할 게 많음
@MessageMapping("/aichat/send")
public void sendMessage(@Payload AiGameMessageSendRequest request, 
                       StompHeaderAccessor headerAccessor) {
    // 세션 확인, 권한 검증, 상태 관리...
}

협업하면서 느낀 점들

1. API 설계의 중요성

처음 API:

// 이런 식으로 만들었더니
@PostMapping("/aichat/create")
public String createRoom(@RequestBody Map<String, Object> request) {
    // ...
}

문제점:

• 프론트엔드 개발자가 "어떤 필드가 필요한지 모르겠어요"
• 타입 체크가 안 되어서 런타임 에러 자주 발생

개선 후:

@PostMapping("/rooms")
public RsData<UnifiedRoomResponse> createRoom(@Valid @RequestBody UnifiedRoomRequest request) {
    // ...
}

// DTO 클래스로 명확하게 정의
public class UnifiedRoomRequest {
    @NotNull(message = "룸 타입은 필수입니다")
    private RoomType roomType;

    @NotBlank(message = "룸 이름은 필수입니다")
    private String roomName;
    // ...
}

배운 점: API는 개발자 간의 약속. 명확할수록 좋음.

2. 문서화의 힘

처음에는: "코드 보면 알 수 있지 않나?"

Swagger 도입 후: "아, 이게 소통이구나"

@Operation(summary = "룸 생성", description = "새로운 AI 게임룸 또는 플레이어 채팅룸을 생성합니다")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "룸 생성 성공"),
    @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터")
})

효과:

• 프론트엔드 개발자가 API 테스트를 혼자서 할 수 있게 됨
• "이 API 어떻게 써요?" 질문이 확실히 줄어듦

3. 에러 메시지의 중요성

처음 에러 메시지:

throw new RuntimeException("오류 발생");

개선된 에러 메시지:

return RsData.of("400", "AI 게임룸은 gameSettings가 필요합니다", null);

체감한 차이:

• 디버깅 시간이 확실히 단축됨
• 프론트엔드에서 사용자에게 의미있는 메시지를 보여줄 수 있게 됨

다음에는 이렇게 해보고 싶다

1. 테스트 주도 개발 (TDD)

이번 프로젝트: 기능 구현 → 테스트 작성

다음 프로젝트: 테스트 작성 → 기능 구현

기대하는 점:

• 더 안정적인 코드
• 리팩토링에 대한 자신감
• 요구사항에 대한 더 명확한 이해

2. 도메인 주도 설계 (DDD) 적용

이번 경험:

• 도메인별로 패키지를 나누긴 했지만...
• 비즈니스 로직이 서비스 계층에 흩어져 있음

다음에는:

// Entity 자체에 비즈니스 로직 포함
public class AiGameRoom {
    public void startGame() {
        if (this.status != AiGameStatus.CREATED) {
            throw new IllegalStateException("게임을 시작할 수 없는 상태입니다");
        }
        this.status = AiGameStatus.ACTIVE;
        this.currentPhase = AiGamePhase.TURN_INPUT;
    }
}

3. 이벤트 기반 아키텍처

현재: 직접 서비스 호출

개선 아이디어:

// 이벤트 발행
eventPublisher.publishEvent(new MatchingCompleteEvent(participants, gameSessionId));

// 이벤트 처리
@EventListener
public void handleMatchingComplete(MatchingCompleteEvent event) {
    // 룸 생성, 알림 전송 등을 분리해서 처리
}

기대 효과:

• 더 느슨한 결합
• 쉬운 기능 추가/제거
• 더 나은 확장성

마치며

4개월 동안 정말 많은 걸 배웠습니다.

기술적으로는:

• 멀티 데이터베이스 설계
• 실시간 통신 구현
• 분산 시스템의 동시성 제어
• 설계 패턴의 실무 적용

개발 프로세스에서는:

• 테스트의 중요성
• 문서화의 힘
• 로그와 모니터링의 필요성
• API 설계의 중요성

개인적으로는:

• "일단 돌아가게" → "제대로 돌아가게"
• 문제를 체계적으로 접근하는 방법
• 동료와 소통하는 방법

가장 인상 깊었던 깨달음:

"좋은 코드는 혼자 봐도 좋은 코드가 아니라, 6개월 후 내가 봐도 이해할 수 있고, 동료가 봐도 이해할 수 있는 코드다."

아직 부족한 점들:

• 테스트 커버리지
• 성능 최적화
• 보안 고려사항
• 운영 모니터링

하지만 완벽한 시스템은 없다는 것도 배웠습니다. 중요한 건 지속적으로 개선해 나가는 것이죠.

이 시리즈를 읽어주신 분들께: 혹시 비슷한 시스템을 개발하게 되신다면, 제가 겪은 시행착오들이 조금이라도 도움이 되었으면 좋겠습니다.

그리고 "이렇게 하면 더 좋을 것 같은데?"하는 의견이 있으시면 언제든 댓글로 공유해 주세요. 계속 배우고 싶거든요.

DungeonTalk 개발기 시리즈 완결

1. 멀티 데이터베이스 아키텍처 설계
2. AI 채팅 시스템 구현 (aichat)
3. 실시간 매칭 시스템 구현 (matching)
4. 통합 룸 시스템 구현 (room)
5. 개발 회고와 진짜 배운 것들 ← 완료

*긴 여정 동안 함께해주셔서 감사합니다! *

Factory와 Adapter 패턴으로 AI 게임룸과 채팅룸을 하나로 통합하다

들어가며

매칭 시스템으로 플레이어들을 모았다면, 이제 실제 게임이 진행될 공간을 만들어야 합니다. DungeonTalk에서는 AI 게임룸과 일반 채팅룸, 두 가지 서로 다른 룸이 동시에 필요합니다.

하지만 각각 다른 서비스로 개발된 상황에서 일관된 인터페이스로 관리하고 싶었습니다. 이번 편에서는 Factory 패턴과 Adapter 패턴을 활용해 통합 룸 시스템을 구현한 과정을 공유합니다.

문제 상황과 해결 목표

기존 문제점

1. 중복된 룸 관리 로직

AI 게임룸 생성 → AiGameRoomService.createAiGameRoom()
채팅룸 생성 → ChatRoomService.createRoom()

2. 일관성 없는 API

GET /v1/aichat/rooms/{roomId}      // AI 게임룸
GET /v1/chat/rooms/{roomId}        // 채팅룸  

3. 매칭 시스템의 복잡성

// 매칭 완료 시 두 개의 서로 다른 서비스 호출
AiGameRoomResponse aiRoom = aiGameRoomService.createAiGameRoom(...);
ChatRoomDto chatRoom = chatRoomService.createRoom(...);

해결 목표

통합된 룸 관리 인터페이스 제공

• 단일 API로 모든 룸 타입 관리
• 확장 가능한 아키텍처
• 기존 서비스와의 호환성 보장

통합 룸 시스템 아키텍처

아키텍처 다이어그램

┌─────────────────────────────────────────────────────────────┐
│                    Client Layer                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │  Web Client     │  │  Mobile App     │  │  Admin Panel │ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
└─────────────────┬───────────────┬───────────────┬───────────┘
                  │               │               │
                  ▼               ▼               ▼
┌─────────────────────────────────────────────────────────────┐
│                 Controller Layer                            │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │            UnifiedRoomController                        │ │
│  │  - POST /v1/rooms (통합 룸 생성)                          │ │
│  │  - GET /v1/rooms/{type}/{id} (룸 조회)                   │ │
│  │  └─────────────────────────────────────────────────────┘ │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                 Service Layer                               │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │              UnifiedRoomService                         │ │
│  │          (비즈니스 로직 & 에러 처리)                        │ │
│  └─────────────────┬───────────────────────────────────────┘ │
│                    │                                         │
│                    ▼                                         │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │             RoomServiceFactory                          │ │
│  │              (Factory Pattern)                          │ │
│  └─────────┬───────────────────────────┬───────────────────┘ │
└───────────┼───────────────────────────┼─────────────────────┘
            │                           │
            ▼                           ▼
┌─────────────────────┐       ┌─────────────────────┐
│   Adapter Layer     │       │   Adapter Layer     │
│ ┌─────────────────┐ │       │ ┌─────────────────┐ │
│ │AiGameRoomService│ │       │ │ChatRoomService  │ │
│ │    Adapter      │ │       │ │    Adapter      │ │
│ │(Adapter Pattern)│ │       │ │(Adapter Pattern)│ │
│ └─────────────────┘ │       │ └─────────────────┘ │
└─────────┬───────────┘       └─────────┬───────────┘
          │                             │
          ▼                             ▼
┌─────────────────────┐       ┌─────────────────────┐
│   Domain Services   │       │   Domain Services   │
│ ┌─────────────────┐ │       │ ┌─────────────────┐ │
│ │AiGameRoomService│ │       │ │ChatRoomService  │ │
│ │AiGameMessage    │ │       │ │ChatMessage      │ │
│ │     Service     │ │       │ │    Service      │ │
│ └─────────────────┘ │       │ └─────────────────┘ │
└─────────┬───────────┘       └─────────┬───────────┘
          │                             │
          ▼                             ▼
┌─────────────────────┐       ┌─────────────────────┐
│   Data Layer        │       │   Data Layer        │
│ ┌─────────────────┐ │       │ ┌─────────────────┐ │
│ │    MongoDB      │ │       │ │    MongoDB      │ │
│ │  (AI Game Data) │ │       │ │  (Chat Data)    │ │
│ └─────────────────┘ │       │ └─────────────────┘ │
└─────────────────────┘       └─────────────────────┘

핵심 컴포넌트 구조

통합 룸 시스템
├── UnifiedRoomController      - 통합 REST API 제공
├── UnifiedRoomService        - 비즈니스 로직 & 응답 처리
├── RoomServiceFactory        - 룸 타입별 서비스 라우팅
├── RoomService (Interface)   - 통합 인터페이스 정의
├── AiGameRoomServiceAdapter  - AI 게임룸 어댑터
└── ChatRoomServiceAdapter    - 채팅룸 어댑터

Factory 패턴 구현

RoomServiceFactory 설계

핵심 아이디어: 룸 타입에 따라 적절한 서비스를 자동으로 선택

@Component
public class RoomServiceFactory {

    private final List<RoomService> roomServices;
    private Map<RoomType, RoomService> serviceMap;

    public RoomService getService(RoomType roomType) {
        initializeServiceMap();

        RoomService service = serviceMap.get(roomType);
        if (service == null) {
            throw new IllegalArgumentException(
                String.format("지원하지 않는 룸 타입: %s", roomType.getDisplayName())
            );
        }

        return service;
    }

    private void initializeServiceMap() {
        if (serviceMap == null) {
            serviceMap = roomServices.stream()
                .collect(Collectors.toMap(
                    RoomService::getSupportedRoomType,
                    Function.identity()
                ));
        }
    }
}

동작 과정:

1. Spring이 모든 RoomService 구현체를 주입
2. 각 서비스의 getSupportedRoomType() 기반으로 맵 구성
3. 요청 시 룸 타입에 맞는 서비스를 즉시 반환

확장 가능한 룸 타입 시스템

public enum RoomType {
    AI_GAME("ai-game", "AI 게임룸"),
    PLAYER_CHAT("player-chat", "플레이어 채팅룸");

    public static RoomType fromCode(String code) {
        return Arrays.stream(values())
            .filter(type -> type.code.equals(code))
            .findFirst()
            .orElseThrow(() -> new IllegalArgumentException("알 수 없는 룸 타입: " + code));
    }
}

새 룸 타입 추가 시:

1. RoomType 열거형에 새 타입 추가
2. RoomService 구현체 작성
3. Spring에서 자동 등록 → 코드 수정 최소화

Adapter 패턴 구현

통합 인터페이스 정의

public interface RoomService {

    RoomType getSupportedRoomType();

    // 룸 관리
    UnifiedRoomResponse createRoom(UnifiedRoomRequest request);
    UnifiedRoomResponse getRoom(String roomId);
    void deleteRoom(String roomId);
    List<UnifiedRoomResponse> getAvailableRooms();

    // 참여자 관리  
    UnifiedRoomResponse joinRoom(String roomId, String memberId);
    UnifiedRoomResponse leaveRoom(String roomId, String memberId);
    List<UnifiedRoomResponse> getUserRooms(String memberId);

    // 메시지 처리
    void processMessage(UnifiedMessageRequest request);
    void sendSystemMessage(String roomId, String message);

    // 상태 확인
    boolean existsRoom(String roomId);
    boolean isRoomActive(String roomId);
    boolean canJoinRoom(String roomId, String memberId);
}

AI 게임룸 어댑터

문제: 기존 AiGameRoomService를 건드리지 않고 통합 인터페이스 지원

해결: Adapter 패턴으로 인터페이스 변환

@Service
public class AiGameRoomServiceAdapter implements RoomService {

    private final AiGameRoomService aiGameRoomService;

    @Override
    public RoomType getSupportedRoomType() {
        return RoomType.AI_GAME;
    }

    @Override
    public UnifiedRoomResponse createRoom(UnifiedRoomRequest request) {
        // UnifiedRoomRequest → AiGameRoomCreateRequest 변환
        AiGameRoomCreateRequest aiRequest = AiGameRoomCreateRequest.builder()
                .gameId(request.getGameId())
                .roomName(request.getRoomName())
                .maxParticipants(request.getMaxParticipants())
                .creatorId(request.getCreatorId())
                .build();

        // 기존 서비스 호출
        AiGameRoomResponse aiResponse = aiGameRoomService.createAiGameRoom(aiRequest);

        // AiGameRoomResponse → UnifiedRoomResponse 변환
        return UnifiedRoomResponse.fromAiGameRoom(aiResponse);
    }
}

채팅룸 어댑터

@Service  
public class ChatRoomServiceAdapter implements RoomService {

    private final ChatRoomService chatRoomService;

    @Override
    public RoomType getSupportedRoomType() {
        return RoomType.PLAYER_CHAT;
    }

    @Override
    public UnifiedRoomResponse createRoom(UnifiedRoomRequest request) {
        // UnifiedRoomRequest → ChatRoomCreateRequestDto 변환
        ChatRoomCreateRequestDto chatRequest = ChatRoomCreateRequestDto.builder()
            .roomName(request.getRoomName())
            .mode(request.getChatMode())
            .maxCapacity(request.getMaxCapacity())
            .build();

        // 기존 서비스 호출
        ChatRoomDto room = chatRoomService.createRoom(chatRequest);

        // ChatRoomDto → UnifiedRoomResponse 변환
        return UnifiedRoomResponse.fromPlayerChatRoom(room);
    }
}

통합 API 설계

단일 컨트롤러로 모든 룸 타입 지원

@RestController
@RequestMapping("/v1/rooms")
public class UnifiedRoomController {

    private final UnifiedRoomService unifiedRoomService;

    @PostMapping
    public RsData<UnifiedRoomResponse> createRoom(@Valid @RequestBody UnifiedRoomRequest request) {
        return unifiedRoomService.createRoom(request);
    }

    @GetMapping("/{roomType}/{roomId}")
    public RsData<UnifiedRoomResponse> getRoom(@PathVariable String roomType, @PathVariable String roomId) {
        return unifiedRoomService.getRoom(roomType, roomId);
    }

    @PostMapping("/{roomType}/{roomId}/join")  
    public RsData<UnifiedRoomResponse> joinRoom(@PathVariable String roomType, @PathVariable String roomId, @RequestBody RoomMemberRequest request) {
        return unifiedRoomService.joinRoom(roomType, roomId, request.getMemberId());
    }
}

API 예시:

# AI 게임룸 생성
POST /v1/rooms
{
  "roomType": "AI_GAME",
  "roomName": "판타지 모험",
  "gameSettings": "중세 판타지 세계관"
}

# 채팅룸 생성  
POST /v1/rooms
{
  "roomType": "PLAYER_CHAT", 
  "roomName": "자유 채팅",
  "chatMode": "MULTI"
}

# 통합 룸 조회
GET /v1/rooms/ai-game/room-12345
GET /v1/rooms/player-chat/room-67890

ResponseService 패턴

일관된 응답 처리:

@Service
public class UnifiedRoomService {

    public RsData<UnifiedRoomResponse> createRoom(UnifiedRoomRequest request) {
        try {
            // 요청 유효성 검증
            request.validateByRoomType();

            // Factory에서 서비스 선택
            RoomService roomService = roomServiceFactory.getService(request.getRoomType());

            // 룸 생성
            UnifiedRoomResponse response = roomService.createRoom(request);

            return RsData.of("200", "룸 생성 성공", response);

        } catch (IllegalArgumentException e) {
            return RsData.of("400", "잘못된 요청: " + e.getMessage(), null);
        } catch (Exception e) {
            return RsData.of("500", "룸 생성 중 오류가 발생했습니다", null);
        }
    }
}

장점:

• 컨트롤러는 단순 위임만 처리
• 비즈니스 로직과 에러 처리를 서비스에서 담당
• 일관된 응답 형식 보장

DTO 변환 및 매핑

통합 요청/응답 객체

@Data
@Builder
public class UnifiedRoomRequest {
    private RoomType roomType;
    private String roomName;
    private String creatorId;
    private List<String> participantIds;

    // AI 게임룸 전용 필드
    private String gameId;
    private String gameSettings;
    private Integer maxParticipants;

    // 채팅룸 전용 필드  
    private ChatMode chatMode;
    private Integer maxCapacity;

    // 룸 타입별 유효성 검증
    public void validateByRoomType() {
        switch (roomType) {
            case AI_GAME:
                if (gameSettings == null) {
                    throw new IllegalArgumentException("AI 게임룸은 gameSettings가 필요합니다");
                }
                break;
            case PLAYER_CHAT:
                if (chatMode == null) {
                    throw new IllegalArgumentException("채팅룸은 chatMode가 필요합니다");
                }
                break;
        }
    }
}

응답 객체 변환

@Data
@Builder  
public class UnifiedRoomResponse {
    private String roomId;
    private RoomType roomType;
    private String roomName;
    private Integer currentParticipantCount;
    private Integer maxParticipantCount;

    // AI 게임룸 → 통합 응답 변환
    public static UnifiedRoomResponse fromAiGameRoom(AiGameRoomResponse aiRoom) {
        return UnifiedRoomResponse.builder()
                .roomId(aiRoom.getId())
                .roomType(RoomType.AI_GAME)
                .roomName(aiRoom.getRoomName())
                .currentParticipantCount(aiRoom.getCurrentParticipantCount())
                .maxParticipantCount(aiRoom.getMaxParticipants())
                .build();
    }

    // 채팅룸 → 통합 응답 변환
    public static UnifiedRoomResponse fromPlayerChatRoom(ChatRoomDto chatRoom) {
        return UnifiedRoomResponse.builder()
                .roomId(chatRoom.getId())
                .roomType(RoomType.PLAYER_CHAT) 
                .roomName(chatRoom.getRoomName())
                .currentParticipantCount(0) // 채팅룸은 현재 참여자 수 미지원
                .maxParticipantCount(Integer.MAX_VALUE)
                .build();
    }
}

매칭 시스템과의 통합

통합 룸 생성으로 매칭 간소화

Before (매칭 시스템의 기존 코드):

// 각각 다른 서비스 호출로 복잡함
AiGameRoomResponse aiRoom = aiGameRoomService.createAiGameRoom(aiRequest);
ChatRoomDto chatRoom = chatRoomService.createRoom(chatRequest);

After (통합 룸 시스템 활용):

public Map<String, String> createUnifiedRooms(String gameSessionId, List<String> participants, WorldType worldType) {
    Map<String, String> roomIds = new HashMap<>();

    // AI 게임룸 생성  
    UnifiedRoomRequest aiRoomRequest = UnifiedRoomRequest.builder()
            .roomType(RoomType.AI_GAME)
            .roomName(worldType.getDisplayName() + " 랜덤 매칭")
            .creatorId(participants.get(0))
            .participantIds(participants)
            .gameId(gameSessionId)
            .gameSettings(worldType.getGameSettings())
            .build();

    UnifiedRoomResponse aiRoom = roomServiceFactory.getService(RoomType.AI_GAME)
                                                  .createRoom(aiRoomRequest);
    roomIds.put("ai", aiRoom.getRoomId());

    // 플레이어 채팅룸 생성
    UnifiedRoomRequest chatRoomRequest = UnifiedRoomRequest.builder()
            .roomType(RoomType.PLAYER_CHAT)
            .roomName(worldType.getDisplayName() + " 채팅방")
            .creatorId(participants.get(0))
            .participantIds(participants)
            .chatMode(ChatMode.MULTI)
            .build();

    UnifiedRoomResponse chatRoom = roomServiceFactory.getService(RoomType.PLAYER_CHAT)
                                                    .createRoom(chatRoomRequest);
    roomIds.put("chat", chatRoom.getRoomId());

    return roomIds;
}

개선 효과:

• 일관된 룸 생성 로직
• 새로운 룸 타입 추가 시 변경 최소화
• 에러 처리 통합

메시지 처리 통합

통합 메시지 인터페이스

public interface RoomService {
    void processMessage(UnifiedMessageRequest request);
    void sendSystemMessage(String roomId, String message);
}

메시지 타입 변환

AI 게임룸 어댑터:

@Override
public void processMessage(UnifiedMessageRequest request) {
    // UnifiedMessageRequest → AiGameMessageSendRequest 변환
    AiGameMessageSendRequest aiRequest = AiGameMessageSendRequest.builder()
            .aiGameRoomId(request.getRoomId())
            .senderId(request.getSenderId())
            .content(request.getContent())
            .messageType(mapToAiMessageType(request.getMessageType()))
            .build();

    // 욕설 필터링이 포함된 메시지 처리
    aiGameMessageService.handleWebSocketMessage(aiRequest);
}

private AiMessageType mapToAiMessageType(UnifiedMessageType unifiedType) {
    switch (unifiedType) {
        case USER: return AiMessageType.USER;
        case SYSTEM: return AiMessageType.SYSTEM;
        case AI_RESPONSE: return AiMessageType.AI;
        default: return AiMessageType.USER;
    }
}

채팅룸 어댑터:

@Override  
public void processMessage(UnifiedMessageRequest request) {
    // UnifiedMessageRequest → ChatMessageSendRequestDto 변환
    ChatMessageSendRequestDto chatRequest = ChatMessageSendRequestDto.builder()
            .roomId(request.getRoomId())
            .senderId(request.getSenderId())
            .content(request.getContent())
            .type(mapToChatMessageType(request.getMessageType()))
            .build();

    chatMessageService.processMessage(chatRequest);
}

private MessageType mapToChatMessageType(UnifiedMessageType unifiedType) {
    switch (unifiedType) {
        case USER:
        case SYSTEM:
        case OTHER_PLAYER:
            return MessageType.TALK;
        case PRESENCE:
            return MessageType.PRESENCE;
        default:
            return MessageType.TALK;
    }
}

성능 및 확장성

1. 지연 초기화 (Lazy Initialization)

public class RoomServiceFactory {
    private void initializeServiceMap() {
        if (serviceMap == null) {  // 첫 요청 시에만 초기화
            serviceMap = roomServices.stream()
                .collect(Collectors.toMap(
                    RoomService::getSupportedRoomType,
                    Function.identity()
                ));
        }
    }
}

2. 캐싱 전략

// 팩토리 상태 정보 캐싱
@Cacheable("factory-status")
public String getFactoryStatus() {
    return roomServiceFactory.getFactoryStatus();
}

3. 확장성 보장

새로운 룸 타입 추가 절차:

1. RoomType 열거형에 새 타입 추가
2. RoomService 인터페이스 구현
3. 기존 어댑터 참고해서 새 어댑터 작성
4. Spring에서 자동 등록 → 추가 설정 불필요

에러 처리 및 안정성

통합 에러 처리

public RsData<UnifiedRoomResponse> createRoom(UnifiedRoomRequest request) {
    try {
        request.validateByRoomType();
        RoomService roomService = roomServiceFactory.getService(request.getRoomType());
        UnifiedRoomResponse response = roomService.createRoom(request);
        return RsData.of("200", "룸 생성 성공", response);

    } catch (IllegalArgumentException e) {
        log.warn("룸 생성 실패 - 잘못된 요청: {}", e.getMessage());
        return RsData.of("400", "잘못된 요청: " + e.getMessage(), null);
    } catch (Exception e) {
        log.error("룸 생성 중 오류 발생: roomType={}", request.getRoomType(), e);
        return RsData.of("500", "룸 생성 중 오류가 발생했습니다", null);
    }
}

서비스별 장애 격리

public RsData<Map<String, List<UnifiedRoomResponse>>> getAvailableRooms() {
    Map<String, List<UnifiedRoomResponse>> availableRooms = roomServiceFactory
            .getSupportedRoomTypes()
            .stream()
            .collect(Collectors.toMap(
                    RoomType::getCode,
                    roomType -> {
                        try {
                            RoomService service = roomServiceFactory.getService(roomType);
                            return service.getAvailableRooms();
                        } catch (Exception e) {
                            log.warn("룸 타입 {} 조회 중 오류: {}", roomType, e.getMessage());
                            return List.of(); // 해당 타입만 실패, 다른 타입은 정상 처리
                        }
                    }
            ));

    return RsData.of("200", "입장 가능한 룸 목록 조회 성공", availableRooms);
}

핵심 성과 및 배운 점

성공한 설계 결정

1. Factory 패턴의 효과

• 룸 타입 추가 시 설정 변경 불필요
• 런타임에 자동 서비스 발견
• 코드 중복 제거

2. Adapter 패턴의 효과

• 기존 서비스 코드 수정 없음
• 점진적 마이그레이션 가능
• 인터페이스 통합으로 일관성 확보

3. ResponseService 패턴

• 컨트롤러 단순화
• 일관된 에러 처리
• 비즈니스 로직 집중

개선이 필요한 부분

1. DTO 변환 오버헤드

• 현재: 매번 객체 변환 발생
• 목표: 변환 캐싱 또는 직접 매핑

2. 타입 안전성

• 현재: 문자열 기반 룸 타입 코드
• 목표: 컴파일 타임 타입 체크 강화

3. 부분 실패 처리

• 현재: 개별 서비스 실패 시 빈 리스트 반환
• 목표: 서킷 브레이커 패턴 적용

통합 효과 측정

Before vs After 비교

API 엔드포인트 수:

• Before: 16개 (AI 룸 8개 + 채팅룸 8개)
• After: 8개 (통합 API)
• 50% 감소

매칭 시스템 코드 복잡도:

• Before: 2개 서비스 × 다른 인터페이스 = 복잡한 분기 처리
• After: 1개 팩토리 × 통합 인터페이스 = 단순한 룸 생성
• 코드 라인 60% 감소

새 룸 타입 추가 비용:

• Before: 컨트롤러, 서비스, API 문서 모두 추가
• After: 어댑터 1개만 추가
• 개발 시간 70% 단축

시리즈 마무리

4편까지의 여정 정리:

1편: 멀티 데이터베이스 아키텍처 → 기반 설계 2편: AI 채팅 시스템 → 실시간 게임 로직
3편: 실시간 매칭 시스템 → 공정한 플레이어 매칭 4편: 통합 룸 시스템 → 확장 가능한 통합 관리

전체 시스템의 시너지:

• 매칭 시스템이 통합 룸 시스템을 활용해 룸 생성
• 통합 룸 시스템이 AI 채팅 시스템과 연계해 게임 진행
• 멀티 데이터베이스가 각 도메인의 데이터 특성을 최적 지원

다음 5편 예고: 개발 회고 & 성능 최적화

• 전체 시스템 성능 분석 및 최적화 사례
• 개발 과정에서 겪은 시행착오와 해결책
• 실제 서비스 런칭을 위한 운영 고려사항
• 팀 협업과 코드 품질 관리 경험

시리즈 목차

1. 멀티 데이터베이스 아키텍처 설계
2. AI 채팅 시스템 구현 (aichat)
3. 실시간 매칭 시스템 구현 (matching)
4. 통합 룸 시스템 구현 ← 현재
5. 개발 회고 & 성능 최적화

3명이 만나야 시작되는 AI 게임, Redis Queue로 공정한 매칭을 만들다

들어가며

AI 채팅 시스템을 구현했다면, 이제 플레이어들을 공정하게 매칭해야 합니다. 3명이 모여야 시작되는 게임 특성상, 매칭 시스템의 안정성과 실시간성이 사용자 경험을 좌우합니다.

이번 편에서는 Redis Queue 기반 매칭 알고리즘과 WebSocket 실시간 알림, 그리고 분산 환경에서의 동시성 제어까지 - 매칭 시스템 구현의 모든 과정을 공유합니다.

매칭 시스템 요구사항

핵심 요구사항

1. 공정한 선입선출 (FIFO)

• 먼저 대기한 사람이 먼저 매칭
• 세계관별 독립적인 큐 관리

2. 실시간 상태 알림

• 현재 대기 순번과 예상 시간
• 매칭 완료 즉시 알림

3. 안정적인 매칭 처리

• 동시성 제어로 중복 매칭 방지
• 매칭 실패 시 자동 복구

4. 확장 가능한 구조

• 세계관 추가 용이
• 매칭 규칙 변경 유연

시스템 아키텍처

컴포넌트 구조

매칭 시스템
├── MatchingController        - REST API 엔드포인트
├── MatchingWebSocketController - WebSocket 매칭 처리  
├── MatchingService          - 매칭 비즈니스 로직
├── MatchingQueueManager     - Redis Queue 관리
├── MatchingWebSocketService - 실시간 알림 전송
└── WorldType               - 세계관별 설정

데이터 플로우

사용자 매칭 요청 → Redis Queue 추가 → 실시간 상태 알림
                      ↓
               3명 모이면 → Lua 스크립트로 추출
                      ↓  
          분산 락 → 룸 생성 → 매칭 완료 알림

Redis Queue 설계

세계관별 Queue 구조

핵심 아이디어: 각 세계관마다 독립적인 Queue와 통계를 유지

public enum WorldType {
    FANTASY("판타지", "중세 판타지 - 마법과 모험의 세계"),
    SF("SF", "미래 SF - 과학기술과 우주탐험"), 
    MODERN("현대", "현대 도시 - 일상과 미스터리");

    public String getQueueKey() {
        return "matching:queue:" + this.name();
    }

    public String getStatsKey() {
        return "matching:stats:" + this.name();
    }
}

Redis 데이터 구조:

• matching:queue:FANTASY - 판타지 세계관 대기열 (List)
• matching:user:{memberId} - 사용자 매칭 정보 (Hash)
• matching:stats:FANTASY - 큐 통계 정보 (Hash)
• matching:lock:FANTASY - 매칭 처리 분산 락 (String)

FIFO 보장 전략

문제: Redis List의 leftPush + rightPop으로 FIFO 구현

해결: 정확한 큐 위치 계산 로직

public int getUserQueuePosition(String userId, WorldType worldType) {
    String queueKey = worldType.getQueueKey();
    List<String> queueUsers = redisTemplate.opsForList().range(queueKey, 0, -1);

    if (queueUsers != null) {
        // leftPush로 추가하므로, 뒤에서부터 찾아야 함 (FIFO 순서)
        for (int i = queueUsers.size() - 1; i >= 0; i--) {
            if (userId.equals(queueUsers.get(i))) {
                return queueUsers.size() - i; // 1부터 시작하는 위치
            }
        }
    }
    return -1;
}

동시성 제어

분산 락을 통한 원자적 매칭

문제: 동시에 여러 요청이 들어와서 중복 매칭이 발생할 수 있음

해결: Redis 분산 락 + Lua 스크립트

public MatchingCompleteResponse processMatching(WorldType worldType) {
    String lockKey = MatchingConstants.LOCK_KEY_PREFIX + worldType.name();
    Boolean lockAcquired = redisTemplate.opsForValue()
        .setIfAbsent(lockKey, "PROCESSING", Duration.ofSeconds(5));

    if (!Boolean.TRUE.equals(lockAcquired)) {
        log.warn("매칭 처리 락 획득 실패: 다른 프로세스에서 처리 중");
        return null;
    }

    try {
        // 실제 매칭 처리 로직
        List<String> participants = queueManager.extractThreeUsers(worldType);
        // ...
    } finally {
        redisTemplate.delete(lockKey); // 락 해제
    }
}

Lua 스크립트로 원자적 추출

핵심: 3명 추출을 하나의 원자적 연산으로 처리

private static final String EXTRACT_USERS_SCRIPT = """
    local queueKey = KEYS[1]
    local queueSize = redis.call('LLEN', queueKey)

    if queueSize < 3 then
        return nil
    end

    local users = {}
    for i = 1, 3 do
        local user = redis.call('RPOP', queueKey)
        if user then
            table.insert(users, user)
        end
    end

    return users
    """;

장점:

• 3명 추출이 모두 성공하거나 모두 실패
• Race Condition 완전 방지
• Redis 서버에서 실행되므로 네트워크 지연 최소화

실시간 WebSocket 알림

WebSocket 메시지 구조

@MessageMapping("/matching/join")
public void joinMatching(@Payload MatchingJoinRequest request) {
    matchingService.handleWebSocketJoinMatching(
        request.getMemberId(), request.getWorldType());
}

메시지 플로우:

1. 클라이언트 → /pub/matching/join
2. 큐 추가 → Redis 상태 업데이트
3. 서버 → /sub/matching/user/{memberId} 상태 알림

실시간 상태 알림 전략

개별 알림: 각 사용자에게 맞춤형 정보 전송

public void sendQueueStatusUpdate(String memberId, WorldType worldType, 
                                int currentPosition, int totalInQueue, long waitingTime) {
    MatchingWebSocketMessage message = messageFactory.createQueueStatusUpdate(
            memberId, worldType, currentPosition, totalInQueue, waitingTime);

    String destination = MatchingConstants.WS_TOPIC_USER_STATUS + memberId;
    messagingTemplate.convertAndSend(destination, message);
}

브로드캐스트: 세계관별 전체 통계 공유

public void broadcastQueueStats(WorldType worldType, int currentWaiting) {
    String destination = MatchingConstants.WS_TOPIC_QUEUE_STATS + worldType.name().toLowerCase();
    messagingTemplate.convertAndSend(destination, message);
}

매칭 완료 알림 로직

public void sendMatchingComplete(List<String> participants, WorldType worldType,
                               String gameSessionId, String aiGameRoomId, String chatRoomId) {
    MatchingWebSocketMessage message = messageFactory.createMatchingComplete(
            participants, worldType, gameSessionId, aiGameRoomId, chatRoomId);

    // 각 참가자에게 개별 전송
    for (String memberId : participants) {
        String destination = MatchingConstants.WS_TOPIC_USER_STATUS + memberId;
        messagingTemplate.convertAndSend(destination, message);
    }
}

매칭 완료 정보 포함 내용:

• 게임 세션 ID
• AI 게임방 ID
• 채팅방 ID
• 매칭된 참가자 목록

Factory 패턴으로 룸 생성

통합 룸 생성 전략

문제: AI 게임방과 채팅방을 각각 생성해야 함

해결: Factory 패턴으로 룸 타입별 통합 생성

public Map<String, String> createUnifiedRooms(String gameSessionId, 
                                            List<String> participants, WorldType worldType) {
    Map<String, String> roomIds = new HashMap<>();

    // AI 게임룸 생성
    UnifiedRoomRequest aiRoomRequest = UnifiedRoomRequest.builder()
            .roomType(RoomType.AI_GAME)
            .roomName(worldType.getDisplayName() + " 랜덤 매칭")
            .maxParticipants(DEFAULT_MAX_PARTICIPANTS)
            .creatorId(participants.get(0))
            .participantIds(participants)
            .gameId(gameSessionId)
            .build();

    UnifiedRoomResponse aiRoom = roomServiceFactory.getService(RoomType.AI_GAME)
                                                  .createRoom(aiRoomRequest);
    roomIds.put("ai", aiRoom.getRoomId());

    // 플레이어 채팅룸 생성
    UnifiedRoomRequest chatRoomRequest = UnifiedRoomRequest.builder()
            .roomType(RoomType.PLAYER_CHAT)
            .roomName(worldType.getDisplayName() + " 채팅방")
            .maxParticipants(DEFAULT_MAX_PARTICIPANTS)
            .creatorId(participants.get(0))
            .participantIds(participants)
            .build();

    UnifiedRoomResponse chatRoom = roomServiceFactory.getService(RoomType.PLAYER_CHAT)
                                                    .createRoom(chatRoomRequest);
    roomIds.put("chat", chatRoom.getRoomId());

    return roomIds;
}

대기시간 예측 시스템

예측 알고리즘

기본 로직: (현재 대기 순번 - 1) / 3 * 평균 매칭 시간

public int calculateEstimatedWaitTime(int position, int averageMatchTime) {
    if (position <= 3) {
        return averageMatchTime; // 다음 매칭에 포함될 예정
    }

    int matchesNeeded = (position - 1) / 3;
    return matchesNeeded * averageMatchTime;
}

고려사항:

• 평균 매칭 시간 실시간 업데이트
• 시간대별 사용자 패턴 반영
• 세계관별 인기도 차이 보정

정기적 매칭 처리

스케줄링 기반 매칭

문제: 실시간 요청 외에도 정기적으로 매칭 확인 필요

해결: Spring Scheduler로 5초마다 전체 큐 검사

@Scheduled(fixedDelay = 5000)
public void processAllQueueMatching() {
    for (WorldType worldType : WorldType.values()) {
        try {
            if (queueManager.canProcessMatching(worldType)) {
                log.info("정기 매칭 처리 시작: worldType={}, queueSize={}", 
                        worldType, queueManager.getQueueSize(worldType));
                processMatchingAsync(worldType);
            }
        } catch (Exception e) {
            log.error("정기 매칭 처리 중 오류: worldType={}", worldType, e);
        }
    }
}

비동기 매칭 처리

@Async("matchingTaskExecutor")
public void processMatchingAsync(WorldType worldType) {
    try {
        processMatching(worldType);
    } catch (Exception e) {
        log.error("비동기 매칭 처리 중 오류: worldType={}", worldType, e);
    }
}

장점:

• 메인 스레드 블로킹 방지
• 여러 세계관 동시 처리 가능
• 에러 격리로 안정성 향상

에러 처리 및 복구

매칭 실패 시나리오

1. 룸 생성 실패

try {
    Map<String, String> roomIds = createUnifiedRooms(gameSessionId, participants, worldType);
} catch (Exception e) {
    // 참가자들을 다시 큐에 추가
    participants.forEach(memberId -> 
        queueManager.addToQueue(memberId, worldType));
    throw new AiChatException(ErrorCode.MATCHING_PROCESSING_ERROR, "룸 생성 실패");
}

2. Redis 연결 장애

public void clearQueue(WorldType worldType) {
    try {
        // 큐 정리 로직
    } catch (QueryTimeoutException e) {
        throw new AiChatException(ErrorCode.MATCHING_PROCESSING_ERROR, "큐 정리 타임아웃");
    } catch (DataAccessException e) {
        throw new AiChatException(ErrorCode.MATCHING_PROCESSING_ERROR, "Redis 액세스 오류");
    }
}

3. WebSocket 알림 실패

• 알림 실패 시에도 매칭은 진행
• 로그 기록 후 계속 처리
• 사용자는 게임방 새로고침으로 복구

모니터링 및 통계

매칭 세션 정보 저장

private void saveMatchingSession(String gameSessionId, String aiGameRoomId, String chatRoomId, 
                               List<String> participants, WorldType worldType) {
    String sessionKey = MatchingConstants.SESSION_KEY_PREFIX + gameSessionId;

    Map<String, String> sessionInfo = Map.of(
            "participants", String.join(",", participants),
            "worldType", worldType.name(),
            "aiGameRoomId", aiGameRoomId,
            "chatRoomId", chatRoomId,
            "createdAt", Instant.now().toString(),
            "status", "ACTIVE"
    );

    redisTemplate.opsForHash().putAll(sessionKey, sessionInfo);
    redisTemplate.expire(sessionKey, Duration.ofSeconds(604800)); // 7일
}

큐 통계 실시간 업데이트

private void updateQueueStats(WorldType worldType, int delta) {
    String statsKey = worldType.getStatsKey();

    redisTemplate.opsForHash().increment(statsKey, "currentWaiting", delta);
    redisTemplate.opsForHash().put(statsKey, "lastUpdated", Instant.now().toString());

    redisTemplate.expire(statsKey, Duration.ofDays(1));
}

성능 최적화

1. Lua 스크립트 활용

• 여러 Redis 명령을 하나의 원자적 연산으로 처리
• 네트워크 라운드 트립 최소화

2. 비동기 처리

• 전용 스레드 풀로 매칭 처리 분리
• 사용자 요청에 대한 즉시 응답

3. TTL 관리

• 사용자 상태: 1시간 TTL
• 세션 정보: 7일 TTL
• 통계 데이터: 1일 TTL

4. 분산 락 타임아웃

• 5초 타임아웃으로 데드락 방지
• 락 해제 보장으로 시스템 안정성

핵심 성과 및 배운 점

성공한 설계 결정

1. Redis Queue + Lua 스크립트

• 공정한 FIFO 보장
• 원자적 연산으로 동시성 문제 해결

2. WebSocket 실시간 알림

• 사용자 경험 향상
• 대기 시간에 대한 명확한 피드백

3. Factory 패턴 룸 생성

• AI 게임방 + 채팅방 통합 생성
• 확장 가능한 룸 타입 관리

개선이 필요한 부분

1. 대기시간 예측 정확도

• 현재: 단순 평균 기반
• 목표: ML 기반 동적 예측

2. 매칭 실패 복구

• 현재: 에러 로그 + 수동 처리
• 목표: 자동 재시도 + 폴백 전략

3. 부하 분산

• 현재: 단일 Redis 인스턴스
• 목표: Redis Cluster로 확장

다음 편 예고

4편에서는 통합 룸 시스템을 다룰 예정입니다:

• Factory 패턴으로 다양한 룸 타입 통합 관리
• Adapter 패턴으로 기존 서비스와의 호환성 보장
• 확장 가능한 룸 시스템 아키텍처
• 룸 간 데이터 동기화 및 상태 관리

시리즈 목차

1. 멀티 데이터베이스 아키텍처 설계
2. AI 채팅 시스템 구현 (aichat)
3. 실시간 매칭 시스템 구현 ← 현재
4. 통합 룸 시스템 구현 (room)
5. 개발 회고 & 성능 최적화

실시간 턴제 AI 게임 채팅을 구현하며 마주한 기술적 도전들

들어가며

1편에서 멀티 데이터베이스 아키텍처를 살펴봤다면, 이번 편에서는 AI 채팅 시스템의 구체적인 구현을 다뤄보겠습니다. 실시간 WebSocket 통신과 외부 AI 서비스 연동, 그리고 턴제 게임 상태 관리까지 - 생각보다 복잡했던 여정을 공유합니다.

AI 채팅 시스템 아키텍처

핵심 설계 원칙

1. 턴제 게임 로직

• 플레이어들이 순서대로 메시지 입력
• AI 응답 중에는 모든 입력 차단
• 게임 페이즈별 상태 관리

2. 실시간 통신

• WebSocket + STOMP 기반 양방향 통신
• 룸별 독립적인 메시지 채널
• 자동 재연결 및 에러 처리

3. 외부 서비스 연동

• Python AI 서비스와 HTTP 통신
• 비동기 처리 및 타임아웃 관리
• 장애 대응 및 폴백 처리

도메인 구조

패키지 구성

aichat/
├── controller/     - REST API & WebSocket 컨트롤러
├── service/        - 비즈니스 로직 처리
├── entity/         - MongoDB 엔티티
├── dto/            - 데이터 전송 객체
├── common/         - 열거형 및 상수
└── event/          - 비동기 이벤트 처리

핵심 컴포넌트

컨트롤러 레이어

• AiGameRoomController: 게임방 CRUD API
• AiChatStompController: 실시간 메시징 처리

서비스 레이어

• AiGameFlowService: AI 턴 플로우 관리
• AiGameStateService: 게임 상태 및 세션 관리
• AiApiService: 외부 AI 서비스 연동

WebSocket 실시간 메시징

STOMP 메시지 매핑

@Controller
public class AiChatStompController {

    @MessageMapping("/aichat/send")
    public RsData<String> sendMessage(@Payload AiGameMessageSendRequest request) {
        return aiGameMessageService.handleWebSocketMessage(request);
    }

    @MessageMapping("/aichat/join")
    public RsData<String> joinRoom(@Payload AiGameMessageSendRequest request) {
        return aiGameMessageService.handleJoinRoom(request);
    }
}

메시지 플로우:

1. 클라이언트 → /pub/aichat/send
2. 서버 처리 → MongoDB 저장 → Redis Pub/Sub
3. 구독자들에게 → /sub/aichat/room/{roomId}

실시간 상태 동기화

핵심 아이디어는 게임 상태를 Redis에서 관리하면서 메시지는 MongoDB에 저장하는 것입니다.

• Redis: 세션, 게임 페이즈, 턴 락 관리
• MongoDB: 메시지 히스토리 영구 저장
• WebSocket: 실시간 상태 브로드캐스트

게임 상태 관리

게임 페이즈 시스템

public enum AiGamePhase {
    WAITING,      // 플레이어 입장 대기
    TURN_INPUT,   // 플레이어 입력 단계  
    AI_RESPONSE,  // AI 응답 생성 중 (입력 차단)
    GAME_END      // 게임 종료
}

턴 락 메커니즘

문제: AI 응답 중에 여러 플레이어가 동시에 메시지를 보내면?

해결: Redis 분산 락으로 AI 처리 중 상태 관리

public boolean lockForAiResponse(String roomId) {
    String lockKey = AI_GAME_TURN_LOCK_PREFIX + roomId;
    boolean locked = valkeyService.setIfNotExists(lockKey, "AI_PROCESSING", 300);

    if (locked) {
        changePhase(roomId, AiGamePhase.AI_RESPONSE);
    }
    return locked;
}

동작 과정:

1. 플레이어 메시지 → AI 응답 요청
2. Redis 락 설정 → 페이즈를 AI_RESPONSE로 변경
3. 다른 메시지들은 차단
4. AI 응답 완료 → 락 해제 → TURN_INPUT으로 복귀

세션 관리 전략

public AiGameRoomResponse startGameSession(String roomId) {
    // MongoDB에서 게임 상태 변경
    AiGameRoom updatedRoom = room.toBuilder()
            .status(AiGameStatus.ACTIVE)
            .currentPhase(AiGamePhase.TURN_INPUT)
            .build();

    // Redis에 세션 정보 저장 (TTL 1시간)
    String sessionKey = AI_GAME_SESSION_PREFIX + roomId;
    valkeyService.setWithExpiration(sessionKey, sessionData, 3600);

    return AiGameRoomResponse.fromEntity(updatedRoom);
}

이중 저장 전략:

• MongoDB: 영구 데이터 (게임 히스토리)
• Redis: 휘발성 데이터 (세션, 락, 캐시)

AI 서비스 연동

HTTP 클라이언트 설계

@Service
public class AiApiService {

    public AiResponseResult generateAiResponse(String gameId, String roomId, 
                                             String currentUser, String currentMessage,
                                             List<AiGameMessageDto> contextMessages, 
                                             int turnNumber) {

        String url = aiServiceUrl + "/ai-response";

        // 요청 데이터 구성
        AiResponseRequest request = AiResponseRequest.builder()
                .gameId(gameId)
                .aiGameRoomId(roomId)
                .currentUser(currentUser)
                .currentMessage(currentMessage)
                .contextMessages(contextMessages.stream()
                        .map(this::convertToContextMessage)
                        .toList())
                .turnNumber(turnNumber)
                .build();

        // Python AI 서비스 호출
        ResponseEntity<Map> response = restTemplate.exchange(
                url, HttpMethod.POST, httpEntity, Map.class);

        // 응답 검증 및 결과 반환
        return parseAiResponse(response);
    }
}

비동기 처리 패턴

문제: AI 응답 생성이 최대 60초까지 소요될 수 있음

해결: 이벤트 기반 비동기 처리

@EventListener
@Async("matchingTaskExecutor")
public void handleAiTurnProcessEvent(AiTurnProcessEvent event) {
    processAiTurn(event.getAiGameRoomId(), event.getAiRequest());
}

처리 플로우:

1. 플레이어 메시지 수신 → 즉시 응답 (논블로킹)
2. 백그라운드에서 AI 이벤트 처리
3. AI 응답 완료 → WebSocket으로 결과 브로드캐스트

장애 처리 전략

public AiResponseResult generateAiResponse(...) {
    try {
        // AI 서비스 호출
        return callAiService(request);

    } catch (ResourceAccessException e) {
        log.error("AI 서비스 연결 시간 초과: roomId={}", roomId);
        throw new AiChatException(ErrorCode.AI_RESPONSE_TIMEOUT_ERROR, e);

    } catch (RestClientException e) {
        log.error("AI 서비스 호출 실패: roomId={}", roomId);
        throw new AiChatException(ErrorCode.AI_RESPONSE_PROCESSING_ERROR, e);
    }
}

에러 시나리오별 대응:

• 타임아웃: 게임 일시정지 + 에러 메시지 전송
• 서비스 장애: 폴백 응답 또는 재시도
• 잘못된 응답: 데이터 검증 후 에러 처리

메시지 순서 보장

MongoDB 인덱싱 전략

핵심 아이디어: messageOrder 필드로 메시지 순서 보장

@Document(collection = "ai_game_messages")  
public class AiGameMessage {
    @Id private String id;
    private String roomId;
    private String content;
    @Indexed private Integer messageOrder;  // 순서 보장용
    private Integer turnNumber;
}

인덱스 설정:

@Configuration
public class AiGameMessageIndexConfig {
    @EventListener(ContextRefreshedEvent.class)
    public void ensureIndexes() {
        mongoTemplate.indexOps(AiGameMessage.class)
            .ensureIndex(Index.on("roomId", Sort.Direction.ASC)
                             .on("messageOrder", Sort.Direction.ASC));
    }
}

메시지 순서 관리

// 턴 시작 메시지: messageOrder = 0
// 플레이어 메시지: messageOrder = 1, 2, 3, ...  
// AI 응답: messageOrder = 5000
// 턴 종료 메시지: messageOrder = 9999
// 에러 메시지: messageOrder = 9998

이렇게 하면 턴별로 메시지가 정확한 순서로 조회됩니다.

컨텍스트 메시지 관리

AI에게 전달할 대화 맥락

문제: AI가 이전 대화 내용을 기억하게 하려면?

해결: 최근 N개 메시지를 컨텍스트로 전달

public List<AiGameMessageDto> getContextMessages(String roomId, int maxCount, int currentTurn) {
    // 현재 턴 이전의 최근 메시지들을 조회
    List<AiGameMessage> messages = aiGameMessageRepository
            .findByAiGameRoomIdAndTurnNumberLessThanOrderByMessageOrderDesc(
                roomId, currentTurn, PageRequest.of(0, maxCount));

    // 시간순으로 정렬하여 반환 (AI가 순서대로 읽을 수 있게)
    return messages.stream()
            .sorted(Comparator.comparing(AiGameMessage::getMessageOrder))
            .map(AiGameMessageDto::fromEntity)
            .toList();
}

설정 가능한 컨텍스트 개수:

# application-dev.properties
aichat.context.message-count=5

성능 최적화

1. 비동기 처리

• 스레드 풀: AI 응답 전용 스레드 풀 분리
• 이벤트 처리: Spring Events로 논블로킹 처리

2. Redis 활용

• 세션 캐싱: 게임 상태를 Redis에서 빠르게 조회
• 분산 락: 동시성 제어로 데이터 무결성 보장

3. MongoDB 최적화

• 복합 인덱스: roomId + messageOrder로 빠른 메시지 조회
• TTL 인덱스: 오래된 게임 데이터 자동 삭제

에러 처리 및 복구

장애 상황별 대응

1. AI 서비스 장애

private RsData<AiGameMessageResponse> handleAiResponseError(String roomId, Exception e, String errorMessage) {
    log.error("AI 응답 오류: roomId={}, error={}", roomId, e.getMessage(), e);

    // 락 해제
    aiGameStateService.unlockAfterAiResponse(roomId);

    // 게임 일시정지  
    aiGameStateService.pauseGame(roomId, "AI 응답 생성 오류");

    return RsData.of("500", errorMessage, null);
}

2. 세션 만료

public boolean isSessionValid(String roomId) {
    String sessionKey = AI_GAME_SESSION_PREFIX + roomId;
    return valkeyService.exists(sessionKey);
}

public void extendSession(String roomId) {
    String sessionKey = AI_GAME_SESSION_PREFIX + roomId;
    if (valkeyService.exists(sessionKey)) {
        valkeyService.expire(sessionKey, DEFAULT_SESSION_TIMEOUT_SECONDS);
    }
}

3. WebSocket 연결 끊김

• 클라이언트 자동 재연결
• 메시지 히스토리 동기화
• 게임 상태 복구

핵심 성과 및 배운 점

성공한 설계 결정

1. 이중 데이터 저장 전략

• MongoDB: 영구 데이터
• Redis: 휘발성 + 실시간 상태

2. 분산 락을 통한 동시성 제어

• AI 응답 중 메시지 차단
• 데이터 무결성 보장

3. 이벤트 기반 비동기 처리

• 논블로킹 사용자 경험
• 장시간 작업의 백그라운드 처리

개선이 필요한 부분

1. AI 응답 시간 최적화

• 현재: 평균 30-60초
• 목표: 10-20초 단축

2. 에러 복구 자동화

• 현재: 수동 게임 재시작
• 목표: 자동 복구 메커니즘

3. 모니터링 강화

• 응답 시간 메트릭
• 에러율 추적
• 사용자 경험 지표

다음 편 예고

3편에서는 실시간 매칭 시스템을 다룰 예정입니다:

• Redis Queue 기반 매칭 알고리즘
• 대기 시간 예측 및 최적화
• WebSocket을 통한 매칭 상태 실시간 업데이트
• 매칭 취소 및 타임아웃 처리

시리즈 목차

1. 멀티 데이터베이스 아키텍처 설계
2. AI 채팅 시스템 구현 ← 현재
3. 실시간 매칭 시스템 구현 (matching)
4. 통합 룸 시스템 구현 (room)
5. 개발 회고 & 성능 최적화