ThinkPHP接口异常自动分类指南

ThinkPHP中throw异常可被完整捕获并打标，而trigger_error触发的错误需手动注册错误处理器转发为异常才能进入统一处理链路；Handle::report是唯一可信打标入口，须过滤HttpResponseException和ValidateException，并确保trace_id在请求入口绑定。

ThinkPHP接口调用链路中，throw 和 trigger_error 的异常捕获行为差异

ThinkPHP 默认只捕获继承自 Throwable 的异常（即 Exception 或 Error 子类），而 trigger_error 触发的 E_WARNING、E_NOTICE 等错误不会进入异常处理器，直接绕过 think\exception\Handle —— 这是链路打标漏掉“非致命但需归类”问题的最常见原因。

• 若业务中混用 trigger_error('xxx', E_USER_WARNING) 做轻量级提示，必须手动注册 set_error_handler 并转发为异常，否则日志里看不到、监控也抓不到
• throw new \Exception() 会被完整捕获，但默认不带业务上下文（如接口名、trace_id），需在抛出前手动注入 $e->setData(['api' => 'user/login'])
• ThinkPHP 6.1+ 支持在 app/exception/Handle.php 中重写 report 方法，这里才是打标逻辑的唯一可信入口，别在中间件里做分类

用 get_class($e) + $e->getCode() 做基础错误类型识别，但别只靠它

单纯判断异常类名或错误码极易误判：比如 think\db\exception\DataNotFoundException 和 think\exception\HttpResponseException 都可能出现在同一个登录接口里，但前者是数据层缺失，后者是主动跳转，语义完全不同。

• 优先提取 $e->getPrevious() 链，真实根因往往藏在上一层（例如 PDO 异常被封装成 DbException，真正要标的是 PDOException 的 SQLSTATE）
• $e->getCode() 对框架异常基本无效（多为 0），应转向解析 $e->getMessage() 中的关键词，如包含 'timeout'、'Connection refused'、'Duplicate entry' 等字符串再归类
• 避免硬编码匹配全路径类名，改用 str_contains(get_class($e), 'db\\') 或 is_a($e, \think\db\exception::class, true) 提高兼容性

在 Handle::report() 里加打标逻辑，但必须避开 HttpResponseException 和 ValidateException

这两类异常是 ThinkPHP 主动抛出的流程控制型异常，不是错误，打标后会污染故障率统计。它们的共性是：不记录堆栈、不触发 render、通常发生在控制器返回前。

• 加白名单过滤：if ($e instanceof \think\exception\HttpResponseException || $e instanceof \think\exception\ValidateException) { return; }
• 打标字段建议固定为三个：error_category（如 'db' / 'http' / 'cache'）、error_level（'fatal' / 'warning' / 'info'）、error_trace（从 debug_backtrace(0, 3) 提取最近 3 层调用，不含框架内部）
• 别在 report 里写 DB 操作——该方法可能被高频调用，写库容易拖慢整个异常处理链路；改用 Redis 缓存临时标记或发消息队列异步落库

日志格式必须含 trace_id，且不能依赖 Log::getLogId()

Log::getLogId() 在 CLI 模式下为空，在 FPM 多请求复用 worker 场景下可能串号。真正的链路 ID 必须在请求入口就生成并绑定到容器或 Request 对象上。

• 在 app/middleware/TraceId.php 中生成：$traceId = $_SERVER['HTTP_X_TRACE_ID'] ?? uniqid('t_', true);，然后 $this->app->bind('trace_id', $traceId)
• 日志 channel 配置里启用 json 格式，并在 extra 字段显式注入：'trace_id' => $this->app->make('trace_id')
• 如果用了 ELK，确保 trace_id 字段被定义为 keyword 类型，否则 Kibana 里无法做聚合分析

链路打标真正的难点不在分类规则，而在保证每个异常都携带可追溯的上下文。漏掉一次 trace_id 绑定，整条链就断了——这事没法事后补。