通过统一响应格式、自定义异常类、集中渲染和智能日志控制，可提升 Laravel API 异常处理的清晰度与可维护性，确保错误信息结构一致、语义明确、便于前端解析与调试。
统一异常响应格式
API 返回的错误信息应与成功响应保持结构一致，便于前端解析。例如：
{
"success": false,
"message": "资源未找到",
"data": null
}
在 App/Exceptions/Handler.php 中重写 render 方法，判断是否为 API 请求，并统一输出格式：
protected $dontReport = [ \Illuminate\Auth\AuthenticationException::class, \Illuminate\Auth\Access\AuthorizationException::class, \Symfony\Component\HttpKernel\Exception\NotFoundHttpException::class, // 可根据需要添加其他非上报异常 ];然后在 render 方法中加入：
if ($this->isApiCall($request)) {
return response()->json([
'success' => false,
'message' => $this->getErrorMessage($exception),
'data' => null
], $this->getStatusCode($exception));
}辅助方法示例：
private function isApiCall($request)
{
return $request->is('api/*') || $request->expectsJson();
}
private function getErrorMessage($exception)
{
return method_exists($exception, 'getMessage')
? $exception->getMessage()
: '服务器内部错误';
}
private function getStatusCode($exception)
{
return method_exists($exception, 'getStatusCode')
? $exception->getStatusCode()
: 500;
}
自定义业务异常类
为不同业务场景创建专用异常类，提升代码可读性和维护性。比如创建：
- InvalidOrderException
- PaymentFailedException
- UserNotFoundException
以 UserNotFoundException 为例：
namespace App\Exceptions;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
class UserNotFoundException extends NotFoundHttpException
{
public function __construct($message = '用户不存在')
{
parent::__construct($message);
}
}
在控制器中抛出：
if (! $user) {
throw new UserNotFoundException();
}
这样不仅语义清晰，还能被统一拦截处理。
使用异常渲染器（ExceptionHandler）集中管理
Laravel 支持通过 report 和 render 方法对异常进行定制化处理。
例如，捕获模型未找到异常并转换为友好提示：
use Illuminate\Database\Eloquent\ModelNotFoundException;
public function render($request, Exception $exception)
{
if ($exception instanceof ModelNotFoundException && $this->isApiCall($request)) {
return response()->json([
'success' => false,
'message' => '请求的资源不存在',
'data' => null
], 404);
}
return parent::render($request, $exception);
}
也可以针对表单验证异常做优化：
use Illuminate\Validation\ValidationException;
if ($exception instanceof ValidationException && $this->isApiCall($request)) {
return response()->json([
'success' => false,
'message' => '数据验证失败',
'errors' => $exception->errors()
], 422);
}
记录日志并过滤敏感异常
不是所有异常都需要上报到日志或监控系统。利用 $dontReport 属性避免冗余日志：
protected $dontReport = [
\Illuminate\Auth\AuthenticationException::class,
\Illuminate\Auth\Access\AuthorizationException::class,
\Symfony\Component\HttpKernel\Exception\NotFoundHttpException::class,
\Illuminate\Validation\ValidationException::class,
];
对于需要特别关注的异常，可在 report 方法中发送通知或记录上下文：
public function report(Exception $exception)
{
if ($this->shouldReport($exception)) {
// 记录用户 ID、请求路径等上下文
\Log::error('API Exception: ' . $exception->getMessage(), [
'user_id' => auth('api')->id(),
'url' => request()->fullUrl(),
'method' => request()->method(),
'ip' => request()->ip()
]);
}
parent::report($exception);
}
基本上就这些。通过统一响应格式、自定义异常类、集中渲染和智能日志控制，可以让 Laravel API 的异常处理更加清晰、可控且易于维护。关键是把错误当成产品的一部分来设计，而不是事后补救。 
