服务注册与分布式协调 / 系统课时
使用 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 很适合“这个订单现在处于什么阶段”“已经处理多少项”“当前等待什么条件”这类实例级问题,但不适合承担审计记录,因为同一次 Query 调用了多少次并不会成为 Workflow 历史的一部分。
用 Handler 暴露进度状态
下面使用 TypeScript SDK。Workflow 代码是片段示例,依赖已经启动的 Temporal Server,以及一个把 progressWorkflow 注册到 query-demo Task Queue 的 Worker。状态在 Workflow 主逻辑中更新,Query Handler 只返回快照。
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 重放。
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);
});预期输出
{ status: 'WAITING', completed: 2, total: 5 }这里的 Query 名称由 defineQuery 固定,返回类型由 TypeScript 约束。调用方不需要访问 Worker 内存地址,也不需要自己重放历史,只需持有目标 Workflow 的 Handle。
设计只读状态的边界
Query 返回值应当小而稳定。优先暴露进度、当前阶段、最近一次业务决定等已经存在于 Workflow 状态中的信息,不要为了“查得更全”把大量历史数据复制成一个巨型对象。
如果需求是跨成千上万个 Workflow 做筛选、排序和聚合,应使用 Visibility 与 Search Attributes;如果需要长期报表或复杂查询,应把数据投影到数据库等外部读模型。Query 最适合回答单个 Workflow Execution 的即时只读问题,而不是替代查询系统。