Construir uma expressão cron

Porquê um cron builder visual?

Uma expressão cron cabe em cinco campos e continua a ser uma das maiores fontes de bugs em produção. Quantas vezes um programador escreveu 0 0 * * 1 a pensar "todas as segundas-feiras", sem se lembrar que 1 pode significar domingo conforme a implementação? Quantas vezes se confundiu */15 com 15? O cron builder responde a esta necessidade: compor visualmente uma expressão crontab, a partir de predefinições comuns ou de campos individuais, e obter a expressão final pronta a colar num crontab Linux, um Kubernetes CronJob ou um schedule do GitHub Actions.

A ferramenta é o inverso do nosso cron decoder: enquanto o conversor recebe uma expressão e enumera as próximas execuções, o builder recebe escolhas humanas e produz a expressão cron correspondente.

Como funciona

A interface gráfica oferece dois modos de composição complementares:

• Modo predefinição: um seletor de frequência (every minute, every hour, every day, every week, every month, every year, custom) que gera imediatamente uma expressão cron válida.
• Modo campos: cinco campos editáveis (minuto, hora, dia do mês, mês, dia da semana) onde introduz livremente *, um inteiro, um intervalo 1-5, uma lista 1,15,30 ou um passo */15.

O builder atualiza a expressão em tempo real e mostra uma leitura humana sucinta ("todos os dias às 3h", "a cada 15 minutos") que serve de garde-fou: se a frase não corresponder à sua intenção, a expressão está provavelmente errada.

Os cinco campos cron, em claro

Uma expressão cron padrão contém cinco campos separados por espaços:

minute  heure  jour-du-mois  mois  jour-de-la-semaine
*       *      *             *     *

• minuto (0 a 59);
• hora (0 a 23);
• dia do mês (1 a 31);
• mês (1 a 12 ou abreviaturas Jan, Feb, etc.);
• dia da semana (0 a 7, 0 e 7 representam ambos domingo na maioria das implementações).

Cada campo aceita várias formas: * (todos os valores), um inteiro preciso (5), uma lista (1,3,5), um intervalo (9-17), um passo (*/15 a cada 15 valores), ou uma combinação (0-30/5).

Casos de uso típicos

• Programador que aprende cron: visualizar como cada campo interage, sem arriscar uma expressão errada em produção.
• Sysadmin com pressa: gerar em poucos segundos um schedule para um cron Linux, um Kubernetes CronJob ou um job Ansible sem reler a man page.
• Programador sem experiência POSIX: produzir uma expressão crontab válida para Symfony Scheduler, Laravel Scheduler ou node-cron sem conhecer a sintaxe histórica.
• DevOps em revisão: prototipar rapidamente uma expressão a propor numa pull request, depois validá-la com o cron decoder.
• Migração legacy: reformular uma expressão cron histórica passando pelo builder para garantir a semântica antes de a empurrar para outro sítio.

Predefinições comuns

Selecionar uma predefinição substitui os campos individuais e produz a expressão correspondente:

• A cada minuto: * * * * *. A evitar em produção salvo necessidade específica.
• A cada hora: 0 * * * *. No início de cada hora.
• Todos os dias: 0 0 * * *. À meia-noite.
• Todas as semanas: 0 0 * * 0. Todos os domingos à meia-noite.
• Todos os meses: 0 0 1 * *. No dia 1 do mês à meia-noite.
• Todos os anos: 0 0 1 1 *. No 1 de janeiro à meia-noite.

Padrões comuns a conhecer

Compor uma expressão personalizada

Para casos mais específicos, o assistente expõe os cinco campos em entrada livre. Alguns exemplos úteis:

• Todos os dias às 3h da manhã: minuto=0, hora=3, outros campos *.
• A cada 15 minutos: minuto=*/15, outros campos *.
• De segunda a sexta às 9h: minuto=0, hora=9, dia-da-semana=1-5.
• Todos os dias 1 e 15 do mês ao meio-dia: minuto=0, hora=12, dia-do-mês=1,15.
• A cada 5 minutos entre as 9h e as 17h: minuto=*/5, hora=9-17.

Como utilizar o cron builder

1. Escolha uma predefinição (every minute, every hour, every day, every week, every month, every year) que corresponda à base da sua necessidade.
2. Afine se necessário editando diretamente os cinco campos (minuto, hora, dia do mês, mês, dia da semana).
3. Leia a frase humana gerada pela ferramenta para confirmar a intenção.
4. Copie a expressão cron produzida com o botão de cópia.
5. Valide o schedule com o nosso cron decoder que calcula as próximas datas de execução reais.
6. Cole a expressão no seu crontab Linux, no seu Kubernetes CronJob, no seu Symfony Scheduler ou no seu workflow do GitHub Actions.

Armadilhas clássicas

• Dia do mês e dia da semana combinados: se nenhum dos dois for *, o comportamento difere conforme as implementações. Linux/Vixie cron aplica um OU; as bibliotecas modernas têm por vezes um comportamento diferente. A evitar.
• Dia 1 = segunda ou domingo?: depende do país e da convenção. A maioria dos cron Unix considera domingo=0 e sábado=6. Verifique o seu agendador.
• Fuso horário: um cron Unix utiliza por defeito o fuso do servidor. Os agendadores aplicacionais (Symfony Scheduler, Quartz) permitem frequentemente fixar um fuso dedicado.
• Minuto em falta: * * * * * executa o job a cada minuto, o que raramente é o que se quer. Pense em fixar um disparador preciso (0) para tarefas horárias.

Leitura humana e saída

Além da expressão cron, a ferramenta oferece uma leitura humana sucinta ("todos os dias à meia-noite", "a cada 5 minutos"). É um garde-fou: se a frase não corresponder à sua intenção, a expressão está provavelmente errada. Para um caso complexo, utilize depois o nosso cron decoder para calcular as próximas datas de execução reais.

Perguntas frequentes

Exemplo de pedido

curl -X POST https://cdrn.fr/api/v1/tools/cron-builder/execute \
  -H "Content-Type: application/json" \
  -d '{"preset":"none","minute":"*","hour":"*","day_of_month":"*","month":"*","day_of_week":"*"}'

Esquema de entrada

Pontos de acesso

• GET https://cdrn.fr/api/v1/tools - lista todas as ferramentas disponíveis
• GET https://cdrn.fr/api/v1/tools/cron-builder - obtém o esquema desta ferramenta
• POST https://cdrn.fr/api/v1/tools/cron-builder/execute - executa esta ferramenta com um payload JSON