Hyperf自定义异常类输出接口报错详情-php教程-PHP中文网

hyperf自定义异常需三者协同：定义继承runtimeexception的业务异常类（含code/message）、编写精准匹配并调用stoppropagation()的异常处理器、按优先级在exceptions.php中注册；否则默认返回500或空响应。

hyperf自定义异常类输出接口报错详情

Hyperf 自定义异常类输出接口报错详情，核心在于异常类 + 异常处理器 + 响应格式三者协同，不能只抛一个异常就指望自动返回结构化错误信息。默认情况下，Hyperf 会把未捕获异常转为 500 页面或空响应，必须主动干预。

1. 定义业务异常类（带 code 和 message）

继承 RuntimeException 即可，无需特殊接口。重点是构造时传入业务码和提示，方便后续提取：

code 用于 JSON body 中的业务错误码（如 1001、2002），不是 HTTP 状态码
message 是面向前端或日志的简明提示，比如“用户不存在”
不要重写 getCode() 方法——它默认返回构造参数，够用

示例：/app/Exception/UserNotFoundException.php

<?php namespace App\Exception;

class UserNotFoundException extends \RuntimeException
{
}
// 使用：throw new UserNotFoundException('用户不存在', 1001);

2. 编写专用异常处理器（精准匹配 + 终止传播）

处理器必须实现 isValid() 严格判断类型，并在 handle() 中手动设置状态码、构造 JSON、调用 stopPropagation()：

HTTP status 固定用 4xx/5xx（如 404），别把业务码 1001 当 status 传给 withStatus()
JSON body 包含 code（业务码）、message（提示）、trace_id（可选，便于查日志）
漏掉 $this->stopPropagation() 会导致异常继续传递，可能被后续兜底处理器覆盖成 500

示例：/app/Exception/Handler/UserNotFoundHandler.php

Hyperframes Creative

HyperFrames视频非动画创意指导，包括设计规范（frame.md/design.md）处理、配色、字体设计、旁白及节奏规划等。

下载

<?php namespace App\Exception\Handler;

use App\Exception\UserNotFoundException;
use Hyperf\ExceptionHandler\ExceptionHandler;
use Hyperf\HttpMessage\Stream\SwooleStream;
use Psr\Http\Message\ResponseInterface;
use Throwable;

class UserNotFoundHandler extends ExceptionHandler
{
    public function handle(Throwable $throwable, ResponseInterface $response)
    {
        $this->stopPropagation();

        $data = json_encode([
            'code' => $throwable->getCode(),
            'message' => $throwable->getMessage(),
            'trace_id' => $this->container->get(\Hyperf\Tracer\Tracer::class)->getTraceId() ?? '',
        ], JSON_UNESCAPED_UNICODE);

        return $response->withStatus(404)->withBody(new SwooleStream($data));
    }

    public function isValid(Throwable $throwable): bool
    {
        return $throwable instanceof UserNotFoundException;
    }
}

3. 注册到配置并注意顺序

在 config/autoload/exceptions.php 的 http 数组中注册，且必须放在 HttpExceptionHandler 之后：

如果放太前，连 404、405 这类框架原生异常也会被你拦截，导致前端收不到正确 status
数组顺序 = 匹配优先级，越靠前越先试 isValid()

正确配置示例：

return [
    'handler' => [
        'http' => [
            // 框架内置兜底，处理所有 HttpException 子类（含 404/405）
            Hyperf\HttpServer\Exception\Handler\HttpExceptionHandler::class,
            // 自定义处理器，仅处理特定业务异常
            App\Exception\Handler\UserNotFoundHandler::class,
            App\Exception\Handler\AppExceptionHandler::class,
        ],
    ],
];