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：根据实际使用的 SDK 语言和已安装版本，选择相应的 API。Python 使用 workflow.patched / workflow.deprecate_patch；其他 SDK 使用不同的 API。部署前重放现有历史记录；请遵循官方 Python 版本管理指南。
2. 新建工作流类型：创建新工作流，并将新的执行路由到该工作流
3. 向后兼容：确保旧事件可以正确重放

弹性与错误处理

重试策略

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

配置重试：

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

不可重试的错误：

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

幂等性要求

重要原因（来源：docs.temporal.io/activities）：

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

实现策略：

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

活动心跳

用途：检测停滞的长时间运行活动

模式：

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

最佳实践

工作流设计

1. 保持工作流专注 - 每个工作流只负责一项职责
2. 采用小型工作流 - 使用子工作流提高可扩展性
3. 明确边界 - 工作流负责编排，活动负责执行
4. 在本地测试 - 使用可跳过时间的测试环境

活动设计

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

常见陷阱

工作流违规：

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

活动错误：

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

运维注意事项

监控：

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

可扩展性：

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

其他资源

官方文档：

• 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. 为故障和恢复进行设计

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请暂停并请求澄清。