PHP 异常链怎样保留底层错误原因

PHP 异常链要保留底层错误原因，关键只有一个动作：在捕获底层 Throwable 后创建新的业务异常，并把原异常作为构造器的第三个参数传入。最外层再通过 getPrevious() 向内读取，就能同时看到“当前层做了什么”和“最初哪里失败”。

官方地址：https://www.php.net/manual/en/exceptions.php

异常链解决的是“业务语义增加后原因不见了”

分层 PHP 服务经常会遇到同一个现场：底层读取配置、访问数据库或调用文件系统时已经产生了具体异常，但上层需要把它改写成“加载订单配置失败”这类业务语义。如果只写一条新消息，调用方得到的上下文更友好，却失去了原始类型、文件和行号。

PHP 官方把 Throwable 定义为可被 throw 的对象基接口，Exception 与 Error 都实现它。Exception 的属性中包含上一层 Throwable，构造器签名也明确提供了 $previous 参数。这个关系可以理解为：当前异常负责描述当前边界，previous 指向更靠近根因的对象。

在 catch 中把底层 Throwable 传给第三个参数

包装异常时，不要只拼接字符串。下面的示例把底层异常交给 RuntimeException 的第三个参数，同时给当前层补充“配置仓库读取失败”的语义。这样，外层只需要处理统一的运行时异常，日志仍可以沿着链条回到最初原因。

readConfigFile($name);
        } catch (Throwable $cause) {
            // 第三个参数保存底层对象，不能只把消息拼进新字符串。
            throw new RuntimeException(
                "读取配置 {$name} 失败",
                0,
                $cause
            );
        }
    }

    private function readConfigFile(string $name): array
    {
        // 示例用异常模拟文件、解析器或依赖组件返回的原始故障。
        throw new InvalidArgumentException("配置 {$name} 不存在");
    }
}

try {
    // 最外层只接收已经带业务上下文的异常。
    (new ConfigRepository())->load('payment');
} catch (Throwable $error) {
    // 这里的 error 是 RuntimeException，previous 才是底层原因。
    echo $error->getMessage();
}

调用链建立后，当前层的 getMessage() 会得到“读取配置 payment 失败”，而 getPrevious() 会返回 InvalidArgumentException。如果中间还有一层服务继续包装，只需把当前异常继续作为第三参数传递，链条就会自然延长。

用 getPrevious() 逐层读出最初原因

异常链不是把所有消息合并成一段文本，而是由多个 Throwable 对象组成。最外层先记录业务语义，然后不断取 getPrevious()；取不到上一层时返回 null，这就是停止条件。

 get_class($current),
            'message' => $current->getMessage(),
            'file' => $current->getFile(),
            'line' => $current->getLine(),
        ];

        // 没有 previous 时得到 null，避免无限循环。
        $current = $current->getPrevious();
    }

    return $items;
}

这个遍历顺序是从外到内：先看到当前层的业务边界，最后看到最靠近根因的异常。生产日志中可以按需要脱敏消息、保留类型和行号；不要因为“方便打印”就把用户输入、令牌或连接信息直接写入每一层。

重新抛出和包装不是一回事

如果当前层没有需要补充的业务语义，可以直接写 throw $error;，这表示继续抛出同一个对象；如果需要增加上下文，再创建新异常并把旧对象放到第三参数。只把消息复制到新异常，会让 getPrevious() 返回 null，原始类型和位置也就断掉了。

还要注意，异常链保存的是“显式传入的 previous”。PHP 内部函数产生的每个异常并不会替你把更早的对象自动挂上去；如果一段代码先捕获、恢复，再从另一个内部调用得到新异常，想保留前一段原因，就必须在你自己的包装点明确传递。

发布前用五个问题检查原因是否还在

• 是否在真正需要增加上下文的边界创建了新异常，而不是到处重复包装？
• 新异常的第三参数是否传入了原始 Throwable？
• 最外层是否用 getPrevious() 遍历到 null，而不是只记录一条消息？
• 是否区分了 throw $error 与“带 previous 的新异常”？
• 日志是否对消息中的用户输入、凭据和内部连接信息做了必要脱敏？

常见问题

只把原异常消息拼到新消息里可以吗？

可以得到一段文字，但不能得到原异常对象、类型、文件、行号和后续链路。需要追踪根因时，应把原对象作为第三个参数传入。

getPrevious() 一定返回 Exception 吗？

不一定。它返回的是 ?Throwable，上一层可能是 Exception，也可能是实现了同一体系的 Error。因此跨层处理时用 Throwable 更稳妥。

什么时候应该直接 throw $error？

当前层没有新的业务语义、分类或边界需要补充时，可以直接重新抛出；只要创建了新异常，就要考虑是否把旧对象挂到 previous 上。