iii-cron-scheduling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cron Scheduling

Cron 调度

Comparable to: node-cron, APScheduler, crontab

同类工具：node-cron、APScheduler、crontab

Key Concepts

核心概念

Use the concepts below when they fit the task. Not every scheduled job needs all of them.

Cron expressions use a 7-field format:

second minute hour day month weekday year

CronModule evaluates expressions and fires triggers on schedule
Handlers should be fast — enqueue heavy work to a queue instead of blocking the cron handler
Each cron trigger binds one expression to one function
Overlapping schedules are fine; each trigger fires independently

当任务符合以下场景时使用这些概念，并非所有调度任务都需要用到全部概念。

Cron表达式采用7字段格式：

second minute hour day month weekday year

CronModule会解析表达式并按调度触发触发器
处理程序应快速执行——将繁重工作加入队列，而非阻塞cron处理程序
每个cron触发器将一个表达式绑定到一个函数
重叠调度不受影响；每个触发器独立触发

Architecture

架构

CronModule timer tick → registerTrigger type:'cron' expression match → registerFunction handler → (optional) TriggerAction.Enqueue for heavy work

CronModule timer tick → registerTrigger type:'cron' expression match → registerFunction handler → (可选) TriggerAction.Enqueue for heavy work

iii Primitives Used

使用的核心组件

Primitive	Purpose
`registerFunction`	Define the handler for the scheduled job
`registerTrigger({ type: 'cron' })`	Bind a cron expression to a function
`config: { expression: '0 0 9 * * * *' }`	Cron schedule in 7-field format

核心组件	用途
`registerFunction`	定义调度任务的处理程序
`registerTrigger({ type: 'cron' })`	将cron表达式绑定到函数
`config: { expression: '0 0 9 * * * *' }`	7字段格式的Cron调度

Reference Implementation

参考实现

See ../references/cron-scheduling.js for the full working example — a recurring scheduled task that fires on a cron expression and optionally enqueues heavy work.

Also available in Python: ../references/cron-scheduling.py

Also available in Rust: ../references/cron-scheduling.rs

完整可运行示例请查看 ../references/cron-scheduling.js —— 一个基于cron表达式触发的周期性调度任务，可选择将繁重工作加入队列。

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

以及Rust版本：../references/cron-scheduling.rs

Common Patterns

常见模式

Code using this pattern commonly includes, when relevant:

```
registerWorker(url, { workerName })
```
— worker initialization
```
registerFunction(id, handler)
```
— define the scheduled handler

registerTrigger({ type: 'cron', config: { expression } })

— bind the schedule

trigger({ function_id, payload, action: TriggerAction.Enqueue({ queue }) })

— offload heavy work

```
const logger = new Logger()
```
— structured logging per job

相关场景下，使用此模式的代码通常包含：

```
registerWorker(url, { workerName })
```
—— 工作进程初始化
```
registerFunction(id, handler)
```
—— 定义调度处理程序

registerTrigger({ type: 'cron', config: { expression } })

—— 绑定调度规则

trigger({ function_id, payload, action: TriggerAction.Enqueue({ queue }) })

—— 卸载繁重工作

```
const logger = new Logger()
```
—— 按任务进行结构化日志记录

Adapting This Pattern

模式适配

Use the adaptations below when they apply to the task.

Adjust the 7-field expression to match your schedule (e.g.
```
0 0 */6 * * * *
```
for every 6 hours)
Keep the cron handler lightweight — use it to validate and enqueue, not to do the heavy lifting
For jobs that need state (e.g. last-run timestamp), combine with
```
iii-state-management
```
Multiple cron triggers can feed the same queue for fan-in processing

当符合以下场景时可进行适配：

调整7字段表达式以匹配你的调度需求（例如
```
0 0 */6 * * * *
```
表示每6小时执行一次）
保持cron处理程序轻量化——仅用于验证和入队，而非执行繁重工作
对于需要状态的任务（如最后运行时间戳），可结合
```
iii-state-management
```
使用
多个cron触发器可将任务送入同一队列，实现扇入处理

Engine Configuration

引擎配置

CronModule must be enabled in iii-config.yaml. See ../references/iii-config.yaml for the full annotated config reference.

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

Pattern Boundaries

模式边界

If the task is about one-off async work rather than recurring schedules, prefer
```
iii-queue-processing
```
.
If the trigger should fire on state changes rather than time, prefer
```
iii-state-reactions
```
.
Stay with
```
iii-cron-scheduling
```
when the primary need is time-based periodic execution.

如果任务是一次性异步工作而非周期性调度，建议使用
```
iii-queue-processing
```
。
如果触发器需基于状态变更而非时间触发，建议使用
```
iii-state-reactions
```
。
当核心需求是基于时间的周期性执行时，使用
```
iii-cron-scheduling
```
。

When to Use

使用场景

Use this skill when the task is primarily about
```
iii-cron-scheduling
```
in the iii engine.
Triggers when the request directly asks for this pattern or an equivalent implementation.

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

Boundaries

边界限制

Never use this skill as a generic fallback for unrelated tasks.
You must not apply this skill when a more specific iii skill is a better fit.
Always verify environment and safety constraints before applying examples from this skill.

切勿将此技能作为无关任务的通用 fallback 方案。
当更特定的 iii 技能更合适时，不得使用此技能。
在应用此技能的示例前，务必验证环境和安全约束。