ما هو ترتيب دورة حياة الطلب (Request Lifecycle) في NestJS؟

Question

Accepted Answer

**دورة حياة الطلب** هي التسلسل الدقيق للمكونات التي يمر بها الطلب عبر NestJS — البرمجيات الوسيطة (middleware)، والحراس (guards)، والمعترضات (interceptors)، والأنابيب (pipes)، ومعالج الطلب (handler)، ثم المعترضات مرة أخرى، ومرشحات الاستثناءات (exception filters) في حالة الأخطاء. معرفة الترتيب الدقيق حاسمة لفهم *متى* يعمل كل جزء من المنطق.

## الترتيب الكامل

```text
Incoming Request
   │
   ▼
1. MIDDLEWARE            (Express-style; raw req/res; runs first)
   │
   ▼
2. GUARDS                (authorization — return true to continue, false/throw to block)
   │
   ▼
3. INTERCEPTORS (pre)    (logic BEFORE the handler — start timing, etc.)
   │
   ▼
4. PIPES                 (validate/transform the handler's arguments — DTO validation)
   │
   ▼
5. ROUTE HANDLER         (your controller method runs)
   │
   ▼
6. INTERCEPTORS (post)   (logic AFTER the handler — transform the response)
   │
   ▼
Response

✗ If an exception is thrown ANYWHERE above →
7. EXCEPTION FILTERS     (catch it and format the error response)
```

## لماذا يهم الترتيب (العواقب العملية)

```text
• Guards run BEFORE pipes → authorization is checked before input validation
  (no point validating a body for an unauthorized request)
• Pipes run JUST BEFORE the handler → the handler always gets validated/transformed args
• Interceptors straddle the handler → they can measure its duration and transform output
• Filters catch errors from any stage → centralized, consistent error handling
```

## ضمن كل فئة، ينطبق ترتيب النطاق (Scope Ordering)

```text
For each type (guards, interceptors, pipes), they run in this scope order:
  Global → Controller → Method (route)
So a global guard runs before a controller-level guard, before a route-level guard.
```

## مثال عملي ملموس

```ts
@Controller("users")
@UseGuards(AuthGuard)                    // 2. checks authorization
@UseInterceptors(LoggingInterceptor)     // 3 (pre) + 6 (post)
export class UsersController {
  @Post()
  create(@Body() dto: CreateUserDto) {    // 4. ValidationPipe validates dto, 5. handler runs
    return this.usersService.create(dto);
  }
}
// Flow: middleware → AuthGuard → LoggingInterceptor(before) → ValidationPipe →
//       create() → LoggingInterceptor(after) → response (or → filter on error)
```

## لماذا يهم

فهم ترتيب دورة حياة الطلب أساسي لبناء تطبيقات NestJS بشكل صحيح — فهو يحدد بدقة *متى* يتم تنفيذ كل جزء من منطق الاهتمامات المستعرضة (cross-cutting logic)، والذي يؤثر بشكل مباشر على قرارات التصميم واستكشاف الأخطاء.

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

معرفة هذا الترتيب — بالإضافة إلى ترتيب النطاق ضمن الفئات (عام → وحدة تحكم → طريقة) — تتيح لك وضع المنطق في المكون الصحيح، والتنبؤ بتدفق التنفيذ، وتصحيح سبب تشغيل شيء ما (أم لا) عند التوقع، وبناء الميزات بشكل صحيح.

إنه يربط معاً كل مكونات معالجة الطلب في الإطار (برمجيات وسيطة، حراس، معترضات، أنابيب، مرشحات) في نموذج عقلي متماسك، مما يجعله موضوعاً مهماً ومختبراً بشكل متكرر يعكس فهماً حقيقياً لكيفية معالجة NestJS للطلبات.