انتقل إلى المحتوى الرئيسي

المقدمة

🎯 ماذا يفعل هذا الموديل؟​

يتيح لك موديل WS (WebSocket) استقبال إشعارات في الوقت الحقيقي - تحديثات المحتوى، تغييرات الطلبات، إجراءات المستخدمين - من خلال إنشاء اتصالات دائمة للحصول على تحديثات فورية دون الحاجة للاستعلام المتكرر، مما يمكّن من ميزات حية مثل الإشعارات، الدردشة الحية، ولوحات المعلومات في الوقت الحقيقي.

فكر في الأمر كنظام إشعارات في الوقت الحقيقي - بدلاً من السؤال المتكرر "هل هناك شيء جديد؟" (الاستعلام المتكرر)، يبقي WebSocket الاتصال مفتوحًا ويدفع الخادم التحديثات إليك على الفور عند حدوث الأحداث.

📖 شرح بسيط​

تحتاج كل تطبيق حديث إلى تحديثات في الوقت الحقيقي:

  • 🔔 إشعارات حية - تنبيهات فورية عند حدوث شيء ما
  • 💬 دردشة حية - رسائل في الوقت الحقيقي بين المستخدمين
  • 📊 لوحات معلومات حية - إحصائيات ومقاييس تتحدث تلقائيًا
  • 🛒 تحديثات الطلبات - تغييرات فورية في حالة الطلب
  • 📝 تحديثات المحتوى - تغييرات ونشر محتوى حي
  • 👥 نشاط المستخدم - وجود وإجراءات المستخدم في الوقت الحقيقي
  • 🔄 مزامنة البيانات - مزامنة تلقائية عبر الأجهزة

المشكلة مع الاستعلام المتكرر (الطلبات المتكررة):

// ❌ سيء - الاستعلام كل 5 ثوانٍ
setInterval(async () => {
  const orders = await Orders.getOrders();
  // تحقق مما إذا كان هناك أي تغيير
  // يهدر عرض النطاق الترددي، يؤخر التحديثات، يحمّل الخادم
}, 5000);

المشكلات:

  • 🔋 استنزاف البطارية - الطلبات المستمرة تهدر الطاقة
  • 📡 هدر الشبكة - معظم الطلبات تعود "بدون تغييرات"
  • ⏱️ تأخير التحديثات - تأخير يصل إلى 5 ثوانٍ
  • 🖥️ حمولة الخادم - طلبات غير ضرورية كل بضع ثوانٍ

حل WebSocket:

// ✅ جيد - اتصال WebSocket في الوقت الحقيقي
const { WS } = defineOneEntry('https://your-site.oneentry.cloud', {
  token: 'your-app-token'
});

// الاشتراك في الأحداث
WS.subscribe('order.created', (order) => {
  console.log('تم استلام طلب جديد!', order);
  // إشعار فوري، لا استعلام!
});

WS.subscribe('content.updated', (content) => {
  console.log('تم تحديث المحتوى!', content);
  // تحديث واجهة المستخدم على الفور
});

الفوائد:

  • 🔋 فعال - اتصال دائم واحد
  • 📡 في الوقت الحقيقي - تحديثات فورية، بدون تأخير
  • ⏱️ زمن استجابة منخفض - تسليم الإشعارات في أقل من ثانية
  • 🖥️ حمولة مخفضة - يدفع الخادم فقط عند الحاجة

✨ المفاهيم الأساسية​

ما هو WebSocket؟​

WebSocket هو اتصال دائم ثنائي الاتجاه بين العميل والخادم:

  • اتصال دائم - يبقى مفتوحًا، بدون مصافحات متكررة
  • ثنائي الاتجاه - يمكن لكل من العميل والخادم إرسال الرسائل
  • في الوقت الحقيقي - تسليم الرسائل الفوري
  • معتمد على الأحداث - الاشتراك في أحداث محددة
  • فعال - تكلفة منخفضة مقارنة بالاستعلام عبر HTTP

WebSocket مقابل الاستعلام عبر HTTP​

الميزةWebSocketالاستعلام عبر HTTP
الاتصالدائم (يبقى مفتوحًا)اتصالات متكررة
الزمن المستغرقأقل من ثانيةيعتمد على الفاصل الزمني (2-30 ثانية)
الكفاءةفعالة جدًامهدرة (الكثير من الاستجابات الفارغة)
حمولة الخادممنخفضة (الأحداث فقط)عالية (طلبات مستمرة)
استخدام البطاريةمنخفضمرتفع (الأجهزة المحمولة)
حالة الاستخدامتحديثات في الوقت الحقيقيمقبولة للتحديثات غير الحرجة

دورة حياة اتصال WebSocket​

1. يتصل العميل بخادم WebSocket
   (WS.connect())
   ↓
2. تم إنشاء الاتصال
   (يتم تشغيل حدث onOpen)
   ↓
3. يشترك العميل في الأحداث
   (WS.subscribe('event.name', callback))
   ↓
4. يرسل الخادم الأحداث عند حدوثها
   (تسليم فوري)
   ↓
5. يتلقى العميل رسائل الأحداث
   (يتم تنفيذ دالة الاستدعاء)
   ↓
6. يبقى الاتصال مفتوحًا
   (لا حاجة لإعادة الاتصال)
   ↓
7. ينفصل العميل عند الانتهاء
   (WS.disconnect())

أحداث WebSocket الشائعة​

نوع الحدثالوصفحالة الاستخدام
order.createdتم تقديم طلب جديدعرض إشعار "طلب جديد!"
order.updatedتغيرت حالة الطلبتحديث حالة الطلب في واجهة المستخدم
content.publishedتم نشر محتوى جديدتحديث قائمة المحتوى
content.updatedتم تعديل المحتوىتحديث المحتوى المعروض
user.registeredتم تسجيل مستخدم جديدعرض مستخدم جديد في لوحة التحكم
payment.completedتم معالجة الدفعتحديث حالة الطلب إلى "مدفوع"
product.outOfStockالمنتج غير متوفرعرض شارة "غير متوفر"

لماذا تستخدم موديل WebSocket؟​

الفائدةالوصف
تحديثات في الوقت الحقيقيإشعارات فورية، بدون تأخير في الاستعلام
فعالاتصال واحد، تكلفة منخفضة
صديق للبطاريةلا استعلام مستمر على الأجهزة المحمولة
قابل للتوسعيدفع الخادم فقط عند الحاجة
مدفوع بالأحداثالاشتراك في أحداث محددة
ميزات حيةتمكين الدردشة، الإشعارات، لوحات المعلومات

🚀 مثال سريع​

📋 ما تحتاج إلى معرفته​

إدارة اتصال WebSocket​

تحتاج اتصالات WebSocket إلى إدارة دقيقة:

أفضل الممارسات:

  • تحقق من حالة الاتصال قبل الاشتراك
  • نفذ منطق إعادة الاتصال
  • تعامل مع أخطاء الاتصال بشكل جيد
  • افصل عند تسجيل خروج المستخدم

إدارة الاشتراك في الأحداث​

اشترك في الأحداث فقط بعد إنشاء الاتصال

أفضل الممارسات:

  • استخدم دوال استدعاء مسماة لتسهيل إلغاء الاشتراك
  • اشترك بعد فتح الاتصال
  • ألغ الاشتراك عند تفكيك المكون
  • لا تشترك في نفس الحدث عدة مرات

إلغاء الاشتراك في الأحداث​

دائمًا ألغ الاشتراك عند الانتهاء لمنع تسرب الذاكرة:

أفضل الممارسات:

  • ألغ الاشتراك في دوال التنظيف
  • افصل WebSocket عند عدم الحاجة
  • منع تسرب الذاكرة في تطبيقات الصفحة الواحدة

استراتيجية إعادة الاتصال​

نفذ إعادة الاتصال التلقائي مع زيادة زمن الانتظار:

أفضل الممارسات:

  • استخدم زيادة زمن الانتظار لإعادة الاتصال
  • حدد الحد الأقصى لمحاولات إعادة الاتصال
  • أعد تعيين العدادات عند الاتصال الناجح
  • اسمح بفصل يدوي دون إعادة الاتصال

هيكل حمولة الحدث​

تتبع حمولة الأحداث هيكلًا متسقًا:

أفضل الممارسات:

  • تحقق من هيكل حمولة الحدث
  • تعامل مع الحقول المفقودة بشكل جيد
  • تحقق من نوع الحمولة في TypeScript

معالجة الأخطاء​

نفذ معالجة شاملة للأخطاء:

أفضل الممارسات:

  • التقاط الأخطاء في معالجات الأحداث
  • سجل الأخطاء لأغراض التصحيح
  • عرض رسائل خطأ سهلة الفهم للمستخدم
  • لا تدع الأخطاء تتسبب في تعطل التطبيق

تحسين الأداء​

قم بتحسين أداء WebSocket:

أفضل الممارسات:

  • قم بتقليل تكرار الأحداث عالية التردد
  • اجمع تحديثات متعددة معًا
  • قم بتأخير تحديثات واجهة المستخدم
  • تجنب العمليات المكلفة في المعالجات

💡 ملاحظات مهمة​

⚠️ إدارة حالة الاتصال​

تحقق دائمًا من حالة الاتصال قبل الاشتراك

🔄 معالجة إعادة الاتصال​

يمكن أن تنقطع اتصالات WebSocket بشكل غير متوقع:

  • تغييرات الشبكة (من WiFi إلى بيانات الهاتف)
  • إعادة تشغيل الخادم
  • انتهاء المهلة بسبب عدم النشاط

دائمًا نفذ منطق إعادة الاتصال

🧹 منع تسرب الذاكرة​

ألغ الاشتراك عند الانتهاء لمنع تسرب الذاكرة

🔒 الأمان​

اتصالات WebSocket مصادق عليها:

  • مصادقة قائمة على الرموز (نفس مصادقة REST API)
  • بروتوكول WebSocket الآمن (WSS)
  • لا حاجة لإرسال الرمز مع كل رسالة

أفضل الممارسات:

  • استخدم WSS (WebSocket الآمن) في الإنتاج
  • لا تعرض بيانات حساسة في معالجات الأحداث
  • تحقق من حمولة الأحداث قبل المعالجة

📱 اعتبارات الهاتف المحمول​

WebSocket على الأجهزة المحمولة:

  • استخدام البطارية (فعال، ولكن اتصال دائم)
  • قد يتم إنهاء الاتصالات في الخلفية
  • تتطلب تغييرات الشبكة إعادة الاتصال

أفضل الممارسات:

  • أعد الاتصال عند عودة التطبيق إلى الواجهة
  • تعامل مع تغييرات حالة الشبكة
  • اعتبر الاستعلام للتحديثات غير الحرجة على الهاتف المحمول

📊 جدول مرجعي سريع​

الطريقةالوصفحالة الاستخدام
connect()الاتصال بخادم WebSocketإنشاء الاتصال

❓ الأسئلة الشائعة (FAQ)​

كيف يمكنني الاتصال بخادم WebSocket؟​

استخدم WS.connect() لإنشاء اتصال. انتظر حتى يفتح الاتصال (استمع لحدث onOpen) قبل الاشتراك في الأحداث. يتم مصادقة الاتصال باستخدام رمز التطبيق الخاص بك من defineOneEntry().

ما هي الأحداث التي يمكنني الاشتراك فيها؟​

اشترك في أحداث مثل order.created، order.updated، content.published، payment.completed، user.registered، إلخ. تعتمد الأحداث المتاحة على تكوين OneEntry الخاص بك وإعدادات موديل الأحداث في لوحة الإدارة.

كيف يمكنني التعامل مع انقطاع الاتصال؟​

نفذ إعادة الاتصال التلقائي مع زيادة زمن الانتظار. استمع لأحداث onClose و onError، ثم حاول إعادة الاتصال بعد تأخير (مثل 1 ثانية، 2 ثانية، 4 ثوانٍ، 8 ثوانٍ، حتى 30 ثانية كحد أقصى). أعد تعيين عداد التأخير عند الاتصال الناجح.

هل يجب أن أستخدم WebSocket أم الاستعلام لتطبيقي؟​

استخدم WebSocket للميزات في الوقت الحقيقي (الدردشة الحية، الإشعارات، لوحات المعلومات) حيث تكون التحديثات الفورية مهمة. استخدم الاستعلام للتحديثات غير الحرجة أو عندما تكون اتصالات WebSocket مشكلة (جدران نارية مقيدة، وضع الخلفية على الهاتف المحمول).

كيف يمكنني منع تسرب الذاكرة مع اشتراكات WebSocket؟​

دائمًا ألغ الاشتراك من الأحداث عند تفكيك المكونات أو عندما لم يعد الاتصال مطلوبًا. في React، استخدم دوال التنظيف في useEffect. في Vue، استخدم دالة دورة الحياة beforeUnmount.

هل يمكنني استخدام WebSocket على الأجهزة المحمولة؟​

نعم، ولكن كن على علم بأن أنظمة تشغيل الهواتف المحمولة قد تنهي اتصالات WebSocket في الخلفية. أعد الاتصال عند عودة التطبيق إلى الواجهة. اعتبر تأثير البطارية للاتصالات الدائمة على الأجهزة المحمولة.

🎓 أفضل الممارسات​

  • تحقق من حالة الاتصال - اشترك فقط بعد فتح الاتصال
  • نفذ إعادة الاتصال - إعادة الاتصال التلقائي عند الانفصال مع زيادة زمن الانتظار
  • ألغ الاشتراك عند التنظيف - منع تسرب الذاكرة في تطبيقات الصفحة الواحدة
  • تعامل مع الأخطاء بشكل جيد - التقاط الأخطاء في معالجات الأحداث
  • قلل من تكرار الأحداث عالية التردد - تجنب إغراق واجهة المستخدم بالتحديثات
  • تحقق من حمولة الأحداث - تحقق من هيكل البيانات قبل المعالجة
  • استخدم استدعاءات مسماة - أسهل في إلغاء الاشتراك والتصحيح
  • سجل حالة الاتصال - تتبع أحداث الفتح/الإغلاق/الخطأ لأغراض التصحيح

مزيد من المعلومات حول واجهة مستخدم الموديل https://doc.oneentry.cloud/docs/events/introduction

تعريف موديل WS​

يمكنك الاشتراك في الأحداث عبر WebSocket لاستقبال الإشعارات


const { WS } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 الوثائق ذات الصلة​