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

Question

Accepted Answer

توفر NestJS **خطافات دورة الحياة** — وهي طرق تطبقها لتشغيل الكود في لحظات محددة من دورة حياة التطبيق أو المزود (initialization و shutdown). وهي ضرورية للإعداد الأولي (الاتصال بالموارد) والتنظيف (إغلاق الاتصالات بشكل صحيح).

## الخطافات الرئيسية

```ts
@Injectable()
export class DatabaseService
  implements OnModuleInit, OnApplicationShutdown {

async onModuleInit() {
    // runs once the host MODULE's dependencies are resolved → do INITIALIZATION
    await this.connect();         // e.g. open a database connection
  }

async onApplicationShutdown(signal: string) {
    // runs when the app is shutting down → do CLEANUP
    await this.disconnect();      // close connections, flush, release resources
  }
}
```

## تسلسل دورة الحياة

```text
INITIALIZATION (startup):
  onModuleInit()          → after the module's providers are initialized
  onApplicationBootstrap()→ after ALL modules are initialized (whole app ready)

SHUTDOWN (graceful termination):
  onModuleDestroy()         → cleanup as modules are destroyed
  beforeApplicationShutdown() → before shutdown completes
  onApplicationShutdown(signal) → final shutdown (signal = SIGTERM, etc.)
```

## حالة استخدام شائعة: خدمة Prisma تتصل وتقطع الاتصال

```ts
@Injectable()
export class PrismaService extends PrismaClient
  implements OnModuleInit, OnModuleDestroy {

async onModuleInit() {
    await this.$connect();        // connect on startup
  }
  async onModuleDestroy() {
    await this.$disconnect();      // disconnect on shutdown — clean release
  }
}
```

هذا هو النمط القياسي للموارد التي تحتاج إلى إعداد/تفكيك صريح — الاتصال في `onModuleInit`، الإفراج في `onModuleDestroy`.

## تفعيل خطافات الإيقاف

```ts
// shutdown hooks must be enabled explicitly
const app = await NestFactory.create(AppModule);
app.enableShutdownHooks();        // ❗ required for onApplicationShutdown etc. to fire
```

خطافات الإيقاف تعمل فقط إذا استدعيت `enableShutdownHooks()` — من السهل نسيانها، وبعدها لا يحدث التنظيف أبداً.

## لماذا يهم الإيقاف الآمن

```text
When the app receives SIGTERM (deploy, scale-down, container stop):
  ✗ Without shutdown hooks → connections left open, in-flight work dropped
  ✓ With shutdown hooks → close DB/Redis/queues cleanly, finish work → zero-downtime
```

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

خطافات دورة الحياة مهمة لإدارة الموارد بشكل صحيح في تطبيقات NestJS — فهي توفر الأماكن المناسبة لإجراء **التهيئة** (فتح اتصالات قواعد البيانات/Redis، تحميل البيانات، التسجيل مع الخدمات) وبشكل حاسم، **التنظيف الآمن** عند الإيقاف (إغلاق الاتصالات، مسح المخزن المؤقت، إنهاء العمل الجاري).

فهمها ضروري لموثوقية الإنتاج: **خطافات التهيئة** (`onModuleInit`, `onApplicationBootstrap`) تضمن حدوث الإعداد في الوقت المناسب بمجرد أن تكون التبعيات جاهزة، و**خطافات الإيقاف** (`onModuleDestroy`, `onApplicationShutdown`) تمكّن **الإيقاف الآمن** — وهو حيوي في النشر الحديث (الحاويات/أدوات التنسيق ترسل SIGTERM باستمرار أثناء النشر والتوسع، وبدون التنظيف المناسب تسرب الاتصالات وتسقط الطلبات النشطة، مما يكسر نشر التوقف الصفري).

نمط الاتصال في `onModuleInit` وقطع الاتصال في `onModuleDestroy` (مثلاً لخدمات Prisma/قاعدة البيانات) هو معرفة NestJS اليومية، ومعرفة التفصيل الدقيق بضرورة استدعاء `enableShutdownHooks()` (أو خطافات الإيقاف تعمل بصمت أبداً) تفصيل عملي يسهل إغفاله.

إتقان خطافات دورة الحياة هو جزء من بناء خدمات NestJS قوية وجاهزة للإنتاج تتعامل مع الموارد والنشر بشكل صحيح.