Dify 中级实验（16）：错误处理与降级——工作流如何有尊严地失败？

1. 业务场景

先讲一个我们实际遇到的场景。

一家公司的自动化运营系统上线第二周，线上出了事故：凌晨的批量任务里，一个外部 API 突然返回 500，整条工作流直接崩溃——后续的几十个任务全部失败，运营同事早上来上班才发现，数据已经漏处理了一整晚。他们复盘时发现，问题不是「那个 API 挂了」（外部服务总会挂），而是工作流对错误毫无准备：没有捕获、没有降级、没有日志，一个异常就能让整条链路崩溃。

我们第一次接这类需求时，第一反应也是「给每个节点套个 try-catch 不就行了」。真正复盘那场事故才发现——错误处理不是「包一层」的事：业务失败和网络失败是两种错误，得分开处理；降级了要留日志；留了日志还得决定要不要告警。

这不是个例。任何「工作流依赖外部服务」的场景都是这个模式：调用第三方支付接口、对接供应商 API、调模型服务、访问内部数据系统——外部服务随时可能 500、超时、限流，错误不是「如果发生」，而是「什么时候发生」。生产级工作流必须让错误「有尊严地失败」：降级优于报错，报错也要留痕。

2. 场景痛点

这个场景的痛点，在这家公司的运营事故里体现得最直接：

• 一个异常拖垮整条链路：中间某个节点失败，后面的节点全部不执行，几十个任务连锁失败——一个外部 API 抖动，整个业务停摆。
• 业务失败和网络失败混为一谈：API 返回 500（请求成功但业务失败）和网络超时（根本没连上）是两种错误，处理方式完全不同，混在一起就只能一刀切地报错。
• 错误不留痕，事后查不到：失败后没有任何日志和记录，出了问题不知道哪一步失败的、为什么失败，复盘全靠猜。
• 所有错误都惊动告警：要么完全不告警（事故没人知道），要么什么错都告警（告警疲劳，真正严重的反而被淹没）。

本质上，生产级工作流和演示工作流的差距，就体现在错误发生时：前者有降级路径、有日志、有分级告警，后者只有一串红色报错。

3. 方案：为什么是 fail-branch + 状态码分流 + 日志分级

Dify 工作流里做生产级容错设计，核心是四件套：节点级异常捕获（fail-branch）、状态码分级降级、统一日志判定、严重级别告警。

选它的理由：

• fail-branch 让节点长出「失败口」：HTTP 节点配 error_strategy: fail-branch 后，同时拥有成功口 source 和失败口 fail——网络层失败（超时/断连）走 fail 口单独降级，业务失败（4xx/5xx）走成功口再判断，两类错误分开处理；
• 状态码分流精确降级：IF-ELSE 按 status_code 判断，500 走降级处理、200 走正常处理，降级路径和正常路径在「日志判定」节点汇合——无论哪条路，错误都要被记录、分级、决定是否告警；
• 分级告警不惊动所有人：severity 分 critical/warning/info 三级，只有 critical 才触发告警通道，warning/info 只记日志正常收尾。

这篇文章我们就用它搭一个「容错架构演练」工作流：用 httpbin.org 可控状态码端点模拟外部 API，完整跑一遍「请求 → 状态码分流 → 日志判定 → 严重级别判断 → 告警或正常收尾」。

4. 整体架构

链路很清晰：入口收数据 → HTTP 请求外部 API → 状态码分流 → 降级/正常两条路径在日志判定节点汇合 → 按严重级别告警或正常收尾。12 个节点、13 条边——关键设计就是「降级路径和正常路径在日志判定节点汇合」：无论哪条路，错误都要被记录、分级、决定是否告警。

5. 模块设计

5.1 HTTP 节点（核心）

type: http-request

url: "https://httpbin.org/status/500"

method: "get"

timeout: {connect: 5, read: 60, write: 20, max_connect_timeout: 300, max_read_timeout: 600, max_write_timeout: 600}

retry_config: {max_retries: 2, retry_enabled: true, retry_interval: 1000}

error_strategy: "fail-branch"

authorization: {config: null, type: no-auth}

ssl_verify: true

要点：

• 超时 5 秒 + 重试 2 次（间隔 1s）——瞬时抖动自动扛过去
• error_strategy: fail-branch 让节点长出两个输出口：成功口 source 和失败口 fail——500 属于「请求成功但业务失败」，走成功口再判断；fail 口只管网络层失败（超时/断连/无响应体）

5.2 状态码判断（IF-ELSE）

数字比较必须写全 varType: number + numberVarType: constant，值仍是字符串字面量：

cases:

- case_id: case_500

  conditions:

  - comparison_operator: "="              # 数字比较用 =，字符串比较才用 is

    numberVarType: constant

    value: "500"

    variable_selector: [http_call, status_code]

    varType: number

  logical_operator: and

- case_id: case_200

  conditions:

  - comparison_operator: "="

    numberVarType: constant

    value: "200"

    variable_selector: [http_call, status_code]

    varType: number

  logical_operator: and

5.3 日志判定节点（Code）

两条路径在此汇合，把错误转成可观测的结构化日志，并输出告警开关（boolean 展平成 string）：

def main(status_code: int, user_input: str, degrade_message: str, normal_message: str) -> dict:

    import time

    try:

        code = int(status_code or 0)

    except Exception:

        code = 0

    if code >= 500:

        severity = "critical"

    elif code >= 400:

        severity = "warning"

    else:

        severity = "info"

    message = degrade_message or normal_message or ""

    log_id = "ERR-{}".format(int(time.time()))

    return {

        "severity": severity,

        "log_message": message,

        "log_id": log_id,

        "need_alert": "true" if severity == "critical" else "false"

    }

severity 分级（critical/warning/info）直接驱动下游 严重级别判断：critical 才触发告警，warning/info 只记日志正常收尾——不是所有错误都要惊动告警通道。

6. 运行验证

运行日志里核对：HTTP 节点耗时、状态码值、log_id 时间戳、最终输出内容。

7. 实战坑

采坑点来自本实验 DSL 生成与运行验证的真实记录（fail-branch 双口语义、httpbin 外网依赖、数字比较格式）。

8. 实验文档及源码获取

• 实验文档（完整操作步骤）：DIFY-17：错误处理与降级架构.md
• 源码（可直接导入）：dify102_17_容错架构演练.yml
• DSL 目录：dify-102/dsl/

文章聚焦核心配置与采坑点；实验文档还包含降级回路（简化提示重试→静态回复）、迭代超时控制、HTTP 超时链、熔断模式、渐进式降级（L1-L4）等完整设计。