Spring Boot 3.x 완벽 가이드: Spring Batch 5 프로젝트 설정부터 실행까지

안녕하세요.

이론은 충분히 익혔으니, 이제 손을 움직일 차례입니다. 하지만 Spring Boot 2.x 시절의 블로그 글을 보고 따라 하다가 JobBuilderFactory가 없다는 빨간 줄(에러)을 보고 당황하신 적 없으신가요?

Spring Boot 3.0(Spring Batch 5.0)으로 넘어오면서 많은 것이 변했습니다. 오늘은 최신 Spring Boot 3.x 환경에서 가장 정확하고 빠르게 Spring Batch 프로젝트를 세팅하는 방법을 알려드립니다.

1. 개발 환경 요구사항 (Prerequisites)

Spring Batch 5.0은 중대한 변화가 있었습니다.

  • Java Version: 최소 Java 17 이상이 필수입니다.
  • Spring Framework: Spring Framework 6 기반입니다.
  • Database: 배치 실행 이력을 저장할 메타 데이터 테이블이 필요합니다. (H2, MySQL 등)

2. 프로젝트 생성 및 의존성 설정 (build.gradle)

Spring Initializr를 사용하거나, 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 {
    // 1. Spring Batch 필수 의존성
    implementation 'org.springframework.boot:spring-boot-starter-batch'

    // 2. JPA 및 DB 관련 (배치 메타 테이블 저장을 위해 필요)
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    runtimeOnly 'com.h2database:h2' // 로컬 테스트용 인메모리 DB
    runtimeOnly 'com.mysql:mysql-connector-j' // (옵션) 운영 환경용

    // 3. 편의 도구
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'

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

3. 설정 파일 (application.yml)

Spring Batch는 실행 시점에 DB에 메타 테이블(BATCH_JOB_INSTANCE 등)이 존재해야 합니다. H2를 사용할 경우 자동으로 생성해주지만, 설정을 명확히 하는 것이 좋습니다.

spring:
  datasource:
    url: jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
    driver-class-name: org.h2.Driver
    username: sa
    password:

  batch:
    jdbc:
      initialize-schema: always # 애플리케이션 시작 시 배치 메타 테이블 자동 생성
    job:
      enabled: true # true: 앱 실행 시 Job 자동 실행 (운영에서는 false 권장)

  jpa:
    show-sql: true
    hibernate:
      ddl-auto: update

주의: spring.batch.jdbc.initialize-schema: always는 개발 환경에서만 사용하세요. 운영 환경에서는 DB 계정에 테이블 생성 권한이 없을 수 있으며, 실수로 데이터를 초기화할 위험이 있습니다.

4. 첫 번째 Batch Job 만들기 (Hello World)

Spring Batch 5부터는 JobBuilderFactory, StepBuilderFactory가 Deprecated(삭제됨) 되었습니다. 대신 JobRepository를 주입받아 직접 빌더를 생성해야 합니다. 이 부분이 가장 많이 바뀐 점입니다.

package com.example.batch.job;

import lombok.RequiredArgsConstructor;
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.repeat.RepeatStatus;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.transaction.PlatformTransactionManager;

@Slf4j
@Configuration
@RequiredArgsConstructor
public class SimpleJobConfig {

    private final JobRepository jobRepository; // Batch 5.x 필수
    private final PlatformTransactionManager transactionManager; // Batch 5.x 필수

    @Bean
    public Job helloJob() {
        return new JobBuilder("helloJob", jobRepository)
                .start(helloStep())
                .build();
    }

    @Bean
    public Step helloStep() {
        return new StepBuilder("helloStep", jobRepository)
                .tasklet((contribution, chunkContext) -> {
                    log.info(">>>>> Hello, Spring Batch 5 World!");
                    log.info(">>>>> 이것이 바로 최신 트렌드 배치입니다.");
                    return RepeatStatus.FINISHED;
                }, transactionManager)
                .build();
    }
}

코드 변경 포인트 (vs Batch 4.x)

  1. @EnableBatchProcessing 제거: Spring Boot의 자동 설정을 활용하기 위해 메인 클래스나 설정 클래스에서 이 어노테이션을 뺍니다. (쓰면 자동 설정이 꺼져서 더 복잡해질 수 있습니다.)
  2. JobBuilderFactory -> new JobBuilder(name, jobRepository): 팩토리 빈 대신 직접 빌더를 생성하며 JobRepository를 명시적으로 전달합니다.
  3. TransactionManager 명시: Step을 빌드할 때 트랜잭션 매니저를 반드시 넘겨줘야 합니다.

5. 실행 및 결과 확인

애플리케이션(@SpringBootApplication이 있는 클래스)을 실행합니다.

콘솔 로그 확인:

INFO ... SimpleJobConfig : >>>>> Hello, Spring Batch 5 World!
INFO ... SimpleJobConfig : >>>>> 이것이 바로 최신 트렌드 배치입니다.
INFO ... o.s.b.c.l.support.SimpleJobLauncher : Job: [SimpleJob: [name=helloJob]] completed with the following parameters: [{}] and the following status: [COMPLETED]

축하합니다! 성공적으로 Spring Batch 5 환경을 구축하고 첫 Job을 실행하셨습니다.

6. 마무리 및 다음 단계

이제 여러분은 최신 환경에서 배치를 개발할 준비를 마쳤습니다. 하지만 이것은 시작일 뿐입니다. 실제 업무에서는 다음과 같은 고민이 필요합니다.

  • 배치 실패 시 어떻게 알림을 받을까? (Slack, Email 연동)
  • 매일 특정 시간에 어떻게 실행할까? (Jenkins, Quartz, K8s CronJob)
  • 동시에 여러 배치를 돌려도 될까? (Multi-threaded Step, Partitioning)

앞으로의 포스팅을 통해 이런 심화 주제들도 하나씩 풀어드리겠습니다. 이 가이드가 여러분의 삽질 시간을 1시간이라도 줄여주었기를 바랍니다.

관련 글 보기