iii-cron-scheduling

Cron 调度

类似于：node-cron、APScheduler、crontab

核心概念

适合任务时，请使用以下概念。并非每个定时任务都需要用到全部概念。

• Cron 表达式采用 7 个字段的格式：second minute hour day month weekday year
• CronModule 会解析表达式，并按计划触发
• 处理函数应当快速执行——将繁重工作加入队列，而不是阻塞 Cron 处理函数
• 每个 Cron 触发器将一个表达式绑定到一个函数
• 调度重叠没有问题；每个触发器都会独立触发

架构

CronModule 定时器每次触发
  → registerTrigger type:'cron' 匹配表达式
    → registerFunction 处理函数
      → （可选）TriggerAction.Enqueue 将繁重工作加入队列

使用的 iii 原语

原语	用途
registerFunction	定义定时任务的处理函数
registerTrigger({ type: 'cron' })	将 Cron 表达式绑定到函数
config: { expression: '0 0 9 * * * *' }	采用 7 个字段格式的 Cron 计划

参考实现

完整的可运行示例请参见 ../references/cron-scheduling.js ——一个按 Cron 表达式触发的重复定时任务，并可选择将繁重工作加入队列。

也提供 Python 版本：../references/cron-scheduling.py

也提供 Rust 版本：../references/cron-scheduling.rs

常见模式

使用此模式的代码通常会在适用时包含：

• registerWorker(url, { workerName }) — 初始化 Worker
• registerFunction(id, handler) — 定义定时处理函数
• registerTrigger({ type: 'cron', config: { expression } }) — 绑定计划
• trigger({ function_id, payload, action: TriggerAction.Enqueue({ queue }) }) — 将繁重工作转交处理
• const logger = new Logger() — 为每个任务记录结构化日志

调整此模式

适用时，请使用以下调整方式。

• 调整 7 个字段的表达式以匹配你的计划（例如，0 0 */6 * * * * 表示每 6 小时执行一次）
• 保持 Cron 处理函数轻量——用于验证并加入队列，而不是执行繁重工作
• 对于需要状态的任务（例如上次运行时间戳），请结合 iii-state-management
• 多个 Cron 触发器可以将任务发送到同一队列，以进行汇聚处理

引擎配置

必须在 iii-config.yaml 中启用 CronModule。完整的注释版配置参考请参见 ../references/iii-config.yaml。

模式边界

• 如果任务是一次性异步工作，而非重复调度，请优先使用 iii-queue-processing。
• 如果触发器应在状态变化时触发，而非按时间触发，请优先使用 iii-state-reactions。
• 如果主要需求是按时间周期执行，请使用 iii-cron-scheduling。

适用场景

• 当任务主要涉及 iii 引擎中的 iii-cron-scheduling 时，请使用此技能。
• 当请求直接要求采用此模式或实现等效功能时触发。

边界

• 切勿将此技能用作无关任务的通用兜底方案。
• 如果有更具体的 iii 技能更适合，则不得使用此技能。
• 应用此技能中的示例前，务必核实环境和安全约束。