نظرة عامة على مزودي الخدمات

يستخدم FORGE بنية قائمة على المزودين للتكامل مع الخدمات الخارجية. المزودون هم تنفيذات قابلة للتبديل لفئات خدمات شائعة مثل SMS والبريد الإلكتروني والتخزين والمدفوعات. كل فئة تُعرّف سمة (trait) مشتركة وتدعم تنفيذات drivers متعددة يمكن تبديلها أثناء التشغيل.

البنية

يتبع نظام المزودين نمط trait-factory:

┌─────────────────────────────────────────────────────────┐
│                    نظام المزودين                          │
├─────────────────────────────────────────────────────────┤
│                                                          │
│   ┌─────────────┐                                        │
│   │   السمة      │  واجهة مشتركة (send، store، إلخ.)     │
│   │  (Trait)    │                                        │
│   └──────┬──────┘                                        │
│          │                                                │
│    ┌─────┼──────────────┐                                │
│    │     │              │                                 │
│    ▼     ▼              ▼                                 │
│ ┌──────┐ ┌──────────┐ ┌────────┐                        │
│ │Twilio│ │ Unifonic  │ │ Vonage │  تنفيذات الـ drivers   │
│ └──────┘ └──────────┘ └────────┘                        │
│    │          │             │                             │
│    └──────────┼─────────────┘                            │
│               ▼                                          │
│        ┌─────────────┐                                   │
│        │   المصنع     │  يُنشئ الـ driver الصحيح أثناء   │
│        │   Factory   │  التشغيل من الإعدادات            │
│        └─────────────┘                                   │
│                                                          │
└─────────────────────────────────────────────────────────┘

كيف يعمل

1. السمة (Trait) -- تُعرّف العقد الذي يجب على جميع drivers تنفيذه (مثل SmsProvider::send())
2. الـ Drivers -- تنفيذات ملموسة لخدمات محددة (مثل Twilio، SendGrid، S3)
3. المصنع (Factory) -- يقرأ الإعدادات ويُنشئ الـ driver الصحيح أثناء التشغيل

هذا التصميم يتيح لك تبديل المزودين بدون تغيير كود التطبيق. على سبيل المثال، الانتقال من Twilio إلى Vonage يتطلب فقط تغيير في الإعدادات.

فئات المزودين

الفئة	السمة	الـ Drivers المتاحة	التوثيق
SMS	SmsProvider	Twilio، Unifonic، Vonage	مزودو SMS
البريد	EmailProvider	SMTP، SendGrid، Mailgun، Amazon SES	مزودو البريد
التخزين	StorageProvider	Local، S3	مزودو التخزين
المدفوعات	PaymentProvider	HyperPay، Checkout.com	مزودو المدفوعات

الإعدادات

يتم إعداد المزودين في مكانين:

1. forge.yaml

قسم providers في forge.yaml يُحدد أي driver يُستخدم لكل فئة:

providers:
  sms: twilio
  email: smtp
  storage: local
  payments: hyperpay

2. جدول الإعدادات

بيانات اعتماد وخيارات الـ driver المحددة تُخزّن في جدول الإعدادات في قاعدة البيانات، مُجمّعة تحت فئة المزود:

┌────────────┬───────────────────┬────────────────────────────┐
│ group_name │ key               │ value                      │
├────────────┼───────────────────┼────────────────────────────┤
│ sms        │ twilio_account_sid│ ACxxxxxxxxxxxxxxxxxxxxxxxx │
│ sms        │ twilio_auth_token │ ••••••••••••••••           │
│ sms        │ twilio_from_number│ +15551234567               │
│ email      │ email_host        │ smtp.example.com           │
│ email      │ email_port        │ 587                        │
│ storage    │ s3_bucket         │ my-app-uploads             │
└────────────┴───────────────────┴────────────────────────────┘

نصيحة

تُخزّن بيانات الاعتماد كـ إعدادات مُشفّرة باستخدام AES-256-GCM. لا تُكشف أبداً بنص واضح من خلال واجهة الإدارة أو API.

تثبيت مزود

استخدم FORGE CLI لتثبيت driver مزود:

# Install a specific provider driver
forge provider:add sms:twilio
forge provider:add email:sendgrid
forge provider:add storage:s3
forge provider:add payments:hyperpay

يقوم أمر provider:add بـ:

1. التحقق من نوع المزود والـ driver
2. تحديث forge.yaml بالـ driver المُختار
3. إضافة متغيرات البيئة المطلوبة إلى .env و .env.example
   • يتخطى المتغيرات الموجودة مسبقاً (لا تكرار عند إعادة التشغيل)
   • يُنشئ الملفات إذا لم تكن موجودة
   • يُجمّع المتغيرات تحت رأس قسم (مثل # Sms Provider (twilio))
4. عرض متغيرات البيئة المطلوبة للمرجعية

نصيحة

الـ Drivers المُسماة log (مثل sms:log، payment:log) للتطوير فقط ولا تتطلب متغيرات بيئة. يتم تخطي خطوة ملف البيئة بالكامل لهذه الـ drivers.

إنشاء المزود أثناء التشغيل

يقرأ المصنع الإعدادات الحالية ويُنشئ الـ driver المناسب:

// Factory creates the correct driver based on settings
let sms = SmsFactory::create(&settings).await?;
sms.send("+1234567890", "مرحباً من FORGE").await?;

// Switch providers by changing settings -- no code changes needed
let email = EmailFactory::create(&settings).await?;
email.send("user@example.com", "مرحباً", "أهلاً!").await?;

let storage = StorageFactory::create(&settings).await?;
storage.put("uploads/file.pdf", data).await?;

تحذير

تأكد من إعداد جميع الإعدادات المطلوبة للـ driver المُختار قبل استخدام المزود. بيانات الاعتماد المفقودة ستؤدي إلى خطأ أثناء التشغيل عندما يحاول المصنع إنشاء الـ driver.

إنشاء مزودين مخصصين

يدعم FORGE إنشاء تنفيذات مزودين خاصة بك. راجع المزودون المخصصون لدليل خطوة بخطوة حول تنفيذ وتسجيل driver مخصص.