운영 배치의 가장 흔한 사고 중 하나는 이거다.
“어제 배치가 또 돌았어요.”
Job은 잘 실행됐는데,
데이터는 두 번 반영되었다.
이건 코드 문제가 아니라,
대부분 JobParameter 설계 부재 때문이다.
Spring Batch에서 JobParameter는
“이번 실행이 어떤 데이터 범위를 처리하는가”를 명확히 구분해주는 기준점이다.
그리고 그 설계가 재처리 가능한 배치인지, 중복 실행이 안전한 배치인지를 결정한다.
1. JobParameter는 ‘실행 구분자(Execution Key)’다
Spring Batch는 같은 Job 이름이라도,
JobParameter 조합이 다르면 새로운 JobInstance를 생성한다.
JobParameters params = new JobParametersBuilder()
.addString("date", "2025-10-17")
.toJobParameters();
jobLauncher.run(myJob, params);
→ date 값이 다르면 다른 실행으로 인식
→ date 값이 같으면 기존 실행(JobInstance)을 재참조
즉 JobParameter는 단순한 인자값이 아니라,
“운영 배치의 실행 이력 구조를 결정하는 키”다.
2. 중복 실행을 막는 기본 원리
Spring Batch는 내부적으로BATCH_JOB_INSTANCE 테이블에 JobName + JobParameters 조합을 저장한다.
- 이미 동일한 조합이 존재하면 → JobInstanceAlreadyCompleteException 발생
- 새로운 조합이면 → 새 JobInstance 생성
💡 따라서 매일 돌리는 Job이라면
반드시 날짜 기반 JobParameter를 넣어야 한다.
예시:
.addString("jobDate", LocalDate.now().toString())
날짜를 넣지 않으면,
오늘 실행과 어제 실행이 동일한 인스턴스로 인식되어 “이미 실행됨” 오류가 발생한다.
3. JobParameter 설계 패턴 3가지
| 목적 | 예시 | 설명 |
|---|---|---|
| 일별 실행형 | jobDate=2025-10-17 | 매일 한 번씩 도는 배치 (기준일 구분) |
| 파일형 | fileName=input_20251017.csv | 파일명 단위로 JobInstance 구분 |
| 업무 단위형 | taskId=APPLY_EXPENSE_20251017 | 특정 업무(보험 청구, 정산 등) 단위 실행 |
이런 Parameter 조합으로 설계하면
운영에서 JobInstance를 명확히 식별할 수 있고,
중복 실행이나 잘못된 재처리를 방지할 수 있다.
4. 재처리(Recovery) 시 JobParameter 설계 주의점
재처리를 할 때 가장 많이 하는 실수는
JobParameter를 바꾸면 동일한 Job으로 인식되지 않는다는 점이다.
예를 들어,
jobDate=2025-10-17
로 실행된 Job이 실패했을 때,
재처리 시 jobDate=2025-10-17-R로 실행하면
→ Spring Batch는 “다른 JobInstance”로 인식
→ 이전 실패 Step을 이어받지 못함
💡 따라서 재처리 시에는 JobParameter를 동일하게 유지해야
StepExecution의 restart 기능이 작동한다.
재처리 Job = 동일 JobInstance의 새로운 JobExecution
5. 재처리 플래그를 분리하는 전략
그럼 재처리 여부는 어떻게 구분할까?
JobParameter 외에 비영향성 파라미터를 추가하면 된다.
JobParameters params = new JobParametersBuilder()
.addString("jobDate", "2025-10-17")
.addLong("run.id", System.currentTimeMillis()) // Spring에서 내부적으로 무시됨
.toJobParameters();
run.id는 JobInstance 생성 시 무시되는 내부 식별자- 동일 JobParameter라도 매번 다른 Execution을 만들 수 있음
- 즉, “같은 데이터, 다른 실행 이력” 구조가 가능하다.
6. JobParameter를 통한 재처리 관리 테이블 설계 예시
운영에서 재처리 이력을 체계적으로 관리하려면
별도 JobParameter 로그 테이블을 두는 게 좋다.
CREATE TABLE TB_BATCH_RUN_PARAM (
JOB_NAME VARCHAR(100),
JOB_DATE VARCHAR(10),
EXECUTION_ID BIGINT,
PARAM_KEY VARCHAR(100),
PARAM_VALUE VARCHAR(200),
STATUS VARCHAR(20),
REG_DTM TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
→ 재처리 여부, 실행자, 실행 시점, 파라미터를 모두 기록해
운영 배치 로그와 연동하면 완벽히 추적 가능하다.
7. JobParameter 관리 실무 팁
1️⃣ 모든 Job은 Parameter를 요구하게 설계하라
→ 개발자가 수동 실행 시에도 누락되지 않게 유효성 검증 추가
2️⃣ Parameter는 JobExecutionContext에도 복사하라
→ Step 단위에서 바로 참조 가능
ExecutionContext context = stepExecution.getExecutionContext();
context.put("jobDate", jobParameters.getString("jobDate"));
3️⃣ 운영 기준일(배치 기준일)과 시스템 일자를 분리하라
→ 전일자 정산 배치 등에서 baseDate를 별도 파라미터로 지정
8. 설계 예시 — 보험 정산 배치 기준
| Job Name | Parameter | 설명 |
|---|---|---|
PAAplyExprOBDentalLJob | baseDate=2025-10-17 | 정산 기준일 |
PAClaimSettleJob | claimDate=2025-10-16 | 전일 청구 정산 |
PAFileExportJob | fileName=export_OBDental_20251017.csv | 파일 단위 실행 |
이 구조로 설계해두면
실패한 Job은 같은 파라미터로 재실행 가능하고,
이전 이력과 혼동되지 않는다.
마치며
Spring Batch의 JobParameter는
단순히 “인자값”이 아니라 운영 배치의 생명선이다.
정확한 파라미터 설계는
- 중복 실행 방지,
- 재처리 안정성 확보,
- 데이터 정합성 유지
이 세 가지를 동시에 달성하게 해준다.
좋은 배치는 좋은 파라미터 설계에서 시작된다.