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

修改 Workflow 时保持 Replay 兼容

修改 Workflow 时保持 Replay 兼容

这篇解决 Workflow 代码发布后的一个核心风险:旧执行已经写入历史,新 Worker 重放这些历史时,必须继续产生与历史匹配的命令序列。对会改变执行顺序或分支的修改,要用版本分支保护旧历史,再逐步淘汰旧路径。

学习目标

  • 能判断哪些 Workflow 修改可能破坏 Replay 兼容
  • 能使用 patched() 为不兼容改动建立新旧执行分支
  • 能理解何时可以安全使用 deprecatePatch() 清理旧版本

Replay 兼容的判断标准

Temporal 会根据 Event History 恢复 Workflow 状态,再让当前 Workflow 代码重放历史。只要同一段历史在当前代码下产生了不同的命令序列,就可能出现 nondeterminism,而不是普通的业务异常。

典型风险包括新增、删除或重排 Activity、Timer、Child Workflow 等命令,或者改变决定这些命令是否执行的条件。相比之下,只修改不影响 Workflow 命令决策的局部实现,通常不会改变历史与当前代码的对应关系。

旧历史与新代码的 Replay 兼容分支

判断一个改动是否安全时,不要只看源代码是否“语法上合理”,而要问:旧历史重放到这里时,当前代码还会不会生成同样的 Temporal Commands? 这是 Replay 兼容的核心检查标准。

用 patched 保护命令序列变化

TypeScript SDK 提供 patched(changeId) 建立确定性的版本分支。对于已有执行没有该 Patch Marker 的历史,调用结果会让代码走旧路径;新执行则可以走新路径。关键不是把新旧代码随便包进 if,而是保证旧分支能够重现原来的 Workflow 逻辑。

片段示例:假设旧版本先执行 activityA,再等待 Timer,再执行 activityB;新版本希望把 activityB 提前。

ts
import { patched, sleep } from "@temporalio/workflow";

export async function exampleWorkflow(): Promise<void> {
  if (patched("move-activity-b")) {
    // 新执行使用新的命令顺序。
    await activityB();
    await activityA();
  } else {
    // 旧历史必须保持原来的命令顺序。
    await activityA();
    await sleep("1 hour");
    await activityB();
  }
}

这里真正重要的是 else 分支不能被“顺手优化”。即使新代码看起来更简单,也不能让旧历史重放时少一次 Activity、少一个 Timer 或改变它们的先后顺序,否则版本分支本身就失去了保护作用。

用 Replay 测试拦截意外变更

代码审查只能发现一部分风险,最可靠的工程护栏之一是拿已有 Workflow History 对当前 Workflow 代码做 Replay 测试。TypeScript SDK 提供 Worker.runReplayHistory 等能力,可在 CI 中把保存下来的历史作为兼容性样本。

片段示例:下面只展示 Replay 检查的核心调用,历史文件来自既有的成功 Workflow 执行。

ts
import { Worker } from "@temporalio/worker";
import history from "./fixtures/workflow-history.json";

test("existing workflow history remains replayable", async () => {
  await Worker.runReplayHistory(
    {
      workflowsPath: require.resolve("./workflows"),
    },
    history,
  );
});

预期结果

text
PASS  workflow replay compatibility
  ✓ existing workflow history remains replayable

Tests: 1 passed, 1 total

一旦这类测试因为 nondeterminism 失败,不要第一时间修改测试让它通过。先对照历史检查新增、删除、重排的 Workflow Commands,再判断应该恢复兼容代码还是增加新的版本分支。

什么时候可以移除旧分支

patched() 不是永久保留的版本管理机制。完成版本切换后,需要确认仍可能重放的旧执行已经退出风险窗口,再使用 deprecatePatch(changeId) 过渡到没有旧业务分支的代码。

安全顺序通常是:先部署带 patched() 的版本,让旧历史和新执行同时得到正确处理;确认所有受旧逻辑影响的执行都已经结束,或者相关历史已经超过保留期;然后部署 deprecatePatch() 版本;最后在更晚的版本中彻底删除 Patch。

例如:

ts
import { deprecatePatch } from "@temporalio/workflow";

export async function exampleWorkflow(): Promise<void> {
  deprecatePatch("move-activity-b");
  await activityB();
  await activityA();
}

预期结果

text
Deployment accepted: new Workflow code uses the patched history marker
Replay compatibility is retained for executions within the supported patch window

这里的“可以删除”不是“代码看起来已经没人用了”,而是要以实际运行中的 Workflow 生命周期和 History 保留窗口为依据。对长期运行的 Workflow,宁可多保留一个 Patch,也不要过早删除导致旧历史无法重放。

哪些修改最值得先做 Replay 检查

最需要警惕的是会改变 Temporal 命令顺序或数量的改动,例如把 Activity 从循环外移到循环内、增加一个 Timer、改变 Child Workflow 的创建条件,或者重新排列多个异步步骤。它们都可能让旧 History 与当前代码产生不同的命令序列。

工程上可以把 Replay Test 与发布流程绑定:先用已有生产历史验证新代码,再部署 Worker;发现不兼容时先回到版本分支设计,而不是依赖“旧 Workflow 应该刚好跑不到那里”的假设。这样即使 Workflow 已经运行数月,代码演进仍然可以保持可控。

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

目录与阅读设置

阅读设置

17

记录一个想法

修改 Workflow 时保持 Replay 兼容

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

登录哪都通