如何使用 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")` 处理传入的事件（类似于 HTTP 中的 `@Post`），并使用注入的 `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 的请求-响应模型无法提供的（服务器可以主动推送给客户端，而不仅仅是响应请求）。

了解它们对于高级开发者来说是宝贵的知识，用于构建现代交互式应用程序。

关键优势在于网关适应 NestJS 的熟悉结构：它们是支持**依赖注入**的提供者，可以使用**守卫、管道、拦截器和过滤器**，就像 HTTP 控制器一样，因此相同的模式和代码组织既适用于实时也适用于 REST。

了解如何处理事件（`@SubscribeMessage`）、广播给客户端（`server.emit`）、使用**房间**将广播限制在相关子集（聊天室、文档协作者），以及管理连接生命周期（在线状态、清理）涵盖了实时工具的实际应用。

至关重要的是**扩展考虑**：WebSocket 连接是有状态的并绑定到单个服务器实例，因此水平扩展需要 **Redis 适配器**来协调实例间的广播/房间（一个常见的陷阱 — 像会话一样，实时状态无法在运行多个实例时存储在单个进程的内存中）。

这是一项重要且日益相关的能力，用于构建现代用户期望的实时、交互式体验，而 NestJS 的简洁集成使其易于访问，同时重用了框架的结构。