WebmanPHP异常处理与日志记录教程

Webman 的异常处理看似简单，实则暗藏关键细节：默认仅捕获 Exception 类异常并写入日志，而 E_WARNING、E_NOTICE 等传统错误需手动通过 set_error_handler 转为 ErrorException 才能纳入统一日志体系；业务异常如 ValidateException 必须在 config/exception.php 中显式注册专用处理器，并重写 report() 方法注入请求 URI、IP、trace_id 等上下文信息，否则日志将缺失排查必需的关键线索——真正决定线上问题定位效率的，从来不是“是否记了日志”，而是“每条日志是否自带完整上下文”。

webman里未捕获异常默认怎么处理

webman 默认会把所有未捕获的异常交给 support\exception\Handler 处理，这个类在 config/exception.php 中注册。它会生成一个 500 响应页，并把异常堆栈写入 runtime/logs/webman.log ——但仅限于 Exception 及其子类，不包括 E_WARNING、E_NOTICE 这类传统 PHP 错误。

这意味着：你写了个 undefined variable $foo，它不会触发这个处理器；但 throw new Exception('boom') 会。

• 检查是否生效，可临时在路由里写 throw new \Exception('test');，看日志是否出现
• 若日志没内容，先确认 config/log.php 中 'level' 设置不低于 \Monolog\Logger::ERROR
• 该处理器默认不记录客户端 IP 和请求 URI，如需补全，得重写 report() 方法

如何让 E_WARNING、E_NOTICE 也被捕获并记日志

PHP 的错误（非异常）必须用 set_error_handler() 接管，webman 没有默认启用它。你需要手动注册一个错误处理器，并把它转成异常再交由框架日志系统处理。

推荐做法是在 app/bootstrap.php 或服务启动前添加：

set_error_handler(function ($errno, $errstr, $errfile, $errline) {
    if (!(error_reporting() & $errno)) {
        return;
    }
    // 转为 ErrorException，让它走统一异常流程
    throw new \ErrorException($errstr, 0, $errno, $errfile, $errline);
});

• 这个转换很重要：否则 error_log() 写的日志格式和框架日志不一致，排查时要切两个文件
• 注意不要在 set_error_handler 里直接调用 Log::error()，否则可能引发递归或日志丢失
• 某些致命错误（如 E_PARSE、E_COMPILE_ERROR）无法被此函数捕获，它们需要靠 register_shutdown_function() 配合 error_get_last() 补漏

自定义业务异常该怎么注册和记录

比如你定义了 app\exception\ValidateException，想让它单独记日志、返回 422 状态码，就不能只靠 try-catch，得在 config/exception.php 显式注册处理类。

配置示例：

return [
    'app\exception\ValidateException' => 'app\exception\ValidateExceptionHandler',
    '' => 'support\exception\Handler',
];

• 处理类必须实现 handle() 和 report() 方法；report() 里调用 Log::error() 才能进日志文件
• 别忘了在 handle() 中调用 response()->json() 或 response()->status(422)，否则仍返回 500
• 如果多个业务异常共用相似逻辑，建议让它们继承同一个基类，然后在配置中注册基类名，避免重复注册

日志内容缺失关键上下文怎么办

默认日志只有异常消息、文件、行号，缺少请求方法、URI、用户 ID、trace_id 等信息，线上排查时效率极低。webman 的 Log 类支持上下文参数，但默认异常处理器没传。

解决方式是重写 report() 方法，在自定义处理器或继承 support\exception\Handler 后注入上下文：

public function report(Exception $exception)
{
    $context = [
        'uri' => request()->uri(),
        'method' => request()->method(),
        'ip' => request()->ip(),
        'trace_id' => \Webman\Utils\Trace::id(),
    ];
    Log::error($exception->getMessage(), $context + [
        'file' => $exception->getFile(),
        'line' => $exception->getLine(),
        'trace' => $exception->getTraceAsString(),
    ]);
}

• request() 在异常发生时可能已不可用（比如解析请求体失败），所以要在 report() 开头就提取关键字段，别等到后面才调用
• trace_id 需提前在中间件中生成并绑定到全局，否则这里取不到
• 不要在日志里 dump 整个 $_POST 或 $_SERVER，敏感字段（密码、token）必须过滤

真正难的不是记下错误，而是让每条日志都带够线索——URI、IP、trace_id、业务标识缺一不可。框架默认给的只是骨架，上下文得自己一处处补全，漏掉任意一个，线上查问题就要多花半小时。

到这里，我们也就讲完了《WebmanPHP异常处理与日志记录教程》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于Webman的知识点！