Spring Boot 스케줄러 잡 중복 실행 방지 구현기

Spring Boot 스케줄러 잡 중복 실행 방지 구현기

환경

• Spring Boot 3.2.1
• JPA/Hibernate
• MySQL

문제 상황

운영 환경에서 여러 서버 인스턴스가 동시에 실행될 때, 스케줄러 잡이 중복으로 실행되는 문제가 발생했습니다. 이는 데이터 일관성 문제와 리소스 낭비를 야기할 수 있습니다.

해결 방안: 데이터베이스 기반 잡 락 시스템

1. 잡 상태 관리 엔티티

@Entity
@Getter
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class ScheduleJobStatus {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "id")
    private Long id;

    @Column(name = "job_name", length = 100, nullable = false, unique = true)
    private String jobName;

    @Column(name = "last_status", length = 20, nullable = false)
    @Enumerated(EnumType.STRING)
    @Builder.Default
    @Setter
    private JobStatus lastStatus = JobStatus.NOT_STARTED;

    @Column(name = "last_executed_at")
    @Setter
    private LocalDateTime lastExecutedAt;

    @CreationTimestamp
    @Column(name = "created_at")
    private LocalDateTime createdAt;

    public enum JobStatus {
        NOT_STARTED,    // 대기 중
        RUNNING,        // 실행 중
        COMPLETED,      // 완료
        FAILED          // 실패
    }
}

2. 잡 락 애노테이션

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface JobLock {
    String value() default "";
    boolean throwOnLockFailure() default false;
}

3. 잡 락 매니저

@Service
@RequiredArgsConstructor
public class JobLockManager {

    private final ScheduleJobStatusRepository scheduleJobStatusRepository;

    public boolean acquireLock(String jobName) {
        try {
            log.info("=== Attempting to acquire lock for job: {} ===", jobName);

            Optional<ScheduleJobStatus> existingJob = 
                scheduleJobStatusRepository.findByJobNameForUpdate(jobName);

            if (existingJob.isPresent()) {
                ScheduleJobStatus jobStatus = existingJob.get();
                log.info("Found existing job status: {} - {}", jobName, jobStatus.getLastStatus());

                // 이미 실행 중인 잡이 있는지 확인: 비정상적으로 종료됐을경우 Running 상태로 남아있을수 있다.
                // 10분 이내라면 잡이 이미 실행 중이라고 판단하고 락 획득을 거부
                if (jobStatus.getLastStatus() == ScheduleJobStatus.JobStatus.RUNNING) {
                    LocalDateTime tenMinutesAgo = LocalDateTime.now().minusMinutes(10);
                    if (jobStatus.getLastExecutedAt().isAfter(tenMinutesAgo)) {
                        log.warn("Job '{}' is already running (last executed at: {})", 
                            jobName, jobStatus.getLastExecutedAt());
                        return false;
                    }
                }

                // 기존 잡이 완료/실패 상태라면 새로 시작
                jobStatus.setLastStatus(ScheduleJobStatus.JobStatus.RUNNING);
                jobStatus.setLastExecutedAt(LocalDateTime.now());

                scheduleJobStatusRepository.save(jobStatus);
                log.info("Job '{}' lock acquired (updated existing status)", jobName);
                return true;

            } else {
                // 잡 상태가 존재하지 않는 경우 (초기화되지 않은 잡)
                log.error("Job '{}' status not found. Please ensure job is properly initialized.", jobName);
                return false;
            }

        } catch (Exception e) {
            log.info("Failed to acquire lock for job '{}'", jobName);
            return false;
        }
    }

    public void releaseLock(String jobName, boolean success, String errorMessage) {
        try {
            log.info("=== Releasing lock for job: {} (success: {}) ===", jobName, success);

            Optional<ScheduleJobStatus> jobStatus = 
                scheduleJobStatusRepository.findByJobNameForUpdate(jobName);

            if (jobStatus.isPresent()) {
                ScheduleJobStatus status = jobStatus.get();

                if (success) {
                    status.setLastStatus(ScheduleJobStatus.JobStatus.COMPLETED);
                    log.info("Job '{}' completed successfully", jobName);
                } else {
                    status.setLastStatus(ScheduleJobStatus.JobStatus.FAILED);
                    log.info("Job '{}' failed: {}", jobName, errorMessage);
                }

                status.setLastExecutedAt(LocalDateTime.now());
                scheduleJobStatusRepository.save(status);

            } else {
                log.warn("No job status found to release: '{}'", jobName);
            }

        } catch (Exception e) {
            log.error("Failed to release lock for job '{}'", jobName, e);
        }
    }
}

4. AOP를 통한 자동 락 관리

@Aspect
@Component
@RequiredArgsConstructor
public class JobLockAspect {

    private final JobLockManager jobLockManager;

    @Around("@annotation(jobLock)")
    public Object around(ProceedingJoinPoint joinPoint, JobLock jobLock) throws Throwable {
        MethodSignature signature = (MethodSignature) joinPoint.getSignature();
        Method method = signature.getMethod();

        // 잡 이름 결정 (어노테이션 값이 있으면 사용, 없으면 메서드명 사용)
        String jobName = jobLock.value().isEmpty() ? method.getName() : jobLock.value();

        log.debug("Attempting to acquire lock for job: {}", jobName);

        // 락 획득 시도
        boolean lockAcquired = jobLockManager.acquireLock(jobName);

        if (!lockAcquired) {
            return null; // 조용히 무시
        }

        try {
            log.info("Executing job: {}", jobName);
            Object result = joinPoint.proceed();
            jobLockManager.releaseLock(jobName, true, null);
            log.info("Job '{}' completed successfully", jobName);
            return result;

        } catch (Exception e) {
            String errorMessage = e.getMessage() != null ? e.getMessage() : e.getClass().getSimpleName();
            jobLockManager.releaseLock(jobName, false, errorMessage);
            log.error("Job '{}' failed: {}", jobName, errorMessage, e);
            throw e;
        }
    }
}

5. 리포지토리 - 락 타임아웃 0초 설정

@Repository
public interface ScheduleJobStatusRepository extends JpaRepository<ScheduleJobStatus, Long> {

    @Lock(LockModeType.PESSIMISTIC_WRITE)
    @QueryHints({
        @QueryHint(name = "jakarta.persistence.lock.timeout", value = "0")
    })
    @Query("SELECT sjs FROM ScheduleJobStatus sjs WHERE sjs.jobName = :jobName")
    Optional<ScheduleJobStatus> findByJobNameForUpdate(@Param("jobName") String jobName);
}

6. 스케줄러 사용 예시

@Component
public class DataSyncScheduler {

    @Scheduled(cron = "0 */5 * * * *")
    @JobLock("data-sync-job")
    @Transactional  // 서비스 메서드 단위로 트랜잭션 관리
    public void syncData() {
        log.info("데이터 동기화 시작");
        // 실제 작업 로직
        log.info("데이터 동기화 완료");
    }
}

7. 잡 락 테스트 예시

실제로 잡 락이 제대로 작동하는지 테스트해보겠습니다:

@Component
@RequiredArgsConstructor
public class JobLockTestScheduler {

    @SneakyThrows
    @Transactional
    @Scheduled(cron = "*/5 * * * * *")  // 5초마다 실행
    @JobLock("job-lock-test")
    public void test1() {
        log.info("=== [TEST1] job-lock-test 선점 테스트 1 시작 (Thread: {}) ===", 
                Thread.currentThread().getName());
        Thread.sleep(8000);  // 8초 대기 (다음 실행과 겹치도록)
        log.info("=== [TEST1] job-lock-test 선점 테스트 1 완료 ===");
    }

    @SneakyThrows
    @Transactional
    @Scheduled(cron = "*/5 * * * * *")  // 5초마다 실행 (같은 시간에 실행되도록)
    @JobLock("job-lock-test")
    public void test2() {
        log.info("=== [TEST2] job-lock-test 선점 테스트 2 시작 (Thread: {}) ===", 
                Thread.currentThread().getName());
        Thread.sleep(2000);  // 2초 대기
        log.info("=== [TEST2] job-lock-test 선점 테스트 2 완료 ===");
    }
}

8. 스레드 풀 설정의 중요성

초기 문제: 처음에는 잡 락이 제대로 작동하지 않았습니다. 이유는 Spring의 기본 스케줄러가 단일 스레드로 실행되기 때문이었습니다.

문제 상황: 단일 스레드에서는 스케줄러가 순차적으로 실행되므로, 같은 잡 이름을 가진 메서드들이 동시에 실행되지 않아 스레드 간 경합이 일어나지 않는 상황이었습니다.

# application.yml
spring:
  task:
    scheduling:
      pool:
        size: 10  # 스레드 풀 크기 설정
      thread-name-prefix: "Scheduler-"

해결 후 결과:

=== [TEST1] job-lock-test 선점 테스트 1 시작 (Thread: Scheduler-1) ===
=== [TEST2] job-lock-test 선점 테스트 2 시작 (Thread: Scheduler-2) ===
Job 'job-lock-test' is already running
=== [TEST1] job-lock-test 선점 테스트 1 완료 ===

스레드 풀을 설정한 후에는 서로 다른 스레드에서 실행되어 정상적으로 락 경합이 발생했습니다.

핵심 포인트

1. 스레드 풀 설정

Spring의 기본 스케줄러는 단일 스레드로 실행되므로, 병렬 실행을 위해 스레드 풀을 설정해야 합니다.

spring:
  task:
    scheduling:
      pool:
        size: 10
      thread-name-prefix: "Scheduler-"

2. 트랜잭션 관리

스케줄러 메서드에 @Transactional을 적용하여 서비스 메서드 단위로 트랜잭션을 관리합니다. 잡 락 매니저는 트랜잭션 애노테이션을 제거하고 호출하는 메서드의 트랜잭션에 참여하도록 합니다.

3. 비정상 종료 처리

10분 이내에 실행된 RUNNING 상태의 잡이 있으면 이미 실행 중으로 판단하여 락 획득을 거부합니다. 이를 통해 비정상 종료된 잡으로 인한 데드락을 방지합니다.

4. 락 타임아웃 0초

for update nowait을 사용하여 즉시 락 획득 실패 시 대기하지 않습니다.

결과

이 구현을 통해:

• ✅ 여러 서버 인스턴스에서 동일한 잡의 중복 실행 방지
• ✅ 데이터베이스 레벨에서의 안전한 락 관리
• ✅ 간단한 애노테이션으로 잡 락 적용
• ✅ 자동 상태 관리 및 에러 처리

운영 환경에서 안정적인 스케줄러 실행을 보장할 수 있게 되었습니다.