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

使用 SideEffect 记录外部值

使用 SideEffect 记录外部值

本篇解决 Workflow 中确实需要读取非确定值时如何保持重放一致。你将用 sideEffect 记录一次性结果,用 mutableSideEffect 管理可变化的外部值,并判断事件历史成本与适用边界。

学习目标

  • 理解 sideEffect 和 mutableSideEffect 为什么能让非确定值参与确定性 Workflow
  • 能写出记录随机数、时间之外外部值的正确用法,并验证重放时不会重新计算
  • 能识别不该使用 SideEffect 的场景,控制 Marker 事件和历史体积

SideEffect 解决的核心问题

Temporal Workflow 可能因为故障恢复而重放历史。相同历史必须得到相同控制流,因此不能直接在 Workflow 中使用随机数、当前时间以外的普通系统时间、环境变量读取或不可预测的外部状态。

sideEffect 的思路不是把非确定函数变成确定函数,而是第一次执行时把结果写入 Workflow History,后续重放直接读取历史中的结果。因此真正需要稳定的是结果,而不是函数本身。

SideEffect 与 Workflow History 的记录和重放关系

用 SideEffect 记录一次性结果

典型场景是需要在 Workflow 中得到一个本身不确定、但结果应该在整个 Workflow 生命周期内保持不变的值。下面使用随机数演示:Workflow 首次运行会生成一次结果,重放时 Temporal 从历史读取相同结果。

ts
import { proxyActivities, sideEffect } from '@temporalio/workflow';

const { recordDecision } = proxyActivities<{
  recordDecision(value: number): Promise<void>;
}>({
  startToCloseTimeout: '1 minute',
});

export async function chooseBucket(): Promise<number> {
  // 随机函数只负责产生一次结果,稳定性由历史中的 Marker 保证。
  const bucket = await sideEffect(() => Math.floor(Math.random() * 100));

  await recordDecision(bucket);
  return bucket;
}

预期结果

text
首次执行:生成一个 0~99 的整数,例如 37,并把 37 记录进 Workflow History
发生重放:不重新调用 Math.random(),仍得到 37
Activity 收到的参数:37

这里的关键不是“随机数变得确定”,而是随机结果被持久化为历史事实。因此 sideEffect 更适合一次性决策,例如生成随机分桶值、生成短期随机令牌或读取一个只需在该次 Workflow 中固定的外部值。

用 MutableSideEffect 控制变化次数

有些外部值允许变化,但在值没有真正变化时又不希望每次调用都产生新的历史事件。这时可以使用 mutableSideEffect,并提供稳定的标识和相等比较函数。

ts
import { mutableSideEffect } from '@temporalio/workflow';

export async function getRoutingVersion(): Promise<string> {
  const version = await mutableSideEffect(
    'routing-version',
    () => process.env.ROUTING_VERSION ?? 'v1',
    (previous, current) => previous === current,
  );

  return version;
}

预期结果

text
第一次得到 v1:历史记录 v1
再次得到 v1:比较结果相等,不产生新的值变更记录,继续使用 v1
后续得到 v2:比较结果不相等,历史记录新的 v2,Workflow 使用 v2

mutableSideEffect 适合“同一个外部值偶尔改变”的场景,例如读取某个版本开关、配置版本或路由版本。它的比较函数也必须保持确定性,否则不同 Worker 在重放时可能得出不同结论。

需要特别注意:Workflow 中直接访问进程环境并不能把运行环境本身变成历史事实;这里依赖的是 mutableSideEffect 对返回值的记录机制。外部值的来源如果会产生网络请求、数据库查询或其他真正的 I/O,应优先放到 Activity 中。

事件历史成本与使用边界

SideEffect 会增加 Workflow History 中的事件数据。调用次数多、返回值大,都会增加历史重放和存储成本,因此它不是“任何非确定逻辑都包一层”的通用逃生口。

可以这样判断:一次性的小型值需要固定下来,可考虑 sideEffect;同一逻辑会反复检查且只有值变化时才需要记录,可考虑 mutableSideEffect;需要真正访问外部系统或执行有业务副作用的操作,则应该设计为 Activity。

当非确定值本身很大,或者需要频繁刷新时,更应该考虑把读取逻辑放进 Activity,再由 Workflow 根据 Activity 返回值推进状态。这样可以把外部访问的重试、超时和可观测性留在 Activity 层,同时避免无意义地膨胀 Workflow History。

最终原则是:SideEffect 记录的是“Workflow 必须记住的值”,不是“Workflow 可以偷偷执行副作用的地方”。只要一个值需要依赖历史保证重放一致,就应优先考虑它是否足够小、足够稳定,以及是否真的属于 Workflow 决策的一部分。

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

目录与阅读设置

阅读设置

17

记录一个想法

使用 SideEffect 记录外部值

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

登录哪都通