[SYSTEM BUILD] 3. JobParameters 주입

1. 프로퍼티와 JobParameters의 차이

Spring Batch에서 프로퍼티와 JobParameters는 역할이 다르다.
프로퍼티는 애플리케이션 환경 설정 값이다. 애플리케이션 구동 시점에 한 번 로딩되며, Spring Batch 메타데이터에 저장되지 않는다. 따라서 프로퍼티 값은 JobInstance 식별, 실행 이력 관리, 재실행 판단의 기준이 될 수 없다.

JobParameters는 배치 실행의 입력값이다. Spring Batch는 Job과 JobParameters의 조합으로 JobInstance를 식별한다. 전달된 JobParameters는 메타데이터 저장소에 기록되며, 이 정보는 배치 실행 이력과 재실행 가능 여부 판단에 사용된다.

같은 Job이라도 JobParameters가 다르면 서로 다른 JobInstance로 인식된다. 반대로 Job과 JobParameters가 모두 동일하면 이미 실행된 JobInstance로 판단된다.

2. 커맨드라인에서 JobParameters 전달하기

실무 환경에서 배치는 대부분 커맨드라인을 통해 실행된다. 크론, Jenkins, Airflow와 같은 스케줄러는 애플리케이션 내부 구조를 알지 못하며, 단순히 실행 명령과 전달할 값을 정의한다.

Spring Boot 환경에서 Spring Batch를 사용할 경우, 커맨드라인 인자는 Spring Boot 애플리케이션 옵션과 JobParameters로 구분되어 해석된다.

./gradlew bootRun --args='
--spring.batch.job.name=dailyJob
processDate=2026-01-01
'

--spring.batch.job.name는 Spring Boot 애플리케이션 옵션이다. 실행할 Job을 지정하는 역할을 하며, 애플리케이션 컨텍스트에 여러 Job 빈이 등록되어 있는 경우 필수로 지정해야 한다.

그 뒤에 전달되는 processDate=2026-01-01은 JobParameters로 해석된다. JobParameters의 기본 표기법은 다음과 같다.

parameterName=parameterValue,parameterType,identifyingFlag

타입과 identifying 여부는 생략할 수 있다. 타입을 생략하면 String으로 처리되며, identifyingFlag를 생략하면 true로 처리된다. 위 예제는 다음과 동일하다.

processDate=2026-01-01,String,true

이 경우 processDate는 JobInstance 식별 기준에 포함된다. 따라서 dailyJob을 동일한 processDate 값으로 다시 실행하면 이미 실행된 JobInstance로 판단되어 예외가 발생한다.

같은 입력값으로 배치를 다시 실행해야 하는 경우에는 식별에 사용되지 않는 파라미터를 추가한다.

./gradlew bootRun --args='
--spring.batch.job.name=dailyJob
processDate=2026-01-01
requestTime=1700000000000,Long,false
'

이 경우 JobInstance 식별에는 processDate만 사용되며, requestTime은 실행 구분을 위한 값으로만 사용된다.

3. POJO를 활용한 JobParameters 주입

JobParameters가 늘어나면 Tasklet이나 Reader에서 개별 파라미터를 직접 참조하는 방식은 관리가 어려워진다. 이 경우 JobParameters를 하나의 POJO로 묶어 사용하는 방식이 적합하다.

@Component
@StepScope
public class DailyJobParameters {

    @Value("#{jobParameters['processDate']}")
    private String processDate;

    public String getProcessDate() {
        return processDate;
    }
}

이 객체에는 @StepScope 또는 @JobScope가 필요하다. JobParameters는 Job 실행 시점에만 유효하므로, 애플리케이션 구동 시점에 생성되는 싱글톤 빈에서는 주입할 수 없다.

Tasklet에서는 해당 POJO를 의존성으로 받아 사용한다.

@Bean
@StepScope
public Tasklet dailyTasklet(DailyJobParameters parameters) {
    return (contribution, chunkContext) -> {
        String date = parameters.getProcessDate();
        // 해당 날짜 데이터 처리
        return RepeatStatus.FINISHED;
    };
}

이 방식은 파라미터 구조를 코드로 명시할 수 있으며, 파라미터 변경 시 영향 범위를 제한할 수 있다.

4. 프로그래밍 방식으로 JobParameters 전달하기

배치를 커맨드라인이 아닌 코드에서 직접 실행해야 하는 경우에는 JobLauncher를 사용해 JobParameters를 생성하고 전달한다.

JobParameters jobParameters = new JobParametersBuilder()
    .addString("processDate", "2026-01-01")
    .toJobParameters();

jobLauncher.run(dailyJob, jobParameters);

같은 입력값으로 배치를 반복 실행해야 하는 경우에는 식별에 사용하지 않는 파라미터를 추가한다.

JobParameters jobParameters = new JobParametersBuilder()
    .addString("processDate", "2026-01-01")
    .addLong("requestTime", System.currentTimeMillis(), false)
    .toJobParameters();

JobParameters에서 identifying 여부는 다음 기준으로 구분된다.

• 배치 실행 결과에 영향을 주는 입력값은 identifying=true
• 실행을 구분하기 위한 값은 identifying=false