Batch Core

⚙️ Batch Core Framework

Reusable Spring Batch Framework for RAIO Backend

---

목차

1. Philosophy
2. Features
3. Architecture
4. Core Modules
5. Batch Runner
6. Payment Batch Example
7. Development Convention
8. Job 추가 체크리스트

---

Philosophy

Important

Spring Batch를 사용하는 것이 목적이 아닙니다. 도메인 개발자가 비즈니스 로직에만 집중할 수 있도록 Spring Batch를 추상화하는 것이 Batch Core의 목표입니다.

RAIO Batch Core는 Spring Batch의 반복적인 Job, Step, Tasklet, Scheduler, JobLauncher 설정을 공통 Framework로 추상화하여, 도메인 개발자가 UseCase와 Job 정의만으로 배치를 개발할 수 있도록 설계되었습니다.

---

Features

• ⚙️ Batch Builder — Spring Batch 보일러플레이트 제거
• ⏰ Batch Scheduler — YML 기반 Cron
• ▶️ Batch Engine — JobRegistry / JobLauncher 실행
• 📊 Batch Dashboard Support — Metadata 자동 생성
• 🎯 Batch On-demand — 관리자 API 기반 실행
• 🧩 Multi Module · 🏛️ Hexagonal Architecture

---

Architecture

flowchart TB
    Runner["Batch Runner"]
    Runner --> Scheduler["Batch Scheduler"]
    Runner --> Ondemand["Batch On-demand"]
    Runner --> Dashboard["Batch Dashboard"]
    Scheduler --> Core["BatchJobRunner"]
    Ondemand --> Core
    Dashboard --> Core
    Core --> Job["Spring Batch Job"]
    Job --> UseCase["Application UseCase"]
    UseCase --> RDB["Driven RDB"]
    UseCase --> Client["Driven Client"]

Loading

---

Core Modules

batch-api

공통 API 및 설정 객체를 제공합니다.

• BatchProperties · JobProperties · BatchJobRunner

batch-builder

Spring Batch 보일러플레이트를 제거합니다. 기존 JobBuilder / StepBuilder / Tasklet 조합 대신:

@Bean
public Job paymentRecoveryJob(BatchJobs batch) {
    return batch.job("paymentRecoveryJob")
            .taskletStep("paymentRecoveryStep", () -> {
                paymentRecoveryUseCase.recover();
                return RepeatStatus.FINISHED;
            })
            .build();
}

장점 — Tasklet 클래스 제거, Builder DSL 제공, Job 정의 단순화

batch-engine

Batch 실행 엔진입니다. JobRegistry 조회 → JobLauncher 실행 → JobParameters 생성 → JobExecution 반환.

batch-scheduler

YML 기반 Cron Scheduler입니다.

app:
  batch:
    jobs:
      paymentRecoveryJob:
        cron: "0 */5 * * * *"

Scheduler는 BatchJobRunner를 호출하여 Job을 실행합니다.

batch-dashboard-support

Spring Batch Metadata를 자동 생성합니다.

지원 DB	PostgreSQL · MySQL · MariaDB · Oracle · SQL Server · H2
생성 대상	BATCH_JOB_INSTANCE · BATCH_JOB_EXECUTION · BATCH_STEP_EXECUTION · BATCH_JOB_EXECUTION_CONTEXT · BATCH_STEP_EXECUTION_CONTEXT

batch-ondemand

관리자 API 기반 Batch 실행을 제공합니다. Scheduler와 동일한 Runner를 사용합니다.

flowchart LR
    A["Admin API"] --> B["BatchOndemandExecutor"] --> C["BatchJobRunner"] --> D["Spring Batch Job"]

Loading

---

Batch Runner

spring:
  batch:
    job:
      enabled: false
    jdbc:
      initialize-schema: never

설정	의미
job.enabled=false	Spring Boot 시작 시 자동 실행 방지 — Scheduler 또는 On-demand가 실행 담당
initialize-schema=never	Metadata 생성은 batch-dashboard-support 담당

---

Payment Batch Example

@Bean
public Job paymentRecoveryJob(BatchJobs batch) {
    return batch.job("paymentRecoveryJob")
            .taskletStep("paymentRecoveryStep", () -> {
                paymentRecoveryUseCase.recover();
                return RepeatStatus.FINISHED;
            })
            .build();
}

도메인 개발자는 Spring Batch API보다 Application UseCase 호출에 집중합니다.

---

Development Convention

1. Application UseCase 작성
2. Driving Batch Adapter 등록
3. app.batch.jobs 설정
4. Local Cron 테스트
5. 운영 Cron 적용

Note

• Batch는 Driving Adapter이며 UseCase만 호출합니다 — Repository를 직접 호출하지 않습니다.
• Scheduler와 On-demand는 BatchJobRunner를 공유합니다.
• Job 이름과 YML Key는 동일해야 합니다.
• Spring Batch보다 Batch Core를 우선 사용합니다.

---

Job 추가 체크리스트

새 배치 Job을 추가할 때 아래 순서로 진행합니다.

• UseCase 작성
• Job 등록
• YML 등록
• Local 실행 확인
• 운영 Cron 적용
• Metadata 생성 확인

---

Summary

Batch Core는 단순한 Wrapper가 아니라, 도메인 개발자가 Spring Batch의 복잡성을 몰라도 비즈니스 로직만 작성하여 Batch를 개발할 수 있도록 만든 Framework입니다.