服务注册与分布式协调 / 系统课时
实现跨服务履约工作流
实现跨服务履约工作流
本课用一个订单履约场景把 Temporal 的主 Workflow、子 Workflow、Activity 和 Signal 串起来:业务调用外部服务时有明确超时与重试,重复执行靠幂等键兜底,支付确认则通过等待信号继续推进,最终形成一条可在本地 Temporal 环境跑通的可靠链路。Temporal 官方文档将 Workflow 定位为可在故障后恢复执行的可靠编排单元,Activity 则适合承载外部副作用。:contentReference[oaicite:0]{index=0}
学习目标
- 能把跨服务履约拆成主 Workflow、子 Workflow 与 Activity,并明确每层职责。
- 能为外部调用配置超时、重试和业务幂等键,理解三者分别解决什么问题。
- 能使用 Signal 等待外部事件,并在本地启动 Worker 与 Workflow 验证完整链路。
先把业务边界拆开
假设订单进入履约后,需要依次完成库存预占、等待支付确认,再启动物流子流程。不要把 HTTP、数据库或 SDK 调用直接写进 Workflow;Workflow 负责决定顺序、状态和等待条件,真正的外部副作用放进 Activity。这样 Workflow 重放时不会重复执行外部操作。
这条链路可以压成四层:主 Workflow 负责订单级编排;库存与支付调用属于 Activity;物流作为相对独立的一段业务流程交给 Child Workflow;支付完成通知通过 Signal 进入主 Workflow。主 Workflow 只保存可持久化的业务状态,不依赖进程内临时状态判断结果。

用 Activity 封装跨服务调用
下面示例采用 TypeScript SDK,并把外部库存服务、支付服务、物流服务都抽象成 Activity。真实项目中,这些 Activity 可以调用 HTTP API、RPC、数据库或消息系统;这里为了本地复现,把远程服务简化成 Worker 内部的函数。Temporal 的可靠性重点不在“函数执行一次”,而在于 Activity 可以按失败策略重试,而 Workflow 本身负责稳定地保存编排进度。
// src/activities.ts
export type ReserveInventoryInput = {
orderId: string;
idempotencyKey: string;
};
const processed = new Set<string>();
export async function reserveInventory(input: ReserveInventoryInput) {
// 幂等键保证重试不会把同一订单重复扣库存。
if (processed.has(input.idempotencyKey)) {
return { status: "ALREADY_RESERVED", orderId: input.orderId };
}
processed.add(input.idempotencyKey);
return { status: "RESERVED", orderId: input.orderId };
}
export async function notifyPaymentService(orderId: string) {
return { orderId, status: "PAYMENT_PENDING" };
}
export async function createShipment(orderId: string) {
return { orderId, shipmentId: `ship-${orderId}` };
}预期结果
reserveInventory 第一次调用返回 RESERVED;使用相同 idempotencyKey 再执行时返回 ALREADY_RESERVED。
notifyPaymentService 返回 PAYMENT_PENDING。
createShipment 返回以订单号构造的 shipmentId。这里的 Set 只是本地演示幂等概念,生产环境不能依赖 Worker 进程内存,因为进程重启后状态会丢失。真实系统通常把幂等键落到目标服务自己的唯一约束、状态表或具备幂等语义的接口中。重试和幂等也不能混为一谈:重试解决“调用失败后再试”,幂等解决“再试时副作用不会被重复应用”。
让主 Workflow 管好超时、重试和等待
主 Workflow 的关键是把不同类型的失败分开处理。库存预占属于一次有边界的远程调用,可以设置 Activity 的 startToCloseTimeout,并允许有限次重试;支付通知同样设置超时,但支付最终确认不是一次同步 RPC 能决定的,因此通知成功后,Workflow 应等待一个 Signal,而不是持续轮询。
// src/workflows.ts
import { proxyActivities, defineSignal, setHandler, condition, executeChild } from "@temporalio/workflow";
import type * as activities from "./activities";
const { reserveInventory, notifyPaymentService } = proxyActivities<typeof activities>({
startToCloseTimeout: "10 seconds",
retry: {
initialInterval: "1 second",
backoffCoefficient: 2,
maximumAttempts: 3,
},
});
export const paymentConfirmed = defineSignal("paymentConfirmed");
export async function fulfillmentWorkflow(orderId: string) {
const paymentState = { confirmed: false };
setHandler(paymentConfirmed, () => {
paymentState.confirmed = true;
});
await reserveInventory({
orderId,
idempotencyKey: `reserve:${orderId}`,
});
await notifyPaymentService(orderId);
await condition(() => paymentState.confirmed, "10 minutes");
if (!paymentState.confirmed) {
throw new Error("payment confirmation timed out");
}
return await executeChild("shippingWorkflow", {
args: [orderId],
workflowId: `shipping:${orderId}`,
});
}
export async function shippingWorkflow(orderId: string) {
return {
orderId,
status: "SHIPPED",
};
}预期结果
支付确认 Signal 到达后,shippingWorkflow 被启动并返回:
{
"orderId": "order-1001",
"status": "SHIPPED"
}
如果 10 分钟内没有 paymentConfirmed Signal,主 Workflow 抛出:
payment confirmation timed out这个例子有三个容易混淆的边界。第一,Activity 的超时限制的是一次外部调用,不是整个订单生命周期。第二,Activity 重试次数有限,并不意味着业务一定成功,因此仍然要有明确的失败分支。第三,condition 是等待状态变化,而不是自己循环查询支付服务;外部支付服务完成后,通过 Signal 推进 Workflow,可以避免持续轮询。
把子流程变成独立履约阶段
物流阶段适合 Child Workflow,是因为它已经具备自己的生命周期。主 Workflow 不需要知道物流内部每一步,只负责在支付成功后启动它,并接收最终结果。使用 executeChild 时,父 Workflow 会等待子 Workflow 完成;如果业务希望先启动子流程、父流程继续执行,则可以改为 startChild,再按业务时机等待子流程结果。
Child Workflow 的 workflowId 应该有稳定的业务语义,例如 shipping:<orderId>。这样做的价值不是简单地“给函数起名字”,而是让同一订单的物流阶段有明确的可定位身份,也方便后续查询和运维。对于会重复触发的业务入口,订单号、支付单号等稳定业务标识应成为幂等设计的一部分。
在本地完整跑通链路
下面给出最小 Worker 与 Client。前提是本机已经启动 Temporal Server,并在项目中安装 @temporalio/worker、@temporalio/client、@temporalio/workflow 和 TypeScript 运行环境。
// src/worker.ts
import { Worker } from "@temporalio/worker";
import * as activities from "./activities";
async function run() {
const worker = await Worker.create({
workflowsPath: require.resolve("./workflows"),
activities,
taskQueue: "fulfillment",
});
await worker.run();
}
run().catch((err) => {
console.error(err);
process.exit(1);
});预期结果
Worker started on task queue: fulfillment// src/client.ts
import { Client, Connection } from "@temporalio/client";
import { fulfillmentWorkflow } from "./workflows";
async function run() {
const connection = await Connection.connect();
const client = new Client({ connection });
const handle = await client.workflow.start(fulfillmentWorkflow, {
taskQueue: "fulfillment",
workflowId: "order:order-1001",
args: ["order-1001"],
});
console.log("started", handle.workflowId);
await new Promise((resolve) => setTimeout(resolve, 1000));
await handle.signal("paymentConfirmed");
const result = await handle.result();
console.log(result);
await connection.close();
}
run().catch((err) => {
console.error(err);
process.exit(1);
});预期结果
started order:order-1001
{ orderId: "order-1001", status: "SHIPPED" }运行时先启动 Worker,再运行 Client。Client 创建 Workflow 后,主流程先完成库存预占和支付通知,然后等待 paymentConfirmed;Client 发送 Signal 后,Workflow 继续执行 Child Workflow 并返回最终履约结果。实际日志格式会随 SDK 与本地启动方式变化,但 Workflow ID、订单号和最终状态应保持对应关系。
可靠编排的验收标准
完成实现后,不要只验证“正常路径返回成功”。至少验证三种结果:外部 Activity 第一次失败后最终成功,证明超时与重试策略生效;同一个订单重复调用时没有产生第二次库存副作用,证明幂等键真的被业务侧执行;支付确认延迟到达时 Workflow 能长期保持等待状态,Signal 到达后再继续执行,证明等待逻辑没有变成轮询。
最终可以把这套结构固化成一个简单原则:Workflow 决定什么时候做,Activity 负责实际去做,Child Workflow 管理独立生命周期,Signal 负责把外部事件带回编排状态,而超时、重试和幂等共同定义失败时仍然可控的边界。