[SYSTEM BUILD] 4. JobParameters 데이터 타입

1. JobParameters는 문자열로 전달되고 타입으로 변환된다

커맨드라인을 통해 전달되는 JobParameters는 모두 문자열 형태로 입력된다. Spring Batch는 전달된 문자열과 함께 명시된 타입 정보를 기반으로 JobParameters 객체를 생성한다. 이 과정은 DefaultJobParametersConverter가 담당한다.

기본 표기법은 다음과 같다.

parameterName=parameterValue,parameterType,identifyingFlag

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

2. 기본 데이터 타입 파라미터

문자열과 숫자 타입은 가장 일반적으로 사용된다.

./gradlew bootRun --args='
--spring.batch.job.name=dailyAggregationJob
processDate=2024-01-01
batchSize=1000,java.lang.Integer
'

위 예제에서 processDate는 타입을 생략했으므로 String으로 처리된다. batchSize는 Integer 타입으로 명시되어 숫자 타입으로 변환된다.

코드에서는 다음과 같이 주입된다.

@Bean
@StepScope
public Tasklet aggregationTasklet(
    @Value("#{jobParameters['processDate']}") String processDate,
    @Value("#{jobParameters['batchSize']}") Integer batchSize
) {
    return (contribution, chunkContext) -> {
        return RepeatStatus.FINISHED;
    };
}

숫자, Boolean처럼 타입 변환 실패 가능성이 있는 값은 타입을 명시하는 편이 안전하다. 타입을 명시하지 않으면 문자열로 처리되며, 이후 코드에서 직접 변환해야 한다.

3. 날짜와 시간 타입 파라미터

배치에서는 날짜와 시간이 처리 범위를 결정하는 기준으로 자주 사용된다. Spring Batch는 LocalDate, LocalDateTime 타입 변환을 지원한다.

./gradlew bootRun --args='
--spring.batch.job.name=dailyAggregationJob
processDate=2024-01-01,java.time.LocalDate
executionTime=2024-01-01T02:30:00,java.time.LocalDateTime
'

@Bean
@StepScope
public Tasklet aggregationTasklet(
    @Value("#{jobParameters['processDate']}") LocalDate processDate,
    @Value("#{jobParameters['executionTime']}") LocalDateTime executionTime
) {
    return (contribution, chunkContext) -> {
        return RepeatStatus.FINISHED;
    };
}

날짜와 시간 타입은 문자열 포맷이 맞지 않으면 Job 실행 전에 변환 단계에서 예외가 발생한다. 이 시점은 Step 실행 이전이므로, 배치 로직이 시작되기 전이다. 운영 환경에서는 포맷 규칙을 사전에 고정하고 실행 주체와 공유해야 한다.

4. Enum 타입 파라미터

실행 옵션이 제한된 값 집합이라면 Enum 타입을 사용하는 방식이 적합하다. Enum은 실행 가능한 값의 범위를 코드 수준에서 제한한다.

public enum ProcessingMode {
    FULL,
    INCREMENTAL
}

./gradlew bootRun --args='
--spring.batch.job.name=dailyAggregationJob
processingMode=FULL,com.example.batch.ProcessingMode
'

@Bean
@StepScope
public Tasklet aggregationTasklet(
    @Value("#{jobParameters['processingMode']}") ProcessingMode processingMode
) {
    return (contribution, chunkContext) -> {
        return RepeatStatus.FINISHED;
    };
}

Enum 타입은 전달된 문자열이 Enum 상수와 정확히 일치해야 한다. 일치하지 않으면 타입 변환 단계에서 예외가 발생한다. Enum을 내부 클래스로 선언하면 타입 문자열에 $가 포함된다. 운영 환경에서는 top-level Enum을 사용하는 편이 관리에 수월하다.

5. 기본 표기법의 한계와 JSON 기반 표기법

기본 JobParameters 표기법은 쉼표를 구분자로 사용한다. 이로 인해 값 자체에 쉼표가 포함되면 파싱이 불가능해진다.

targetServers=api-1,api-2,java.lang.String

이 경우 api-1이 값인지, 타입인지 구분할 수 없어 파싱에 실패한다.

이를 해결하기 위해 JSON 기반 표기법을 사용할 수 있다.

targetServers='{"value":"api-1,api-2","type":"java.lang.String"}'

JSON 표기법을 사용하려면 JsonJobParametersConverter를 등록해야 한다.

@Bean
public JobParametersConverter jobParametersConverter() {
    return new JsonJobParametersConverter();
}

JSON 기반 표기법은 기본 표기법이 모호해지는 경우에만 사용한다. 모든 파라미터를 JSON으로 전달하는 방식은 권장되지 않는다.