saga-orchestration

Saga 编排

用于在不使用两阶段提交的情况下管理分布式事务和长时间运行业务流程的模式。

输入与输出

你需要提供：

• 服务边界与所有权（哪个服务拥有哪个步骤）
• 事务要求（哪些步骤必须原子化，哪些可以最终一致）
• 每个步骤的失败模式（瞬时 vs. 永久、重试策略）
• 每个步骤的 SLA 要求（用于确定超时配置）
• 现有的事件/消息基础设施（Kafka、RabbitMQ、SQS 等）

此技能会产出：

• 包含有序步骤、动作命令和补偿命令的 Saga 定义
• 为你所选模式实现的编排器或编排式（choreography）实现
• 每个参与方服务的补偿逻辑（幂等、始终成功）
• 带每步截止时间的步骤超时配置
• 监控设置：状态机指标、卡住的 Saga 检测、DLQ 恢复

---

何时使用此技能

• 在没有分布式锁的情况下协调多服务事务
• 为部分失败实现补偿事务
• 管理长时间运行的业务工作流（从几分钟到几小时）
• 在需要原子性的分布式系统中处理失败
• 构建订单履约、审批或预订流程
• 用异步补偿替换脆弱的两阶段提交

---

详细章节：核心概念

已移至 references/details.md。

详细章节：模板

已移至 references/details.md。

最佳实践

应该做的

• 让每个步骤都幂等 — 命令可能会在 broker 重连时被重放
• 谨慎设计补偿 — 它们是最关键的代码路径
• 使用关联 ID — saga_id 必须贯穿每个事件和日志
• 实现每步超时 — 绝不要无限期等待参与方回复
• 记录状态转换 — 每次变更时记录 saga_id、step_name、old_state → new_state
• 显式测试补偿路径 — 在集成测试中于每个步骤索引处注入失败

不应该做的

• 不要假设立即完成 — Saga 是异步的，可能需要几分钟
• 不要跳过补偿测试 — 回滚路径是最难做对的部分
• 不要让服务直接耦合 — 使用异步消息，绝不要在 Saga 步骤内进行同步调用
• 不要忽略部分失败 — 即使某步骤只是部分执行，也仍然需要补偿
• 不要使用全局超时 — 每个步骤都有不同的延迟特征

---

故障排查

Saga 卡在 COMPENSATING 状态

Saga 进入补偿阶段，但永远无法到达 FAILED。这意味着某个补偿处理器抛出了未处理的异常，并且从未发布 SagaCompensationCompleted。为补偿消费者添加死信队列（DLQ）处理，并确保每个补偿动作都会发布结果事件，即使底层操作已经被回滚。

async def handle_release_reservation(self, command: Dict):
    try:
        await self.release_reservation(command["original_result"]["reservation_id"])
    except ReservationNotFoundError:
        pass  # Already released — treat as success
    # Always publish completion, regardless of outcome
    await self.event_publisher.publish("SagaCompensationCompleted", {
        "saga_id": command["saga_id"],
        "step_name": "reserve_inventory"
    })

重启时出现重复的 saga 执行

如果你的编排器服务在 saga 执行中途重启，它可能会重放事件并重新执行已经完成的步骤。为每个步骤动作加上幂等键保护 — 参见上文的 Template 3。

编排式（choreography）Saga 丢失事件

在基于 choreography 的 saga 中，如果下游服务在事件发布时处于离线状态，它可能会错过该事件。使用持久化消息 broker（带复制的 Kafka、带持久化的 RabbitMQ），并将当前 saga 状态存储在专用的 saga_log 表中，以便你可以从最后一个已知良好的步骤开始重放。

超时在缓慢但有效的步骤完成前触发

像 create_shipment 这样的步骤在高峰负载时可能需要长达 15 分钟，但你的全局超时是 5 分钟，从而导致误触发补偿。让步骤超时可按步骤类型配置 — 参见 references/advanced-patterns.md 中的 TimeoutSagaOrchestrator 实现和 STEP_TIMEOUTS 字典模式。

补偿顺序与执行顺序不匹配

当两个步骤都在检测到失败之前完成时，补偿必须严格按照相反的顺序运行，否则会将数据置于不一致状态。请验证 _compensate() 是否从 current_step - 1 向下迭代到 0，并添加一个在每个步骤索引处故意失败的集成测试，以确认回滚顺序正确。

---

高级模式

references/ 目录包含大多数 saga 不需要的生产级实现：

• references/advanced-patterns.md — 完整的 SagaOrchestrator 抽象基类、带有每步骤截止时间的 TimeoutSagaOrchestrator、详细的银行转账补偿事务链、Prometheus 埋点、卡住的 saga PromQL 告警，以及 DLQ 恢复工作器。

---

相关技能

• cqrs-implementation — 将 saga 与 CQRS 配对，以便在每一步完成后更新读模型
• event-store-design — 将 saga 事件存储在事件存储中，以获得完整的审计追踪和重放能力
• workflow-orchestration-patterns — 基于 saga 概念构建的更高层工作流引擎（Temporal、Conductor）