服务注册与分布式协调 / 系统课时
使用 SideEffect 记录外部值
使用 SideEffect 记录外部值
本篇解决 Workflow 中确实需要读取非确定值时如何保持重放一致。你将用 sideEffect 记录一次性结果,用 mutableSideEffect 管理可变化的外部值,并判断事件历史成本与适用边界。
学习目标
- 理解
sideEffect和mutableSideEffect为什么能让非确定值参与确定性 Workflow - 能写出记录随机数、时间之外外部值的正确用法,并验证重放时不会重新计算
- 能识别不该使用 SideEffect 的场景,控制 Marker 事件和历史体积
SideEffect 解决的核心问题
Temporal Workflow 可能因为故障恢复而重放历史。相同历史必须得到相同控制流,因此不能直接在 Workflow 中使用随机数、当前时间以外的普通系统时间、环境变量读取或不可预测的外部状态。
sideEffect 的思路不是把非确定函数变成确定函数,而是第一次执行时把结果写入 Workflow History,后续重放直接读取历史中的结果。因此真正需要稳定的是结果,而不是函数本身。

用 SideEffect 记录一次性结果
典型场景是需要在 Workflow 中得到一个本身不确定、但结果应该在整个 Workflow 生命周期内保持不变的值。下面使用随机数演示:Workflow 首次运行会生成一次结果,重放时 Temporal 从历史读取相同结果。
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;
}预期结果
首次执行:生成一个 0~99 的整数,例如 37,并把 37 记录进 Workflow History
发生重放:不重新调用 Math.random(),仍得到 37
Activity 收到的参数:37这里的关键不是“随机数变得确定”,而是随机结果被持久化为历史事实。因此 sideEffect 更适合一次性决策,例如生成随机分桶值、生成短期随机令牌或读取一个只需在该次 Workflow 中固定的外部值。
用 MutableSideEffect 控制变化次数
有些外部值允许变化,但在值没有真正变化时又不希望每次调用都产生新的历史事件。这时可以使用 mutableSideEffect,并提供稳定的标识和相等比较函数。
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;
}预期结果
第一次得到 v1:历史记录 v1
再次得到 v1:比较结果相等,不产生新的值变更记录,继续使用 v1
后续得到 v2:比较结果不相等,历史记录新的 v2,Workflow 使用 v2mutableSideEffect 适合“同一个外部值偶尔改变”的场景,例如读取某个版本开关、配置版本或路由版本。它的比较函数也必须保持确定性,否则不同 Worker 在重放时可能得出不同结论。
需要特别注意:Workflow 中直接访问进程环境并不能把运行环境本身变成历史事实;这里依赖的是 mutableSideEffect 对返回值的记录机制。外部值的来源如果会产生网络请求、数据库查询或其他真正的 I/O,应优先放到 Activity 中。
事件历史成本与使用边界
SideEffect 会增加 Workflow History 中的事件数据。调用次数多、返回值大,都会增加历史重放和存储成本,因此它不是“任何非确定逻辑都包一层”的通用逃生口。
可以这样判断:一次性的小型值需要固定下来,可考虑 sideEffect;同一逻辑会反复检查且只有值变化时才需要记录,可考虑 mutableSideEffect;需要真正访问外部系统或执行有业务副作用的操作,则应该设计为 Activity。
当非确定值本身很大,或者需要频繁刷新时,更应该考虑把读取逻辑放进 Activity,再由 Workflow 根据 Activity 返回值推进状态。这样可以把外部访问的重试、超时和可观测性留在 Activity 层,同时避免无意义地膨胀 Workflow History。
最终原则是:SideEffect 记录的是“Workflow 必须记住的值”,不是“Workflow 可以偷偷执行副作用的地方”。只要一个值需要依赖历史保证重放一致,就应优先考虑它是否足够小、足够稳定,以及是否真的属于 Workflow 决策的一部分。