可视化工作流中的第三方 API 熔断模式

为什么第三方 API 故障会影响多个功能\n\n单个第三方 API 往往处在日常流程的关键位置：处理支付、验证地址、同步库存、发送消息、身份校验等。当供应商出现问题时，通常不会只影响一个按钮；依赖该响应的整个流程可能被冻住。\n\n因此熔断器很重要。这不是理论，而是让核心业务在集成异常时仍能运行的实用方法。\n\n慢与宕机造成的影响不同。\n\n当 API 变慢时，工作流仍在尝试成功，但每一步都在等待。用户会看到加载旋转，支持团队会收到“卡住了”的工单，后台任务会堆积。慢的问题难以排查，因为看起来像是自身系统在出问题。\n\n当 API 宕机时，会出现超时或明确错误。表面上更清晰，但往往更危险，因为工作流通常会重试。当大量请求同时重试时，会制造流量风暴，延缓恢复并可能拖垮自己的系统。\n\n常见症状出现得很快：超时、持续增长的队列、部分更新，以及大量手动清理工作。\n\n真正的损害是连锁反应。如果某个运费提供方变慢，订单创建就会变慢，因为工作流在没有报价时不愿确认订单。如果支付通道宕机，支持团队可能无法发起退款，即便其它系统都在正常工作。\n\n不能假装故障不存在。目标是用清晰的回退路径、临时阻断规则和告警设计工作流，这样业务可以在集成恢复期间继续接单、服务客户并记录工作。\n\n## 用通俗话说的熔断器\n\n熔断器就是针对 API 调用的安全开关。当第三方服务开始失败时，熔断器阻止你的工作流反复敲打它。你不再把一次故障变成加载缓慢、超时和卡住的任务，而是控制影响范围。\n\n熔断器有三种简单结果：\n\n- 当供应商健康时，允许调用。\n- 当失败率高时，阻止调用并立即走回退路径。\n- 在短暂暂停后，尝试有限的测试调用以确认供应商是否恢复。\n\n如果喜欢术语，就是“Closed（闭合）”、“Open（打开）”和“Half-open（半开）”。名字不是重点，可预测性才是。供应商不健康时，你的工作流每次都应有相同的行为。\n\n这并不是把错误隐藏。你仍应记录失败，向用户或运维显示清晰状态，并告警到相关人员。你是在选择快速失败、把工作路由到更安全的替代方案，或在短暂停顿后再试探。\n\n## 选择哪些 API 调用绝不能阻塞业务\n\n熔断器在有选择时效果最佳。并非每个供应商调用都需要特殊保护。先从那些一旦被阻止就会阻塞收入、订单或客户访问的步骤开始。\n\n一个实用方法是沿着一个用户请求端到端地走一遍。哪些超时会迫使用户放弃任务，或产生之后需要人工清理的混乱？\n\n典型的“不能阻碍核心业务”的调用包括支付、运输与履约、登录/SSO/MFA、一次性验证码和与审批相关的合规检查。\n\n还要把面向用户的步骤与后台任务区分开。如果有人在结账页面等待，你需要快速决定：成功、回退或明确中止。对于像同步运单号这样的后台工作，较慢的重试是可以接受的，只要它们不阻塞主流程即可。\n\n先小范围开始以避免范围蔓延。先保护 1–3 个工作流，然后再扩展。\n\n在构建前先定义“安全回退”是什么意思。好的回退是具体且可测试的：\n\n- 支付：把订单保存为“待支付”，避免购物车丢失。\n- 运输：使用缓存费率或统一费率，或先确认订单再延迟购买面单。\n- 身份：当 SSO 宕机时允许密码登录，或切换到邮箱验证。\n- 消息：将短信排队稍后发送，并在可能时提供替代路径。\n\n在 AppMaster 的 Business Process Editor 中，这通常表现为一个清晰的分支：核心操作继续，而受供应商依赖的步骤走受控的替代路径。\n\n## 状态、阈值和可解释的计时器\n\n熔断器是一个安全开关。大多数时候它允许调用；当供应商开始失败时，它会切换以保护你的工作流免于浪费时间和错误堆积。\n\n### 三种状态\n\n**Closed（闭合）**是正常状态，你调用 API 并继续。\n\n如果失败超过某个阈值，熔断器进入 Open（打开）。此时你停止调用供应商一段短时间，并立即路由到回退（缓存值、排队工作或替代流程）。\n\n冷却期过后，熔断器进入 Half-open（半开）。你允许少量测试调用。如果成功，返回 Closed；如果失败，回到 Open。\n\n### 测量什么\n\n使用能反映供应商真实失败方式的信号：\n\n- 超时\n- HTTP 5xx 错误\n- 延迟上升（慢到对流程无用）\n- 连接/DNS 错误\n- 429 限流\n\n在可视化工作流工具中，这些通常对应简单检查：状态码、耗时和特定错误输出。\n\n### 初始阈值与两个关键计时器\n\n从易于解释的数字开始，然后根据真实流量调整。示例：\n\n- 如果在 30–60 秒内有 5–10 次调用失败，则打开熔断器。\n- 或者在滚动窗口内当 20%–40% 的调用失败时打开。\n- 当延迟超过流程可容忍值（通常 2–5 秒）时，把延迟当作失败处理。\n\n然后设置两个计时器：\n\n- 冷却时间（Open 状态）： 通常 30 秒到 5 分钟。\n- 半开测试窗口： 允许 1–5 次测试调用，或短时间窗口（如 10–30 秒）。\n\n目标很直接：在供应商不健康时快速失败，在其恢复时自动恢复。\n\n## 逐步指南：在可视化工作流中构建熔断器\n\n最重要的设计选择是把“我们现在应该调用供应商吗？”的决定放在一个地方，而不是散布在每个工作流中。\n\n### 1）把供应商调用放入可复用模块\n\n创建一个子流程（可重用的工作流块），所有需要该供应商的工作流都使用它。在 AppMaster 中，这自然对应一个可从端点或自动化调用的 Business Process。保持职责单一：输入进来，发出供应商请求，并返回清晰的成功/失败结果。\n\n### 2）用时间记录失败，而不仅仅计数\n\n为每次结果记录时间戳。保存诸如最后一次成功、最后一次失败、窗口内的失败次数、当前状态以及冷却截止时间等字段。\n\n把这些字段持久化到表中，使熔断器能在重启后存活并在多个实例间保持一致。PostgreSQL（通过 Data Designer）很适合此用途。\n\n### 3）定义每次都遵循的状态转换规则\n\n保持规则简单。例如：若 2 分钟内发生 5 次失败，则切换到 Open。在 Open 时跳过供应商调用，直到冷却期结束。冷却结束后进入 Half-open，允许一次受控尝试；若成功则关闭熔断器，失败则再次打开。\n\n### 4）分支工作流：供应商路径 vs 回退路径\n\n在供应商请求之前，检查存储的状态：\n\n- Closed： 调用供应商，然后根据结果更新成功或失败。\n- Open： 跳过调用并执行回退。\n- Half-open： 允许有限尝试，然后决定是关闭还是重新打开。\n\n例如：如果运单面单 API 不可用，回退可以创建一个“面单待处理”的订单并排队重试，而不是阻塞结账或仓库工作。\n\n### 5）在工作流间共享熔断器状态\n\n如果你有多个工作流和服务器，它们必须读写相同的熔断器状态。否则一个实例可能继续敲打供应商，而另一个实例已经决定暂停。\n\n## 能让工作继续的回退路径\n\n熔断器只有在你事先决定阻断时如何处理才有意义。一个好的回退让用户能继续操作，保护数据，并使后续清理可预测。\n\n为每项任务选择合适的回退。如果运费提供方不可用，你可能不需要精确价格来接受订单。在可视化工作流中，把失败的 API 步骤路由到能产生可用结果的回退分支。\n\n实践中，回退通常包括：\n\n- 使用缓存的最近值（并注明新鲜度窗口）。\n- 使用带明确标注的默认估算值。\n- 路由到人工审核。\n- 将工作排队以便稍后异步重试。\n\n用户体验和逻辑同等重要。不要显示模糊错误，要说明发生了什么以及用户接下来可以做什么：“我们无法确认当前运费。你可以按估算运费下单，或保存以便审核。”\n\n还要为短期与长期故障制定不同策略。短期故障（几分钟）通常意味着“继续前进，后台重试”。长期故障（几小时）可能需要更严格的行为，例如更多人工审核或批准。\n\n最后，追踪每次回退以便对账。至少记录回退类型、原始请求细节、向用户返回的内容（是否为估算），以及后续跟进状态。\n\n## 临时阻断规则与更聪明的重试\n\n不受控的重试会把小故障放大为真正的宕机。当很多工作流同时重试时，会产生峰值（“群体奔涌”问题）。供应商变慢，你的队列增长，速率限制被耗尽。\n\n重试应可预测且有限，并且应尊重熔断器状态。实用策略：\n\n- 将最大重试次数保持较低（通常 2–3 次）。\n- 使用指数退避（例如 2s、8s、30s）。\n- 添加抖动以避免重试同步。\n- 限制总重试时间（例如 60–90 秒）。\n- 若熔断器为 Open，则不再重试，直接走回退。\n\n临时阻断相关但有所不同。用于当响应告诉你“现在不可用”的情况。常见规则：\n\n- 429 限流： 按 Retry-After 或安全固定窗口阻断。\n- 401/403 认证失败： 阻断直到凭证刷新，然后再测试一次。\n- 持续 5xx： 短暂阻断，然后允许小规模测试。\n\n在阻断期间，决定已在进行中的工作如何处理：把它排队、重路由，或优雅降级（例如接受订单但延迟发送短信）。\n\n## 告警要指明该做什么\n\n如果没人及时知道熔断器状态变化，熔断器就没多大用处。目标不是制造噪声，而是在行为变化时发出一条清晰的信息：调用被阻止、回退在生效，或熔断器比预期持续打开更久。\n\n好的默认触发器包括：\n\n- 熔断器打开时告警。\n- 如果持续打开超过时间限制则告警。\n- 在打开前错误急剧上升时告警。\n\n让告警具有可操作性。包括供应商和端点、当前状态和变更时间、用户会感受到的影响、工作流当前的处理方式（阻断、重试、回退），以及一个建议的下一步。\n\n按严重性分流告警。非关键的 enrichment API 可以发邮件；支付、登录或订单提交类问题通常值得页面告警（page）。在 AppMaster 中，这可通过基于严重性标志的分支发送电子邮件、Telegram 或 SMS 来实现。\n\n追踪一小组关键指标以观察是否在恢复：每个供应商的阻断调用数和回退使用率通常就足够了。\n\n## 示例场景：在不阻止下单的前提下应对供应商故障\n\n一个常见故障是：运费供应商在客户结账时宕机。如果工作流在创建订单时坚持要求实时费率，单次故障就可能完全阻止下单。\n\n在正常情况下，先创建订单，再请求实时费率，并将所选承运人和价格保存在订单中。\n\n当供应商开始失败时，调用会超时或返回 5xx。达到阈值后（例如 2 分钟内 5 次失败），熔断器打开。\n\n在 Open 期间，工作流在短窗口内（比如 10 分钟）停止调用运费服务。这防止故障供应商拖垮所有人的结账流程。\n\n回退策略可以是：\n\n- 应用统一费率或安全估算。\n- 仍然创建订单。\n- 将订单标记为“运费待确认”，稍后重新计算。\n- 保存供应商错误详情以便跟进。\n\n在 AppMaster 中，这在 Business Process Editor 里表现为清晰的分支，并由 Data Designer 中类似 shipping_rate_status 和 shipping_rate_source 的字段支持。\n\n## 上线前的快速检查\n\n熔断器在高压下的表现应与演示时一致。发布前确认以下要点：\n\n- 阈值和冷却时间有文档并易于更改。\n- Open 状态立即阻止调用（不再等待供应商超时）。\n- 回退行为对金钱和客户承诺是安全的。\n- 半开探测仅限少量测试调用。\n- 日志能清晰回答时间和影响范围。\n\n在回退安全性上多花点时间。一个“让工作继续”的回退也可能引入财务风险。如果支付提供方宕机，将订单标记为已付款是危险的。更安全的方法是使用“待支付”并对客户做明确说明。\n\n请有意测试恢复流程：强制失败、观察熔断器打开、等待冷却，然后确认半开阶段只发送少量探针。若探针成功，熔断器应迅速关闭；若失败，应在不泛洪供应商的情况下重新打开。\n\n你的日志在一分钟内应能回答：谁受影响、何时开始、哪个工作流步骤触发了熔断器、使用了哪种回退。\n\n## 下一步：在 AppMaster 中实现该模式\n\n挑选一个若失败会影响日常运营的集成（支付、面单、SMS、CRM 同步等）。先为该单一调用端到端构建熔断器。团队信任后，把相同模板复制到下一个供应商。\n\n在 AppMaster 中，通过 Data Designer 在 PostgreSQL 建模熔断器状态。保持简单：每个供应商（或端点）一条记录，字段可以包含 state、failure_count、last_failure_at、open_until 和简短的 last_error。\n\n然后在 Business Process Editor 中实现逻辑并用可读的分支表现。清晰比巧妙更重要。\n\n实用的构建顺序示例：\n\n1. 检查熔断器状态，当 open_until 在未来时阻止调用。\n2. 调用供应商 API 并捕获成功与错误输出。\n3. 成功时重置计数并关闭熔断器。\n4. 失败时递增计数并在达到阈值时打开熔断器。\n5. 将面向用户的流程路由到回退（排队工作、使用缓存数据或允许人工处理）。\n\n用通俗的语言记录回退决策，方便支持和运维知道用户会看到什么。\n\n当熔断器打开时，使用 AppMaster 的消息模块（电子邮件、SMS、Telegram）通知负责人。包含关键信息：供应商、端点、状态和首要建议操作。\n\n如果你在 AppMaster 构建这些工作流，appmaster.io 是个实用的起点，因为同一个可视化 Business Process 可以为端点、后台任务和告警提供统一的熔断器状态支持。