/** * CRON 表达式工具类 * 提供 CRON 表达式的解析、格式化、验证等功能 */ /** CRON 字段类型枚举 */ export enum CronFieldType { SECOND = 'second', MINUTE = 'minute', HOUR = 'hour', DAY = 'day', MONTH = 'month', WEEK = 'week', YEAR = 'year' } /** CRON 字段配置 */ export interface CronFieldConfig { key: CronFieldType label: string min: number max: number names?: Record // 名称映射,如月份名称 } /** CRON 字段配置常量 */ export const CRON_FIELD_CONFIGS: Record = { [CronFieldType.SECOND]: { key: CronFieldType.SECOND, label: '秒', min: 0, max: 59 }, [CronFieldType.MINUTE]: { key: CronFieldType.MINUTE, label: '分', min: 0, max: 59 }, [CronFieldType.HOUR]: { key: CronFieldType.HOUR, label: '时', min: 0, max: 23 }, [CronFieldType.DAY]: { key: CronFieldType.DAY, label: '日', min: 1, max: 31 }, [CronFieldType.MONTH]: { key: CronFieldType.MONTH, label: '月', min: 1, max: 12, names: { JAN: 1, FEB: 2, MAR: 3, APR: 4, MAY: 5, JUN: 6, JUL: 7, AUG: 8, SEP: 9, OCT: 10, NOV: 11, DEC: 12 } }, [CronFieldType.WEEK]: { key: CronFieldType.WEEK, label: '周', min: 0, max: 7, names: { SUN: 0, MON: 1, TUE: 2, WED: 3, THU: 4, FRI: 5, SAT: 6 } }, [CronFieldType.YEAR]: { key: CronFieldType.YEAR, label: '年', min: 1970, max: 2099 } } /** 解析后的 CRON 字段 */ export interface ParsedCronField { type: 'any' | 'specific' | 'range' | 'step' | 'list' | 'last' | 'weekday' | 'nth' values: number[] original: string description: string } /** 解析后的 CRON 表达式 */ export interface ParsedCronExpression { second: ParsedCronField minute: ParsedCronField hour: ParsedCronField day: ParsedCronField month: ParsedCronField week: ParsedCronField year?: ParsedCronField isValid: boolean description: string nextExecutionTime?: Date } /** 常用 CRON 表达式预设 */ export const CRON_PRESETS = { EVERY_SECOND: '* * * * * ?', EVERY_MINUTE: '0 * * * * ?', EVERY_HOUR: '0 0 * * * ?', EVERY_DAY: '0 0 0 * * ?', EVERY_WEEK: '0 0 0 ? * 1', EVERY_MONTH: '0 0 0 1 * ?', EVERY_YEAR: '0 0 0 1 1 ?', WORKDAY_9AM: '0 0 9 ? * 2-6', // 工作日上午9点 WORKDAY_6PM: '0 0 18 ? * 2-6', // 工作日下午6点 WEEKEND_10AM: '0 0 10 ? * 1,7' // 周末上午10点 } as const /** CRON 表达式工具类 */ export class CronUtils { /** 验证 CRON 表达式格式 */ static validate(cronExpression: string): boolean { if (!cronExpression || typeof cronExpression !== 'string') { return false } const parts = cronExpression.trim().split(/\s+/) // 支持 5-7 个字段的 CRON 表达式 if (parts.length < 5 || parts.length > 7) { return false } // 基本格式验证 const cronRegex = /^[0-9*\/\-,?LW#]+$/ return parts.every((part) => cronRegex.test(part)) } /** 解析单个 CRON 字段 */ static parseField( fieldValue: string, fieldType: CronFieldType, config: CronFieldConfig ): ParsedCronField { const field: ParsedCronField = { type: 'any', values: [], original: fieldValue, description: '' } // 处理特殊字符 if (fieldValue === '*' || fieldValue === '?') { field.type = 'any' field.description = `每${config.label}` return field } // 处理最后一天 (L) if (fieldValue === 'L' && fieldType === CronFieldType.DAY) { field.type = 'last' field.description = '每月最后一天' return field } // 处理范围 (-) if (fieldValue.includes('-')) { const [start, end] = fieldValue.split('-').map(Number) if (!isNaN(start) && !isNaN(end) && start >= config.min && end <= config.max) { field.type = 'range' field.values = Array.from({ length: end - start + 1 }, (_, i) => start + i) field.description = `${config.label} ${start}-${end}` } return field } // 处理步长 (/) if (fieldValue.includes('/')) { const [base, step] = fieldValue.split('/') const stepNum = Number(step) if (!isNaN(stepNum) && stepNum > 0) { field.type = 'step' if (base === '*') { field.description = `每${stepNum}${config.label}` } else { const startNum = Number(base) field.description = `从${startNum}开始每${stepNum}${config.label}` } } return field } // 处理列表 (,) if (fieldValue.includes(',')) { const values = fieldValue .split(',') .map(Number) .filter((n) => !isNaN(n)) if (values.length > 0) { field.type = 'list' field.values = values field.description = `${config.label} ${values.join(',')}` } return field } // 处理具体数值 const numValue = Number(fieldValue) if (!isNaN(numValue) && numValue >= config.min && numValue <= config.max) { field.type = 'specific' field.values = [numValue] field.description = `${config.label} ${numValue}` } return field } /** 解析完整的 CRON 表达式 */ static parse(cronExpression: string): ParsedCronExpression { const result: ParsedCronExpression = { second: { type: 'any', values: [], original: '*', description: '每秒' }, minute: { type: 'any', values: [], original: '*', description: '每分' }, hour: { type: 'any', values: [], original: '*', description: '每时' }, day: { type: 'any', values: [], original: '*', description: '每日' }, month: { type: 'any', values: [], original: '*', description: '每月' }, week: { type: 'any', values: [], original: '?', description: '任意周' }, isValid: false, description: '' } if (!this.validate(cronExpression)) { result.description = '无效的 CRON 表达式' return result } const parts = cronExpression.trim().split(/\s+/) const fieldTypes = [ CronFieldType.SECOND, CronFieldType.MINUTE, CronFieldType.HOUR, CronFieldType.DAY, CronFieldType.MONTH, CronFieldType.WEEK ] // 如果只有5个字段,则第一个字段是分钟 const startIndex = parts.length === 5 ? 1 : 0 for (let i = 0; i < parts.length; i++) { const fieldType = fieldTypes[i + startIndex] if (fieldType && CRON_FIELD_CONFIGS[fieldType]) { const config = CRON_FIELD_CONFIGS[fieldType] result[fieldType] = this.parseField(parts[i], fieldType, config) } } // 处理年份字段(如果存在) if (parts.length === 7) { const yearConfig = CRON_FIELD_CONFIGS[CronFieldType.YEAR] result.year = this.parseField(parts[6], CronFieldType.YEAR, yearConfig) } result.isValid = true result.description = this.generateDescription(result) return result } /** 生成 CRON 表达式的可读描述 */ static generateDescription(parsed: ParsedCronExpression): string { const parts: string[] = [] // 构建时间部分描述 if (parsed.hour.type === 'specific' && parsed.minute.type === 'specific') { const hour = parsed.hour.values[0] const minute = parsed.minute.values[0] parts.push(`${hour.toString().padStart(2, '0')}:${minute.toString().padStart(2, '0')}`) } else if (parsed.hour.type === 'specific') { parts.push(`每天${parsed.hour.values[0]}点`) } else if (parsed.minute.type === 'specific' && parsed.minute.values[0] === 0) { if (parsed.hour.type === 'any') { parts.push('每小时整点') } } else if (parsed.minute.type === 'step') { const step = parsed.minute.original.split('/')[1] parts.push(`每${step}分钟`) } else if (parsed.hour.type === 'step') { const step = parsed.hour.original.split('/')[1] parts.push(`每${step}小时`) } // 构建日期部分描述 if (parsed.day.type === 'specific') { parts.push(`每月${parsed.day.values[0]}日`) } else if (parsed.week.type === 'specific') { const weekNames = ['周日', '周一', '周二', '周三', '周四', '周五', '周六'] const weekDay = parsed.week.values[0] if (weekDay >= 0 && weekDay <= 6) { parts.push(`每${weekNames[weekDay]}`) } } else if (parsed.week.type === 'range') { parts.push('工作日') } // 构建月份部分描述 if (parsed.month.type === 'specific') { parts.push(`${parsed.month.values[0]}月`) } return parts.length > 0 ? parts.join(' ') : '自定义时间规则' } /** 格式化 CRON 表达式为可读文本 */ static format(cronExpression: string): string { if (!cronExpression) return '' const parsed = this.parse(cronExpression) return parsed.isValid ? parsed.description : cronExpression } /** 获取预设的 CRON 表达式列表 */ static getPresets() { return Object.entries(CRON_PRESETS).map(([key, value]) => ({ label: this.format(value), value, key })) } /** 计算 CRON 表达式的下次执行时间 */ static getNextExecutionTime(cronExpression: string, fromDate?: Date): Date | null { const parsed = this.parse(cronExpression) if (!parsed.isValid) { return null } const now = fromDate || new Date() // eslint-disable-next-line prefer-const let nextTime = new Date(now.getTime() + 1000) // 从下一秒开始 // 简化版本:处理常见的 CRON 表达式模式 // 对于复杂的 CRON 表达式,建议使用专门的库如 node-cron 或 cron-parser // 处理每分钟执行 if (parsed.second.type === 'specific' && parsed.minute.type === 'any') { const targetSecond = parsed.second.values[0] nextTime.setSeconds(targetSecond, 0) if (nextTime <= now) { nextTime.setMinutes(nextTime.getMinutes() + 1) } return nextTime } // 处理每小时执行 if ( parsed.second.type === 'specific' && parsed.minute.type === 'specific' && parsed.hour.type === 'any' ) { const targetSecond = parsed.second.values[0] const targetMinute = parsed.minute.values[0] nextTime.setMinutes(targetMinute, targetSecond, 0) if (nextTime <= now) { nextTime.setHours(nextTime.getHours() + 1) } return nextTime } // 处理每天执行 if ( parsed.second.type === 'specific' && parsed.minute.type === 'specific' && parsed.hour.type === 'specific' ) { const targetSecond = parsed.second.values[0] const targetMinute = parsed.minute.values[0] const targetHour = parsed.hour.values[0] nextTime.setHours(targetHour, targetMinute, targetSecond, 0) if (nextTime <= now) { nextTime.setDate(nextTime.getDate() + 1) } return nextTime } // 处理步长执行 if (parsed.minute.type === 'step') { const step = parseInt(parsed.minute.original.split('/')[1]) const currentMinute = nextTime.getMinutes() const nextMinute = Math.ceil(currentMinute / step) * step if (nextMinute >= 60) { nextTime.setHours(nextTime.getHours() + 1, 0, 0, 0) } else { nextTime.setMinutes(nextMinute, 0, 0) } return nextTime } // 对于其他复杂情况,返回一个估算时间 return new Date(now.getTime() + 60000) // 1分钟后 } /** 获取 CRON 表达式的执行频率描述 */ static getFrequencyDescription(cronExpression: string): string { const parsed = this.parse(cronExpression) if (!parsed.isValid) { return '无效表达式' } // 计算大概的执行频率 if (parsed.second.type === 'any' && parsed.minute.type === 'any') { return '每秒执行' } if (parsed.minute.type === 'any' && parsed.hour.type === 'any') { return '每分钟执行' } if (parsed.hour.type === 'any' && parsed.day.type === 'any') { return '每小时执行' } if (parsed.day.type === 'any' && parsed.month.type === 'any') { return '每天执行' } if (parsed.month.type === 'any') { return '每月执行' } return '按计划执行' } /** 检查 CRON 表达式是否会在指定时间执行 */ static willExecuteAt(cronExpression: string, targetDate: Date): boolean { const parsed = this.parse(cronExpression) if (!parsed.isValid) { return false } // 检查各个字段是否匹配 const second = targetDate.getSeconds() const minute = targetDate.getMinutes() const hour = targetDate.getHours() const day = targetDate.getDate() const month = targetDate.getMonth() + 1 const weekDay = targetDate.getDay() return ( this.fieldMatches(parsed.second, second) && this.fieldMatches(parsed.minute, minute) && this.fieldMatches(parsed.hour, hour) && this.fieldMatches(parsed.day, day) && this.fieldMatches(parsed.month, month) && (parsed.week.type === 'any' || this.fieldMatches(parsed.week, weekDay)) ) } /** 检查字段值是否匹配 */ private static fieldMatches(field: ParsedCronField, value: number): boolean { if (field.type === 'any') { return true } if (field.type === 'specific' || field.type === 'list') { return field.values.includes(value) } if (field.type === 'range') { return value >= field.values[0] && value <= field.values[field.values.length - 1] } if (field.type === 'step') { const [base, step] = field.original.split('/').map(Number) if (base === 0 || field.original.startsWith('*')) { return value % step === 0 } return value >= base && (value - base) % step === 0 } return false } }