Hyperf 异常处理需确保注册顺序、类型判断、响应构造和传播控制四环节协同；定义业务异常类并继承 RuntimeException，编写精准 isValid 和 handle 方法，按优先级在 exceptions.php 中注册，最后用 curl 验证响应状态码与 JSON 结构。
Hyperf 重写异常返回类，核心目标是让接口在出错时返回结构清晰、字段明确、便于前端解析的错误信息，而不是默认的空白页或简单文本。关键不在“重写类”本身，而在于注册顺序、类型判断、响应构造和传播控制四个环节必须协同到位。
定义业务异常类，区分语义
不要直接 throw new Exception()，而是创建有业务含义的异常类，比如：
- 继承 RuntimeException 或更具体的基类（如 BaseException），避免与框架 HTTP 异常混淆；
- 构造函数中传入 message 和 code，code 作为业务错误码，不直接映射 HTTP 状态码；
- 示例：
throw new UserNotFoundException('用户不存在', 1001);
编写精准匹配的异常处理器
处理器必须严格限定处理范围，避免误吞其他异常：
- isValid() 方法只返回 true 当且仅当 $throwable 是目标异常类型，不能写 return true；
- handle() 中调用 $this->stopPropagation()，防止异常继续传递到后续处理器；
- 手动设置 HTTP 状态码（如 404、422、500），并把业务 code 和 message 放进 JSON body；
- 示例响应体：
{"code":1001,"message":"用户不存在"}
按优先级注册到 exceptions.php
配置顺序决定执行顺序，顺序错了会导致 404 变成 500：
- 自定义处理器必须放在 Hyperf\HttpServer\Exception\Handler\HttpExceptionHandler 之后；
- 因为 HttpExceptionHandler 已负责处理 NotFoundException、MethodNotAllowedHttpException 等，返回正确状态码；
- 若你的 AppExceptionHandler 写在它前面且 isValid 返回 true，所有 404 都会被拦截成 500；
- 确认 config/autoload/server.php 中 HTTP server 的 name（如 http、api），exceptions.php 中 handler 键名必须完全一致。
验证是否生效的实操方法
别只看代码，用 curl 快速验证真实响应：
- 启动服务后，执行
curl -v http://127.0.0.1:9501/test/exception； - 检查响应头 status 是否为你设定的值（如 404）；
- 检查响应 body 是否为标准 JSON，含 code/message 字段；
- 若返回空白或原始 PHP 错误，说明异常没被任何 handler 捕获，检查类路径、命名空间、注册配置是否拼写正确。
