NestJS — Node.js للمؤسسات

WebSockets والبوابات

16 دقيقة الدرس 35 من 48

WebSockets والبوابات

HTTP بروتوكول طلب/استجابة — يبدأ العميل دائمًا، وتُغلَق الاتصال بعد كل تبادل. تقلب WebSockets هذا النموذج: يتيح اتصال مستمر واحد لأيٍّ من الطرفين دفع الرسائل في أي وقت، ما يُمكّن ميزات الوقت الحقيقي كالدردشة، ولوحات المعلومات الحيّة، والإشعارات، والتحرير التعاوني.

يُغلّف NestJS مكتبات WebSocket (Socket.IO افتراضيًّا، أو محوّل ws الأصلي) خلف واجهة برمجية متسقة مدفوعة بالمزخرفات تُسمّى البوابات (Gateways). تبدو البوابة وتتصرف تمامًا كوحدة التحكم — تُزخرِف صنفًا، وتُعلّق الدوال المعالجة، وتحقن الخدمات — لذا تنتقل أنماط NestJS القائمة مباشرةً.

الإعداد

npm install @nestjs/websockets @nestjs/platform-socket.io socket.io

اختيار المحوّل. يستخدم @nestjs/platform-socket.io مكتبة Socket.IO (مع الغرف والنطاقات وإعادة الاتصال التلقائي). للحصول على بنية أخف دون هذه الميزات، يمكنك التبديل إلى @nestjs/platform-ws الذي يستخدم حزمة ws الأصلية؛ وتعمل مزخرفات البوابة مع كليهما.

إنشاء بوابة

البوابة صنف مُزخرَف بـ @WebSocketGateway(). يمكن تمرير منفذ وخيارات CORS بشكل اختياري. استخدم @WebSocketServer() لحقن نسخة الخادم الأساسي، و@SubscribeMessage() للتعامل مع الأحداث المُسمّاة من العملاء:

import {
  WebSocketGateway,
  WebSocketServer,
  SubscribeMessage,
  MessageBody,
  ConnectedSocket,
  OnGatewayConnection,
  OnGatewayDisconnect,
} from '@nestjs/websockets';
import { Server, Socket } from 'socket.io';

@WebSocketGateway({ cors: { origin: '*' } })
export class ChatGateway implements OnGatewayConnection, OnGatewayDisconnect {
  @WebSocketServer()
  server: Server;

  handleConnection(client: Socket) {
    console.log(`Client connected: ${client.id}`);
  }

  handleDisconnect(client: Socket) {
    console.log(`Client disconnected: ${client.id}`);
  }

  @SubscribeMessage('message')
  handleMessage(
    @MessageBody() data: string,
    @ConnectedSocket() client: Socket,
  ): void {
    // بث الرسالة إلى كل عميل متصل
    this.server.emit('message', { from: client.id, text: data });
  }
}

@WebSocketGateway() — يُعلّم الصنف معالجًا لـ WebSocket. بدون وسائط يرتبط بالمنفذ ذاته لخادم HTTP.
@WebSocketServer() — يحقن نسخة Server لتتمكن من إرسال الأحداث عالميًّا.
@SubscribeMessage('event') — يُعيّن أسماء أحداث Socket.IO الواردة على دوال المعالج.
@MessageBody() — يستخرج الحمولة من الحدث الوارد (مكافئ @Body() في HTTP).
@ConnectedSocket() — يحقن مقبس العميل الفردي.

الغرف والبث الموجّه

تتيح غرف Socket.IO تجميع المقابس وإرسال الرسائل فقط إلى أعضاء مجموعة محددة — مثالي لدردشة القنوات، وصالات الألعاب، أو التعاون على مستوى المستند:

@SubscribeMessage('joinRoom')
handleJoin(
  @MessageBody() room: string,
  @ConnectedSocket() client: Socket,
): void {
  client.join(room);
  // إخطار الجميع في الغرفة
  this.server.to(room).emit('userJoined', { id: client.id, room });
}

@SubscribeMessage('roomMessage')
handleRoomMessage(
  @MessageBody() payload: { room: string; text: string },
  @ConnectedSocket() client: Socket,
): void {
  // الإرسال فقط إلى المقابس في الغرفة المستهدفة
  this.server.to(payload.room).emit('roomMessage', {
    from: client.id,
    text: payload.text,
  });
}

أرسل إلى المُرسِل فقط بـ client.emit(). أرسل إلى الجميع ما عدا المُرسِل بـ client.broadcast.emit(). أرسل إلى غرفة محددة بـ this.server.to(room).emit(). معرفة أي نوع تستخدم يتجنب تكرار الرسائل.

النطاقات (Namespaces)

توفر النطاقات فصلًا منطقيًّا للقنوات على مستوى الاتصال — مفيدة حين يستضيف خادم واحد ميزات وقت حقيقي غير مترابطة (مثلًا، /chat و/notifications). حدّد النطاق في المزخرف:

@WebSocketGateway({ namespace: '/chat', cors: { origin: '*' } })
export class ChatGateway { /* ... */ }

@WebSocketGateway({ namespace: '/notifications', cors: { origin: '*' } })
export class NotificationGateway { /* ... */ }

تسجيل البوابة

البوابات موفّرون عاديون — صرّح بهم في مصفوفة providers الخاصة بالوحدة تمامًا كالخدمات:

@Module({
  providers: [ChatGateway, ChatService],
})
export class ChatModule {}

CORS في الإنتاج. يستخدم المثال أعلاه origin: '*' للتطوير. في الإنتاج، قيّد المصدر بنطاق الواجهة الأمامية لديك لمنع اتصالات WebSocket غير المصرّح بها.

الخلاصة

تجلب بوابات NestJS الأسلوب المدفوع بالمزخرفات والقابل لحقن التبعيات ذاته إلى WebSockets. تُعلن @WebSocketGateway() صنف المعالج، وتُوجّه @SubscribeMessage() الأحداث المُسمّاة إلى الدوال، ويكشف @WebSocketServer() عن نسخة Socket.IO Server الأساسية للإرسال العام أو الموجّه، وتتيح غرف Socket.IO البث الدقيق لمجموعات فرعية من العملاء المتصلين. تتيح النطاقات تشغيل قنوات منطقية متعددة على خادم واحد. ولأن البوابات موفّرون، فأنت تحقن الخدمات فيها تمامًا كما تفعل في وحدة التحكم.