llmbackend/app/Exceptions/Handler.php

<?php

declare(strict_types=1);

namespace App\Exceptions;

use App\Constants\ErrorCode;
use Illuminate\Auth\Access\AuthorizationException;
use Illuminate\Auth\AuthenticationException;
use Illuminate\Database\Eloquent\ModelNotFoundException;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\HttpException;
use Symfony\Component\HttpKernel\Exception\MethodNotAllowedHttpException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
use Symfony\Component\HttpKernel\Exception\TooManyRequestsHttpException;
use Throwable;

class Handler extends ExceptionHandler
{
    /**
     * API 路由前缀
     */
    protected const API_PREFIX = 'api';

    /**
     * 不需要报告的异常类型
     *
     * @var array<int, class-string<Throwable>>
     */
    protected $dontReport = [
        AuthenticationException::class,
        AuthorizationException::class,
        ValidationException::class,
        ModelNotFoundException::class,
    ];

    /**
     * 注册异常处理回调
     */
    public function register(): void
    {
        $this->renderable(function (Throwable $e, Request $request) {
            if ($this->isApiRequest($request)) {
                return $this->handleApiException($e);
            }
        });
    }

    /**
     * 处理 API 异常
     *
     * @param Throwable $e
     * @return JsonResponse
     */
    protected function handleApiException(Throwable $e): JsonResponse
    {
        if ($e instanceof ValidationException) {
            return $this->error(
                ErrorCode::VALIDATION_ERROR,
                ErrorCode::getMessage(ErrorCode::VALIDATION_ERROR),
                $e->errors(),
                Response::HTTP_UNPROCESSABLE_ENTITY
            );
        }

        if ($e instanceof AuthenticationException) {
            return $this->error(
                ErrorCode::UNAUTHORIZED,
                ErrorCode::getMessage(ErrorCode::UNAUTHORIZED),
                null,
                Response::HTTP_UNAUTHORIZED
            );
        }

        if ($e instanceof AuthorizationException) {
            return $this->error(
                ErrorCode::FORBIDDEN,
                ErrorCode::getMessage(ErrorCode::FORBIDDEN),
                null,
                Response::HTTP_FORBIDDEN
            );
        }

        if ($e instanceof ModelNotFoundException) {
            return $this->error(
                ErrorCode::RESOURCE_NOT_FOUND,
                ErrorCode::getMessage(ErrorCode::RESOURCE_NOT_FOUND),
                null,
                Response::HTTP_NOT_FOUND
            );
        }

        if ($e instanceof NotFoundHttpException) {
            return $this->error(
                ErrorCode::RESOURCE_NOT_FOUND,
                ErrorCode::getMessage(ErrorCode::RESOURCE_NOT_FOUND),
                null,
                Response::HTTP_NOT_FOUND
            );
        }

        if ($e instanceof MethodNotAllowedHttpException) {
            return $this->error(
                ErrorCode::METHOD_NOT_ALLOWED,
                ErrorCode::getMessage(ErrorCode::METHOD_NOT_ALLOWED),
                null,
                Response::HTTP_METHOD_NOT_ALLOWED
            );
        }

        if ($e instanceof TooManyRequestsHttpException) {
            return $this->error(
                ErrorCode::TOO_MANY_REQUESTS,
                ErrorCode::getMessage(ErrorCode::TOO_MANY_REQUESTS),
                null,
                Response::HTTP_TOO_MANY_REQUESTS
            );
        }

        if ($e instanceof HttpException) {
            return $this->error(
                ErrorCode::SERVER_ERROR,
                $e->getMessage(),
                null,
                $e->getStatusCode()
            );
        }

        // 记录未处理的异常
        $this->report($e);

        return $this->error(
            ErrorCode::SERVER_ERROR,
            ErrorCode::getMessage(ErrorCode::SERVER_ERROR),
            config('app.debug') ? [
                'message' => $e->getMessage(),
                'trace' => $e->getTraceAsString(),
            ] : null,
            Response::HTTP_INTERNAL_SERVER_ERROR
        );
    }

    /**
     * 判断是否为 API 请求
     *
     * @param Request $request
     * @return bool
     */
    protected function isApiRequest(Request $request): bool
    {
        return $request->is(static::API_PREFIX . '/*') || $request->expectsJson();
    }

    /**
     * 返回错误响应
     *
     * @param string $error 错误代码
     * @param string $message 错误消息
     * @param mixed $errors 详细错误信息
     * @param int $code HTTP状态码
     * @return JsonResponse
     */
    protected function error(string $error, string $message, mixed $errors = null, int $code = Response::HTTP_BAD_REQUEST): JsonResponse
    {
        $response = [
            'success' => false,
            'error' => $error,
            'message' => $message,
        ];

        if ($errors !== null) {
            $response['errors'] = $errors;
        }

        return response()->json($response, $code);
    }
}