PHP Throwable 与 Exception 怎样设计统一错误入口

我在把多个 PHP 入口的错误处理合并时，最容易踩的坑不是少写了一个 catch，而是把 Exception 当成了所有可抛出对象。正确的分层是：Throwable 负责描述“能被 throw、能被 catch 的对象”，Exception 更适合承载可预期的业务失败，Error 则通常说明代码或运行时出现了需要修复的编程问题。

官方地址：https://www.php.net/manual/en/language.error-handling.php

统一错误入口可以在应用边界捕获 Throwable，用于记录 trace、生成兜底响应和保证清理；但业务分支仍应优先捕获具体的 Exception 子类，不能用一个大而空的 catch (Throwable) 把 TypeError、ParseError 等编程错误伪装成正常业务失败。

先把三层关系摆正

Throwable 是接口，不是让业务代码直接实现的基类。PHP 手册把所有可以通过 throw 抛出的对象归到这条接口下，常见的两条分支是 Exception 和 Error。用户自定义异常应继承 Exception，而不是直接实现 Throwable。

getMessage();
}

这里的重点是“类型表达意图”。调用方知道 PaymentDeclined 可以转成支付失败提示，但不应该把任意 Error 也当成支付失败。

为什么统一入口要捕获 Throwable

如果只写 catch (Exception $e)，代码确实能接住大多数自定义异常，但接不住继承自 Error 的可抛出对象。PHP 7 以后，类型错误、参数数量错误等情况可能以 Error 层级对象出现；它们和业务异常都实现了 Throwable，却不代表它们有相同的修复方式。

因此我会把捕获点拆成两层：靠近业务的函数捕获具体异常，HTTP 控制器、命令行入口或消息消费入口再用 Throwable 做最后一道边界。边界的职责是记录、清理、转换和终止当前请求，不是继续执行一段已经处于未知状态的业务。

 'payment_declined']);
    } catch (Throwable $e) {
        // 最外层只做统一记录和兜底响应，避免泄露内部细节。
        logThrowable($e);
        respond(500, ['error' => 'internal_error']);
    }
}

function respond(int $status, array $body): void
{
    // 示例只保留边界职责；真实项目中还要交给响应组件发送。
    http_response_code($status);
    echo json_encode($body, JSON_UNESCAPED_UNICODE);
}

function logThrowable(Throwable $e): void
{
    // 记录类名、消息和 trace，生产环境不要直接回显给用户。
    error_log(get_class($e) . ': ' . $e->getMessage());
}

这个顺序不能反过来。若先写 catch (Throwable)，后面的具体 catch 永远不会有机会执行，因为第一个匹配的捕获块会接管当前对象。

Exception 和 Error 应该怎样分工

Exception 适合表示调用方能够理解并作出选择的失败，例如库存不足、支付被拒、输入不符合领域规则。它可以被转换为业务错误码，也可以在上层包装成带有 previous 的应用异常。

Error 则更像“程序需要修复”的信号。TypeError、ArgumentCountError、ParseError 等对象虽然也能被 catch，但不应该在普通业务分支里被当成用户可重试的异常。生产边界可以捕获并记录它们，开发阶段则应让监控和测试尽快暴露问题。

用 previous 保留真正的因果链

统一入口并不等于把底层错误的消息原样抛给用户。更稳妥的做法是在跨层时创建一个新的应用异常，把底层对象作为第三个构造参数传给 Exception。这样上层使用稳定的类型，日志仍然可以沿着 getPrevious() 追到 PDO、文件或 HTTP 客户端的根因。

prepare('SELECT id, name FROM users WHERE id = :id');
        $stmt->execute(['id' => $id]);
        $user = $stmt->fetch(PDO::FETCH_ASSOC);
        if ($user === false) {
            // 查无数据是领域结果，不一定要伪装成运行时 Error。
            throw new UserRepositoryFailure('用户不存在');
        }
        return $user;
    } catch (Throwable $e) {
        // 包装时保留 previous，日志才能看见原始数据库异常。
        throw new UserRepositoryFailure('读取用户失败', 0, $e);
    }
}

如果已经是同一层级的业务异常，也不要无意义地反复包装；应先判断是否需要增加上下文。无论是否包装，最外层记录时都要递归输出因果链，而不是只记录最外层的一句“读取失败”。

finally 负责清理，不能拿来改变错误语义

finally 适合关闭句柄、释放锁、清理临时状态。它会在正常返回、异常传播和调用栈回退时执行。需要特别小心的是：如果 finally 自己再次抛出异常，它可能覆盖原本正在传播的对象，导致真正的根因只剩在 previous 中，甚至完全丢失。

三种捕获方式怎么选

我通常按“是否知道错误类型、是否处于应用边界、是否需要继续运行”来选。

1. 知道业务类型：在领域服务或用例层捕获具体的 Exception 子类，只处理这一类失败，其他对象继续上抛。
2. 到达请求或任务边界：用 catch (Throwable $e) 记录类名、消息、trace 和 request/job ID，再输出统一的安全响应。
3. 需要全局兜底：用 set_exception_handler() 接住未捕获对象。它适合统一日志和最后响应，但处理器返回后脚本不会恢复到原来的业务流程。

getMessage()
    ));
    http_response_code(500);
    echo '服务器暂时无法处理请求';
});

最后用这张表检查统一入口

一句话总结：Throwable 是统一入口的边界类型，Exception 是业务异常的建模起点，Error 是需要优先修复的程序信号。分层捕获、保留 previous、用 finally 清理，才能同时得到一致的日志和清晰的错误语义。

相关问题

• 为什么 catch (Exception) 接不住 TypeError？
• 业务异常应该继承 Exception 还是 RuntimeException？
• set_exception_handler() 能让脚本继续执行吗？
• 包装异常时为什么要传入 previous？