IT技术社区_专业开发者平台_最新编程教程与解决方案 -沐辰社区

PHP项目Laravel API异常响应格式

wen PHP项目 148

本文目录导读：

PHP项目Laravel API异常响应格式

  1. 基础方案：自定义异常处理器
  2. 使用中间件方案
  3. 高级方案：统一异常响应服务
  4. 在控制器中使用
  5. 使用服务提供者
  6. 全局助手函数
  7. 配置异常级别
  8. 异常响应示例
  9. 推荐方案

在Laravel中统一处理API异常响应格式,我推荐以下几种方案：

基础方案：自定义异常处理器

1 创建统一响应格式

// app/Exceptions/ApiResponseTrait.php
<?php
namespace App\Exceptions;
use Illuminate\Http\JsonResponse;
trait ApiResponseTrait
{
    /**
     * 成功响应
     */
    protected function success($data = null, string $message = '操作成功', int $code = 200): JsonResponse
    {
        return response()->json([
            'code' => $code,
            'message' => $message,
            'data' => $data,
            'timestamp' => now()->timestamp
        ]);
    }
    /**
     * 失败响应
     */
    protected function error(string $message = '操作失败', int $code = 400, $data = null): JsonResponse
    {
        return response()->json([
            'code' => $code,
            'message' => $message,
            'data' => $data,
            'timestamp' => now()->timestamp
        ]);
    }
    /**
     * 分页响应
     */
    protected function paginated($paginator, string $message = '操作成功'): JsonResponse
    {
        return response()->json([
            'code' => 200,
            'message' => $message,
            'data' => [
                'items' => $paginator->items(),
                'pagination' => [
                    'current_page' => $paginator->currentPage(),
                    'per_page' => $paginator->perPage(),
                    'total' => $paginator->total(),
                    'last_page' => $paginator->lastPage(),
                    'has_more_pages' => $paginator->hasMorePages()
                ]
            ]
        ]);
    }
}

2 自定义异常类

// app/Exceptions/ApiException.php
<?php
namespace App\Exceptions;
use Exception;
use Throwable;
class ApiException extends Exception
{
    protected $data;
    public function __construct(
        string $message = 'API错误',
        int $code = 400,
        $data = null,
        Throwable $previous = null
    ) {
        parent::__construct($message, $code, $previous);
        $this->data = $data;
    }
    public function getData()
    {
        return $this->data;
    }
}
// 自定义业务异常
class BusinessException extends ApiException
{
    public function __construct(string $message = '业务处理失败', $data = null)
    {
        parent::__construct($message, 422, $data);
    }
}
// 权限异常
class PermissionException extends ApiException
{
    public function __construct(string $message = '没有权限执行此操作', $data = null)
    {
        parent::__construct($message, 403, $data);
    }
}

3 修改异常处理器

// app/Exceptions/Handler.php
<?php
namespace App\Exceptions;
use Illuminate\Auth\Access\AuthorizationException;
use Illuminate\Auth\AuthenticationException;
use Illuminate\Database\Eloquent\ModelNotFoundException;
use Illuminate\Database\QueryException;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Illuminate\Http\JsonResponse;
use Illuminate\Validation\ValidationException;
use Symfony\Component\HttpKernel\Exception\MethodNotAllowedHttpException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
use Throwable;
class Handler extends ExceptionHandler
{
    use ApiResponseTrait;
    protected $dontReport = [
        ApiException::class,
        ValidationException::class,
    ];
    protected $dontFlash = [
        'current_password',
        'password',
        'password_confirmation',
    ];
    public function register(): void
    {
        $this->reportable(function (Throwable $e) {
            // 日志记录
            if (config('app.debug')) {
                \Log::error($e->getMessage(), [
                    'exception' => get_class($e),
                    'file' => $e->getFile(),
                    'line' => $e->getLine(),
                ]);
            }
        });
        $this->renderable(function (Throwable $e, $request) {
            // 只处理API请求
            if ($request->is('api/*') || $request->expectsJson()) {
                return $this->handleApiException($e, $request);
            }
        });
    }
    /**
     * 处理API异常
     */
    protected function handleApiException(Throwable $e, $request): JsonResponse
    {
        // 自定义业务异常
        if ($e instanceof ApiException) {
            return $this->error($e->getMessage(), $e->getCode(), $e->getData());
        }
        // 验证异常
        if ($e instanceof ValidationException) {
            return $this->error(
                '数据验证失败',
                422,
                ['errors' => $e->errors()]
            );
        }
        // 认证异常
        if ($e instanceof AuthenticationException) {
            return $this->error('未认证或认证已过期', 401);
        }
        // 授权异常
        if ($e instanceof AuthorizationException) {
            return $this->error('没有权限执行此操作', 403);
        }
        // 模型未找到
        if ($e instanceof ModelNotFoundException) {
            return $this->error('资源不存在', 404);
        }
        // 路由未找到
        if ($e instanceof NotFoundHttpException) {
            return $this->error('请求路径不存在', 404);
        }
        // 请求方法不允许
        if ($e instanceof MethodNotAllowedHttpException) {
            return $this->error('请求方法不允许', 405);
        }
        // 数据库查询异常
        if ($e instanceof QueryException) {
            return $this->error('数据库操作失败', 500);
        }
        // 其他异常
        if (config('app.debug')) {
            return $this->error($e->getMessage(), 500, [
                'debug' => [
                    'exception' => get_class($e),
                    'trace' => $e->getTrace(),
                ]
            ]);
        }
        // 生产环境默认响应
        return $this->error('服务器内部错误', 500);
    }
}

使用中间件方案

// app/Http/Middleware/ForceJsonResponse.php
<?php
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
class ForceJsonResponse
{
    public function handle(Request $request, Closure $next)
    {
        $request->headers->set('Accept', 'application/json');
        $response = $next($request);
        // 确保所有API响应都是JSON格式
        if (!$response instanceof \Illuminate\Http\JsonResponse) {
            $response = response()->json([
                'code' => $response->getStatusCode(),
                'message' => $response->getContent(),
                'data' => null
            ], $response->getStatusCode());
        }
        return $response;
    }
}

高级方案：统一异常响应服务

// app/Services/ApiResponseService.php
<?php
namespace App\Services;
use Illuminate\Http\JsonResponse;
use Illuminate\Support\MessageBag;
class ApiResponseService
{
    /**
     * 成功响应
     */
    public function success($data = null, string $message = '操作成功'): JsonResponse
    {
        return $this->sendResponse($data, $message, 200, true);
    }
    /**
     * 创建成功
     */
    public function created($data = null, string $message = '创建成功'): JsonResponse
    {
        return $this->sendResponse($data, $message, 201, true);
    }
    /**
     * 无内容
     */
    public function noContent(string $message = '操作成功'): JsonResponse
    {
        return $this->sendResponse(null, $message, 204, true);
    }
    /**
     * 错误响应
     */
    public function error(string $message, int $code = 400, $errors = null): JsonResponse
    {
        return $this->sendResponse(null, $message, $code, false, $errors);
    }
    /**
     * 验证错误
     */
    public function validationError(MessageBag $errors): JsonResponse
    {
        return $this->error('数据验证失败', 422, [
            'errors' => $errors->toArray()
        ]);
    }
    /**
     * 发送响应
     */
    protected function sendResponse($data, string $message, int $code, bool $status, $errors = null): JsonResponse
    {
        $response = [
            'code' => $code,
            'status' => $status,
            'message' => $message,
            'data' => $data,
            'timestamp' => now()->toISOString(),
            'time' => round(microtime(true) - LARAVEL_START, 3),
        ];
        if ($errors) {
            $response['errors'] = $errors;
        }
        return response()->json($response, $code);
    }
    /**
     * 分页响应
     */
    public function paginator($items, int $total, int $page, int $perPage): JsonResponse
    {
        return $this->success([
            'items' => $items,
            'meta' => [
                'total' => $total,
                'page' => $page,
                'per_page' => $perPage,
                'last_page' => ceil($total / $perPage),
            ],
        ]);
    }
}

在控制器中使用

// app/Http/Controllers/Api/UserController.php
<?php
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use App\Services\ApiResponseService;
use Illuminate\Http\Request;
class UserController extends Controller
{
    protected $apiResponse;
    public function __construct(ApiResponseService $apiResponse)
    {
        $this->apiResponse = $apiResponse;
    }
    public function index()
    {
        try {
            $users = User::paginate(15);
            return $this->apiResponse->paginator(
                $users->items(),
                $users->total(),
                $users->currentPage(),
                $users->perPage()
            );
        } catch (\Exception $e) {
            return $this->apiResponse->error('获取用户列表失败: '.$e->getMessage());
        }
    }
    public function store(Request $request)
    {
        try {
            $validated = $request->validate([
                'name' => 'required|string|max:255',
                'email' => 'required|email|unique:users',
            ]);
            $user = User::create($validated);
            return $this->apiResponse->created($user);
        } catch (ValidationException $e) {
            return $this->apiResponse->validationError($e->errors());
        } catch (\Exception $e) {
            return $this->apiResponse->error('创建用户失败');
        }
    }
}

使用服务提供者

// app/Providers/ApiResponseServiceProvider.php
<?php
namespace App\Providers;
use App\Services\ApiResponseService;
use Illuminate\Support\ServiceProvider;
class ApiResponseServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->singleton('api.response', function ($app) {
            return new ApiResponseService();
        });
    }
    public function boot()
    {
        //
    }
}

全局助手函数

// app/helpers.php
<?php
if (!function_exists('api_success')) {
    function api_success($data = null, string $message = '操作成功')
    {
        return app('api.response')->success($data, $message);
    }
}
if (!function_exists('api_error')) {
    function api_error(string $message, int $code = 400, $errors = null)
    {
        return app('api.response')->error($message, $code, $errors);
    }
}

配置异常级别

// config/api.php
<?php
return [
    // 是否显示调试信息
    'debug' => env('API_DEBUG', false),
    // 响应格式配置
    'response' => [
        'include_timestamp' => true,
        'include_time_cost' => true,
        'snake_case' => false,
    ],
    // 错误码配置
    'error_codes' => [
        'success' => 200,
        'created' => 201,
        'bad_request' => 400,
        'unauthorized' => 401,
        'forbidden' => 403,
        'not_found' => 404,
        'validation_error' => 422,
        'server_error' => 500,
    ],
];

异常响应示例

// 成功响应
{
    "code": 200,
    "status": true,
    "message": "操作成功",
    "data": {
        "id": 1,
        "name": "Test User"
    },
    "timestamp": "2024-01-15T10:30:00+00:00",
    "time": 12.3
}
// 验证错误响应
{
    "code": 422,
    "status": false,
    "message": "数据验证失败",
    "data": null,
    "timestamp": "2024-01-15T10:30:00+00:00",
    "time": 5.6,
    "errors": {
        "email": ["The email field is required."],
        "name": ["The name field is required."]
    }
}
// 服务器错误响应
{
    "code": 500,
    "status": false,
    "message": "服务器内部错误",
    "data": null,
    "timestamp": "2024-01-15T10:30:00+00:00",
    "time": 8.9
}

推荐方案

建议采用方案1（自定义异常处理器）+ 方案4（服务类）的组合：

  1. 使用 ApiException 和业务异常类处理业务异常
  2. 使用 ApiResponseService 统一响应格式
  3. 在 Handler 中统一处理所有异常
  4. 在控制器中使用 try-catch 或直接抛出异常

这样既保证了异常处理的统一性，又提供了灵活性，如果是团队项目，建议将响应格式做成可配置的,方便不同场景适配。

版权声明：NBA直播 NBA直播 NBA直播 NBA直播 NBA直播 NBA直播 NBA直播 NBA直播 NBA直播 NBA直播 NBA直播 NBA直播 NBA直播 NBA直播 NBA直播 NBA直播 NBA直播 NBA直播 CBA直播 CBA直播 CBA直播 CBA直播 CBA直播 CBA直播 CBA直播 CBA直播 CBA直播 CBA直播 CBA直播 CBA直播 CBA直播 CBA直播 CBA直播 CBA直播 CBA直播 CBA直播 足球直播 足球直播 足球直播 足球直播 足球直播 足球直播 足球直播 足球直播 足球直播 足球直播 足球直播 足球直播 足球直播 足球直播 足球直播 足球直播 足球直播 足球直播 英超直播 英超直播 英超直播 英超直播 英超直播 英超直播 英超直播 英超直播 英超直播 英超直播 英超直播 英超直播 英超直播 英超直播 英超直播 英超直播 英超直播 英超直播

上一篇PHP项目Laravel验证后回调处理

下一篇PHP项目Laravel验证失败跳转来源

相关文章

抱歉，评论功能暂时关闭!

友情链接攻略窝 · 礼包窝 · 配置窝 · 换算窝 · 算法窝 · 查文窝 · 手册窝 · 问答窝 · 全文搜 · 手册库
相关站点礼包窝 · 查文窝