Wing 云定时任务详解:使用 cloud.Schedule 编写 Cron 与周期性调度

原创2026-10-12 12:35:261,996 阅读
文章标签:编程语言编译器云原生语言运行时

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),这是跨平台语义差异的典型体现,包含三条规则:

  1. * 冲突处理:AWS 不允许 day of month 与 day of week 同时为 *,当两者都为 * 时,将 day of week 替换为 ?;
  2. 双限制报错:若 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 '*';
  3. 字段偏移与扩展: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 下的测试用例加深对边界行为的理解。

登录后查看全文
wing