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

使用 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。

Workflow Update 从校验到接受和完成的生命周期

Accepted 的关键意义是 Update 已经通过校验并被持久化。若 Handler 后续执行失败,调用方仍会在等待结果时收到失败,而不是把它误认为“从未接收过”。这比单纯把命令塞进异步消息后自行猜测处理结果更明确。

实现带校验的状态修改

下面实现一个库存 Workflow。Workflow 代码是片段示例,依赖已经启动的 Temporal Server,以及一个把 inventoryWorkflow 注册到 update-demo Task Queue 的 Worker。

ts
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 阶段被拒绝。

ts
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);
});

预期输出

text
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 结束前是否仍有未完成的消息处理。

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

目录与阅读设置

阅读设置

17

记录一个想法

使用 Update 修改状态并返回结果

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

登录哪都通