---


---
name: workflow-orchestration-patterns
description: 使用 Temporal 为分布式系统设计持久化工作流。涵盖工作流与活动分离、Saga 模式、状态管理和确定性约束。在构建长时间运行的进程、分布式事务或微服务编排时使用。
---

# 工作流编排模式

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

## 何时使用工作流编排

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

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

### 何时不应使用

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

## 详细模式与工作示例

详细模式文档位于 `references/details.md`。当上述导航层级不够用时，请阅读该文件。

## 最佳实践

### 工作流设计

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