[Spring Batch] JobParametersValidator로 안전장치 마련하기

Spring Batch에서 Job은 JobParameters에 따라 동작이 달라지는 경우가 많습니다. 예를 들어, 처리할 파일의 이름이나 특정 날짜를 파라미터로 받곤 하죠.

만약 이 파라미터가 잘못 들어온다면 어떻게 될까요? Job이 중간에 실패하거나, 최악의 경우엔 잘못된 데이터를 처리하여 시스템 전체에 문제를 일으킬 수도 있습니다.

이러한 위험을 막아주는 첫 번째 방어선이 바로 JobParametersValidator입니다. 이번 글에서는 왜, 어떻게 사용해야 하는지 알아보겠습니다.

🧐 왜 파라미터 검증이 필요할까요?

매일 아침 특정 폴더에 생성되는 user_data.csv 파일을 읽어서 처리하는 배치 Job을 만든다고 가정해보겠습니다.

만약 이 fileName 파라미터를 제대로 검증하지 않으면, 어떤 문제 상황이 발생할 수 있을까요?

1. "양식에 맞지 않는 파일 처리 문제": 만약 user_data.csv가 아닌 전혀 다른 형식의 파일을 처리하려고 하면, 데이터를 읽는 단계부터 에러가 나거나, 혹은 운 나쁘게 에러 없이 넘어가더라도 완전히 잘못된 데이터가 DB에 저장될 수 있습니다. Validator는 이런 데이터 오염을 막아주는 첫 번째 방어선이죠.
2. "기록 및 정보 혼동 문제": 배치 작업은 무슨 조건으로 실행했고, 그 결과가 어땠는가를 추적하는 게 굉장히 중요합니다. 잘못된 파라미터로 실행된 기록이 남으면, 나중에 문제의 원인을 찾거나 데이터를 복구할 때 큰 혼란을 일으킬 수 있습니다.

🚀 JobParametersValidator 직접 구현하기

Validator를 만드는 방법은 간단합니다. JobParametersValidator 인터페이스의 validate 메서드를 구현하면 됩니다.

public interface JobParametersValidator {

    void validate(JobParameters parameters) throws JobParametersInvalidException;

}

메서드의 실행 과정은 다음과 같습니다.

1. Job이 실행될 때 모든 파라미터(JobParameters)가 메서드로 전달 됩니다.
2. 리턴 타입이 void인 점은 메서드가 끝나면 그 자체로 성공으로 간주됩니다.
3. 검증 시 문제가 있다면, JobParametersInvalidException 예외를 던져야 하며, 해당 예외 발생 시 Job 실행을 즉시 중단시킵니다.

결국 우리가 할 일은 JobParametersValidator를 구현하는 클래스를 만들고, 그 안에 파라미터를 확인하여 유효하지 않을 때 JobParametersInvalidException을 던지도록 구현하면 됩니다.

@Override
public void validate(JobParameters parameters) throws JobParametersInvalidException {
    String fileName = parameters.getString("fileName");

    if (!StringUtils.hasText(fileName)) {
        throw new JobParametersInvalidException("fileName 파라미터는 필수입니다.");
    }
}

🚀 DefaultJobParametersValidator로 더 간편하게

Spring Batch는 파라미터의 존재 유무를 확인하는 가장 흔한 검증 로직을 위해 DefaultJobParametersValidator라는 기본 구현체를 제공합니다. 이 클래스를 사용하면 필수 파라미터와 선택 파라미터를 지정하는 것만으로 간단하게 검증을 끝낼 수 있습니다.

여기에 더해, 특정 포맷 검증 등 우리만의 커스텀 로직을 추가하고 싶다면 DefaultJobParametersValidator를 상속받아 확장할 수 있습니다.

@Component
public class CustomJobParametersValidator extends DefaultJobParametersValidator {

    public CustomJobParametersValidator() {
        // "fileName", "date"는 필수 파라미터, "version"은 선택 파라미터로 지정
        super(new String[]{"fileName", "date"}, new String[]{"version"});
    }

    @Override
    public void validate(JobParameters parameters) throws JobParametersInvalidException {
        // 1. 부모 클래스의 기본 검증(필수/선택 파라미터 존재 유무)을 먼저 수행합니다.
        super.validate(parameters);

        // 2. 추가적인 커스텀 검증 로직을 구현합니다.
        String date = parameters.getString("date");
        try {
            // date 파라미터가 'yyyy-MM-dd' 형식에 맞는지 검증
            DateTimeFormatter.ISO_LOCAL_DATE.parse(date);
        } catch (DateTimeParseException e) {
            throw new JobParametersInvalidException("date 파라미터는 'yyyy-MM-dd' 형식이어야 합니다.");
        }
    }
}

🚀 Job에 Validator 등록하기

Validator를 만들었다면, 이제 실제 Job에 등록해야 효력이 발생합니다. Job을 설정하는 코드에 .validator() 메서드를 체이닝하여 우리가 만든 Validator를 등록해 줍니다.

@RequiredArgsConstructor  
@Configuration  
public class SimpleJobBatchConfig {  
  
    private final JobRepository jobRepository;  
    private final PlatformTransactionManager transactionManager;  
    private final CustomJobParametersValidator customValidator;

    @Bean
    public Job myJob() {
        return new JobBuilder("myJob", jobRepository)
                .start(step1())
                .validator(customValidator)
                .build();
    }
    // ... Step 설정 ...
}

💡 Validator와 Job 생명주기

JobParametersValidator의 validate() 메서드는 JobLauncher가 Job을 실행하기 바로 직전에 호출됩니다. 즉, Spring Batch의 실행 정보가 담기는 메타데이터 테이블(BATCH_JOB_INSTANCE 등)에 기록이 남기 전에 실행됩니다.

이를 통해 유효하지 않은 파라미터로 인한 Job 실행 시도를 사전에 차단할 수 있습니다. 덕분에 불필요한 실행 기록이 데이터베이스에 남는 것을 방지하여 Job의 이력을 깔끔하게 관리할 수 있습니다.