YaoDocs

外观

计划任务 ​

计划任务即是定时作业，用于在指定的时间自动执行特定的处理器或异步任务。

利用任务计划功能，可以将任何 DSL 脚本、Flows 安排在某个最方便的时间运行。任务计划在每次系统启动的时候启动并在后台运行。 当我们需要在服务器上定时执行一些重复性的事件时使用的，可以通过计划任务程序来运行准备好的 DSL 脚本在某个特定的时间运行。

配置 ​

创建定时作业配置文件./schedules/mail.sch.yao,配置文件需要保存在目录schedules,配置文件后缀名为：sch.yao,sch.jsonc, sch.json

计划任务支持两种调度方式，如果两个配置同时存在，优先使用异步任务。

  • 直接调用处理器：适用于执行时间较短的简单任务
  • 调用异步任务：如果是长时间耗时任务，建议使用异步任务，避免阻塞其他计划任务的执行

基本配置项 ​

配置项说明是否必填
name计划任务名称是
process要执行的处理器是
scheduleCron 表达式，定义任务执行时间是
task异步任务 ID，如果要以异步任务方式执行，需要填写对应的 task ID否
args处理器参数或异步任务参数否

配置示例 ​

示例 1：每 5 分钟执行一次的邮件接收任务 ​

json
{
  "name": "receive mail",
  "process": "scripts.app.email.client.receive",
  "schedule": "0/5 * * * *",
  "task": "",
  "args": []
}

示例 2：每天凌晨 1 点执行的数据备份任务（使用异步任务） ​

json
{
  "name": "database backup",
  "process": "",
  "schedule": "0 1 * * *",
  "task": "backup",
  "args": ["main_db"]
}

示例 3：工作日每小时执行的数据同步任务 ​

json
{
  "name": "sync data",
  "process": "scripts.sync.data",
  "schedule": "0 * * * 1-5",
  "args": []
}

Cron 表达式说明 ​

在 Yao 中，计划任务表达式与 Linux 的 crontab 不同，它的最小周期是分钟，而不是秒。

表达式的文档参考：https://pkg.go.dev/github.com/robfig/cron/v3@v3.0.0

Cron 表达式由 5 个空格分隔的字段组成：

字段名称是否必填允许的值允许的特殊字符
分钟是0-59* / , -
小时是0-23* / , -
日期是1-31* / , - ?
月份是1-12 或 JAN-DEC* / , -
星期是0-6 或 SUN-SAT* / , - ?

特殊字符说明 ​

  • *：表示任意值
  • /：步进值，如 */5 表示每 5 个单位
  • ,：列举值，如 1,3,5 表示 1、3、5 这三个值
  • -：范围值，如 1-5 表示 1 到 5 的所有值
  • ?：用于日期和星期字段，表示不指定具体值

常用表达式示例 ​

  • 0 * * * * - 每小时整点执行
  • */15 * * * * - 每 15 分钟执行一次
  • 0 0 * * * - 每天午夜 0 点执行
  • 0 8-18 * * 1-5 - 工作日上午 8 点到下午 6 点整点执行
  • 0 0 1 * * - 每月 1 号 0 点执行

最佳实践 ​

  1. 合理安排执行时间

    • 避免在业务高峰期执行耗时任务
    • 将数据备份等重要任务安排在系统负载较低的时段

  2. 异常处理

    • 在处理器中实现完善的错误处理机制
    • 记录任务执行日志，便于问题排查

  3. 资源管理

    • 评估任务的资源消耗
    • 合理分配并发任务数量
    • 对于耗时任务，建议使用异步任务方式执行

  4. 监控和维护

    • 定期检查任务执行状态和日志
    • 及时清理过期的任务配置
    • 对关键任务设置监控告警

调试方法 ​

  1. 使用日志

    javascript
    function taskHandler(...args) {
  console.log('Task started', args);
  try {
    // 任务处理逻辑
    console.log('Task completed');
  } catch (err) {
    console.error('Task failed:', err);
    throw err;
  }
}

  2. 手动触发测试

    • 可以通过处理器直接调用任务逻辑进行测试
    • 使用较小的测试数据验证任务逻辑

  3. 环境隔离

    • 在开发环境中使用较高的执行频率进行测试
    • 在生产环境中使用正常的执行频率