ما هي موفرات مخصصة ورموز الحقن؟

Question

Accepted Answer

خارج فئات `@Injectable()` البسيطة، يدعم NestJS **موفرات مخصصة** — طرق مرنة لتحديد ما يتم حقنه — باستخدام **رموز الحقن**. هذا يسمح لك بحقن القيم، وتكوين كيفية إنشاء الحالات، وتبديل التطبيقات، وحقن التبعيات غير الصنفية.

## أربعة أنواع موفرات مخصصة

```ts
@Module({
  providers: [
    // 1. useClass — standard (or swap the implementation behind a token)
    { provide: PaymentService, useClass: StripePaymentService },

// 2. useValue — inject a constant/object/mock (great for config and testing)
    { provide: "CONFIG", useValue: { apiKey: "abc", timeout: 5000 } },

// 3. useFactory — compute the provider dynamically (can use other deps)
    {
      provide: "DATABASE_CONNECTION",
      useFactory: async (config: ConfigService) => {
        return await createConnection(config.get("DB_URL"));   // async setup
      },
      inject: [ConfigService],        // dependencies for the factory
    },

// 4. useExisting — create an alias for an existing provider
    { provide: "ALIAS", useExisting: PaymentService },
  ],
})
export class AppModule {}
```

## رموز الحقن — للتبعيات غير الصنفية

```ts
// classes can be tokens directly (by type). For values/interfaces, use a string/Symbol token:
@Injectable()
export class PaymentProcessor {
  constructor(@Inject("CONFIG") private config: AppConfig) {}   // inject by token
}
```

بما أنك لا يمكنك حقن واجهة أو قيمة عادية حسب النوع (فهي لا توجد في وقت التشغيل)، فأنت تستخدم **رمز** (سلسلة نصية أو `Symbol`) مع `@Inject(token)` لحقنه. بهذه الطريقة تحقن كائنات التكوين أو عملاء الجهات الخارجية أو التبعيات المكتوبة بواجهة.

## useFactory — الأكثر قوة (إعداد ديناميكي وغير متزامن)

```ts
// create a provider whose value depends on runtime config / async initialization
{
  provide: "REDIS_CLIENT",
  useFactory: (config: ConfigService) => new Redis(config.get("REDIS_URL")),
  inject: [ConfigService],
}
```

`useFactory` يشغل دالة (مع التبعيات المحقونة) لإنتاج الموفر — ضروري للاتصالات أو العملاء أو أي شيء يحتاج إلى إعداد وقت التشغيل أو إعداد غير متزامن.

## تبديل التطبيقات (useClass) — المرونة والاختبار

```ts
// inject a different implementation based on environment
{
  provide: PaymentService,
  useClass: process.env.NODE_ENV === "test" ? MockPaymentService : StripePaymentService,
}
```

لأن المستهلكين يعتمدون على الرمز (`PaymentService`)، يمكنك تبديل الفئة الملموسة — خدمة Stripe حقيقية في الإنتاج أو محاكاة في الاختبارات — دون تغيير أي كود مستهلك.

## لماذا الأمر مهم

الموفرات المخصصة ورموز الحقن توسع الحقن التبعي في NestJS خارج الفئات البسيطة، مما يعطيك المرونة المطلوبة للتطبيقات الحقيقية.

فهمها مهم للعديد من السيناريوهات الشائعة: **حقن قيم غير صنفية** (كائنات التكوين أو الثوابت) عبر `useValue` ورموز النص أو Symbol (لأنك لا يمكنك حقن الواجهات أو القيم العادية حسب النوع)؛ **الإنشاء الديناميكي/غير المتزامن للموفر** عبر `useFactory` (الشكل الأقوى — إنشاء اتصالات قاعدة البيانات أو عملاء Redis أو مثيلات SDK الجهات الخارجية المكونة من القيم في وقت التشغيل، مع تبعياتهم المحقونة الخاصة)؛ و**تبديل التطبيقات** عبر `useClass` خلف رمز (تفعيل التطبيقات المستندة إلى البيئة و، بشكل حاسم، **المحاكاة السهلة في الاختبارات** — توفر فئة محاكاة لرمز دون لمس المستهلكين).

هذه المرونة هي التي تجعل DI في NestJS قوية للهندسة المعمارية الإنتاجية والاختبار الممتاز.

معرفة أنواع الموفرات الأربعة (`useClass` و `useValue` و `useFactory` و `useExisting`)، وكيف تعمل رموز الحقن للتبعيات غير الصنفية، وعند اللجوء إلى كل واحدة منها هو خطوة مهمة تتجاوز DI الأساسي — فهي كيف تربط قواعد البيانات والخدمات الخارجية والتكوين والتبعيات القابلة للتبديل/المحاكاة بطريقة idiomatica لـ NestJS، مما يجعلها موضوعاً مطلوباً بشكل متكرر وذو أهمية معمارية في التطبيقات الحقيقية.