Fundamentos de Expressões Cron: Entendendo os 5 Campos
Uma explicação em linguagem simples da sintaxe cron padrão que você pode aplicar imediatamente
Experimentar o Explicador de CronPor que Expressões Cron Confundem até Desenvolvedores Experientes
A maioria dos erros de cron começa antes da implantação, quando a intenção do agendamento e a sintaxe divergem. Você quer que um job rode todos os dias úteis às 8h, mas um valor mal posicionado muda o agendamento para toda hora ou todo dia do mês. A causa raiz é quase sempre a mesma: os cinco campos de uma expressão cron são compactos, posicionais e implacáveis.
Uma expressão cron padrão é uma única linha de cinco campos separados por espaço. Cada campo mapeia para uma unidade de tempo, e juntos eles definem um agendamento repetitivo. Não há rótulos, não há palavras-chave por padrão, e não há espaço para ambiguidade uma vez que o agendador lê a linha.
Este artigo explica a estrutura do formato cron de 5 campos em linguagem simples. Você aprenderá o que cada campo controla, como os tokens comuns funcionam e onde ocorrem as interpretações incorretas típicas. Cada exemplo pode ser verificado instantaneamente no Explicador de Cron do Cronwise, que fornece uma descrição em linguagem simples e uma pré-visualização dos próximos horários com fuso horário para qualquer expressão que você inserir.
Seja escrevendo sua primeira entrada no crontab ou revisando um agendamento que outra pessoa escreveu, entender esses cinco campos é a base para todo fluxo de trabalho cron que se segue.
Os Cinco Campos: O que Cada Um Controla
Toda expressão cron padrão segue o mesmo formato posicional. Da esquerda para a direita, os cinco campos são:
| Posição | Campo | Valores Permitidos | Descrição |
|---|---|---|---|
| 1 | Minuto | 0 – 59 | O minuto da hora quando o job executa |
| 2 | Hora | 0 – 23 | A hora do dia (formato 24 horas) |
| 3 | Dia do Mês | 1 – 31 | O dia do calendário |
| 4 | Mês | 1 – 12 | O mês do ano |
| 5 | Dia da Semana | 0 – 7 | O dia da semana (0 e 7 ambos representam domingo) |
Um exemplo concreto torna o mapeamento claro. A expressão 30 8 * * 1-5 significa: no minuto 30, da hora 8, em todo dia do mês, em todo mês, mas apenas nos dias úteis de segunda a sexta-feira. Em linguagem simples: 8:30, de segunda a sexta.
O asterisco (*) é um curinga que corresponde a todo valor permitido para aquele campo. Quando você o vê, leia como "todo." Então * * * * * significa todo minuto de toda hora de todo dia — o agendamento mais frequente possível no cron padrão.
Tokens Comuns e Como Funcionam
Além do curinga asterisco, campos cron suportam vários tokens que permitem expressar intervalos, passos e listas sem escrever entradas separadas.
Vírgula (Lista)
Uma vírgula separa valores individuais. 0 9,12,18 * * * dispara às 9:00, 12:00 e 18:00 todos os dias. Cada valor na lista é tratado independentemente.
Hífen (Intervalo)
Um hífen define um intervalo contínuo. 0 9-17 * * * dispara no início de cada hora das 9:00 às 17:00. Intervalos são inclusivos em ambas as extremidades.
Barra (Passo)
Uma barra define um intervalo de passo. */15 * * * * dispara a cada 15 minutos, começando no minuto 0. Você pode combinar um intervalo com um passo: 0-30/10 * * * * dispara nos minutos 0, 10, 20 e 30 de cada hora.
Combinando Tokens
Tokens podem ser combinados dentro de um único campo. 0 8-12,18 * * 1-5 executa no início das horas 8 a 12 e também na hora 18, mas apenas em dias úteis. Cada campo é avaliado independentemente, e o agendador dispara quando todos os cinco campos coincidem simultaneamente.
Para um guia mais aprofundado de estratégias de leitura, veja Como Ler Expressões Cron Rapidamente, que cobre modelos mentais para interpretar expressões rapidamente.
Como Interpretar Agendamentos Reais
Ler uma expressão cron corretamente significa traduzir cada campo em ordem e depois combiná-los em uma única frase. Aqui estão exemplos práticos com seus equivalentes em linguagem simples:
| Expressão | Significado | Quando Usar | Notas de Risco |
|---|---|---|---|
0 0 * * * | Meia-noite todos os dias | Jobs batch diários, rotação de logs | Carga pesada se muitos jobs compartilham esse horário |
*/5 * * * * | A cada 5 minutos | Health checks, polling de filas | Alta frequência; confirme que o job é idempotente |
0 9 1 * * | Às 9:00 no dia 1 de cada mês | Relatórios mensais | Meses com menos de 31 dias funcionam normalmente |
30 2 * * 0 | Às 2:30 todo domingo | Janela de manutenção semanal | Pode sobrepor com transições de horário de verão na primavera |
0 */2 * * 1-5 | A cada 2 horas nos dias úteis | Polling em horário comercial | Executa às 0, 2, 4 … 22 — não apenas horário comercial |
O último exemplo é uma interpretação incorreta comum. */2 no campo de hora significa a cada segunda hora a partir de 0, não a cada duas horas durante o horário comercial. Se você quer apenas das 9h às 17h, precisa de 0 9-17/2 * * 1-5. Esse é exatamente o tipo de erro sutil que o Explicador do Cronwise captura mostrando as próximas 10 execuções agendadas no seu fuso horário.
Casos Extremos e Limites de Campo
O formato de 5 campos tem limites que são fáceis de esquecer. Entendê-los previne falhas silenciosas.
Interação entre Dia do Mês e Dia da Semana
No cron padrão, quando tanto o dia do mês (campo 3) quanto o dia da semana (campo 5) são definidos com valores não-curinga, a maioria das implementações os trata como uma união: o job executa se qualquer condição for verdadeira. Isso significa que 0 9 15 * 1 não significa "o dia 15 se for segunda-feira." Significa "todo dia 15 do mês e toda segunda-feira." Essa é uma das surpresas mais frequentemente reportadas no cron.
Limites de Mês e Dia da Semana
Definir dia do mês como 31 significa que o job executará apenas nos meses que têm 31 dias (janeiro, março, maio, julho, agosto, outubro, dezembro). Os meses mais curtos serão silenciosamente pulados. Da mesma forma, valores de dia da semana 0 e 7 ambos representam domingo, mas misturá-los na mesma expressão pode causar confusão durante revisões de código.
Dependência de Fuso Horário
Uma expressão cron não contém informação de fuso horário por si só. O agendador interpreta os horários no fuso horário em que está configurado, que pode ser UTC, o horário local do servidor ou uma substituição explícita. Se sua equipe abrange múltiplos fusos horários, sempre confirme a configuração de fuso do agendador antes de implantar. O Cronwise permite selecionar qualquer fuso horário IANA e visualizar execuções de acordo.
Aplique o que Você Sabe no Fluxo do Cronwise
Uma vez que você entende os cinco campos, o próximo passo é passar da leitura de expressões cron para construí-las com confiança. O Cronwise oferece dois caminhos complementares para isso.
Explique Primeiro, Depois Gere
Comece com o Explicador de Cron para verificar uma expressão existente. Cole-a, leia o resumo em linguagem simples e examine a tabela de próximos horários. Se o agendamento não é o que você pretendia, mude para o Gerador de Cron para construir a expressão correta visualmente, campo por campo. O gerador elimina suposições de sintaxe permitindo que você selecione valores em dropdowns e abas.
Checklist de Verificação Antes da Implantação
| Verificação | Por que Importa | Critério de Aprovação |
|---|---|---|
| Resumo em linguagem simples corresponde à intenção | Captura erros de ordem de campo | Frase resumo alinha com seu objetivo de agendamento |
| Timestamps dos próximos horários estão corretos | Captura uso incorreto de tokens (intervalos, passos) | Primeiras 5 execuções correspondem às datas e horários esperados |
| Fuso horário corresponde ao ambiente alvo | Previne execução com horas a mais ou a menos | Fuso selecionado é igual ao fuso configurado no agendador |
| Sem avisos de validação | Captura padrões arriscados cedo | Zero avisos ou cada aviso intencionalmente aceito |
Para um guia completo do construtor visual, leia Gerador Visual de Cron: Fluxo Passo a Passo, que cobre navegação por abas, presets salvos e opções de exportação.
Conclusão: Implante com Confiança
O formato cron de 5 campos é enganosamente simples: minuto, hora, dia do mês, mês e dia da semana. Dominá-lo significa conhecer não apenas as posições dos campos mas também como os tokens se combinam, onde os casos extremos se escondem e por que uma verificação de validação de 10 segundos vale o esforço toda vez.
Aqui estão as regras principais para levar adiante:
- Leia campos da esquerda para a direita: minuto, hora, dia, mês, dia da semana.
- Um asterisco significa "todo" — não é um placeholder ou um padrão.
- Intervalos, listas e passos podem ser combinados, mas cada campo é avaliado independentemente.
- Dia do mês e dia da semana formam uma união quando ambos são não-curinga — não uma interseção.
- Sempre verifique o fuso horário do agendador e visualize as próximas execuções antes de implantar.
O Cronwise foi construído para tornar essa verificação rápida. Cole uma expressão, leia a explicação, verifique as execuções e implante com confiança. Navegue por todos os artigos sobre cron no Cronwise para continuar aprendendo, ou vá direto para a ferramenta.