服务注册与分布式协调 / 系统课时
使用 Update 修改状态并返回结果
使用 Update 修改状态并返回结果
当调用方不仅要改变 Workflow 状态,还必须马上知道“这次修改是否被接受、修改后的结果是什么”时,Workflow Update 比 Signal 更合适。它支持在执行前校验输入,接受后持久化,并让调用方等待接受阶段或最终执行结果。
学习目标
- 使用
defineUpdate与setHandler实现可返回结果的状态修改。 - 使用 Validator 在 Update 被接受前拒绝非法请求。
- 区分 Update 的 Accepted、Completed 语义以及它与 Signal 的确认差异。
Update 的确认语义
Signal 与 Update 都能向运行中的 Workflow 发送消息并改变状态,但调用方得到的确认不同。
| 能力 | Signal | Update |
|---|---|---|
| 修改 Workflow 状态 | 可以 | 可以 |
| Handler 返回业务结果 | 不返回给发送方 | 可以 |
| 发送方等待 Handler 完成 | 不保证 | 可以 |
| 接受前业务校验 | 通常在 Handler 内自行处理 | 可使用 Validator 在接受前拒绝 |
| 典型用途 | 通知、触发、异步控制 | 同步命令、库存预留、配置修改 |
executeUpdate 会等待 Update 完成并直接返回 Handler 的结果;startUpdate 可以先等待到 Accepted,再拿到 Update Handle,之后通过 result() 等待 Completed。这让“请求已被可靠接受”和“业务处理已经完成”成为两个可区分的阶段。
校验、接受与完成
Validator 在 Update Handler 之前运行,只能读取 Workflow 状态并校验参数,不能修改状态或发出 Workflow 命令。校验失败时请求被拒绝,Handler 不执行;通过校验或未配置 Validator 时,Update 进入 Accepted,随后执行 Handler 并最终进入 Completed。

Accepted 的关键意义是 Update 已经通过校验并被持久化。若 Handler 后续执行失败,调用方仍会在等待结果时收到失败,而不是把它误认为“从未接收过”。这比单纯把命令塞进异步消息后自行猜测处理结果更明确。
实现带校验的状态修改
下面实现一个库存 Workflow。Workflow 代码是片段示例,依赖已经启动的 Temporal Server,以及一个把 inventoryWorkflow 注册到 update-demo Task Queue 的 Worker。
import { condition, defineUpdate, setHandler } from '@temporalio/workflow';
export const reserveStock = defineUpdate<number, [number]>('reserveStock');
export async function inventoryWorkflow(initialStock: number): Promise<void> {
let available = initialStock;
setHandler(
reserveStock,
(quantity: number) => {
// 只有通过 Validator 的请求才会真正修改库存。
available -= quantity;
return available;
},
{
validator: (quantity: number) => {
if (!Number.isInteger(quantity) || quantity <= 0) {
throw new Error('quantity must be a positive integer');
}
if (quantity > available) {
throw new Error(`insufficient stock: ${available}`);
}
},
},
);
// 示例保持 Workflow 运行,以便持续接收 Update。
await condition(() => false);
}客户端先用 startUpdate 等待 Accepted,再等待最终结果;第二次请求超过剩余库存,会在 Validator 阶段被拒绝。
import {
Client,
Connection,
WorkflowUpdateStage,
} from '@temporalio/client';
import { inventoryWorkflow, reserveStock } from './workflows';
async function main(): Promise<void> {
const connection = await Connection.connect();
const client = new Client({ connection });
// 启动一个库存为 10 的长运行 Workflow。
const handle = await client.workflow.start(inventoryWorkflow, {
taskQueue: 'update-demo',
workflowId: `inventory-${Date.now()}`,
args: [10],
});
// 先等待 Accepted,再通过 Update Handle 等待 Completed。
const update = await handle.startUpdate(reserveStock, {
args: [3],
waitForStage: WorkflowUpdateStage.ACCEPTED,
});
console.log('accepted');
console.log(`remaining=${await update.result()}`);
// executeUpdate 直接等待最终结果;非法请求会在 Validator 阶段失败。
try {
await handle.executeUpdate(reserveStock, { args: [8] });
} catch {
console.log('rejected');
}
}
main().catch((err) => {
console.error(err);
process.exit(1);
});预期输出
accepted
remaining=7
rejected第一个请求在 Validator 看到库存为 10 时通过,Handler 扣减 3 并返回 7;第二个请求看到库存只剩 7,因此在真正修改状态之前被拒绝。
选择 Update 还是 Signal
需要调用方拿到业务返回值、确认输入已被接受,或希望在修改前执行显式校验时,优先使用 Update。若调用方只需要“发出通知后继续做自己的事”,不希望同步等待 Workflow 处理,Signal 往往更自然。
同步 Handler 像本例一样在一个 Workflow Task 内完成最容易推理;如果 Update Handler 会 await Timer、Activity 或其他长期操作,还要额外考虑多个 Handler 与主 Workflow 逻辑之间的并发交错,以及 Workflow 结束前是否仍有未完成的消息处理。