服务注册与分布式协调 / 系统课时
使用 Schedule 触发周期工作流
使用 Schedule 触发周期工作流
本课解决“应用内 cron 越跑越难管”的问题:把周期启动交给 Temporal Schedule,并用重叠策略、补跑和暂停能力控制执行节奏,最终让周期任务具备统一的可观测与运维入口。
学习目标
- 能创建一个按固定间隔启动 Workflow 的 Schedule
- 能根据任务耗时选择重叠策略,并理解补跑与暂停的边界
- 能用 Schedule Handle 执行暂停、补跑、查看等运维操作
Schedule 的职责
Schedule 不是把 cron 字符串塞进业务代码,而是在 Temporal Service 中保存“何时启动什么 Workflow,以及发生重叠时怎么处理”的调度配置。创建后,Schedule 可以被描述、更新、暂停、触发和补跑;删除 Schedule 也不会终止已经启动的 Workflow。:contentReference[oaicite:0]{index=0}

创建一个周期 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 连接。
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;
});预期输出
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()。
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;
});预期输出
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 处理暂停、查看和补跑。这样周期任务才真正从“进程里的定时器”升级成可控制的工作流调度资源。