Formato cron do Spring
Uma expressão Spring tem seis campos: segundo, minuto, hora, dia do mês, mês e dia da semana, por exemplo 0 0 9 * * MON-FRI para 09:00 nos dias úteis. O domingo pode ser escrito como 0, 7 ou SUN. Desde o Spring Framework 5.3, o parser também entende L, W e # nos campos de dia, além de macros como @hourly e @daily.
Fuso horário do @Scheduled
Por padrão, as expressões são avaliadas no fuso horário padrão do servidor. Defina o atributo zone, por exemplo @Scheduled(cron = "0 0 2 * * *", zone = "America/Sao_Paulo"), para que o agendamento não dependa do host. Escolha o mesmo fuso na ferramenta para conferir as execuções.
Spring x Quartz
As expressões do Spring se parecem com as do Quartz, mas mudam em detalhes: não há campo de ano, o domingo é 0 e não 1, e “?” é aceito, mas não obrigatório. Quando os dois campos de dia são restritos, o Spring exige que ambos coincidam. O conversor mostra o equivalente Quartz quando ele existe.
Ativando o agendamento
Métodos com cron só rodam quando o agendamento é ativado com @EnableScheduling. Por padrão o Spring usa uma única thread, então uma tarefa longa atrasa todos os outros métodos agendados; configure um ThreadPoolTaskScheduler ou spring.task.scheduling.pool.size se tiver várias tarefas. Em cluster, cada instância dispara o mesmo cron — use uma trava como o ShedLock se a tarefa só puder rodar uma vez.
Perguntas frequentes
- Por que o Spring diz que a expressão precisa ter seis campos?
- O Spring precisa de um campo de segundos. Acrescente 0 no início de uma expressão crontab de cinco campos: 0 */5 * * * * roda a cada cinco minutos.
- Como desativo uma tarefa @Scheduled com cron?
- Use o valor especial "-" (Scheduled.CRON_DISABLED), normalmente por meio de um placeholder de propriedade.
- O Spring suporta o último dia do mês?
- Sim, desde a 5.3: 0 0 0 L * * roda à meia-noite do último dia de cada mês.
- Posso ler a expressão cron da configuração?
- Sim, por exemplo @Scheduled(cron = "${jobs.cleanup.cron}"), para que o agendamento mude conforme o ambiente.