ما هي الوحدات الديناميكية وما هو نمط forRoot/forFeature؟

Question

Accepted Answer

**الوحدات الديناميكية** هي وحدات يمكن **تكوينها عند استيرادها** — بدلاً من `@Module({...})` ثابتة، تكشف عن methods ثابتة (بشكل تقليدي **`forRoot`** و **`forFeature`**) التي ترجع وحدة مكونة بناءً على الوسائط التي تمررها. هذه هي الطريقة التي تقبل بها الوحدات القابلة للتكوين وإعادة الاستخدام (config، database، JWT) خيارات.

## المشكلة التي تحلها

```text
A static module is fixed — but reusable modules (DatabaseModule, ConfigModule,
JwtModule) need to be CONFIGURED per app (connection URL, secret, options).
Dynamic modules let a module accept configuration at import time.
```

## لقد استخدمتها بالفعل

```ts
@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),               // ← forRoot with options
    TypeOrmModule.forRoot({ type: "postgres", url: ... }),  // ← configured at import
    JwtModule.register({ secret: process.env.SECRET }),      // ← register variant
    TypeOrmModule.forFeature([User, Post]),                  // ← forFeature for specifics
  ],
})
export class AppModule {}
```

استدعاءات `.forRoot()`/`.register()`/`.forFeature()` التي تراها عند استيراد الوحدات هي methods الوحدة الديناميكية التي تقبل التكوين.

## اتفاقية forRoot مقابل forFeature

```text
forRoot()    → configure the module ONCE, globally (the connection, the secret, core setup)
               called in the root/app module a single time
forFeature() → register feature-specific pieces in each feature module that needs them
               (e.g. TypeOrmModule.forFeature([User]) registers entities per module)
```

الاتفاقية: `forRoot` للتكوين العام/لمرة واحدة؛ `forFeature` لتسجيل كل ميزة تستدعيها في عدة وحدات.

## بناء وحدتك الديناميكية الخاصة

```ts
@Module({})
export class StorageModule {
  static forRoot(options: StorageOptions): DynamicModule {
    return {                                  // returns a configured module
      module: StorageModule,
      providers: [
        { provide: "STORAGE_OPTIONS", useValue: options },   // inject the passed options
        StorageService,
      ],
      exports: [StorageService],
      global: true,                            // optionally make it global
    };
  }
}
// usage: StorageModule.forRoot({ bucket: "my-bucket", region: "us-east-1" })
```

الـ method الثابتة ترجع كائن `DynamicModule` (وحدة + providers + exports)، وتوصل الخيارات المُمررة إلى providers الوحدة (غالباً عبر injection token).

## التكوين غير المتزامن (forRootAsync)

```ts
// configure using OTHER injected dependencies (e.g. ConfigService) — async/factory
StorageModule.forRootAsync({
  useFactory: (config: ConfigService) => ({ bucket: config.get("BUCKET") }),
  inject: [ConfigService],
});
```

متغير `forRootAsync` يسمح بأن يعتمد التكوين على providers أخرى (مثل `ConfigService`) — ضروري عندما تأتي الخيارات من تكوين معتمد.

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

الوحدات الديناميكية ونمط `forRoot`/`forFeature` هو مفهوم NestJS مهم لبناء **وحدات قابلة للتكوين وإعادة الاستخدام** — وفهمها قيم لكل من *استخدام* النظام البيئي و*بناء* وحدات مشتركة.

كل وحدة NestJS كبرى تقريباً (ConfigModule، TypeOrmModule، JwtModule، BullModule، CacheModule) هي وحدة ديناميكية مكونة عبر `.forRoot()`/`.register()`/`.forFeature()`، لذا التعرف على ماهية هذه الاستدعاءات (تمرير التكوين إلى وحدة عند وقت الاستيراد، وليس استيراد ثابت) يوضح كيفية توصيل النظام البيئي بأكمله.

**اتفاقية forRoot مقابل forFeature** (forRoot للإعداد العام لمرة واحدة مثل اتصال قاعدة البيانات أو السر؛ forFeature لتسجيل كل ميزة مثل تسجيل الكيانات في كل وحدة) هو نمط تواجهه باستمرار.

بالنسبة للمطورين الأكبر، معرفة كيفية **بناء وحداتك الديناميكية الخاصة** (إرجاع `DynamicModule` مع providers مكونة من الخيارات المُمررة، غالباً عبر injection tokens، مع متغيرات غير متزامنة للإعداد المعتمد على التكوين) هي ما يسمح لك بإنشاء وحدات قابلة لإعادة الاستخدام والتكوين — البنية التحتية المشتركة (التخزين، عملاء API الخارجيين، التكوين المخصص) التي يستوردها الأجزاء الأخرى من التطبيق أو المشاريع الأخرى برسائلهم الخاصة.

هذا موضوع أكثر تقدماً، لكنه أساسي لفهم معمارية NestJS المعيارية بعمق ولبناء مكتبات وحدات احترافية وقابلة لإعادة الاستخدام، مما يجعله قدرة مهمة لتصميم أنظمة NestJS كبيرة وجيدة التنظيم.