NestJS Enterprise Backend APIs · Урок

Шлюзы WebSocket с адаптером Socket.IO

Реализуйте обработчики @WebSocketGateway, комнаты и хуки жизненного цикла для обмена данными в реальном времени

Урок 1 из 413 шагов

«Шлюзы WebSocket с адаптером Socket.IO» — бесплатный урок NestJS Enterprise Backend APIs на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения NestJS Enterprise Backend APIs, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс NestJS Enterprise Backend APIs содержит 4 уроков всего.

Части этого урока еще не переведены и отображаются на английском.

Why Gateways Exist

REST handles request/response, but real-time features (chat, presence, live dashboards) need a persistent, bidirectional channel. NestJS wraps this with a WebSocket Gateway.

A gateway is a provider decorated with @WebSocketGateway().
By default Nest uses the Socket.IO platform adapter (@nestjs/platform-socket.io).
Gateways are normal Nest classes: they support dependency injection, guards, pipes, and interceptors just like controllers.

Install the deps with npm i @nestjs/websockets @nestjs/platform-socket.io socket.io.

Declaring a Gateway

Decorate a class with @WebSocketGateway() and register it as a provider in a module. You can pass a port and options such as namespace and CORS config.

@SubscribeMessage('event') binds a handler to an inbound Socket.IO event.
The return value (or a WsResponse) is emitted back to the calling client.

Below, clients sending ping receive a pong reply.

import { WebSocketGateway, SubscribeMessage, MessageBody } from '@nestjs/websockets';

@WebSocketGateway({ namespace: '/chat', cors: { origin: '*' } })
export class ChatGateway {
  @SubscribeMessage('ping')
  handlePing(@MessageBody() data: string): { event: string; data: string } {
    return { event: 'pong', data: `received: ${data}` };
  }
}

Accessing the Server Instance

To broadcast to many clients you need the underlying Socket.IO Server. Inject it with the @WebSocketServer() property decorator.

server.emit('event', payload) sends to every connected client in the namespace.
This is the foundation for fan-out features like global announcements.

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

@WebSocketGateway({ namespace: '/chat' })
export class ChatGateway {
  @WebSocketServer()
  server: Server;

  @SubscribeMessage('broadcast')
  handleBroadcast(@MessageBody() message: string): void {
    this.server.emit('announcement', message);
  }
}

The Connected Socket

Each client has its own Socket. Inject it per-handler with @ConnectedSocket() to read auth data, the socket id, or to reply only to that client.

client.emit(...) targets just the sender.
client.id uniquely identifies the connection.
client.handshake exposes headers, query, and auth handed in at connect time.

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

@WebSocketGateway({ namespace: '/chat' })
export class ChatGateway {
  @SubscribeMessage('whoami')
  whoAmI(@ConnectedSocket() client: Socket, @MessageBody() _: unknown): void {
    client.emit('identity', { id: client.id, token: client.handshake.auth?.token });
  }
}

Lifecycle Hooks

Gateways can implement lifecycle interfaces to react to connection events:

OnGatewayInit → afterInit(server) runs once the server is ready.
OnGatewayConnection → handleConnection(client) fires per new client.
OnGatewayDisconnect → handleDisconnect(client) fires when a client leaves.

Use these for presence tracking, auth on connect, and cleanup.

import { WebSocketGateway, OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect } from '@nestjs/websockets';
import { Server, Socket } from 'socket.io';
import { Logger } from '@nestjs/common';

@WebSocketGateway({ namespace: '/chat' })
export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect {
  private readonly logger = new Logger(ChatGateway.name);

  afterInit(server: Server): void {
    this.logger.log('Gateway initialized');
  }

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

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

Rooms: Grouping Sockets

A room is a server-side label you attach to sockets so you can broadcast to a subset. A socket can belong to many rooms.

client.join('room') adds the socket to a room.
client.leave('room') removes it.
Socket.IO automatically puts each socket in a room named after its own client.id.

Rooms are how you build per-channel chat, per-tenant dashboards, or per-document collaboration.

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

@WebSocketGateway({ namespace: '/chat' })
export class ChatGateway {
  @SubscribeMessage('joinRoom')
  joinRoom(@ConnectedSocket() client: Socket, @MessageBody() room: string): void {
    client.join(room);
    client.emit('joined', room);
  }
}

Broadcasting to a Room

Target a room with server.to('room').emit(...). To exclude the sender, emit from the client socket: client.to('room').emit(...) sends to everyone in the room except that client.

server.to(room).emit(...) → everyone in the room.
client.to(room).emit(...) → everyone in the room but the sender.

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

@WebSocketGateway({ namespace: '/chat' })
export class ChatGateway {
  @WebSocketServer() server: Server;

  @SubscribeMessage('sendToRoom')
  sendToRoom(
    @ConnectedSocket() client: Socket,
    @MessageBody() body: { room: string; text: string },
  ): void {
    client.to(body.room).emit('message', { from: client.id, text: body.text });
  }
}

Acknowledgements with WsResponse

Socket.IO supports request/response style acknowledgements. In Nest you can return a value, a WsResponse<T> object, or even an Observable that streams multiple emissions back.

Return { event, data } to emit a named event back to the caller.
Returning an Observable emits one message per value, useful for progress updates.

import { WebSocketGateway, SubscribeMessage, MessageBody, WsResponse } from '@nestjs/websockets';
import { from, Observable } from 'rxjs';
import { map } from 'rxjs/operators';

@WebSocketGateway({ namespace: '/jobs' })
export class JobsGateway {
  @SubscribeMessage('countdown')
  countdown(@MessageBody() n: number): Observable<WsResponse<number>> {
    const ticks = Array.from({ length: n }, (_, i) => n - i);
    return from(ticks).pipe(map((value) => ({ event: 'tick', data: value })));
  }
}

Validation with Pipes

Gateways reuse Nest's ValidationPipe, but errors are thrown as WsException rather than HTTP exceptions. Apply the pipe at the handler or gateway level and validate a DTO via @MessageBody().

Set transform: true so plain payloads become class instances.
A WsException is serialized to an exception event on the client.

import { WebSocketGateway, SubscribeMessage, MessageBody } from '@nestjs/websockets';
import { UsePipes, ValidationPipe } from '@nestjs/common';
import { IsString, MinLength } from 'class-validator';

class SendMessageDto {
  @IsString() @MinLength(1)
  text: string;
}

@WebSocketGateway({ namespace: '/chat' })
export class ChatGateway {
  @UsePipes(new ValidationPipe({ transform: true }))
  @SubscribeMessage('send')
  send(@MessageBody() dto: SendMessageDto): { event: string; data: string } {
    return { event: 'sent', data: dto.text };
  }
}

Authenticating on Connect

Authenticate clients during handleConnection by reading the token from the handshake and disconnecting unauthorized sockets early. Storing the user on client.data makes it available to every later handler.

Token usually arrives via handshake.auth.token or an Authorization header.
Call client.disconnect() to reject bad clients before they join rooms.

import { WebSocketGateway, OnGatewayConnection } from '@nestjs/websockets';
import { Socket } from 'socket.io';
import { JwtService } from '@nestjs/jwt';

@WebSocketGateway({ namespace: '/chat' })
export class ChatGateway implements OnGatewayConnection {
  constructor(private readonly jwt: JwtService) {}

  async handleConnection(client: Socket): Promise<void> {
    try {
      const token = client.handshake.auth?.token as string;
      client.data.user = await this.jwt.verifyAsync(token);
    } catch {
      client.emit('error', 'Unauthorized');
      client.disconnect();
    }
  }
}

Swapping the Adapter for Scale

Out of the box, Socket.IO state lives in a single process. To run multiple Nest instances behind a load balancer you must share room/emit state. Use a custom adapter with the Redis adapter so broadcasts reach clients on other nodes.

Subclass IoAdapter and attach @socket.io/redis-adapter in createIOServer.
Register it via app.useWebSocketAdapter(new RedisIoAdapter(app)) in main.ts.

import { IoAdapter } from '@nestjs/platform-socket.io';
import { ServerOptions } from 'socket.io';
import { createAdapter } from '@socket.io/redis-adapter';
import { createClient } from 'redis';

export class RedisIoAdapter extends IoAdapter {
  private adapterConstructor: ReturnType<typeof createAdapter>;

  async connectToRedis(): Promise<void> {
    const pub = createClient({ url: 'redis://localhost:6379' });
    const sub = pub.duplicate();
    await Promise.all([pub.connect(), sub.connect()]);
    this.adapterConstructor = createAdapter(pub, sub);
  }

  createIOServer(port: number, options?: ServerOptions): any {
    const server = super.createIOServer(port, options);
    server.adapter(this.adapterConstructor);
    return server;
  }
}

Quick Check

Test your understanding of room broadcasting semantics.

Ответь в интерактивном уроке

Recap

You built a real-time layer with NestJS WebSocket gateways on the Socket.IO adapter:

Gateway basics: @WebSocketGateway() providers with @SubscribeMessage handlers; inject the server via @WebSocketServer() and the per-client socket via @ConnectedSocket().
Lifecycle hooks: afterInit, handleConnection, and handleDisconnect for init, presence, and cleanup.
Rooms: client.join/leave, then server.to(room) for everyone or client.to(room) to exclude the sender.
Robustness: validate payloads with ValidationPipe (errors become WsException), authenticate in handleConnection, and use acknowledgements/Observables for replies.
Scale: swap in a Redis-backed IoAdapter so broadcasts work across multiple instances.

Можно начать бесплатно

Изучай TypeScript с ИИ-репетитором — бесплатно

Пиши и запускай код прямо в браузере, получай мгновенную помощь от ИИ-репетитора 24/7 и продолжи учиться на сайте или в приложении.

Курсы: 20
Уроки: 76

Начать учиться бесплатно Посмотреть полный курс

Часто задаваемые вопросы

Урок «Шлюзы WebSocket с адаптером Socket.IO» бесплатный?

Да — полный текст урока «Шлюзы WebSocket с адаптером Socket.IO» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс NestJS Enterprise Backend APIs, подпишись на CoddyKit PRO. Курс NestJS Enterprise Backend APIs содержит 4 уроков всего.

Чему я научусь в уроке «Шлюзы WebSocket с адаптером Socket.IO»?

Реализуйте обработчики @WebSocketGateway, комнаты и хуки жизненного цикла для обмена данными в реальном времени Ты практикуешь NestJS Enterprise Backend APIs с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать NestJS Enterprise Backend APIs?

Предыдущий опыт не требуется. NestJS Enterprise Backend APIs на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «Шлюзы WebSocket с адаптером Socket.IO»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке NestJS Enterprise Backend APIs?

Да. Каждый урок NestJS Enterprise Backend APIs включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

Шлюзы WebSocket с адаптером Socket.IO
Аутентификация и защита Socket-соединений
События, отправляемые сервером, для односторонней передачи
Масштабирование обмена данными в реальном времени с Redis Pub/Sub

← Назад к NestJS Enterprise Backend APIs