Caracteres especiales de Quartz: L, W y # explicados
Guía profunda a nivel de token para los operadores L, W y # de Quartz, para que puedas construir programaciones precisas sin sorpresas en tiempo de ejecución.
Abrir generador QuartzPor qué importan los caracteres especiales de Quartz
La mayoría de los errores de cron comienzan antes del despliegue, cuando la intención de la programación y la sintaxis divergen. El cron estándar de cinco campos cubre minutos, horas, día del mes, mes y día de la semana. Quartz extiende esto con un campo de segundos, un campo de año y tres caracteres especiales—L, W y #—que desbloquean una precisión de programación que el cron estándar no puede igualar.
Estos caracteres se comportan de manera diferente según el campo en el que aparecen, y pequeños malentendidos se propagan en programaciones que se ejecutan el día equivocado u omiten ejecuciones por completo. Este artículo explica cada carácter con ejemplos prácticos, verificaciones de validación y acciones claras que puedes tomar en el Generador Quartz de Cronwise.
El carácter L: último día y último día de la semana
L significa "último" y es válido en dos campos: día del mes y día de la semana. Su significado cambia según dónde lo coloques.
L en día del mes
Cuando se usa solo, L significa el último día del mes. La expresión 0 0 18 L * ? se ejecuta a las 6:00 PM el último día de cada mes—ya sea el 28, 29, 30 o 31. Nunca necesitas codificar las longitudes de los meses.
Puedes combinar L con un offset negativo. L-3 significa tres días antes del último día. En un mes de 31 días se resuelve al 28; en febrero de un año no bisiesto se resuelve al 25. Esto es útil para ventanas de corte de facturación.
L en día de la semana
En el campo de día de la semana, emparejas L con un número de día de la semana: 6L significa el último viernes del mes. La expresión 0 0 9 ? * 6L se ejecuta a las 9:00 AM el último viernes de cada mes—útil para procesamiento de nómina o reportes de fin de mes que deben caer en un día específico de la semana.
El carácter W: día hábil más cercano
W es válido solo en el campo de día del mes. Selecciona el día hábil más cercano (lunes a viernes) a la fecha especificada. Escribe 15W para significar "el día hábil más cercano al 15".
Cómo se resuelve W
Si el 15 cae en sábado, la programación se desplaza al viernes 14. Si cae en domingo, se desplaza al lunes 16. La resolución nunca cruza límites de mes: si el 1.° es sábado, 1W se resuelve al lunes 3, no al viernes anterior.
Combinación de L y W
Quartz permite la combinación LW, que significa "el último día hábil del mes". Esto es ideal para cierres financieros de fin de mes que deben ejecutarse en un día laboral. Si el último día es sábado, LW se resuelve al viernes. Ten en cuenta que W no puede combinarse con una lista o rango—expresiones como 1W,15W son inválidas.
El carácter #: enésimo día de la semana del mes
# es válido solo en el campo de día de la semana y especifica la enésima ocurrencia de un día de la semana dentro de un mes. La sintaxis es día#N, donde día es el número de día de la semana (1–7, domingo a sábado) y N es la ocurrencia (1–5).
Ejemplos prácticos
0 0 10 ? * 2#1 se ejecuta a las 10:00 AM el primer lunes de cada mes. 0 0 14 ? * 6#3 se ejecuta a las 2:00 PM el tercer viernes. Estos patrones reemplazan soluciones frágiles que dependen de rangos de día del mes y lógica condicional.
Cuando N excede las ocurrencias reales
Si especificas 2#5 (el quinto lunes), la programación no se ejecuta en meses con solo cuatro lunes. Quartz trata esto como una no-coincidencia, no un error—una omisión silenciosa que hace esencial el monitoreo del conteo de ejecuciones.
El carácter # no puede aparecer en día del mes y no puede combinarse con listas, rangos o incrementos. Cada campo de día de la semana acepta como máximo una especificación #.
Comportamiento límite y modos de fallo
Los errores sutiles con estos caracteres rara vez activan errores de validación pero desvían silenciosamente de la intención.
Problemas comunes
| Expresión | Esperado | Real | Corrección |
|---|---|---|---|
0 0 9 L * 6 | Último día si es viernes | Conflicto: ambos campos de día configurados | Usa ? en un campo de día |
0 0 9 1W * ? (el 1.° es sábado) | Viernes anterior | Lunes 3 (sin cruzar mes) | Verifica con la vista previa de ejecuciones |
0 0 9 ? * 2#5 | Quinto lunes mensual | Solo meses con cinco lunes | Agrega monitoreo del conteo de ejecuciones |
0 0 9 LW * ? en febrero | Último día hábil | 26, 27 o 28 según el año | Verifica con vista previa según zona horaria |
El error más peligroso es especificar valores en ambos campos de día del mes y día de la semana sin usar ? como marcador de posición. Quartz requiere que exactamente un campo de día contenga ?. Omitirlo produce un error de análisis o comportamiento indefinido según la versión de Quartz.
Marco de decisión: elegir el carácter correcto
Cada carácter especial resuelve un problema de programación diferente. Seleccionar el correcto depende de si tu programación está anclada a una fecha del calendario, un día de la semana o una posición relativa dentro del mes.
| Requisito | Carácter | Campo | Ejemplo |
|---|---|---|---|
| Ejecutar el último día de cada mes | L | Día del mes | 0 0 18 L * ? |
| Ejecutar N días antes del fin de mes | L-N | Día del mes | 0 0 18 L-3 * ? |
| Ejecutar el último día de la semana específico | nL | Día de la semana | 0 0 9 ? * 6L |
| Ejecutar el día hábil más cercano a una fecha | W | Día del mes | 0 0 9 15W * ? |
| Ejecutar el último día hábil del mes | LW | Día del mes | 0 0 17 LW * ? |
| Ejecutar el enésimo día de la semana del mes | # | Día de la semana | 0 0 10 ? * 2#1 |
Cuando tu requisito es puramente basado en fecha ("el 15"), no necesitas caracteres especiales en absoluto. Usa W solo cuando se requiere alineación con días hábiles. Usa # solo cuando una ocurrencia recurrente de día de la semana importa más que una fecha fija. Y usa L cuando la semántica de fin de mes debe adaptarse automáticamente a longitudes de mes variables.
Robustecimiento para producción: verificaciones previas al despliegue
Antes de que cualquier programación Quartz llegue a producción, recorre estos pasos de verificación para detectar casos límite que la validación estática no puede revelar.
Lista de verificación
| Verificación | Por qué importa | Criterio de aprobación |
|---|---|---|
| Análisis sin errores | Confirma validez sintáctica | Sin excepciones del analizador |
| Inspeccionar próximas 10 ejecuciones | Revela sorpresas de límite de mes | Todas las fechas coinciden con la intención |
| Verificar alineación de zona horaria | Discrepancias entre zona del servidor y del negocio | Las ejecuciones coinciden con la zona horaria objetivo |
Confirmar ubicación de ? | Ambos campos de día activos es indefinido | Un campo de día tiene ? |
| Verificar omisiones silenciosas | #5 puede ejecutarse < 12 veces/año | Conteo anual documentado |
La vista previa de ejecuciones de Cronwise muestra las próximas 10 ejecuciones en tu zona horaria seleccionada, permitiéndote verificar estos criterios sin desplegar un trabajo de prueba. Si tu equipo opera en diferentes zonas horarias, revisa Zonas horarias de cron explicadas para equipos globales para orientación adicional.
Resumen final
Los caracteres L, W y # de Quartz te dan un poder de programación que el cron estándar no puede igualar. L se adapta a longitudes de mes variables, W alinea la ejecución con días hábiles y # fija ejecuciones a ocurrencias específicas de día de la semana. Usados correctamente, eliminan soluciones frágiles y hacen explícita la intención de la programación en la propia expresión.
Las reglas de decisión clave son directas. Usa L para lógica de fin de mes. Usa W cuando necesites el día hábil más cercano. Usa # para el enésimo día de la semana de un mes. Siempre coloca ? en el campo de día que no estés usando. Y siempre verifica con una vista previa de ejecuciones antes de desplegar.
¿Listo para construir o validar tu programación Quartz? Abre el Generador Quartz de Cronwise para construir expresiones visualmente, ver explicaciones en lenguaje natural y previsualizar ejecuciones en tu zona horaria objetivo. Para más guías de programación cron e inmersiones profundas, explora todos los artículos sobre cron en Cronwise.