Wing 云定时任务详解:使用 cloud.Schedule 编写 Cron 与周期性调度
Wing 云定时任务详解:使用 cloud.Schedule 编写 Cron 与周期性调度
cloud.Schedule 是 Wing 标准库(@winglang/sdk)内置的定时调度资源,用于按固定间隔或 Cron 表达式周期性地触发事件,是编写备份、数据同步、每日报表推送等定时任务的推荐方式。本文基于 cloud.Schedule 官方文档,结合其 SDK 源码实现与仓库测试用例,完整讲解 cron 与 rate 两种触发模式、参数校验规则、onTick 处理器注册方式,以及 Simulator、AWS、GCP 等平台底层的实现原理,帮助读者在真实项目中正确使用定时任务。
一、什么是 cloud.Schedule
cloud.Schedule 是一个抽象的预检(preflight)资源,其职责是在指定时刻周期性地触发事件,从而驱动一段 inflight 业务逻辑执行。它非常适合运行在云端、需要无人值守重复执行的任务,例如:
- 定期备份数据库或对象存储;
- 每日定时生成并发送业务报表;
- 定时轮询外部数据源并写入队列;
- 定期清理过期数据或回收闲置资源。
该资源的语义与领域无关,同一段 Wing 代码可以通过切换平台(sim、tf-aws、awscdk、tf-gcp 等)在本地模拟器或真实云环境中运行,这正是 Wing 统一编程模型的体现。SDK 中 Schedule 类定义于 packages/@winglang/sdk/src/cloud/schedule.ts,其节点描述为 "A cloud schedule to trigger events at regular intervals"。
一个重要的语义约定:Cron 表达式使用的时区始终是 UTC,这与 AWS EventBridge 等云服务的默认行为一致,在编写跨时区业务时需要注意时区换算。
二、两种触发模式:cron 与 rate
cloud.Schedule 提供两种互斥的触发方式,由 ScheduleProps 中的 cron 和 rate 两个可选字段决定。官方文档给出了两个最简示例,这里完整呈现并加以说明。
1. 使用 cron 表达式(cron)
bring cloud;
let schedule = new cloud.Schedule(cron: "* * * * *");
schedule.onTick(inflight () => {
log("schedule: triggered");
});
cron 字段接收 UNIX cron 格式的字符串,包含 5 个字段:<a href="https://link.gitcode.com/i/6d65157fb02e00b3d818067c7de558e6" target="_blank">minute] [hour] [day of month] [month] [day of week]。各字段的取值规则在 [ScheduleProps 定义 中有明确说明:
| 字段 | 允许取值 | 说明 |
|---|---|---|
minute |
0-59 | 分钟 |
hour |
0-23 | 小时 |
day of month |
1-31 | 月中的某一天 |
month |
1-12 或 JAN-DEC |
月份 |
day of week |
0-6 或 SUN-SAT |
星期几 |
通配符语法遵循 UNIX cron 规范:* 表示所有可能值,- 表示一个取值区间(如 9-17),, 表示取值列表(如 0,30)。示例 "* * * * *" 表示每分钟触发一次。
2. 使用周期速率(rate)
bring cloud;
let schedule = new cloud.Schedule(rate: 1m);
schedule.onTick(inflight () => {
log("schedule: triggered");
});
rate 字段接收 Wing 的 Duration 类型(如 1m、5m、30m),表示每隔一个固定时间间隔触发一次。需要注意:rate 最小粒度是 1 分钟,秒级精度不被支持(详见下文参数校验)。
3. 两种模式的选择建议
- 需要"每天凌晨 3 点"、"每月 1 日"这类具体时间点触发时,优先使用
cron,表达力更强; - 只需要"每 N 分钟/小时"这种固定频率时,使用
rate更简洁直观,且无需关心具体触发时刻。
从实现角度看,两种模式最终都会被各平台转换为对应的调度表达式(AWS 的 rate(N minutes) / cron(...)、GCP Cloud Scheduler 的 cron、模拟器的 cron 解析),差异仅在表达层。
三、onTick:注册定时触发的处理函数
onTick 是 Schedule 唯一的对外方法,用于注册定时事件触发时要执行的 inflight 函数,其签名定义如下:
onTick(inflight: IScheduleOnTickHandler, props?: ScheduleOnTickOptions): Function
schedule.onTick(inflight () => {
// 定时触发的业务逻辑
});
该方法接受一个实现了 IScheduleOnTickHandler 的 inflight 闭包,并返回一个 cloud.Function 资源——这意味着每个 onTick 注册本质上都会在目标平台创建一个云函数(如 AWS Lambda、GCP Cloud Functions),调度器到点后触发该函数执行。从 cloud/schedule.ts 的抽象声明看,onTick 是抽象方法,具体行为由各平台的 Schedule 子类实现。
一个 Schedule 可以注册多个 onTick 处理器。在 AWS 实现(target-tf-aws/schedule.ts)中,同一个 inflight 处理器会被缓存复用(通过 handlers[inflight._id] 去重),避免重复创建函数。
ScheduleOnTickOptions:处理器函数的配置项
onTick 的第二个可选参数 props 类型为 ScheduleOnTickOptions,它在源码中定义为 extends FunctionProps(见 cloud/schedule.ts),即完全继承 cloud.Function 的配置能力。各配置项及默认值如下(依据 API 参考文档 与 FunctionProps):
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
concurrency |
num |
平台相关(模拟器为 100) | 同一时刻允许的最大并发调用数 |
env |
MutMap<str> |
无 | 注入处理函数的环境变量 |
logRetentionDays |
num |
30 | 函数日志保留天数,负值表示日志永不过期 |
memory |
num |
1024 | 分配给函数的内存,单位 MB |
timeout |
duration |
1m |
函数最长运行时间 |
例如,可以这样为定时任务配置更长的超时和更多内存:
let schedule = new cloud.Schedule(cron: "0 2 * * *"); // 每天凌晨 2 点(UTC)
schedule.onTick(
inflight () => {
// 执行耗时较长的数据批处理
},
timeout: 10m,
memory: 2048,
logRetentionDays: 7,
);
四、构造参数的校验规则与常见错误
Schedule 的构造器内置了严格的参数校验(见 cloud/schedule.ts),确保 cron 与 rate 的配置合法。仓库的测试文件 tests/sdk_tests/schedule/init.test.w 逐一验证了这些错误分支,是理解校验行为的最佳依据:
| 校验条件 | 触发错误信息 |
|---|---|
rate 与 cron 同时配置 |
rate and cron cannot be configured simultaneously. |
rate 与 cron 均为空 |
rate or cron need to be filled. |
rate 小于 1 分钟(如 1s) |
rate can not be set to less than 1 minute. |
cron 不是合法的 UNIX cron 格式(如 6 字段 "* * * * * *",或含 ? 的 "* * * * ?") |
cron string must be in UNIX cron format |
其中 cron 格式校验由 cron-validator 库完成,校验选项在源码中明确指定为:alias: true(允许 JAN-DEC、SUN-SAT 这类别名)、allowSevenAsSunday: true(允许 7 表示周日)、allowBlankDay: false、seconds: false(不启用秒字段)。因此传入 6 字段或含 AWS 风格 ? 的表达式都会在构造阶段直接报错,这种"fail fast"设计能尽早暴露配置错误,而不是等到部署后才失败。
五、各平台实现原理
cloud.Schedule 是抽象资源,Wing 会根据编译目标平台选择具体实现。以下分别说明仓库中可确认的各平台实现。
1. 模拟器(sim):基于 setTimeout 的递归调度
原文档说明模拟器使用 JavaScript 标准的 setTimeout 触发 tick 回调。深入源码可以看到更完整的调度机制(target-sim/schedule.ts 与 target-sim/schedule.inflight.ts):
- 构造时,
rate会被转换为 cron 表达式:cron ?? convertDurationToCronExpression(rate!)。转换逻辑位于 target-sim/util.ts:将分钟数拆分为小时与分钟,生成*/m */h * * *形式的 cron(不足 1 分钟的秒级精度会抛错)。 - inflight 运行时,用
cron-parser的parseExpression(cronExpression, { utc: true })解析表达式(schedule.inflight.ts),通过interval.next()计算下一次执行时刻与当前时间的差值,再用setTimeout延迟触发;任务执行完成后递归调用scheduleFunction()继续安排下一次执行(schedule.inflight.ts)。 - 每个 tick 到点时,遍历所有已注册任务,通过模拟器上下文获取对应的
IFunctionClient并调用invoke(),单次调用失败会被捕获并记录为 error 级别 trace(schedule.inflight.ts)。
也就是说,模拟器实现了一个纯 JavaScript 的、行为接近云端语义的定时器,方便在本地无云环境下联调测试。
2. AWS(tf-aws / awscdk):基于 Amazon EventBridge(CloudWatch Events)
原文档将 AWS 实现指向 Amazon CloudWatch(即 EventBridge 规则)。源码实现位于 target-tf-aws/schedule.ts 与共享逻辑 shared-aws/schedule.ts:
- 构造时生成 AWS 调度表达式(target-tf-aws/schedule.ts):
rate模式:rate(N minute(s)),精确到分钟;cron模式:cron(<转换后的表达式>)。
- 创建一个
CloudwatchEventRule承载scheduleExpression;每次onTick注册时创建一个Function(Lambda),为其添加来自events.amazonaws.com的调用权限,并创建CloudwatchEventTarget将规则指向该函数的 ARN(target-tf-aws/schedule.ts)。
需要特别说明 UNIX cron 到 AWS cron 的转换(shared-aws/schedule.ts),这是跨平台语义差异的典型体现,包含三条规则:
*冲突处理:AWS 不允许day of month与day of week同时为*,当两者都为*时,将day of week替换为?;- 双限制报错:若
day of month与day of week都指定了具体值,直接抛错Cannot restrict both 'day-of-month' and 'day-of-week' in a cron expression, at least one must be '*'; - 字段偏移与扩展:AWS 的星期字段取值是 1-7(1 为周日)而 UNIX 是 0-6(0 为周日),因此数值型
day of week会通过convertDayOfWeekFromUnixToAWS整体 +1 偏移;同时 AWS 使用包含年份的 6 字段格式,转换末尾会追加*作为年份字段。
这意味着 Wing 侧统一使用 UNIX cron 语法,平台差异由 SDK 在编译期自动适配。
3. GCP(tf-gcp):Cloud Scheduler 实现
原文档标记 GCP 为"尚未支持"(tracking issue #1292),但从仓库源码结构看,target-tf-gcp/schedule.ts 已经包含完整的 GCP 实现,可以推断该平台正在演进中。其实现要点:
- 调度表达式为 UNIX cron 格式,
rate模式被转换为*/N * * * *(每 N 分钟,见 target-tf-gcp/schedule.ts); - 每次
onTick创建处理函数后,会创建一个专用ServiceAccount,为函数授予调用权限,再创建CloudSchedulerJob,以Etc/UTC时区、HTTP GET 请求(携带 OIDC token)的方式定时调用函数的 HTTPS 触发器(target-tf-gcp/schedule.ts)。
读者若使用 tf-gcp 平台,应以实际编译产物为准,同时留意该实现与文档标记状态的差异。
4. Azure(tf-azure):暂不支持
原文档明确标注 Azure 平台尚未支持 cloud.Schedule(tracking issue #1291),仓库中也没有发现对应的 Azure 实现文件。在 tf-azure 平台上使用 Schedule 需要关注项目后续的 issue 进展。
六、测试验证:定时任务行为如何被检验
仓库为 Schedule 提供了针对性的 SDK 测试,可用于理解正确的用法与预期行为:
- init.test.w:验证合法构造(
rate: 5m)以及上述四种非法参数组合均抛出预期错误信息,是参数规则的直接证据; - on_tick.test.w:创建一个
cron: "* * * * *"和一个rate: 1m的 Schedule,各自注册onTick自增计数器,然后在测试内等待 2.1 分钟,断言两个计数器都被至少递增了一次——直观验证了两种模式"每分钟触发"的实际行为。测试还展示了std.Test配合timeout的用法,说明在模拟器上验证定时任务时,需要让测试等待足够长的周期。
七、实战要点小结
- 时区固定为 UTC:所有 cron 表达式按 UTC 解释,涉及本地时间换算时自行偏移;
- 二选一配置:
cron与rate不能同时设置,也不能都为空;rate最小 1 分钟; - cron 用 UNIX 格式:5 字段、支持
*/-/,与月份、星期的别名写法,6 字段或?会被拒绝; onTick返回云函数:每个注册都会在目标平台创建函数资源,可用ScheduleOnTickOptions(继承FunctionProps)配置内存、超时、并发、环境变量与日志保留期;- 平台差异由 SDK 适配:UNIX cron 在 AWS 上会自动转换(
?占位、星期偏移、年份字段),业务代码无需感知; - 本地开发用
sim:模拟器通过setTimeout递归调度真实执行 tick,配合std.Test可编写端到端的定时任务行为测试。
依赖本文讲解的资源,你可以在 packages/@winglang/sdk/src/cloud/schedule.ts 查看完整类型定义,在 docs/api/04-standard-library/cloud/schedule.md 查阅生成式 API 参考,并通过 tests/sdk_tests/schedule 下的测试用例加深对边界行为的理解。