服务注册与分布式协调 / 系统课时

使用 Schedule 触发周期工作流

使用 Schedule 触发周期工作流

本课解决“应用内 cron 越跑越难管”的问题:把周期启动交给 Temporal Schedule,并用重叠策略、补跑和暂停能力控制执行节奏,最终让周期任务具备统一的可观测与运维入口。

学习目标

  • 能创建一个按固定间隔启动 Workflow 的 Schedule
  • 能根据任务耗时选择重叠策略,并理解补跑与暂停的边界
  • 能用 Schedule Handle 执行暂停、补跑、查看等运维操作

Schedule 的职责

Schedule 不是把 cron 字符串塞进业务代码,而是在 Temporal Service 中保存“何时启动什么 Workflow,以及发生重叠时怎么处理”的调度配置。创建后,Schedule 可以被描述、更新、暂停、触发和补跑;删除 Schedule 也不会终止已经启动的 Workflow。:contentReference[oaicite:0]{index=0}

Schedule 触发与运维控制关系

创建一个周期 Schedule

TypeScript SDK 当前可以通过 client.schedule.create() 创建 Schedule。下面把一个名为 daily-report 的 Workflow 配置为每 24 小时启动一次;catchupWindow 控制错过计划时间后的补偿窗口,overlap 则定义上一轮仍在运行时下一轮该怎么处理。Temporal 官方示例同时支持 interval 和 calendar 两类时间规格。:contentReference[oaicite:1]{index=1}

下面是片段示例,依赖 Worker 已注册名为 dailyReport 的 Workflow,并使用默认 Namespace 与 Temporal Service 连接。

ts
import { Client, Connection, ScheduleOverlapPolicy } from '@temporalio/client';

async function main(): Promise<void> {
  const connection = await Connection.connect();
  const client = new Client({ connection });

  await client.schedule.create({
    scheduleId: 'daily-report',
    action: {
      type: 'startWorkflow',
      workflowType: 'dailyReport',
      args: [{ reportDate: 'scheduled' }],
      taskQueue: 'report-task-queue',
    },
    policies: {
      catchupWindow: '2 hours',
      overlap: ScheduleOverlapPolicy.SKIP,
    },
    spec: {
      intervals: [{ every: '24 hours' }],
    },
  });

  console.log('Schedule created: daily-report');
  await connection.close();
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

预期输出

text
Schedule created: daily-report

选择 SKIP 的含义是:若某次到点时已有该 Schedule 启动的 Workflow 正在运行,就不再额外启动这一轮。对于报表、周期汇总等“旧一轮没完成时,新一轮通常没有价值”的任务,这比无条件并发更安全。具体的重叠行为由 Schedule 的 Overlap Policy 决定。:contentReference[oaicite:2]{index=2}

补跑与暂停

周期调度最容易出问题的地方不是“能不能按时启动”,而是维护窗口和事故恢复。Temporal Schedule 提供 backfill() 按时间范围提前执行 Action,适合补发漏掉的时间段;pause() 则暂停未来的 Schedule 触发。暂停时,已经被 Schedule 启动且仍在运行的 Workflow 不会因为“暂停”而自动结束。:contentReference[oaicite:3]{index=3}

下面是一个运维片段示例:先暂停调度,再描述当前状态,需要补跑时再按时间窗口调用 backfill()。

ts
import { Client, Connection, ScheduleOverlapPolicy } from '@temporalio/client';

async function main(): Promise<void> {
  const connection = await Connection.connect();
  const client = new Client({ connection });
  const handle = client.schedule.getHandle('daily-report');

  await handle.pause('maintenance');

  const description = await handle.describe();
  console.log(`paused=${description.state.paused}`);

  await handle.backfill({
    start: new Date(Date.now() - 2 * 60 * 60 * 1000),
    end: new Date(Date.now() - 60 * 60 * 1000),
    overlap: ScheduleOverlapPolicy.SKIP,
  });

  console.log('Schedule paused and backfill submitted.');
  await connection.close();
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

预期输出

text
paused=true
Schedule paused and backfill submitted.

这里的时间范围只是示例,实际值会随执行时间变化。backfill 是“按时间范围补发 Action”,不是修改原来的业务数据,也不是把 Schedule 的时钟永久向后移动。Temporal 文档明确把 backfill 定义为在指定时间范围前提前执行 Action,可用于漏跑或提前测试。:contentReference[oaicite:4]{index=4}

重叠策略怎么选

不要先问“哪个策略最好”,先问“上一轮未完成时,下一轮还有没有业务价值”。若重复执行没有意义,可以优先考虑跳过;若允许多轮并发,就要确认下游幂等、资源容量和数据一致性。Schedule 的重叠策略是调度层面的约束,不能替代 Workflow 内部的业务幂等。

常见选择可以这样判断:

场景 关注点 建议方向
每日汇总、同步快照 重复一轮通常无意义 偏向跳过重叠
多轮任务可以并行 下游必须承受并发 允许并发
同一业务对象不能同时处理 需要串行 选择串行语义
维护期间暂时停发 未来触发不应继续增长 Pause,恢复后再评估补跑

从应用内 cron 迁移时的落点

迁移时,把“什么时候启动”从应用进程中移出,把“启动后做什么”继续留在 Workflow。这样应用实例重启不会让调度规则散落在多个副本里;同时,Schedule 本身有独立的查看、更新、暂停、触发和补跑入口。Temporal 官方文档也明确推荐使用 Schedule,而不是 Cron Job,因为 Schedule 提供了更多配置与运行期控制能力。:contentReference[oaicite:5]{index=5}

最终要形成的边界很简单:Schedule 负责何时启动与如何处理重叠,Workflow 负责一次业务执行如何可靠完成,运维通过 Schedule Handle 处理暂停、查看和补跑。这样周期任务才真正从“进程里的定时器”升级成可控制的工作流调度资源。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 Schedule 触发周期工作流

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通