💯 Exception 异常插件
v1.6.2 版本
2025-07-30 版本更新时间
10090 安装
16 star
简介
安装
composer require tinywan/exception-handler使用
配置
config/exception.php
return [ // 这里配置异常处理类 '' => \Tinywan\ExceptionHandler\Handler::class, ];🤬🤬 webman-admin 中配置
异常接管
/plugin/admin/config/exception.php
return [ '' => \Tinywan\ExceptionHandler\Handler::class, ];接口不存在路由处理
/plugin/admin/config/route.php
Route::fallback(function () { throw new \Tinywan\ExceptionHandler\Exception\RouteNotFoundException(); }, 'admin');基本用法
请求参数错误
use support\Request; use support\Response; use Tinywan\ExceptionHandler\Exception\BadRequestHttpException; class Token{ public function issueToken(Request $request): Response { $params = $request->post(); if (empty($params)) { throw new BadRequestHttpException('账号或密码不能为空'); } } }以上异常抛出错误信息，如下格式：
HTTP/1.1 400 Bad Request Content-Type: application/json;charset=utf-8 { "code": 0, "msg": "账号或密码不能为空", "data": {}, }所有返回的异常信息将以json格式返回，以上为
返回简略的异常信息
所有的异常错误处理器根据配置文件 config/app.php中debug的值来调整错误显示， 当debug值为true (表示在调试模式)， 错误处理器会显示异常以及详细的函数调用栈和源代码行数来帮助调试，将返回详细的异常信息。 当debug值为false，只有错误信息会被显示以防止应用的敏感信息泄漏，将返回简略的异常信息。
返回详细的异常信息
HTTP/1.1 400 Bad Request Content-Type: application/json;charset=utf-8 { "code": 0, "msg": "password不允许为空", "data": { "request_url": "POST //127.0.0.1:8888/oauth/issue-token", "timestamp": "2022-03-06 15:19:12", "client_ip": "172.18.0.1", "request_param": { "username": "webman" }, "error_message": "password不允许为空", "error_trace": "#0 /var/www/webman-admin/app/functions.php(68): Tinywan\\Validate\\Validate->check(Array)\n#1 /var/www/webman-admin/app/controller/Authentication.php(25): ..." } }如何自定义一个自己的异常类
编写异常类
假设自定义一个：405 Method Not Allowed（表示：请求行中指定的请求方法不能被用于请求相应的资源）
自定义异常类只需要继承Tinywan\ExceptionHandler\Exception\BaseException类即可
<?php declare(strict_types=1); namespace support\exception; use Tinywan\ExceptionHandler\Exception\BaseException; class MethodNotAllowedException extends BaseException { /** * @var int */ public $statusCode = 405; /** * @var string */ public $errorMessage = '请求行中指定的请求方法不能被用于请求相应的资源'; }使用异常类
use support\Request; use support\Response; use support\exception\MethodNotAllowedException; class Token{ public function issueToken(Request $request): Response { $params = $request->post(); if (empty($params)) { throw new MethodNotAllowedException(); } } }使用postman请求截图
已支持插件异常类
- JWT 权限认证插件 异常类
JwtTokenException - Validate 验证器插件 异常类
ValidateException
内置异常类
- 客户端异常类（HTTP Status 400）：BadRequestHttpException
- 身份认证异常类（HTTP Status 401）：UnauthorizedHttpException
- 资源授权异常类（HTTP Status 403）：ForbiddenHttpException
- 资源不存在异常类（HTTP Status 404）：NotFoundHttpException
- 路由地址不存在异常类（HTTP Status 404）：RouteNotFoundException
- 请求限流在异常类（HTTP Status 429）：TooManyRequestsHttpException
- 服务器内部错误异常类（HTTP Status 500）：ServerErrorHttpException
HTTP 响应状态码
https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Status
自定义异常 Response
只支持修改body的三个字段的key值。必须保持顺序是：
- ① 状态码
- ② 错误消息
- ③ 响应数据
使用场景
- 每个项目有标准的统一输出，自定义返回内容
- 前后端分离：前端要求返回的
HTTP状态码并不是429，而是200或者其他- 响应的
body不是{"code":0,"msg":"Too Many Requests"}，而是{"error_code":200,"message":"Too Many Requests"}等其他内容
自定义HTTP状态码
编辑 config/plugin/tinywan/exception-handler/app.php 文件的 status HTTP 状态码
自定义body返回内容
编辑 config/plugin/tinywan/exception-handler/app.php 文件的 body 的字段
默认选项是
{ "code": 0, "msg": "Too Many Requests", "data": null }自定义选项参考一
1、假设status HTTP 状态码设置为 200
2、假设body的数组设为为
'body' => [ 'error_code' => 200, 'message' => '请求太多请稍后重试' ]则响应内容为
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "error_code": 200, "message": "请求太多请稍后重试" }其他的可以根据自身业务自定义即可
扩展自己的 Handler
当项目需要自定义情况比较多的时候，很可能需要扩展 Handler，此时可以继承 Tinywan\ExceptionHandler\Handler 然后修改对应方法即可。
使用场景
- response需要响应
xml，而不是json格式，只需要覆盖buildResponse方法- 扩展其他Exception的响应，我只要覆盖
solveExtraException- 要异常推送微信消息，我可以覆盖
triggerNotifyEvent
自定义异常 ErrorHandler
namespace support; use Illuminate\Validation\ValidationException; use Tinywan\ExceptionHandler\Handler; use Webman\Http\Response; class ErrorHandler extends Handler { /** * @inheritDoc */ protected function solveExtraException(\Throwable $e): void { // 当前项目下的异常扩展 if ($e instanceof ValidationException) { $this->errorMessage = $e->validator->errors()->first(); $this->errorCode = 422; return; } parent::solveExtraException($e); } /** * @inheritDoc */ protected function triggerNotifyEvent(\Throwable $e): void { // ... 这里省略触发其他错误推送渠道 parent::triggerNotifyEvent($e); } /** * @inheritDoc */ protected function buildResponse(): Response { // 构造自己项目下的响应 return json([ 'code' => $this->statusCode, // 使用 statusCode 作为 code 返回 'msg' => $this->errorMessage, 'data' => $this->responseData, ]); } }异常通知（钉钉机器人）
