服务注册与分布式协调 / 系统课时
划分 Activity 边界与幂等责任
划分 Activity 边界与幂等责任
本篇解决“什么应该放进 Activity,以及 Activity 被重复执行时如何保证业务安全”的问题。你将用数据库写入、HTTP 调用和文件操作建立边界,并把幂等键、去重状态与重试策略放到正确的位置。
学习目标
- 能判断数据库、HTTP、文件等副作用为什么应该由 Activity 承担
- 能根据重复执行风险设计业务幂等键和服务端去重逻辑
- 能把 Workflow 的编排责任与 Activity 的副作用、重试责任清晰分开
Activity 边界怎么划
Workflow 负责描述业务流程和状态转移,Activity 负责接触外部世界。数据库事务、HTTP 请求、文件读写、消息发送等操作都可能产生不可逆副作用,不应直接写进 Workflow 主体。
真正有用的边界不是“一个函数算一件事”,而是一次 Activity 执行拥有清晰的重试语义和副作用责任。如果一个操作失败后重试会造成重复扣款、重复创建订单或重复上传,那么幂等设计必须和 Activity 一起完成,而不能只依赖 Workflow 不重复调用。

用幂等键保护可重试副作用
下面以“创建支付记录”为例。Workflow 产生稳定的业务幂等键,Activity 每次重试都携带同一个键;数据库通过唯一约束保证同一个业务动作最多落一次。这里的重点是:幂等键属于业务语义,而不是 Activity 的重试序号。
import { proxyActivities } from '@temporalio/workflow';
interface PaymentActivities {
createPayment(input: {
orderId: string;
amount: number;
idempotencyKey: string;
}): Promise<{ paymentId: string; created: boolean }>;
}
const { createPayment } = proxyActivities<PaymentActivities>({
startToCloseTimeout: '1 minute',
});
export async function createOrderPayment(orderId: string, amount: number) {
// 同一个 Workflow 对同一笔业务动作使用稳定键,Activity 重试也复用它。
const idempotencyKey = `payment:${orderId}`;
return createPayment({ orderId, amount, idempotencyKey });
}Activity 侧应把这个键交给业务存储或下游系统,并利用唯一索引、幂等 API 或去重记录实现“重复请求得到同一业务结果”。一个最小的数据库表可以是:
CREATE TABLE payment_request (
idempotency_key VARCHAR(128) NOT NULL,
order_id BIGINT NOT NULL,
payment_id BIGINT NOT NULL,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (idempotency_key)
);预期结果
首次 Activity:payment:123 首次写入,生成 payment_id=9001
Activity 因超时重试:再次携带 payment:123
数据库唯一键命中:不创建第二条 payment_request,返回已存在的 payment_id=9001
最终业务结果:同一个订单只有一个对应支付记录如果下游 HTTP 服务本身支持标准幂等键,也应把同一个业务键透传给下游,而不是每次 Activity 重试时生成新键。这样即使 Activity 已经让远端完成操作,却在响应返回前发生超时,后续重试也仍可得到相同业务结果。
数据库、HTTP 与文件操作的边界
数据库写入通常以 Activity 为边界,因为需要连接池、事务、超时和失败处理。一个 Activity 可以完成一个有明确一致性要求的数据库动作,但不要把几十个互不相关的写操作无条件塞进同一个 Activity;边界应围绕业务原子性建立。
HTTP 调用需要特别关注“请求已经成功,但响应丢失”的情况。Activity 超时并不等于远端没有执行,因此重试之前必须确认 API 是否支持幂等键,或者自行建立业务去重记录。
文件操作也同样存在重复风险。例如“上传文件”重试可能留下多个对象。可以使用稳定对象键、上传状态表或支持幂等覆盖的接口,把文件名或对象键与业务动作绑定,而不是每次尝试随机生成新路径。
幂等责任应该放在哪里
Workflow 最适合负责生成并传播稳定的业务标识,例如订单号、支付请求号或业务操作号;Activity 负责把这个标识带到数据库或下游服务;真正执行去重的地方应靠数据库唯一约束、状态机、幂等 API 或其他业务一致性机制完成。
因此一个可靠设计通常满足三个条件:Workflow 重试不会改变业务动作的身份;Activity 重试不会生成新的副作用身份;外部系统能够根据这个身份识别“这是同一件事”。只做到其中一个,仍可能在故障窗口产生重复操作。
对于无法做到幂等的外部操作,应在 Activity 中明确风险,并避免无限自动重试。必要时可以把操作拆成“预留 → 确认 → 查询状态”几个可恢复步骤,让 Workflow 在不确定结果时先查询事实,再决定是否继续,而不是盲目再次执行。
最终可以用一句话检查 Activity 设计:假设这个函数刚刚成功,但调用方没有收到成功响应,再执行一次会发生什么? 如果答案是“业务结果仍然唯一且可识别”,边界和幂等责任通常已经设计到位;如果答案是“可能重复扣款、重复创建、重复上传”,就还需要把幂等键和去重机制补到副作用真正发生的那一层。