ما هي مرشحات الاستثناءات (Exception Filters)؟

Question

Accepted Answer

**مرشحات الاستثناءات** توفر لك تحكماً كاملاً في كيفية **التقاط الأخطاء وتحويلها إلى استجابات**. تقع في نهاية دورة حياة الطلب، وتلتقط الاستثناءات المرمية في أي مكان في الطلب وتسمح لك بتخصيص صيغة الاستجابة للخطأ والحالة والتسجيل.

## مرشح استثناء أساسي

```ts
import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from "@nestjs/common";

@Catch(HttpException)                    // catch HttpExceptions specifically
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const request = ctx.getRequest();
    const status = exception.getStatus();

// build a CUSTOM error response shape
    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      message: exception.message,
    });
  }
}
```

مزخرف `@Catch()` يحدد أنواع الاستثناءات التي يتعامل معها هذا المرشح، والدالة `catch()` تستقبل الاستثناء بالإضافة إلى السياق — مما يسمح لك بصياغة أي استجابة تريدها.

## التقاط جميع الاستثناءات (بما في ذلك غير HTTP)

```ts
@Catch()                                 // no argument = catch EVERYTHING
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const status = exception instanceof HttpException
      ? exception.getStatus()
      : 500;                              // unknown errors → 500
    // log the full error internally, return a safe message to the client
    this.logger.error(exception);
    ctx.getResponse().status(status).json({ statusCode: status, message: "..." });
  }
}
```

مرشح بـ `@Catch()` (بدون معاملات) يتعامل مع كل استثناء — المكان المناسب لتسجيل الأخطاء غير المتوقعة والتأكد من أن حتى الأخطاء غير HTTP ترجع استجابة نظيفة وآمنة (بدون تسريب تتبعات المكدس للعملاء).

## تطبيق المرشحات

```ts
@UseFilters(HttpExceptionFilter)         // method or controller level
export class UsersController {}

app.useGlobalFilters(new AllExceptionsFilter());   // GLOBAL — app-wide, most common
```

عادةً ما تُطبق المرشحات **عالمياً** لفرض صيغة خطأ متسقة عبر كامل API.

## لماذا نستخدم مرشحات الاستثناءات؟

```text
✓ Consistent error response format across ALL endpoints (a standard shape)
✓ Centralized error LOGGING (log every error in one place)
✓ Handle non-HTTP errors safely (turn unexpected errors into clean 500s)
✓ Hide internal details from clients (no leaked stack traces — security)
✓ Add context (request path, timestamp, correlation IDs) to error responses
```

## المرشحات مقابل رمي الاستثناءات

```text
Throwing exceptions (NotFoundException, etc.) → SIGNALS an error with a status
Exception filters → control HOW those errors are FORMATTED/logged into responses
→ You throw exceptions in your code; filters customize the resulting response globally.
```

## لماذا يهم هذا

مرشحات الاستثناءات هي ميزة مهمة في NestJS لبناء APIs قوية واحترافية مع **معالجة أخطاء متسقة ومتحكم بها**.

بينما طبقة الاستثناءات المدمجة في NestJS تحول بالفعل الاستثناءات المرمية إلى استجابات HTTP، مرشحات الاستثناءات توفر لك تحكماً كاملاً لتخصيص هذا السلوك — وهذا يهم لعدة اهتمامات حقيقية: فرض **صيغة استجابة خطأ متسقة** عبر كل endpoint (بحيث يحصل العملاء دائماً على الأخطاء بنفس الصيغة)، **مركزية تسجيل الأخطاء** (التقاط كل خطأ في مكان واحد بدلاً من تشتته في try/catch متعددة)، التعامل الآمن **مع الأخطاء غير HTTP غير المتوقعة** (تحويلها إلى 500 نظيفة بدلاً من التعطل أو تسريب التفاصيل)، و**الأمان** (إخفاء تتبعات المكدس الداخلية والتفاصيل الحساسة عن العملاء مع تسجيلها داخلياً).

مرشح "catch-all" عام مع رمي استثناءات HTTP محددة في الكود هو النمط القياسي لمعالجة الأخطاء في مستوى الإنتاج.

فهم متى وكيف تستخدم المرشحات (مقابل رمي الاستثناءات ببساطة)، وتطبيقها عالمياً للحصول على التسق، هو علامة مميزة للتطبيقات المدمجة جيداً في NestJS ويعكس الممارسة الناضجة في الخلفية حول المسألة الحرجة لكن غالباً المتجاهلة وهي معالجة الأخطاء.