[Spring Batch] 2. Job과 Step 구조

이전 편에서 배치 처리의 개념과 Spring Batch의 전체 아키텍처를 살펴봤다. 이제 Spring Batch의 가장 기본적인 구성 단위인 Job과 Step을 파고들어보자. 이 두 개념을 이해하면 Spring Batch의 절반은 안 셈이다.

Job — 배치 작업의 최상위 단위

Job은 하나의 완전한 배치 작업을 정의한다. "월말 정산 Job", "일일 통계 Job"처럼 독립적으로 실행 가능한 배치 작업 하나가 하나의 Job이다.

Job 자체는 실행 로직을 가지고 있지 않다. 내부에 하나 이상의 Step을 포함하며, Step의 실행 순서와 흐름을 정의하는 컨테이너 역할을 한다.

Job을 정의하는 코드는 다음과 같다.

@Configuration
public class SettlementJobConfig {

    @Bean
    public Job settlementJob(JobRepository jobRepository,
                             Step fetchOrdersStep,
                             Step calculateStep,
                             Step notifyStep) {
        return new JobBuilder("settlementJob", jobRepository)
                .start(fetchOrdersStep)
                .next(calculateStep)
                .next(notifyStep)
                .build();
    }
}

JobBuilder로 Job의 이름을 지정하고, start()와 next()로 Step의 실행 순서를 정의한다. 이 Job을 실행하면 Step 1 → Step 2 → Step 3 순서대로 진행된다.

Step — 작업의 실행 단위

Step은 Job 내에서 실제로 작업을 수행하는 단위다. 데이터를 읽거나, 가공하거나, 저장하는 로직이 Step 안에 들어간다.

Step은 두 가지 모델 중 하나를 선택한다.

Chunk 모델

데이터를 일정 크기(chunk)로 나눠서 반복 처리하는 모델이다. Reader가 데이터를 읽고, Processor가 가공하고, Writer가 저장한다. 대량 데이터 처리의 핵심 모델이다. 자세한 내용은 Chunk 기반 처리 편에서 다룬다.

@Bean
public Step calculateStep(JobRepository jobRepository,
                           PlatformTransactionManager transactionManager) {
    return new StepBuilder("calculateStep", jobRepository)
            .<Order, Settlement>chunk(1000, transactionManager)
            .reader(orderReader())
            .processor(settlementProcessor())
            .writer(settlementWriter())
            .build();
}

chunk(1000)은 1,000건씩 읽어서 처리한다는 뜻이다. 10만 건이면 100번 반복한다.

Tasklet 모델

단일 작업을 한 번 실행하는 모델이다. chunk로 나눌 필요 없는 간단한 작업에 적합하다.

@Bean
public Step cleanupStep(JobRepository jobRepository,
                         PlatformTransactionManager transactionManager) {
    return new StepBuilder("cleanupStep", jobRepository)
            .tasklet((contribution, chunkContext) -> {
                tempFileRepository.deleteExpired();
                return RepeatStatus.FINISHED;
            }, transactionManager)
            .build();
}

RepeatStatus.FINISHED를 반환하면 작업이 완료된 것이다. RepeatStatus.CONTINUABLE을 반환하면 같은 Tasklet을 다시 실행한다.

실행 단위의 계층 구조

Spring Batch에서 가장 혼동하기 쉬운 개념이 JobInstance, JobExecution, StepExecution의 관계다. 이 셋을 정확히 이해해야 "재시작"이 어떻게 가능한지 알 수 있다.

JobInstance

Job + JobParameters의 조합으로 식별되는 논리적 실행 단위다.

"정산 Job"을 2024-01-15 파라미터로 실행하면 하나의 JobInstance가 생긴다. 같은 파라미터로 이미 성공한 JobInstance가 있으면, 같은 파라미터로 다시 실행할 수 없다.

비유하자면 JobInstance는 "과제"다. "1월 15일자 정산 과제"라는 하나의 과제가 주어진 것이다.

JobExecution

JobInstance의 실제 실행 시도 하나를 나타낸다. 같은 JobInstance에 대해 여러 번 실행을 시도할 수 있다.

1월 15일 정산을 돌렸는데 Step 2에서 실패했다. 이게 첫 번째 JobExecution이다. 문제를 수정하고 다시 돌리면 두 번째 JobExecution이 생긴다. 같은 "과제"에 대한 두 번째 "시도"인 셈이다.

JobExecution은 다음 상태를 가진다.

• COMPLETED : 성공적으로 완료. 같은 파라미터로 다시 실행 불가.
• FAILED : 실패. 재시작 가능.
• STOPPED : 사용자에 의해 중단. 재시작 가능.

StepExecution

Step의 실제 실행 시도 하나를 나타낸다. 각 StepExecution에는 읽은 건수, 쓴 건수, 건너뛴 건수 등의 통계가 기록된다.

// StepExecution이 기록하는 정보
readCount     // 읽은 건수
writeCount    // 쓴 건수
commitCount   // 커밋 횟수
skipCount     // 건너뛴 건수
rollbackCount // 롤백 횟수
startTime     // 시작 시간
endTime       // 종료 시간
status        // 상태 (COMPLETED, FAILED 등)

JobParameters

JobParameters는 Job 실행 시 전달하는 파라미터다. 같은 Job이라도 파라미터가 다르면 다른 JobInstance로 취급된다.

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

실행 시 파라미터를 전달한다.

JobParameters params = new JobParametersBuilder()
        .addString("targetDate", "2024-01-15")
        .addLong("version", 1L)
        .toJobParameters();

jobLauncher.run(settlementJob, params);

Step 내부에서 파라미터를 꺼내 쓸 수 있다.

@Bean
@StepScope
public ItemReader<Order> orderReader(
        @Value("#{jobParameters['targetDate']}") String targetDate) {
    // targetDate를 사용해서 해당 날짜의 주문만 조회
    return new JpaPagingItemReaderBuilder<Order>()
            .queryString("SELECT o FROM Order o WHERE o.orderDate = :date")
            .parameterValues(Map.of("date", targetDate))
            .build();
}

@StepScope와 @Value("#{jobParameters['targetDate']}")의 조합으로 파라미터를 주입받는다. @StepScope는 Step이 실행될 때 빈을 생성하므로, 실행 시점의 파라미터 값을 사용할 수 있다.

JobRepository와 메타데이터 테이블

JobRepository는 Job과 Step의 실행 이력을 DB에 저장하고 조회하는 컴포넌트다. 재시작, 실행 이력 조회, 중복 실행 방지의 핵심이다.

Spring Batch가 자동으로 생성하는 메타데이터 테이블은 다음과 같다.

개발자가 이 테이블을 직접 조회하거나 조작할 일은 거의 없다. Spring Batch가 내부적으로 관리한다. 하지만 이 테이블이 어떤 역할을 하는지는 알고 있어야 재시작이나 실패 분석 시 도움이 된다.

JobLauncher

JobLauncher는 Job을 실행하는 진입점이다. Job과 JobParameters를 받아서 실행한다.

@Service
@RequiredArgsConstructor
public class BatchScheduler {

    private final JobLauncher jobLauncher;
    private final Job settlementJob;

    public void runSettlement(String targetDate) {
        JobParameters params = new JobParametersBuilder()
                .addString("targetDate", targetDate)
                .addLong("timestamp", System.currentTimeMillis())
                .toJobParameters();

        jobLauncher.run(settlementJob, params);
    }
}

timestamp를 파라미터에 추가하면, 같은 targetDate로 여러 번 실행할 수 있다. 파라미터 조합이 달라지면 다른 JobInstance로 취급되기 때문이다.

전체 실행 흐름

지금까지 배운 개념들이 실제로 어떻게 동작하는지 전체 흐름을 정리해보자.

1. 스케줄러가 JobLauncher.run()을 호출한다
2. JobLauncher가 JobRepository에서 이전 실행 이력을 확인한다
3. 새로운 JobExecution을 생성하고 Job을 실행한다
4. Job은 정의된 순서대로 Step을 실행한다
5. 각 Step의 실행 결과가 JobRepository에 기록된다
6. 모든 Step이 완료되면 Job의 상태가 COMPLETED로 갱신된다

자주 하는 실수