Calcular as próximas execuções de uma expressão cron

Uma expressão cron é uma cadeia curta que descreve uma recorrência no tempo. O formato herdado de Unix cabe em cinco campos separados por espaços: minuto, hora, dia do mês, mês e dia da semana. Esta sintaxe nasceu com o demónio cron de Brian Kernighan nos anos 1970, depois generalizado pelo Vixie cron (1987) retomado por todas as distribuições Linux e macOS modernas. Atualmente, a mesma sintaxe encontra-se na maioria dos agendadores cloud (AWS EventBridge, GCP Cloud Scheduler, Azure Logic Apps) e CI/CD (GitHub Actions, GitLab CI, Jenkins).

┌──── minute (0-59)
│ ┌── heure (0-23)
│ │ ┌── jour du mois (1-31)
│ │ │ ┌── mois (1-12 ou JAN-DEC)
│ │ │ │ ┌── jour de la semaine (0-7 ou SUN-SAT, 0 et 7 = dimanche)
│ │ │ │ │
* * * * *

Uma expressão cron bem formada define portanto um cron schedule preciso: cada campo pode ser um valor fixo, um intervalo, uma lista, um passo ou um asterisco que corresponde a tudo. A compacidade da expressão crontab é a sua força, mas é também o que torna um cron decoder indispensável para validar visualmente a intenção. É todo o objeto deste cron converter: produzir uma explicação cron legível e a lista das próximas execuções.

Os cinco campos partilham uma gramática comum. Eis os limites aceites por cada coluna de uma expressão crontab padrão:

• Minuto: 0-59.
• Hora: 0-23, formato 24h.
• Dia do mês: 1-31.
• Mês: 1-12 ou as abreviaturas textuais JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC.
• Dia da semana: 0-7 em que 0 e 7 representam ambos domingo, ou as abreviaturas SUN, MON, TUE, WED, THU, FRI, SAT.

Caracteres especiais partilhados pelos cinco campos:

• *: any value, corresponde a todos os valores permitidos do campo.
• ,: lista discreta, por exemplo 1,15,30 no campo minuto.
• -: intervalo inclusivo, por exemplo 9-17 para o horário de escritório.
• /: passo (step), por exemplo */15 = a cada 15 unidades, ou 0-30/5 = a cada 5 minutos entre 0 e 30.

Extensões Quartz (Java, AWS EventBridge, Spring): a gramática sobe para 6 ou 7 campos com uma coluna segundos no início (0-59) e por vezes uma coluna ano no fim (1970-2099). O Quartz introduz também ? (no specific value, para desacoplar dia-do-mês e dia-da-semana), L (last: último dia do mês, ou última sexta com 5L), W (dia útil mais próximo) e # (N-ésimo dia da semana do mês, por exemplo 2#3 para a 3ª segunda-feira). Uma expressão Quartz não é, em geral, compatível com um crontab UNIX, e vice-versa: é a principal fonte de erro quando se copia uma expressão cron de uma plataforma para outra.

# UNIX / Vixie cron (5 champs)
0 9 * * 1-5

# Quartz (6 champs avec secondes)
0 0 9 ? * MON-FRI

# Quartz (7 champs avec année)
0 0 9 ? * MON-FRI 2026

Ler 0 0 * * * é rápido. Ler */7 2-5 1,15 * 1-5 já não é. Quando uma expressão sai do trivial, o risco de erro de interpretação aumenta e a descodificação cron torna-se uma etapa de revisão por direito próprio.

• Debug em produção: perceber porque é que uma tarefa disparou às 03h17 e não às 03h00, ou identificar uma sobreposição entre dois jobs.
• Code review: validar que um agendador colocado em pull request faz mesmo o que o autor afirma, sem ter de memorizar a semântica de cada símbolo.
• Auditoria de agendadores: passar em revista os cron jobs Linux em /etc/crontab e /etc/cron.d/, os triggers do Jenkins, os spec.schedule dos Kubernetes CronJob, as regras AWS EventBridge e os jobs GCP Cloud Scheduler.
• Migração legacy: pegar num /etc/crontab histórico sem documentação e reconstruir o mapeamento das tarefas antes de uma mudança de infraestrutura.
• Onboarding: permitir que um novo programador releia uma crontab sem ter de aprender todos os caracteres especiais de um dia para o outro.

Os passos para descodificar uma expressão crontab com a ferramenta:

1. Cole a sua expressão cron no campo de entrada (5 campos separados por espaços).
2. Indique o número de próximas execuções a calcular.
3. Clique em convert para iniciar a descodificação cron: a ferramenta devolve uma frase humana que explica o disparo, mais a lista datada das próximas execuções.
4. Verifique visualmente que as datas correspondem à sua intenção (hora, dia, frequência).
5. Copie a saída com o botão de cópia para a colar num ticket, num PR ou numa documentação técnica.

A ferramenta não se limita a um parsing sintático: fornece uma explicação cron em linguagem natural, o que a torna ao mesmo tempo um cron decoder e um validador de planeamento.

Os padrões abaixo cobrem o essencial dos cron schedules encontrados em produção. Todos são válidos em Linux crontab, Kubernetes CronJob, GitHub Actions e na maioria dos agendadores aplicacionais.

Para executar uma tarefa cron num servidor Linux, edita-se a crontab do utilizador a partir da shell:

# éditer la crontab de l'utilisateur courant
$ crontab -e

# lister les tâches existantes
$ crontab -l

# exemple de ligne ajoutée : sauvegarde quotidienne à 3h
0 3 * * * /usr/local/bin/backup.sh >> /var/log/backup.log 2>&1

Exemplo de saída do cron converter para */5 * * * *:

2026-05-05 00:00:00
2026-05-05 00:05:00
2026-05-05 00:10:00
2026-05-05 00:15:00
2026-05-05 00:20:00
...