ما هي Interceptors؟

Question

ما هي Interceptors؟

Accepted Answer

**Interceptors** تغلّف تنفيذ معالج المسار (route handler)، مما يتيح لك تشغيل منطق **قبل وبعد** تنفيذه — وتحويل الطلب أو الاستجابة. إنها مستوحاة من البرمجة الموجهة للجوانب (aspect-oriented programming)، وهي مثالية للاهتمامات العرضية مثل التسجيل (logging)، وتحويل الاستجابة، والتخزين المؤقت (caching)، والقياس الزمني.

## البنية: قبل وبعد عبر RxJS

```ts
@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    console.log("Before handler");          // runs BEFORE the route handler
    const now = Date.now();

return next.handle().pipe(               // next.handle() = invoke the handler
      tap(() => console.log(`After: ${Date.now() - now}ms`)),   // runs AFTER
    );
  }
}
```

مُعترض يطبّق `intercept()`. الكود قبل `next.handle()` يعمل **قبل** معالج؛ `next.handle()` يُرجع `Observable` من RxJS للاستجابة، والعوامل مثل `tap`/`map` تتيح لك التصرف بناءً على الاستجابة **بعد** انتهاء المعالج.

## تحويل الاستجابة (حالة استخدام شائعة)

```ts
@Injectable()
export class TransformInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler) {
    return next.handle().pipe(
      map(data => ({ success: true, data, timestamp: new Date().toISOString() })),
      // wraps EVERY response in a consistent envelope: { success, data, timestamp }
    );
  }
}
```

باستخدام `map`، يمكن لمُعترض إعادة تشكيل كل استجابة — مثلاً تغليف جميع الاستجابات في غلاف موحد، وهو نمط شائع جداً للاستجابات API متسقة.

## استخدامات قوية أخرى

```ts
// caching — return a cached response, skipping the handler entirely
// timeout — fail requests taking too long
return next.handle().pipe(timeout(5000));

// error mapping — transform exceptions
return next.handle().pipe(catchError(err => throwError(() => new BadGatewayException())));

// excluding fields (serialization) — ClassSerializerInterceptor strips @Exclude() fields
```

```text
Common interceptor uses:
  ✓ Logging / timing requests (before + after)
  ✓ Transforming responses (consistent envelopes, field exclusion)
  ✓ Caching responses
  ✓ Adding timeouts
  ✓ Mapping/handling errors
```

## تطبيق Interceptors

```ts
@UseInterceptors(LoggingInterceptor)   // method or controller level
app.useGlobalInterceptors(new TransformInterceptor());   // global
```

## Interceptors مقابل middleware مقابل guards

```text
Middleware  → runs BEFORE everything, with raw req/res (can't easily touch the response)
Guard       → AUTHORIZATION decision (allow/block) before the handler
Interceptor → wraps the handler — runs BEFORE and AFTER, can TRANSFORM the response
```

الميزة المحددة: يمكن للمعترضات تشغيل منطق **بعد** المعالج و**تحويل الاستجابة** — وهو ما لا تستطيع middleware و guards فعله بسهولة.

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

Interceptors هي ميزة NestJS قوية للتعامل مع **الاهتمامات العرضية** بأناقة، وقدرتها المميزة — تشغيل منطق قبل *وبعد* المعالج، وتحويل الاستجابة — تجعلها الأداة الصحيحة للاحتياجات التي لا تستطيع middleware و guards معالجتها.

فهمها مهم لأن العديد من المتطلبات الشائعة تُخطّط بشكل طبيعي للمعترضات: تنسيق الاستجابة المتسق (تغليف جميع الاستجابات في غلاف موحد `{ success, data }`)، التسجيل/القياس الزمني (قياس مدة المعالج)، التخزين المؤقت (إرجاع الاستجابات المخزنة)، المهل الزمنية (timeouts)، تحويل الأخطاء، والتسلسل (استبعاد الحقول الحساسة).

فهم البنية (Observable `next.handle()`، مع `tap`/`map`/`catchError` للتصرف قبل/بعد)، وحالات الاستخدام الشائعة، وخاصة **كيفية اختلاف Interceptors عن middleware و guards** (القدرة على تغليف وتحويل الاستجابة) هو جزء رئيسي من الكفاءة المعمارية في NestJS.

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