服务注册与分布式协调 / 系统课时
选择 Activity 与 Local Activity
选择 Activity 与 Local Activity
普通 Activity 和 Local Activity 都能承载 Workflow 之外的非确定性工作,但它们的调度与恢复边界不同。本篇用同一条业务链路比较两者,并给出一个可执行决策:默认选普通 Activity,只有任务极短、低延迟敏感且能接受重新执行时才考虑 Local Activity。
学习目标
- 说清普通 Activity 与 Local Activity 的调度路径和持久化边界
- 根据执行时长、路由、心跳和失败恢复要求选择合适类型
- 避免把 Local Activity 当成普通 Activity 的无条件低延迟替代品
先看两条调度路径
普通 Activity 的调用由 Workflow 产生调度命令,Temporal Service 管理 Activity Task 的持久化、投递、超时与重试,Activity Worker 执行后再把结果交回 Service。Worker 进程重启时,未完成的 Activity 可以依据超时和重试策略重新调度。
Local Activity 不创建独立的服务端 Activity Task,而是在执行当前 Workflow Task 的 Worker 进程中运行。它省去了常规 Activity 调度路径上的额外开销,但结果要随 Workflow Task 的进度被持久化;如果 Workflow Task 在结果安全记录前失败,Local Activity 可能从头再次执行。

两者都不提供“外部副作用恰好执行一次”的魔法保证。普通 Activity 在超时或 Worker 丢失后也可能重试,因此写数据库、扣款、调用第三方接口时仍应使用业务幂等键;Local Activity 还需要额外考虑 Workflow Task 失败造成的本地重做窗口。
用恢复需求做第一判断
先问任务是否需要服务端管理的独立执行生命周期。只要答案是“需要”,优先使用普通 Activity,例如执行时间可能较长、需要 Activity Heartbeat 汇报进度、要把任务路由到专用 Worker、需要全局限流,或者希望 Workflow Worker 与 I/O Worker 分开扩缩容。
Local Activity 更适合几秒内完成的短操作:代码与 Workflow Worker 可以部署在同一进程,不依赖专用 Task Queue 路由,也不需要独立 Heartbeat,并且端到端延迟确实值得优化。它不能像普通 Activity 那样通过 Activity Heartbeat 保存进度,因此不适合长循环、大文件处理或不可快速重做的步骤。
| 判断项 | 普通 Activity | Local Activity |
|---|---|---|
| 调度 | Service 管理 Activity Task | Workflow Worker 本地执行 |
| 长任务与 Heartbeat | 适合,可独立 Heartbeat | 不适合,不能独立 Heartbeat |
| 路由与独立 Worker 池 | 支持 | 不支持独立 Task Queue 路由 |
| Worker 故障后的恢复 | 依据超时与重试重新调度 | Workflow Task 恢复时可能重新执行 |
| 典型选择 | 默认方案 | 极短、低延迟敏感的例外方案 |
在同一个 Workflow 中比较 API
下面是片段示例,依赖 Temporal Go SDK;PersistCharge 需要注册到 Activity Worker,LookupRoute 作为函数传给 ExecuteLocalActivity。示例只展示选择边界,不包含 Worker 启动与外部支付实现。
package workflows
import (
"time"
"go.temporal.io/sdk/temporal"
"go.temporal.io/sdk/workflow"
)
func CheckoutWorkflow(ctx workflow.Context, orderID string) error {
localCtx := workflow.WithLocalActivityOptions(ctx, workflow.LocalActivityOptions{
ScheduleToCloseTimeout: 2 * time.Second,
RetryPolicy: &temporal.RetryPolicy{
MaximumAttempts: 3,
},
})
var route string
if err := workflow.ExecuteLocalActivity(
localCtx,
LookupRoute,
orderID,
).Get(localCtx, &route); err != nil {
return err
}
activityCtx := workflow.WithActivityOptions(ctx, workflow.ActivityOptions{
StartToCloseTimeout: 30 * time.Second,
ScheduleToCloseTimeout: 2 * time.Minute,
RetryPolicy: &temporal.RetryPolicy{
MaximumAttempts: 5,
},
})
return workflow.ExecuteActivity(
activityCtx,
PersistCharge,
orderID,
route,
).Get(activityCtx, nil)
}预期行为是:短小的路由查询在当前 Workflow Worker 内完成;真正写入外部支付或订单系统的步骤走普通 Activity,由 Temporal 管理独立任务、超时与重试。若路由查询开始变慢、需要 Heartbeat 或必须送到专用 Worker,就应把它改为普通 Activity,而不是继续放宽 Local Activity 超时。
把 Local Activity 保持在小范围内
选择 Local Activity 时给它明确的 ScheduleToCloseTimeout,并让实现可重复执行。不要把“同进程”误解为“不会失败”:进程崩溃、Workflow Task 超时或结果尚未持久化都可能让这段工作再次发生。
一个稳妥的团队规则是:普通 Activity 是默认值,Local Activity 必须有可说明的低延迟收益和可重做证据。如果你需要为 Local Activity 设计复杂的断点续跑、长时间重试或专门容量治理,通常已经说明它应该回到普通 Activity。