مدیریت خطاهای API در لاراول یکی از بخش‌های حیاتی برای توسعه یک API حرفه‌ای و قابل اعتماد است. کاربر نهایی یا کلاینت API باید پاسخ‌های واضح، قابل درک و استانداردی در صورت وقوع خطا دریافت کند. در این مقاله به بررسی روش‌های مدیریت خطا در API لاراول می‌پردازیم:

🧩 انواع خطاها در API

• خطاهای اعتبارسنجی (Validation Errors)

• خطاهای احراز هویت (Authentication Errors)

• خطاهای مجوز (Authorization Errors)

• خطاهای HTTP عمومی (404, 500 و...)

• خطاهای منطقی و تجاری (Business Logic Errors)

🛠️ روش‌های مدیریت خطا

1. استفاده از try-catch در کنترلرها

برای کنترل خطاهای خاص در هنگام اجرای متدها، از try-catch استفاده می‌شود:

php
CopyEdit
public function show($id)
{
    try {
        $user = User::findOrFail($id);
        return response()->json($user);
    } catch (ModelNotFoundException $e) {
        return response()->json(['error' => 'User not found'], 404);
    } catch (\Exception $e) {
        return response()->json(['error' => 'Server error'], 500);
    }
}

2. هندل کردن خطاها در فایل app/Exceptions/Handler.php

فایل اصلی مدیریت خطا در لاراول همین فایل است. در متد render() می‌توانید انواع خطاها را بررسی و پاسخ مناسب برگردانید:

php
CopyEdit
public function render($request, Throwable $exception)
{
    if ($request->expectsJson()) {
        if ($exception instanceof ModelNotFoundException) {
            return response()->json(['error' => 'Record not found'], 404);
        }

        if ($exception instanceof AuthenticationException) {
            return response()->json(['error' => 'Unauthenticated'], 401);
        }

        if ($exception instanceof AuthorizationException) {
            return response()->json(['error' => 'Unauthorized'], 403);
        }

        if ($exception instanceof ValidationException) {
            return response()->json([
                'error' => 'Validation failed',
                'details' => $exception->errors(),
            ], 422);
        }

        return response()->json([
            'error' => 'Something went wrong'
        ], 500);
    }

    return parent::render($request, $exception);
}

3. استفاده از Form Request برای اعتبارسنجی و مدیریت خطا

در لاراول، کلاس‌های FormRequest راهی مناسب برای اعتبارسنجی ورودی و مدیریت خطاهای مربوط به آن هستند.

php
CopyEdit
class StoreUserRequest extends FormRequest
{
    public function rules()
    {
        return [
            'name' => 'required',
            'email' => 'required|email|unique:users',
        ];
    }

    public function failedValidation(Validator $validator)
    {
        throw new HttpResponseException(response()->json([
            'error' => 'Validation error',
            'details' => $validator->errors(),
        ], 422));
    }
}

4. ساخت ساختار استاندارد پاسخ‌ها

برای یکپارچگی پاسخ‌ها، می‌توانید از یک هلسپر یا کلاس پاسخ عمومی استفاده کنید:

php
CopyEdit
class ApiResponse
{
    public static function success($data, $message = '')
    {
        return response()->json([
            'success' => true,
            'message' => $message,
            'data' => $data
        ]);
    }

    public static function error($message, $code = 500, $details = [])
    {
        return response()->json([
            'success' => false,
            'message' => $message,
            'errors' => $details
        ], $code);
    }
}

5. پاسخ‌دهی استاندارد با JSON:API یا Laravel Error Resources

برای پاسخ‌دهی کاملاً استاندارد، می‌توانید از پکیج‌هایی مانند Laravel JSON:API یا Resource-based error responses استفاده کنید.

🧪 نمونه‌ای از پاسخ خطا

json
CopyEdit
{
  "success": false,
  "message": "Validation error",
  "errors": {
    "email": ["The email field is required."]
  }
}

🧷 نکات امنیتی در مدیریت خطا

• اطلاعات حساس (مانند مسیر فایل یا خطای SQL) را در محیط production نمایش ندهید.

• از فایل .env برای تنظیم APP_DEBUG=false در محیط واقعی استفاده کنید.

• پیام‌های خطا را برای کاربر واضح اما ایمن بنویسید.

🎯 نتیجه‌گیری

مدیریت خطای خوب در API لاراول باعث بهبود تجربه کاربری، کاهش مشکلات کلاینت و آسان‌سازی دیباگ کردن می‌شود. با استفاده از قابلیت‌های پیش‌فرض لاراول مانند Handler, FormRequest, middlewareها و ساختار JSON منظم، می‌توانید APIهایی دقیق، ایمن و حرفه‌ای توسعه دهید.

اگر دوست داشتی، می‌تونم یه قالب JSON پاسخ‌های استاندارد API هم برات آماده کنم.