workflow-orchestration-patterns

工作流编排模式

通过 Temporal 掌握工作流编排架构，涵盖基础设计决策、弹性模式以及构建可靠分布式系统的最佳实践。

何时使用工作流编排

理想用例（来源：docs.temporal.io）

• 跨机器/服务/数据库的多步骤流程
• 需要满足全有或全无语义的分布式事务
• 长时间运行的工作流（数小时至数年），并自动持久化状态
• 需要从上一个成功步骤恢复的故障恢复
• 业务流程：预订、订单、营销活动、审批
• 实体生命周期管理：库存跟踪、账户管理、购物车工作流
• 基础设施自动化：CI/CD 流水线、资源配置、部署
• 需要超时和升级处理的人工参与系统

不适用的场景

• 简单的 CRUD 操作（使用直接 API 调用）
• 纯数据处理流水线（使用 Airflow、批处理）
• 无状态请求/响应（使用标准 API）
• 实时流处理（使用 Kafka、事件处理器）

关键设计决策：工作流与活动

基本规则（来源：temporal.io/blog/workflow-engine-principles）：

• 工作流 = 编排逻辑和决策
• 活动 = 外部交互（API、数据库、网络调用）

工作流（编排）

特征：

• 包含业务逻辑和协调逻辑
• 必须具有确定性（相同输入 → 相同输出）
• 不能直接进行外部调用
• 故障期间自动保留状态
• 即使基础设施发生故障，也可以运行数年

工作流任务示例：

• 决定要执行哪些步骤
• 处理补偿逻辑
• 管理超时和重试
• 协调子工作流

活动（外部交互）

特征：

• 处理所有外部系统交互
• 可以具有非确定性（API 调用、数据库写入）
• 内置超时和重试逻辑
• 必须具有幂等性（调用 N 次 = 调用一次）
• 生命周期较短（通常为数秒至数分钟）

活动任务示例：

• 调用支付网关 API
• 写入数据库
• 发送电子邮件或通知
• 查询外部服务

设计决策框架

Does it touch external systems? → Activity
Is it orchestration/decision logic? → Workflow

核心工作流模式

1. 带补偿的 Saga 模式

用途：实现支持回滚的分布式事务

模式（来源：temporal.io/blog/compensating-actions-part-of-a-complete-breakfast-with-sagas）：

For each step:
  1. Register compensation BEFORE executing
  2. Execute the step (via activity)
  3. On failure, run all compensations in reverse order (LIFO)

示例：支付工作流

1. 预留库存（补偿操作：释放库存）
2. 扣款（补偿操作：退款）
3. 履行订单（补偿操作：取消履行）

关键要求：

• 补偿操作必须具有幂等性
• 在执行步骤之前注册补偿操作
• 按相反顺序运行补偿操作
• 妥善处理部分故障

2. 实体工作流（Actor 模型）

用途：表示单个实体实例的长期运行工作流

模式（来源：docs.temporal.io/evaluate/use-cases-design-patterns）：

• 一次工作流执行 = 一个实体（购物车、账户、库存项）
• 工作流在实体的整个生命周期中持续存在
• 接收用于状态变更的信号
• 支持查询当前状态

用例示例：

• 购物车（添加商品、结账、过期）
• 银行账户（存款、取款、余额查询）
• 商品库存（库存更新、预留）

优势：

• 封装实体行为
• 保证每个实体的一致性
• 自然支持事件溯源

3. 扇出/扇入（并行执行）

目的：并行执行多个任务并汇总结果

模式：

• 启动子工作流或并行活动
• 等待所有任务完成
• 汇总结果
• 处理部分失败

扩展规则（来源：temporal.io/blog/workflow-engine-principles）：

• 不要扩展单个工作流
• 对于 1M 个任务：启动 1K 个子工作流，每个工作流处理 1K 个任务
• 为每个工作流设定边界

4. 异步回调模式

目的：等待外部事件或人工审批

模式：

• 工作流发送请求并等待信号
• 外部系统异步处理
• 发送信号以恢复工作流
• 工作流收到响应后继续执行

使用场景：

• 人工审批工作流
• Webhook 回调
• 长时间运行的外部进程

状态管理与确定性

自动保存状态

Temporal 的工作方式（来源：docs.temporal.io/workflows）：

• 自动保存完整的程序状态
• Event History 记录每条命令和事件
• 从崩溃中无缝恢复
• 应用程序恢复到故障前的状态

确定性约束

工作流以状态机的形式执行：

• 重放行为必须保持一致
• 相同输入 → 每次都产生相同输出

工作流中禁止使用（来源：docs.temporal.io/workflows）：

• ❌ 线程、锁、同步原语
• ❌ 随机数生成（random()）
• ❌ 全局状态或静态变量
• ❌ 系统时间（datetime.now()）
• ❌ 直接进行文件 I/O 或网络调用
• ❌ 非确定性库

工作流中允许使用：

• ✅ workflow.now()（确定性时间）
• ✅ workflow.random()（确定性随机数）
• ✅ 纯函数和计算
• ✅ 调用活动（非确定性操作）

版本管理策略

挑战：旧执行仍在运行时更改工作流代码

解决方案：

1. 版本管理 API：使用 workflow.get_version() 安全地进行更改
2. 新建工作流类型：创建新工作流，并将新的执行路由到该工作流
3. 向后兼容：确保旧事件可以正确重放

韧性与错误处理

重试策略

默认行为：Temporal 会无限重试活动

配置重试：

• 初始重试间隔
• 退避系数（指数退避）
• 最大间隔（限制重试延迟）
• 最大尝试次数（达到上限后失败）

不可重试的错误：

• 无效输入（验证失败）
• 违反业务规则
• 永久性故障（未找到资源）

幂等性要求

为何至关重要（来源：docs.temporal.io/activities）：

• 活动可能会执行多次
• 网络故障会触发重试
• 必须确保重复执行是安全的

实现策略：

• 幂等键（去重）
• 使用唯一约束进行检查后再操作
• 使用 Upsert 操作而不是 Insert
• 跟踪已处理的请求 ID

活动心跳

目的：检测长时间运行的活动是否停滞

模式：

• 活动定期发送心跳
• 心跳包含进度信息
• 未收到心跳时触发超时
• 支持基于进度的重试

最佳实践

工作流设计

1. 保持工作流专注——每个工作流只负责一项职责
2. 使用小型工作流——通过子工作流实现可扩展性
3. 划分清晰的边界——工作流负责编排，活动负责执行
4. 本地测试——使用可跳过时间的测试环境

活动设计

1. 幂等操作——支持安全重试
2. 短时运行——耗时几秒到几分钟，而不是几小时
3. 配置超时——始终设置超时时间
4. 长时间任务使用心跳——报告进度
5. 错误处理——区分可重试与不可重试的错误

常见陷阱

工作流违规：

• 使用 datetime.now() 而不是 workflow.now()
• 在工作流代码中使用线程或异步操作
• 直接从工作流调用外部 API
• 在工作流中使用非确定性逻辑

活动错误：

• 执行非幂等操作（无法处理重试）
• 未设置超时（活动会一直运行）
• 未对错误分类（会重试验证错误）
• 忽略负载限制（每个参数 2 MB）

运维注意事项

监控：

• 工作流执行时长
• 活动失败率
• 重试次数和退避策略
• 待处理工作流数量

可扩展性：

• 使用工作器进行水平扩展
• 对任务队列进行分区
• 拆分子工作流
• 适时批量处理活动

其他资源

官方文档：

• Temporal 核心概念：docs.temporal.io/workflows
• 工作流模式：docs.temporal.io/evaluate/use-cases-design-patterns
• 最佳实践：docs.temporal.io/develop/best-practices
• Saga 模式：temporal.io/blog/saga-pattern-made-easy

核心原则：

1. 工作流 = 编排，活动 = 外部调用
2. 工作流必须保持确定性
3. 幂等性对活动至关重要
4. 状态会自动保留
5. 针对故障和恢复进行设计