CakePHP 4中如何实现API自动返回JSON错误响应且不影响Web应用的HTML错误页面

你遇到的这个问题确实是多应用场景下的典型需求——CakePHP默认的异常处理没直接区分Web和API场景，但咱们只要给异常处理加个「场景判断」就能完美解决，既满足API返回JSON错误，又不影响Web端的HTML错误页面。

下面是一步步的实现方案，亲测有效：

第一步：配置全局自定义异常渲染器 #

首先在config/app.php里，把默认的异常渲染器替换成我们自己的类，这样所有异常都会经过我们的自定义逻辑处理：

// config/app.php
'Error' => [
    'errorLevel' => E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED,
    // 替换为自定义渲染器
    'exceptionRenderer' => App\Error\AppExceptionRenderer::class,
    'skipLog' => [],
    'log' => true,
    'trace' => true,
],

第二步：创建智能判断的自定义异常渲染器 #

在src/Error/目录下新建AppExceptionRenderer.php文件，这个类继承CakePHP默认的WebExceptionRenderer，核心逻辑是先判断请求是否来自API，再决定返回JSON还是HTML：

<?php
declare(strict_types=1);

namespace App\Error;

use Cake\Error\Renderer\WebExceptionRenderer;
use Cake\Http\Response;
use Cake\Core\Configure;

class AppExceptionRenderer extends WebExceptionRenderer
{
    /**
     * 渲染异常，根据请求场景返回对应格式
     *
     * @return \Cake\Http\Response
     */
    public function render(): Response
    {
        // 识别API请求：通过路由里标记的_isApi参数判断（第三步会配置）
        if ($this->request->getParam('_isApi', false)) {
            return $this->renderApiError();
        }

        // 非API请求，沿用默认的Web异常渲染（返回HTML页面）
        return parent::render();
    }

    /**
     * 专门处理API异常，返回标准JSON结构
     *
     * @return \Cake\Http\Response
     */
    protected function renderApiError(): Response
    {
        $exception = $this->error;
        $httpCode = $this->getHttpCode($exception);
        $errorMessage = $this->getMessage($exception);

        // 构建符合API规范的JSON响应
        $responseData = [
            'error' => true,
            'message' => $errorMessage,
            'code' => $httpCode,
        ];

        // 调试模式下额外返回异常详情（方便开发调试）
        if (Configure::read('debug')) {
            $responseData['trace'] = $exception->getTraceAsString();
            $responseData['file'] = $exception->getFile();
            $responseData['line'] = $exception->getLine();
        }

        // 生成最终响应
        return $this->response
            ->withStatus($httpCode)
            ->withType('application/json')
            ->withStringBody(json_encode($responseData, JSON_THROW_ON_ERROR));
    }
}

第三步：给API路由添加识别标记 #

在config/routes.php里，给所有API路由添加一个自定义参数_isApi，这样我们的异常渲染器就能精准区分API和Web请求：

// config/routes.php
use Cake\Routing\RouteBuilder;
use Cake\Routing\Route\DashedRoute;

return static function (RouteBuilder $routes) {
    $routes->setRouteClass(DashedRoute::class);

    // Web应用路由：不需要特殊标记，正常配置即可
    $routes->scope('/', function (RouteBuilder $builder) {
        $builder->connect('/', ['controller' => 'Home', 'action' => 'index']);
        // 其他Web端业务路由...
    });

    // API路由配置：添加前缀并标记_isApi
    $routes->prefix('Api', function (RouteBuilder $builder) {
        $builder->setPrefix('api/v1'); // 对应URL路径：/api/v1/xxx
        $builder->setExtensions(['json']); // 可选：限制API仅接受JSON格式请求

        // 给该范围内的所有API路由添加_isApi标识
        $builder->scope('/', function (RouteBuilder $builder) {
            $builder->connect('/*', [], ['_isApi' => true]);
            // 具体的API接口路由，比如：
            // $builder->connect('/users', ['controller' => 'Users', 'action' => 'index']);
            // $builder->connect('/users/:id', ['controller' => 'Users', 'action' => 'view']);
        });
    });
};

最终效果 #

• Web端用户：访问错误页面（比如404）时，依然看到CakePHP默认的HTML错误页面，完全不影响体验。
• API调用方/PHPUnit测试：API返回的所有错误（404、500等）都是标准JSON格式，$this->assertContentType('application/json')测试能正常通过。
• 可扩展性：如果以后新增其他场景（如移动端专属API），只需要在路由里添加对应标记，在渲染器里扩展判断逻辑即可。

内容来源于stack exchange