一次性任务与重复任务的区别

一、一次性任务详解（recurring: false）

一次性任务（One-time Task）是在调用CronCreate时将 recurring 参数设为 false 所创建的任务模式，也称为"发射后不管"（fire-and-forget）模式。这种任务在指定的时间点精确执行一次，执行完毕后系统自动将其删除，无需任何后续清理操作。

核心特点包括：仅在指定时间执行一次，不会重复触发；执行完成后任务记录自动从系统中移除，不留残留；适合"明天上午10点提醒我开会"、"一小时后发送欢迎邮件"等一次性提醒场景；不需要开发者编写额外的任务管理和清理代码，大幅降低开发成本。

一次性任务的典型应用场景包括：用户注册后的欢迎通知、定时发送的验证码邮件、预约提醒短信、临时性的数据导出请求、以及任何只需要在未来某个时间点执行一次的延迟操作。

// 一次性任务示例：明天上午10点发送提醒
CronCreate({
  name: "meeting-reminder",
  cron: "0 10 * * *",
  data: { type: "reminder", msg: "10点会议提醒" },
  recurring: false
})

二、重复任务详解（recurring: true）

重复任务（Recurring Task）是通过将 recurring 参数设为 true（或省略该参数，因为默认值即为 true）创建的任务模式。这种任务会按照Cron表达式定义的时间规则持续重复执行，适用于需要周期性运行的业务逻辑。

核心行为机制：按Cron表达式持续重复执行，例如 "0 8 * * *" 表示每天早上8点执行；默认行为是当 recurring 省略时默认为 true，即如果不显式设为 false，系统将视为重复任务；任务创建后有效期为7天，超过7天自动过期不再触发，如需长时间运行需要设置 durable 持久化选项；适合日常巡检、周期报告生成、定时数据同步、健康检查等持续性场景。

重复任务与一次性任务最本质的区别在于其生命周期——重复任务不会自动消亡（除非设置了过期时间），它会按照既定的时间规则周期性醒来执行指定的任务逻辑。

// 重复任务示例：每天早上8点生成日报
CronCreate({
  name: "daily-report",
  cron: "0 8 * * *",
  data: { type: "report", format: "html" },
  durable: true       // 启用持久化，避免7天过期
})

三、生命周期对比表格

从多个维度对比一次性任务与重复任务的核心差异，帮助开发者快速理解两种模式的本质区别：

对比维度	一次性任务	重复任务
执行次数	仅执行一次	按Cron规则重复多次
自动清理	执行后自动删除	需手动删除或等待过期
持久化需求	不需要（执行即销毁）	需要 durable 选项避免7天过期
适用场景	一次性提醒、定时通知	周期性报告、持续监控
资源占用	低（创建后仅唤醒一次）	较高（周期性持续占用调度资源）
管理复杂度	低（无需后续管理）	中等（需监控运行状态、处理过期）
失败重试	单次失败即结束	下次周期自动重试
Cron表达式	仅用于指定执行时间点	用于定义重复周期

四、选择策略

在实际开发中，合理选择任务模式是保障系统健壮性和资源效率的关键。以下是基于不同业务需求的选择策略：

确定时间点只需一次——使用一次性任务（recurring: false）。这是最简单的场景，任务执行后自动清理，无需关心后续状态。例如：用户预约提醒、一次性密码验证。
需要持续监控——使用重复任务（recurring: true）。对于系统巡检、服务健康检查等持续性需求，重复任务配合Cron表达式可以精确控制检查频率。
不确定需要多久——先用一次性再加循环。可以先创建一个一次性任务作为"种子"，在该任务执行的逻辑中动态判断是否需要继续，如需继续则在执行体内再创建新的任务，形成灵活的运行链条。
周期性报告——使用重复任务 + durable 持久化。日/周/月报表等常规周期任务，设置 durable: true 可以避免7天过期限制，确保长期稳定运行。
临时性的定时操作——优先考虑一次性任务。很多开发者习惯性地将短时效的定时操作也做成重复任务，这不仅增加了系统负担，也带来了额外的管理成本。

选择建议：当不确定使用哪种模式时，先问自己一个问题——"这个任务如果执行完一次之后，未来是否还需要再次执行？"如果答案是"否"，请使用一次性任务。

五、混合编排技巧

在真实业务场景中，一次性任务和重复任务往往不是孤立使用的，将二者灵活组合可以实现更强大的业务逻辑。下面介绍几种常见的混合编排模式：

模式一：一次性任务触发后根据需要创建重复任务。典型的"开关"模式——用户执行某个一次性操作（如开启监控），该任务的处理逻辑中判断条件满足后，动态创建一个新的重复任务来持续执行后续操作。这种方式既保持了用户操作的即时响应，又实现了后续的自动化运行。

// 用户开启监控 → 创建一次性任务
CronCreate({
  name: "enable-monitoring",
  cron: "0 0 * * *",      // 次日零点执行
  recurring: false,
  data: { action: "start-monitor" }
})

// 在一次性任务的处理函数中
// 条件满足则创建重复任务
CronCreate({
  name: "health-check",
  cron: "*/5 * * * *",     // 每5分钟检查一次
  recurring: true,
  durable: true
})

模式二：重复任务中的某次执行判断目标达成后自动停止。重复任务每次执行时都会检查某个终止条件，一旦条件满足（如数据同步完成、目标指标达成），就在执行体内调用CronDelete主动删除自身，实现"智能自停"的效果。这种方式避免了手动干预，也防止了资源的无效占用。

// 重复任务执行体内的自停逻辑
function handleTask() {
  const done = checkTargetAchieved();
  if (done) {
    CronDelete({ name: "sync-job" });  // 目标达成，自我删除
  } else {
    doSync();                          // 继续执行同步
  }
}

模式三：通过CronDelete手动停止不再需要的重复任务。当业务发生变化，某个正在运行的重复任务不再需要时，可以随时通过CronDelete接口手动将其删除。这在运维管理、系统迁移、配置变更等场景中非常实用。

// 手动停止不再需要的重复任务
CronDelete({
  name: "daily-report"
})

模式四：一次性任务作为"延迟启动器"。有时我们希望重复任务从未来的某个时间点开始执行，而不是立即开始。此时可以先创建一个一次性任务作为启动器，在该启动器到达执行时间时再去创建真正的重复任务，从而实现"定时启动重复任务"的效果。

核心要点总结：一次性任务追求"使命必达、过河拆桥"，适合确认性的单次操作；重复任务追求"持续在线、循环往复"，适合常态化的周期运维。将二者灵活组合，可以设计出既高效又健壮的任务编排体系。在实际开发中，推荐默认优先考虑一次性任务，只有当确实需要周期性执行时才使用重复任务，并配合durable和CronDelete做好生命周期管理。