Caracteres Especiais do Quartz: L, W e # Explicados
Orientação detalhada no nível de token para os operadores L, W e # do Quartz para que você construa agendamentos precisos sem surpresas em tempo de execução.
Abrir Gerador QuartzPor que os Caracteres Especiais do Quartz Importam
A maioria dos erros de cron começa antes da implantação, quando a intenção do agendamento e a sintaxe divergem. O cron padrão de cinco campos cobre minutos, horas, dia do mês, mês e dia da semana. O Quartz estende isso com um campo de segundos, um campo de ano e três caracteres especiais -- L, W e # -- que desbloqueiam uma precisão de agendamento que o cron padrão não consegue alcançar.
Esses caracteres se comportam diferentemente dependendo de qual campo aparecem, e pequenos mal-entendidos se propagam em agendamentos que disparam no dia errado ou pulam execuções inteiramente. Este artigo explica cada caractere com exemplos práticos, verificações de validação e próximas ações claras que você pode tomar no Gerador Quartz do Cronwise.
O Caractere L: Último Dia e Último Dia da Semana
L significa "último" e é válido em dois campos: dia do mês e dia da semana. Seu significado muda dependendo de onde você o coloca.
L no Dia do Mês
Quando usado sozinho, L significa o último dia do mês. A expressão 0 0 18 L * ? dispara às 18:00 no último dia de cada mês -- seja o 28, 29, 30 ou 31. Você nunca precisa codificar comprimentos de meses.
Você pode combinar L com um offset negativo. L-3 significa três dias antes do último dia. Em um mês de 31 dias, isso resolve para o dia 28; em fevereiro de um ano não bissexto, resolve para o dia 25. Isso é útil para janelas de corte de faturamento.
L no Dia da Semana
No campo dia da semana, você combina L com um número de dia: 6L significa a última sexta-feira do mês. A expressão 0 0 9 ? * 6L dispara às 9:00 na última sexta-feira de cada mês -- útil para processamento de folha de pagamento ou relatórios de fim de mês que devem cair em um dia da semana específico.
O Caractere W: Dia Útil Mais Próximo
W é válido apenas no campo dia do mês. Ele seleciona o dia útil mais próximo (segunda a sexta) da data especificada. Escreva 15W para significar "o dia útil mais próximo do dia 15."
Como W Resolve
Se o dia 15 cai em um sábado, o agendamento muda para sexta-feira dia 14. Se cai em um domingo, muda para segunda dia 16. A resolução nunca cruza limites de mês: se o dia 1 é sábado, 1W resolve para segunda dia 3, não para a sexta-feira anterior.
Combinando L e W
O Quartz permite a combinação LW, significando "o último dia útil do mês." Isso é ideal para fechamentos financeiros de fim de mês que devem rodar em um dia comercial. Se o último dia é sábado, LW resolve para sexta. Note que W não pode ser combinado com uma lista ou intervalo -- expressões como 1W,15W são inválidas.
O Caractere #: Enésimo Dia da Semana do Mês
# é válido apenas no campo dia da semana e especifica a enésima ocorrência de um dia da semana dentro de um mês. A sintaxe é dia#N, onde dia é o número do dia da semana (1-7, domingo a sábado) e N é a ocorrência (1-5).
Exemplos Práticos
0 0 10 ? * 2#1 dispara às 10:00 na primeira segunda-feira de cada mês. 0 0 14 ? * 6#3 dispara às 14:00 na terceira sexta-feira. Esses padrões substituem alternativas frágeis que dependem de intervalos de dia do mês e lógica condicional.
Quando N Excede Ocorrências Reais
Se você especifica 2#5 (a quinta segunda-feira), o agendamento não dispara em meses com apenas quatro segundas-feiras. O Quartz trata isso como não-correspondência, não como erro -- um pulo silencioso que torna o monitoramento de contagem de execuções essencial.
O caractere # não pode aparecer em dia do mês e não pode ser combinado com listas, intervalos ou incrementos. Cada campo de dia da semana aceita no máximo uma especificação #.
Comportamento Extremo e Modos de Falha
Erros sutis com esses caracteres raramente acionam erros de validação mas silenciosamente desviam da intenção.
Armadilhas Comuns
| Expressão | Esperado | Real | Correção |
|---|---|---|---|
0 0 9 L * 6 | Último dia se sexta | Conflito: ambos campos de dia definidos | Use ? em um campo de dia |
0 0 9 1W * ? (1º é sábado) | Sexta anterior | Segunda dia 3 (não cruza mês) | Verifique com pré-visualização |
0 0 9 ? * 2#5 | Quinta segunda mensal | Apenas meses com cinco segundas | Adicione monitoramento de contagem |
0 0 9 LW * ? em fevereiro | Último dia útil | 26, 27 ou 28 dependendo do ano | Verifique pré-visualização com fuso |
O erro mais perigoso é especificar valores em ambos dia do mês e dia da semana sem usar ? como placeholder. O Quartz exige que exatamente um campo de dia contenha ?. Omiti-lo produz erro de parsing ou comportamento indefinido dependendo da versão do Quartz.
Framework de Decisão: Escolhendo o Caractere Certo
Cada caractere especial resolve um problema diferente de agendamento. Selecionar o correto depende de se seu agendamento é ancorado a uma data do calendário, um dia da semana ou uma posição relativa dentro do mês.
| Requisito | Caractere | Campo | Exemplo |
|---|---|---|---|
| Executar no último dia de cada mês | L | Dia do Mês | 0 0 18 L * ? |
| Executar N dias antes do fim do mês | L-N | Dia do Mês | 0 0 18 L-3 * ? |
| Executar no último dia da semana específico | nL | Dia da Semana | 0 0 9 ? * 6L |
| Executar no dia útil mais próximo de uma data | W | Dia do Mês | 0 0 9 15W * ? |
| Executar no último dia útil do mês | LW | Dia do Mês | 0 0 17 LW * ? |
| Executar no enésimo dia da semana do mês | # | Dia da Semana | 0 0 10 ? * 2#1 |
Quando seu requisito é puramente baseado em data ("o dia 15"), você não precisa de caracteres especiais. Use W apenas quando alinhamento com dias úteis for necessário. Use # apenas quando uma ocorrência recorrente de dia da semana importar mais que uma data fixa. E use L quando a semântica de fim de mês precisa se adaptar automaticamente a comprimentos variáveis de mês.
Fortalecimento para Produção: Verificações Pré-Implantação
Antes de qualquer agendamento Quartz chegar à produção, passe por estas etapas de verificação para capturar casos extremos que a validação estática não consegue detectar.
Checklist de Verificação
| Verificação | Por que Importa | Critério de Aprovação |
|---|---|---|
| Parse sem erros | Confirma validade sintática | Sem exceções de parser |
| Inspecionar próximos 10 horários | Revela surpresas de limite de mês | Todas as datas correspondem à intenção |
| Verificar alinhamento de fuso | Incompatibilidades servidor vs negócio | Execuções correspondem ao fuso alvo |
Confirmar posição do ? | Ambos campos de dia ativos é indefinido | Um campo de dia tem ? |
| Verificar pulos silenciosos | #5 pode disparar < 12 vezes/ano | Contagem anual documentada |
A pré-visualização dos próximos horários do Cronwise retorna as próximas 10 execuções no fuso selecionado, permitindo verificar esses critérios sem implantar um job de teste. Se sua equipe opera em múltiplos fusos horários, revise Fusos Horários no Cron Explicados para Equipes Globais para orientação adicional.
Juntando Tudo
Os caracteres L, W e # do Quartz dão a você um poder de agendamento que o cron padrão não consegue alcançar. L se adapta a comprimentos variáveis de mês, W alinha execução com dias úteis, e # fixa execuções em ocorrências específicas de dia da semana. Usados corretamente, eliminam alternativas frágeis e tornam a intenção do agendamento explícita na própria expressão.
As regras de decisão chave são diretas. Use L para lógica de fim de mês. Use W quando precisar do dia útil mais próximo. Use # para o enésimo dia da semana de um mês. Sempre coloque ? no campo de dia que não está usando. E sempre verifique com uma pré-visualização dos próximos horários antes de implantar.
Pronto para construir ou validar seu agendamento Quartz? Abra o Gerador Quartz do Cronwise para construir expressões visualmente, ver explicações em linguagem simples e visualizar horários de execução no seu fuso horário alvo. Para mais guias de agendamento cron e mergulhos profundos, navegue por todos os artigos sobre cron no Cronwise.