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

使用 Query 读取运行状态

使用 Query 读取运行状态

长流程执行几分钟甚至几天时,调用方常需要知道“现在进行到哪一步”。Query 用同步请求读取 Workflow 内存中的只读状态,不改变执行路径,也不向事件历史追加业务事件,适合进度页、诊断页和运维查看入口。

学习目标

  • 使用 defineQuery 与 setHandler 暴露类型安全的只读状态。
  • 理解 Query 与 Workflow 状态、Worker 和事件历史之间的关系。
  • 判断哪些信息适合 Query,哪些应改用 Search Attributes 或外部读模型。

Query 的职责边界

Query 是“读当前状态”的消息。调用方通过 Workflow Handle 发起 Query,Temporal 将请求交给能够执行该 Workflow 代码的 Worker,Query Handler 读取已经恢复出的 Workflow 状态并直接返回结果。

在 TypeScript SDK 中,Query Handler 必须同步返回,不能写入 Workflow 变量,也不能调度 Activity、Timer、Child Workflow 等命令。换句话说,Handler 可以计算和组装返回值,但它的执行不应改变下一次重放得到的状态。

读取链路与事件历史

一次 Query 涉及 Client、Temporal Service、Worker 与 Workflow 状态,但它和 Signal、Update 最大的区别是:Query 本身不写入 Workflow Event History。Worker 必要时先依据已有历史恢复状态,再执行只读 Handler,把结果沿原路返回。

Query 从客户端读取 Workflow 状态且不写入事件历史

因此,Query 很适合“这个订单现在处于什么阶段”“已经处理多少项”“当前等待什么条件”这类实例级问题,但不适合承担审计记录,因为同一次 Query 调用了多少次并不会成为 Workflow 历史的一部分。

用 Handler 暴露进度状态

下面使用 TypeScript SDK。Workflow 代码是片段示例,依赖已经启动的 Temporal Server,以及一个把 progressWorkflow 注册到 query-demo Task Queue 的 Worker。状态在 Workflow 主逻辑中更新,Query Handler 只返回快照。

ts
import { defineQuery, setHandler, sleep } from '@temporalio/workflow';

export interface Progress {
  status: 'WAITING' | 'DONE';
  completed: number;
  total: number;
}

export const getProgress = defineQuery<Progress>('getProgress');

export async function progressWorkflow(total: number): Promise<void> {
  // 业务状态只由 Workflow 主逻辑维护。
  let progress: Progress = {
    status: 'WAITING',
    completed: 2,
    total,
  };

  // Query 只读取当前状态,并返回一个新对象作为快照。
  setHandler(getProgress, () => ({ ...progress }));

  await sleep('10 minutes');
  progress = {
    status: 'DONE',
    completed: total,
    total,
  };
}

在 Worker 运行后,客户端可以启动实例并读取状态。Date.now() 位于普通 Client 代码中,不参与 Workflow 重放。

ts
import { Client, Connection } from '@temporalio/client';
import { getProgress, progressWorkflow } from './workflows';

async function main(): Promise<void> {
  const connection = await Connection.connect();
  const client = new Client({ connection });

  // Client 侧生成 Workflow ID,不参与 Workflow 的确定性重放。
  const handle = await client.workflow.start(progressWorkflow, {
    taskQueue: 'query-demo',
    workflowId: `progress-${Date.now()}`,
    args: [5],
  });

  // Query 直接返回 Handler 组装的只读快照。
  const progress = await handle.query(getProgress);
  console.log(progress);
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

预期输出

text
{ status: 'WAITING', completed: 2, total: 5 }

这里的 Query 名称由 defineQuery 固定,返回类型由 TypeScript 约束。调用方不需要访问 Worker 内存地址,也不需要自己重放历史,只需持有目标 Workflow 的 Handle。

设计只读状态的边界

Query 返回值应当小而稳定。优先暴露进度、当前阶段、最近一次业务决定等已经存在于 Workflow 状态中的信息,不要为了“查得更全”把大量历史数据复制成一个巨型对象。

如果需求是跨成千上万个 Workflow 做筛选、排序和聚合,应使用 Visibility 与 Search Attributes;如果需要长期报表或复杂查询,应把数据投影到数据库等外部读模型。Query 最适合回答单个 Workflow Execution 的即时只读问题,而不是替代查询系统。

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

目录与阅读设置

阅读设置

17

记录一个想法

使用 Query 读取运行状态

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

登录哪都通