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

实现跨服务履约工作流

实现跨服务履约工作流

本课用一个订单履约场景把 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 本身负责稳定地保存编排进度。

ts
// 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}` };
}

预期结果

text
reserveInventory 第一次调用返回 RESERVED;使用相同 idempotencyKey 再执行时返回 ALREADY_RESERVED。
notifyPaymentService 返回 PAYMENT_PENDING。
createShipment 返回以订单号构造的 shipmentId。

这里的 Set 只是本地演示幂等概念,生产环境不能依赖 Worker 进程内存,因为进程重启后状态会丢失。真实系统通常把幂等键落到目标服务自己的唯一约束、状态表或具备幂等语义的接口中。重试和幂等也不能混为一谈:重试解决“调用失败后再试”,幂等解决“再试时副作用不会被重复应用”。

让主 Workflow 管好超时、重试和等待

主 Workflow 的关键是把不同类型的失败分开处理。库存预占属于一次有边界的远程调用,可以设置 Activity 的 startToCloseTimeout,并允许有限次重试;支付通知同样设置超时,但支付最终确认不是一次同步 RPC 能决定的,因此通知成功后,Workflow 应等待一个 Signal,而不是持续轮询。

ts
// 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",
  };
}

预期结果

text
支付确认 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 运行环境。

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

预期结果

text
Worker started on task queue: fulfillment
ts
// 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);
});

预期结果

text
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 负责把外部事件带回编排状态,而超时、重试和幂等共同定义失败时仍然可控的边界。

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

目录与阅读设置

阅读设置

17

记录一个想法

实现跨服务履约工作流

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

登录哪都通