@Scheduled — 주기적 작업을 스프링에서 실행하는 방법

@Configuration
@EnableScheduling  // 필수: 스케줄링 활성화
public class SchedulingConfig {
}

@Component
@Slf4j
public class MetricsCollector {

    // 10초마다 실행 (이전 작업이 끝나지 않아도 시간이 되면 실행 예약)
    @Scheduled(fixedRate = 10_000)
    public void collectMetrics() {
        log.info("메트릭 수집 시작");
        // 서버 상태, 메모리 사용량 등 수집
    }

    // 문자열로 외부 설정 가능
    @Scheduled(fixedRateString = "${metrics.collect.interval:10000}")
    public void collectMetricsConfigurable() {
        // application.yml에서 간격 설정
    }
}

@Component
public class ExternalApiPoller {

    // 이전 작업이 끝나고 5초 후 다시 실행
    @Scheduled(fixedDelay = 5_000)
    public void pollExternalApi() {
        // 외부 API 호출 — 응답 시간이 가변적일 때 적합
        List<Event> events = externalApi.fetchNewEvents();
        eventProcessor.process(events);
    }

    // 애플리케이션 시작 후 30초 뒤에 첫 실행
    @Scheduled(fixedDelay = 5_000, initialDelay = 30_000)
    public void pollWithInitialDelay() {
        // 초기화가 완료된 후에 실행
    }
}

초  분  시  일  월  요일
0   0   2   *   *   *      → 매일 새벽 2시
0   */5 *   *   *   *      → 5분마다
0   0   9   *   *   MON-FRI → 평일 오전 9시
0   0   0   1   *   *      → 매월 1일 자정

@Component
public class DailyBatchJob {

    // 매일 새벽 2시에 실행
    @Scheduled(cron = "0 0 2 * * *")
    public void cleanupExpiredData() {
        log.info("만료 데이터 정리 시작");
        dataCleanupService.removeExpiredRecords();
    }

    // 평일 오전 9시에 리포트 생성
    @Scheduled(cron = "0 0 9 * * MON-FRI")
    public void generateDailyReport() {
        reportService.createDailyReport();
    }

    // 타임존 지정
    @Scheduled(cron = "0 0 2 * * *", zone = "Asia/Seoul")
    public void seoulTimeJob() {
        // 한국 시간 기준 새벽 2시
    }

    // 외부 설정으로 cron 표현식 관리
    @Scheduled(cron = "${batch.cleanup.cron:0 0 2 * * *}")
    public void configurableCronJob() {
        // application.yml에서 cron 변경 가능
    }
}

fixedRate = 5초, 작업 시간 = 3초인 경우:
|--작업(3초)--|--대기(2초)--|--작업(3초)--|--대기(2초)--|
0            3            5            8           10

fixedDelay = 5초, 작업 시간 = 3초인 경우:
|--작업(3초)--|----대기(5초)----|--작업(3초)--|----대기(5초)----|
0            3               8            11              16

@Configuration
public class SchedulerConfig implements SchedulingConfigurer {

    @Override
    public void configureTasks(ScheduledTaskRegistrar registrar) {
        ThreadPoolTaskScheduler scheduler = new ThreadPoolTaskScheduler();
        scheduler.setPoolSize(5);                    // 스레드 5개
        scheduler.setThreadNamePrefix("scheduler-");
        scheduler.setErrorHandler(t ->
            log.error("스케줄 작업 에러: ", t));       // 에러 핸들링
        scheduler.setWaitForTasksToCompleteOnShutdown(true);
        scheduler.setAwaitTerminationSeconds(30);
        scheduler.initialize();

        registrar.setTaskScheduler(scheduler);
    }
}

spring:
  task:
    scheduling:
      pool:
        size: 5
      thread-name-prefix: scheduler-
      shutdown:
        await-termination: true
        await-termination-period: 30s

@Scheduled(fixedRate = 60_000)
public void robustScheduledTask() {
    try {
        riskyOperation();
    } catch (TransientException e) {
        // 일시적 오류 — 다음 실행에서 재시도
        log.warn("일시적 오류, 다음 실행에서 재시도: {}", e.getMessage());
    } catch (Exception e) {
        // 심각한 오류 — 알림 발송
        log.error("스케줄 작업 실패: ", e);
        alertService.sendAlert("스케줄 작업 실패: " + e.getMessage());
    }
}

// build.gradle
implementation 'net.javacrumbs.shedlock:shedlock-spring:5.16.0'
implementation 'net.javacrumbs.shedlock:shedlock-provider-jdbc-template:5.16.0'

CREATE TABLE shedlock (
    name       VARCHAR(64)  NOT NULL PRIMARY KEY,
    lock_until TIMESTAMP(3) NOT NULL,
    locked_at  TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
    locked_by  VARCHAR(255) NOT NULL
);

@Configuration
@EnableSchedulerLock(defaultLockAtMostFor = "10m")
public class ShedLockConfig {

    @Bean
    public LockProvider lockProvider(DataSource dataSource) {
        return new JdbcTemplateLockProvider(
            JdbcTemplateLockProvider.Configuration.builder()
                .withJdbcTemplate(new JdbcTemplate(dataSource))
                .usingDbTime()   // DB 서버 시간 사용
                .build()
        );
    }
}

@Component
public class DistributedBatchJob {

    @Scheduled(cron = "0 0 2 * * *")
    @SchedulerLock(
        name = "cleanupExpiredData",     // 락 이름 (고유해야 함)
        lockAtLeastFor = "5m",           // 최소 잠금 유지 시간
        lockAtMostFor = "30m"            // 최대 잠금 유지 시간
    )
    public void cleanupExpiredData() {
        // 여러 인스턴스 중 하나만 실행
        dataCleanupService.removeExpiredRecords();
    }
}

@Service
@RequiredArgsConstructor
public class DynamicSchedulerService {
    private final TaskScheduler taskScheduler;
    private ScheduledFuture<?> scheduledFuture;

    public void scheduleTask(String cronExpression) {
        // 기존 스케줄 취소
        if (scheduledFuture != null) {
            scheduledFuture.cancel(false);
        }

        // 새로운 스케줄 등록
        scheduledFuture = taskScheduler.schedule(
            () -> {
                log.info("동적 스케줄 작업 실행");
                executeTask();
            },
            new CronTrigger(cronExpression)
        );
    }

    public void cancelTask() {
        if (scheduledFuture != null) {
            scheduledFuture.cancel(false);
            scheduledFuture = null;
        }
    }
}