skillhub-093-workflow-orchestration-patterns/SKILL.md

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