ThinkPHP隐藏技巧：利用中间件实现全局异常捕获与统一JSON响应【技巧】-ThinkPHP-PHP中文网

必须用uniformjsonresponse中间件在响应出口前强制统一封装，因exceptionhandler的render()仅在生命周期末尾触发且无法拦截验证失败、路由未匹配等框架级异常；需注册为全局中间件并置于responsetrace之后、缓存中间件之前，同时在handler::render()中结合accept头判断返回json。

thinkphp隐藏技巧：利用中间件实现全局异常捕获与统一json响应【技巧】

在ThinkPHP项目中，当API接口抛出未捕获异常时，前端收到的可能是HTML错误页、空响应或结构混乱的JSON，导致联调失败、监控告警失灵。这并非代码写错，而是异常流未被中间件层主动拦截和重写。

为什么不能只靠ExceptionHandler？

ExceptionHandler类的render()方法仅在请求生命周期末尾触发，但此时响应头可能已发送、中间件链已终止；更重要的是，它无法干预验证失败（ValidateException）、路由未匹配（HttpException）等框架级中断点——这些异常在到达ExceptionHandler前，已被其他中间件提前处理并输出了原始格式。

必须在响应生成出口前插入一层“强制统一封装”，而中间件是唯一能稳定拦截所有响应类型的执行节点。

新建UniformJsonResponse中间件

第一步：执行命令生成中间件文件：php think make:middleware UniformJsonResponse

第二步：打开app/middleware/UniformJsonResponse.php，清空handle()方法内容，填入以下逻辑：

public function handle($request, \Closure $next)
{
  $response = $next($request);
  if ($response instanceof \think\Response && !($response instanceof \think\response\Json)) {
    $originalData = $response->getData();
    if (is_array($originalData) && isset($originalData['code'])) {
      $wrapped = $originalData;
    } else {
      $wrapped = [
        'code' => 500,
        'msg' => 'Server error',
        'data' => null
      ];
    }
    $jsonResponse = json($wrapped, 500)->header(['Content-Type' => 'application/json; charset=utf-8']);
    return $jsonResponse;
  }
  return $response;
}

注意：此处【必须用json()构造Response对象，不能直接return数组】，否则框架会自动包装成HTML响应，破坏统一性。

注册为全局中间件并调整执行顺序

第一步：打开app/middleware.php

第二步：将\app\middleware\UniformJsonResponse::class添加到中间件数组开头位置

Browser Js

轻量级CDP浏览器控制，适用于AI代理。相较于内置浏览器工具，token消耗降低3‑10倍，仅在浏览时使用。

下载

第三步：确认该中间件排在\think\middleware\ResponseTrace::class之后、\think\middleware\CheckRequestCache::class之前——只有在此区间内，才能确保它接收到的是最终响应体，又不会被缓存中间件覆盖输出。

这一步操作起来很简单，直接把中间件类名拖到数组第二位就行。

配合ExceptionHandler禁用调试页干扰

方法一：确保config/app.php中设置'exception_handle' => \app\exception\Handler::class，且该Handler类存在

方法二：在Handler的render()方法中，强制返回JSON，避免开发环境回退到HTML调试页：

public function render($request, Throwable $e): Response
{
  if ($request->isAjax() || $request->header('accept') === 'application/json') {
    return json(['code' => -1, 'msg' => $e->getMessage(), 'data' => null], 500);
  }
  return parent::render($request, $e);
}

关键点在于【isAjax()判断不可靠，必须结合accept头】，因为Postman、curl、小程序等非浏览器客户端不发X-Requested-With头，仅靠isAjax()会漏判。