02. Шедулинг

Базовое использование: @EnableScheduling + @Scheduled

Декларативный шедулинг в Spring включается одной аннотацией на конфигурационном классе и размечает методы, которые должны выполняться по расписанию:

@Configuration
@EnableScheduling
class SchedulingConfig {
}

@Component
class OrderReconciliationJob {

    // Следующий запуск стартует через fixedDelay ПОСЛЕ ЗАВЕРШЕНИЯ предыдущего
    @Scheduled(fixedDelay = 30_000)
    void reconcilePendingOrders() {
        orderService.reconcile();
    }

    // Запуск СТРОГО каждые 60 секунд от начала предыдущего запуска,
    // независимо от того, успел ли он завершиться
    @Scheduled(fixedRate = 60_000, initialDelay = 10_000)
    void refreshExchangeRates() {
        rateService.refresh();
    }

    // Cron-выражение: 6 полей (сек мин час день месяц день-недели),
    // выполнить в 02:00 каждый будний день
    @Scheduled(cron = "0 0 2 * * MON-FRI", zone = "Europe/Moscow")
    void nightlySettlement() {
        settlementService.runNightly();
    }
}

Механика внутри: ScheduledAnnotationBeanPostProcessor

В отличие от @Retryable/@Async/@Transactional, шедулинг не создаёт AOP-прокси — вызов размеченного метода не нужно перехватывать на каждом обращении, потому что вызывающей стороны как таковой нет: метод вызывается не пользовательским кодом, а самим фреймворком по таймеру. Поэтому механика проще и один раз выполняется на старте контекста:

1. @EnableScheduling импортирует SchedulingConfiguration, которая регистрирует бин ScheduledAnnotationBeanPostProcessor
2. На фазе postProcessAfterInitialization этот BeanPostProcessor сканирует методы каждого бина в поисках @Scheduled (и мета-аннотации @Schedules для нескольких расписаний на одном методе)
3. Для каждого найденного метода атрибуты аннотации конвертируются в объект Trigger: cron → CronTrigger, fixedRate/fixedDelay → PeriodicTrigger
4. Метод оборачивается в Runnable (обычный рефлективный вызов — ScheduledMethodRunnable) и регистрируется в ScheduledTaskRegistrar
5. ScheduledTaskRegistrar передаёт задачи в бин TaskScheduler, который непосредственно ставит их в очередь исполнения (под капотом почти всегда — обёртка вокруг java.util.concurrent.ScheduledExecutorService)

// Упрощённо: что TaskScheduler.schedule(task, trigger) делает при
// каждом срабатывании — вычисляет следующий момент запуска через Trigger
// и заново регистрирует одноразовый ScheduledFuture в ScheduledExecutorService
Instant nextExecution = trigger.nextExecution(triggerContext);
Duration delay = Duration.between(Instant.now(), nextExecution);
executor.schedule(() -> {
    task.run();
    scheduleNext(task, trigger); // пересчитать и запланировать следующий запуск
}, delay.toMillis(), TimeUnit.MILLISECONDS);

Дефолтный TaskScheduler: главная ловушка — один поток на все задачи

Если в контексте не объявлен собственный бин TaskScheduler, Spring Boot создаёт дефолтный через TaskSchedulingAutoConfiguration. Классическая, годами известная ловушка: если этот дефолт не настроен явно, он опирается на один поток — а значит все @Scheduled-методы во всём приложении фактически выполняются последовательно, конкурируя за единственный поток. Одна зависшая задача блокирует расписание вообще всех остальных.

# application.yml — минимально необходимая настройка пула
# для дефолтного ThreadPoolTaskScheduler
spring:
  task:
    scheduling:
      pool:
        size: 10
      thread-name-prefix: "scheduling-"
      shutdown:
        await-termination: true
        await-termination-period: 20s

Либо — эквивалентно, но программно, если нужна более тонкая настройка (кастомный ErrorHandler, конкретный ThreadFactory):

@Configuration
@EnableScheduling
class SchedulingConfig {

    @Bean
    TaskScheduler taskScheduler() {
        ThreadPoolTaskScheduler scheduler = new ThreadPoolTaskScheduler();
        scheduler.setPoolSize(10);
        scheduler.setThreadNamePrefix("scheduling-");
        scheduler.setErrorHandler(t -> log.error("Scheduled task failed", t));
        return scheduler;
    }
}

Кастомный планировщик на виртуальных потоках: SimpleAsyncTaskScheduler

Начиная со Spring Framework 6.1 (и как дефолт-опция в Spring Boot 4 через spring.threads.virtual.enabled=true) появился альтернативный TaskScheduler — SimpleAsyncTaskScheduler. В отличие от ThreadPoolTaskScheduler, который держит фиксированный пул платформенных потоков и переиспользует их, SimpleAsyncTaskScheduler создаёт новый поток на каждое выполнение задачи — и умеет делать это виртуальными потоками через setVirtualThreads(true) (под капотом — Executors.newVirtualThreadPerTaskExecutor()).

@Configuration
@EnableScheduling
class VirtualThreadSchedulingConfig {

    @Bean
    TaskScheduler taskScheduler() {
        SimpleAsyncTaskScheduler scheduler = new SimpleAsyncTaskScheduler();
        scheduler.setVirtualThreads(true);
        scheduler.setThreadNamePrefix("vt-scheduling-");
        // Опциональный "мягкий" бульхед: не более 50 одновременно
        // ВЫПОЛНЯЮЩИХСЯ задач, несмотря на дешевизну виртуальных потоков —
        // защищает downstream-ресурсы (БД, внешние API), а не сам поток
        scheduler.setConcurrencyLimit(50);
        return scheduler;
    }
}

Или ещё проще — если в проекте достаточно включить единый флаг, Boot 4 сам подставит виртуальные потоки и для шедулера, и для дефолтного @Async-экзекьютора:

# application.yml
spring:
  threads:
    virtual:
      enabled: true

Почему это уместно именно для шедулинга: типичные @Scheduled-задачи (опрос БД, вызов внешнего API, обработка очереди) — это I/O-bound работа с долгими периодами блокировки на ожидании ответа, а не CPU-bound вычисления. Именно такая нагрузка — идеальный кандидат для виртуальных потоков: пока поток заблокирован на сетевом или JDBC-вызове, он не занимает платформенный carrier-поток (при условии, что блокировка честно «отпускает» carrier — см. предостережение про pinning ниже), поэтому сотни параллельно выполняющихся задач обходятся системе почти бесплатно по сравнению с эквивалентным пулом из сотен платформенных потоков.

Связка с @Async на виртуальных потоках

@Scheduled и @Async решают разные задачи (когда запускать vs как не блокировать вызывающий поток), но часто используются вместе: шедулер запускает лёгкий метод-триггер, а тяжёлая работа делегируется в @Async-метод, чтобы шедулер не держал свой (пусть даже виртуальный) поток на всё время долгой обработки и мог вовремя запланировать следующий тик.

@Configuration
@EnableAsync
class AsyncConfig {

    // Имя бина "applicationTaskExecutor" или "taskExecutor" — Spring
    // Boot использует его как дефолтный Executor и для @Async, и для
    // ThreadPoolTaskExecutorBuilder, если бин объявлен явно
    @Bean("applicationTaskExecutor")
    Executor applicationTaskExecutor() {
        SimpleAsyncTaskExecutor executor = new SimpleAsyncTaskExecutor("async-vt-");
        executor.setVirtualThreads(true);
        executor.setConcurrencyLimit(100); // защита downstream, не самого пула
        return executor;
    }
}

@Component
class OutboundNotificationJob {

    private final NotificationService notificationService;

    // Шедулер (тоже на виртуальных потоках) вызывает лёгкий метод,
    // который лишь ставит задачи в работу и сразу освобождается
    @Scheduled(fixedDelay = 15_000)
    void dispatchPendingNotifications() {
        notificationService.findPending().forEach(notificationService::sendAsync);
    }
}

@Service
class NotificationService {

    // Каждый вызов уходит в отдельный виртуальный поток из
    // applicationTaskExecutor и не блокирует вызывающую сторону
    @Async
    CompletableFuture<Void> sendAsync(Notification notification) {
        deliveryClient.send(notification); // блокирующий I/O — ок для virtual thread
        return CompletableFuture.completedFuture(null);
    }
}

Здесь работают два независимых Executor на виртуальных потоках с разной ролью: TaskScheduler отвечает за таймер («когда запускать») и не должен занимать поток дольше, чем нужно для диспетчеризации; @Async-Executor отвечает за фактическое выполнение потенциально долгой работы и содержит собственный setConcurrencyLimit — важно понимать, что лимит здесь ограничивает не «потоки» (они почти бесплатны), а реальную нагрузку на downstream-зависимости (пул соединений к БД, rate limit внешнего API), которые остаются дорогим ресурсом независимо от модели потоков.

Программный шедулинг и кастомный Trigger

Помимо декларативного @Scheduled, TaskScheduler можно внедрить как обычный бин и использовать императивно — полезно, когда расписание конкретной задачи вычисляется динамически (например, зависит от настроек в БД) или когда логика следующего запуска сложнее, чем выражается cron-строкой:

class BusinessDaysTrigger implements Trigger {

    private final LocalTime runAt;

    BusinessDaysTrigger(LocalTime runAt) {
        this.runAt = runAt;
    }

    @Override
    public Instant nextExecution(TriggerContext context) {
        ZonedDateTime candidate = ZonedDateTime.now().with(runAt);
        if (context.lastActualExecution() != null && !candidate.isAfter(ZonedDateTime.now())) {
            candidate = candidate.plusDays(1);
        }
        while (isWeekendOrHoliday(candidate.toLocalDate())) {
            candidate = candidate.plusDays(1);
        }
        return candidate.toInstant();
    }
}

@Component
class SettlementScheduler {

    SettlementScheduler(TaskScheduler taskScheduler) {
        taskScheduler.schedule(
            this::runSettlement,
            new BusinessDaysTrigger(LocalTime.of(2, 0))
        );
    }

    private void runSettlement() { /* ... */ }
}

taskScheduler.schedule(task, trigger) возвращает ScheduledFuture<?>, который можно сохранить и вызвать на нём cancel(false) для отмены задачи в рантайме — то, что недоступно декларативному @Scheduled, у которого расписание фиксировано на этапе старта контекста.

Множество инстансов: проблема дублирующегося запуска

@Scheduled — механизм уровня одного JVM-процесса: он ничего не знает о других инстансах приложения. При горизонтальном масштабировании (несколько подов/инстансов одного сервиса) каждый инстанс независимо запустит одну и ту же задачу по одному и тому же расписанию — для идемпотентных задач это может быть безобидно (пустая работа), но для неидемпотентных (например, «отправить email-дайджест раз в сутки») это прямой баг дублирования.

Сам Spring эту проблему не решает — для распределённой блокировки задач между инстансами применяют внешние библиотеки (например, ShedLock, которая через аннотацию @SchedulerLock берёт распределённую блокировку в БД/Redis перед выполнением) либо переносят действительно критичные по единственности исполнения задачи на выделенный worker-компонент вместо декларативного @Scheduled в каждом реплицированном инстансе веб-сервиса.

Сравнение вариантов TaskScheduler