PHP 异常 previous 链的日志呈现方法

PHP 项目把底层异常转换成业务异常后，日志里经常只剩一句“保存失败”，真正的数据库、网络或参数原因被藏在 previous 链中。稳定的呈现方法不是简单拼接多段字符串，而是从当前 Throwable 开始，逐层提取类型、消息、错误码和位置，最后以结构化数组写入日志。

官方参考：https://www.php.net/manual/en/throwable.getprevious.php

先保留异常链，再把每层转换为独立日志项；外层说明业务动作，内层保留根因。请求参数、密码和令牌则放在链条之外单独脱敏。

先确认 previous 链从哪里产生

包装异常时，当前异常描述“业务动作失败”，previous 才描述“最初为什么失败”。如果构造新异常时漏掉第三个参数，后续再调用 getPrevious() 只能得到 null，日志展示自然会断在外层。

这里捕获的是 Throwable，因此既覆盖 Exception，也覆盖可被抛出的 Error。但不要在所有层级都重新包装；通常在跨越基础设施边界、需要补充业务语义时包装一次即可。

日志按外层到根因输出

日志阅读通常先关心“哪个业务动作失败”，再追查“底层究竟抛了什么”。因此可以从外到内遍历，并为每层保留稳定字段。用数组而不是一条长文本，后续写入 JSON、日志平台或告警索引都会更方便。

 get_class($current),
            'message' => $current->getMessage(),
            'code' => $current->getCode(),
            'file' => $current->getFile(),
            'line' => $current->getLine(),
            'depth' => $depth,
        ];
        // 没有 previous 时返回 null，循环自然结束。
        $current = $current->getPrevious();
    }

    return $items;
}

function writeErrorLog(Throwable $error, string $requestId): void
{
    // 上下文与异常链分开，避免把原始请求参数整体写入。
    $record = [
        'request_id' => $requestId,
        'exception_chain' => exceptionChain($error),
    ];
    error_log((string) json_encode($record, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES));
}
?> 

字段可以按下面的边界理解：

把敏感信息和请求上下文分开

previous 链适合记录技术原因，不适合承载整段请求数据。比如数据库异常消息里可能出现 SQL 片段，HTTP 客户端异常可能包含 URL 查询参数。生产日志应只放请求编号、业务动作和经过筛选的资源标识，原始输入由应用层按白名单记录。

 $requestId,
        'action' => $action,
        'order_id' => $orderId,
    ];
}
?> 

对外响应可以只返回通用错误和请求编号；对内日志保留链条。两者职责分开后，既不丢排查线索，也不会把内部路径、数据库细节直接暴露给调用方。

常见问题与复查清单

为什么调用 getPrevious() 总是得到 null？

先检查包装异常的构造函数是否把原异常作为第三个参数传入。单独 throw new RuntimeException($e->getMessage()) 只复制了文字，没有建立链。

应该记录 getTraceAsString() 还是 previous 链？

两者用途不同：链条回答“错误如何层层包装”，trace 回答“当前异常在哪条调用路径创建”。日志平台优先存结构化链，必要时再按权限保存受控的 trace。

捕获 Exception 能覆盖所有可抛出问题吗？

不能。PHP 7 及以上可抛出的 Error 与 Exception 都实现 Throwable；跨基础设施边界统一记录时，应按场景捕获 Throwable，不要因此吞掉错误后继续执行。

链条长度应该设置多少？

没有固定值。可按服务的包装层数设置上限，并在达到上限时增加一个“truncated”标记；关键是让日志体积可控，同时保留最外层和最近的根因线索。

复查这类日志时，先看最外层 type 和 message 是否表达业务动作，再沿 depth 找到底层类型，最后确认请求编号能关联同一次调用。这样 previous 链就从隐藏属性变成了可检索的故障证据。