كيف تبني ميزات في الوقت الفعلي باستخدام بوابات WebSocket؟

Question

Accepted Answer

يدعم NestJS **الاتصال ثنائي الاتجاه في الوقت الفعلي** عبر **بوابات WebSocket** — فئات مزينة بـ `@WebSocketGateway()` تتعامل مع اتصالات WebSocket والرسائل (عادة عبر Socket.IO). تمكّن ميزات مثل الدردشة والإشعارات المباشرة ولوحات المعلومات المباشرة، باستخدام نفس بنية NestJS (الحقن التبعي، المزخرفات).

## تحديد البوابة

```ts
import { WebSocketGateway, SubscribeMessage, MessageBody, WebSocketServer } from "@nestjs/websockets";
import { Server } from "socket.io";

@WebSocketGateway({ cors: true })
export class ChatGateway {
  @WebSocketServer()
  server: Server;                        // the Socket.IO server instance

// handle a 'message' event from a client
  @SubscribeMessage("message")
  handleMessage(@MessageBody() data: { text: string }) {
    // BROADCAST to all connected clients
    this.server.emit("message", data);   // everyone receives the message
  }
}
```

تستخدم البوابة `@SubscribeMessage("event")` للتعامل مع الأحداث الواردة (مشابهة لـ `@Post` للـ HTTP) والـ `server` المحقونة لـ **إصدار** الأحداث مرة أخرى للعملاء — `server.emit` يبث إلى الجميع.

## خطافات دورة حياة الاتصال

```ts
export class ChatGateway implements OnGatewayConnection, OnGatewayDisconnect {
  handleConnection(client: Socket) {
    console.log(`Client connected: ${client.id}`);   // a user joined
  }
  handleDisconnect(client: Socket) {
    console.log(`Client disconnected: ${client.id}`); // a user left — clean up
  }
}
```

يمكن للبوابات الاستجابة لاتصال العملاء وقطع الاتصال — مفيد لتتبع الحضور والتنظيف.

## استهداف عملاء وغرف محددة

```ts
@SubscribeMessage("joinRoom")
handleJoin(@ConnectedSocket() client: Socket, @MessageBody() room: string) {
  client.join(room);                              // add the client to a room
}

@SubscribeMessage("roomMessage")
sendToRoom(@MessageBody() data: { room: string; text: string }) {
  this.server.to(data.room).emit("message", data.text);   // emit only to that room
  // client.emit(...) → just that client; server.emit(...) → everyone
}
```

**الغرف** تجميع العملاء (مثل غرفة دردشة، متعاونو المستند)، مما يسمح لك بالبث إلى مجموعات فرعية محددة بدلاً من الجميع — ضروري للميزات في الوقت الفعلي ذات النطاق المحدد.

## تعيد البوابات استخدام ميزات NestJS

```text
Gateways are providers → they support dependency injection (inject services),
and can use guards, pipes, interceptors, and filters — just like HTTP controllers.
→ The same structure/patterns apply to real-time as to REST.
```

## توسيع نطاق WebSockets

```text
⚠️ WebSocket connections are STATEFUL and live on ONE server instance.
To scale across multiple instances, use a Redis adapter (socket.io-redis) so
broadcasts/rooms work across all instances. (Like sessions, don't keep state in
one process's memory when scaling horizontally.)
```

## لماذا يهم

بوابات WebSocket هي كيفية دعم NestJS **لميزات ثنائية الاتجاه في الوقت الفعلي** — الدردشة والإشعارات المباشرة والحضور والتحرير التعاوني ولوحات المعلومات المباشرة والتفاعلات متعددة اللاعبين — التي لا يمكن لنموذج الطلب والاستجابة في REST توفيرها (يمكن للخادم الدفع إلى العملاء وليس فقط الاستجابة للطلبات).

فهمها معرفة قيّمة على مستوى كبير لبناء تطبيقات تفاعلية حديثة.

تكمن القوة الرئيسية في أن البوابات تناسب بنية NestJS المألوفة: فهي موفرات تدعم **الحقن التبعي** ويمكنها استخدام **الحراس والأنابيب والمعترضات والمرشحات** تماماً مثل متحكمات HTTP، لذلك تنطبق نفس الأنماط وتنظيم الكود على الوقت الفعلي كما على REST.

معرفة كيفية التعامل مع الأحداث (`@SubscribeMessage`)، والبث إلى العملاء (`server.emit`)، واستخدام **الغرف** لتحديد نطاق البث إلى مجموعات فرعية ذات صلة (غرف الدردشة، متعاونو المستند)، وإدارة دورة حياة الاتصال (الحضور والتنظيف) يغطي مجموعة أدوات الوقت الفعلي العملية.

مهم بشكل حاسم هو **اعتبار التوسع**: اتصالات WebSocket تابعة للحالة ومرتبطة بمثيل خادم واحد، لذا فإن التوسع الأفقي يتطلب **محول Redis** لتنسيق البث والغرف عبر المثيلات (فخ شائع — مثل الجلسات، لا يمكن أن تعيش حالة الوقت الفعلي في ذاكرة عملية واحدة عند تشغيل مثيلات متعددة).

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