Как создавать функции реального времени с WebSocket шлюзами?

Question

Accepted Answer

NestJS поддерживает **двусторонний обмен данными в реальном времени** через **WebSocket шлюзы** — классы, оформленные декоратором `@WebSocketGateway()`, которые обрабатывают WebSocket соединения и сообщения (обычно через Socket.IO). Они позволяют реализовать функции вроде чатов, живых уведомлений и интерактивных панелей управления, используя ту же структуру NestJS (DI, декораторы).

## Определение шлюза

```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.
```

## Масштабирование WebSocket

```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 не может обеспечить (сервер может отправлять клиентам, а не только отвечать на запросы).

Понимание шлюзов — ценное знание уровня senior для создания современных интерактивных приложений.

Основная сильная сторона в том, что шлюзы соответствуют привычной структуре NestJS: они являются поставщиками с поддержкой **dependency injection** и могут использовать **guards, pipes, interceptors и filters** точно как HTTP контроллеры, так что те же паттерны и организация кода применяются к реальному времени как к REST.

Знание того, как обрабатывать события (`@SubscribeMessage`), транслировать клиентам (`server.emit`), использовать **комнаты** для ограничения трансляций релевантными подмножествами (комнаты чата, сотрудники документа) и управлять жизненным циклом соединения (присутствие, очистка) — это практический набор инструментов для реального времени.

Критически важно учитывать **аспект масштабирования**: WebSocket соединения являются stateful и привязаны к одному экземпляру сервера, поэтому горизонтальное масштабирование требует **Redis адаптера** для координации трансляций и комнат между экземплярами (частая ошибка — как и сессии, состояние реального времени не может находиться в памяти одного процесса при запуске нескольких экземпляров).

Это важная и всё более релевантная возможность для создания интерактивного опыта реального времени, который ожидают современные пользователи, и чистая интеграция NestJS делает это доступным, переиспользуя структуру фреймворка.