Crontab 模块

Crontab 模块为 XScript 提供定时任务调度功能，支持秒级精度的 cron 表达式和灵活的任务管理。

功能特性

秒级 Cron 表达式 - 支持6段式 cron 语法（秒/分/时/日/月/周）

任务超时控制 - 为每个任务设置执行超时时间

优先级调度 - 支持任务优先级设置

事件驱动 - 通过事件名称或脚本路径触发任务执行

任务管理 - 添加、删除、运行任务

全局控制 - 启动、关闭、清空调度器

基本使用

引入模块

添加定时任务

删除任务

任务控制

API 参考

任务管理

`crontab.add(name, schedule, eventName, ...params)`

添加定时任务。

参数:

name (string) - 任务唯一标识

schedule (string) - Cron 表达式（格式：秒分时日月星期超时秒数）

eventName (string) - 要触发的事件名称或脚本路径（.js 文件）

params (可变参数) - 传递给事件处理器的参数

返回: (boolean) 是否添加成功

Cron 表达式格式:

秒 分 时 日 月 星期 超时秒数
* * * * * * 0
│ │ │ │ │ │ │
│ │ │ │ │ │ └─── 超时时间（秒），0表示无超时限制
│ │ │ │ │ └───── 星期 (0-6, 0=星期日)
│ │ │ │ └─────── 月份 (1-12)
│ │ │ └───────── 日期 (1-31)
│ │ └─────────── 小时 (0-23)
│ └───────────── 分钟 (0-59)
└─────────────── 秒 (0-59)

示例:

`crontab.padd(name, schedule, priority, eventName, ...params)`

添加带优先级的定时任务。

参数:

name (string) - 任务唯一标识

schedule (string) - Cron 表达式（格式：秒分时日月星期超时秒数）

priority (number) - 任务优先级（数字越大优先级越高，默认为9999）

eventName (string) - 要触发的事件名称或脚本路径

params (可变参数) - 传递给事件处理器的参数

返回: (boolean) 是否添加成功

示例:

`crontab.remove(name)`

删除指定任务。

参数:

name (string) - 任务名称

返回: (boolean) 是否删除成功

示例:

`crontab.clear()`

清空所有任务。

返回: (boolean) 是否成功

示例:

`crontab.run(name)`

立即执行指定任务一次（不影响定时调度）。

参数:

name (string) - 任务名称

返回: (boolean) 是否执行成功

示例:

`crontab.runAll()`

立即执行所有任务。

返回: (boolean) 是否成功

示例:

调度器控制

`crontab.startup()`

启动定时器，开始任务调度。

返回: (boolean) 是否成功

示例:

`crontab.shutdown()`

关闭定时器，停止任务调度。

返回: (boolean) 是否成功

示例:

Cron 表达式详解

表达式结构

本模块使用7段式 Cron 表达式：

秒 分 时 日 月 星期 超时秒数

字段说明

字段	允许值	特殊字符
秒	0-59	`*` `,` `-` `/`
分	0-59	`*` `,` `-` `/`
时	0-23	`*` `,` `-` `/`
日	1-31	`*` `,` `-` `/`
月	1-12	`*` `,` `-` `/`
星期	0-6 (0=星期日)	`*` `,` `-` `/`
超时	任意正整数	-

特殊字符

* - 任意值，匹配所有可能的值

, - 列举多个值，如 1,3,5 表示第1、3、5个单位

- - 范围，如 1-5 表示1到5

/ - 步长，如 */10 表示每10个单位

常用示例

注意事项

任务名称唯一 - 同名任务会导致添加失败

表达式验证 - 添加任务前会验证 cron 表达式格式

超时控制 - 超时时间设为0表示无超时限制，建议根据实际任务耗时设置合理的超时值

事件驱动 - 第三个参数是事件名称而非回调函数，需要配合事件系统使用

资源管理 - 不用的任务及时删除，避免资源浪费

秒级精度 - 本模块支持秒级调度，相比传统 crontab 更精确

实际应用场景

数据库备份

日志清理

数据同步

健康检查

报表生成

使用外部脚本

优先级任务示例

最佳实践

合理的执行频率 - 避免过于频繁的任务执行，每秒执行的任务要特别注意性能影响

设置超时时间 - 为每个任务设置合理的超时时间，防止任务卡死

日志记录 - 记录任务执行情况便于排查问题

错误处理 - 在事件处理器中添加错误处理逻辑

资源清理 - 任务执行完毕后清理临时资源

监控告警 - 关键任务失败时及时通知

避免阻塞 - 使用异步操作避免阻塞事件循环

任务隔离 - 不同类型的任务使用不同的事件名称

与标准 Crontab 的区别

特性	标准 Crontab	XScript Crontab
最小时间单位	分钟	秒
表达式段数	5段	7段（6段cron + 超时）
超时控制	不支持	支持
优先级	不支持	支持
执行方式	执行命令

crontab

Crontab 模块#

功能特性#

基本使用#

引入模块#

添加定时任务#

删除任务#

任务控制#

API 参考#

任务管理#

crontab.add(name, schedule, eventName, ...params)#

crontab.padd(name, schedule, priority, eventName, ...params)#

crontab.remove(name)#

crontab.clear()#

crontab.run(name)#

crontab.runAll()#

调度器控制#

crontab.startup()#

crontab.shutdown()#

Cron 表达式详解#

表达式结构#

字段说明#

特殊字符#

常用示例#

注意事项#

实际应用场景#

数据库备份#

日志清理#

数据同步#

健康检查#

报表生成#

使用外部脚本#

优先级任务示例#

最佳实践#

与标准 Crontab 的区别#

Crontab 模块

功能特性

基本使用

引入模块

添加定时任务

删除任务

任务控制

API 参考

任务管理

`crontab.add(name, schedule, eventName, ...params)`

`crontab.padd(name, schedule, priority, eventName, ...params)`

`crontab.remove(name)`

`crontab.clear()`

`crontab.run(name)`

`crontab.runAll()`

调度器控制

`crontab.startup()`

`crontab.shutdown()`

Cron 表达式详解

表达式结构

字段说明

特殊字符

常用示例

注意事项

实际应用场景

数据库备份

日志清理

数据同步

健康检查

报表生成

使用外部脚本

优先级任务示例

最佳实践

与标准 Crontab 的区别