Bagaimana anda membina ciri masa nyata dengan WebSocket gateway?

Question

Accepted Answer

NestJS menyokong **komunikasi dua hala masa nyata** melalui **WebSocket gateway** — kelas yang didekorasi dengan `@WebSocketGateway()` yang mengendalikan sambungan dan mesej WebSocket (biasanya melalui Socket.IO). Ia membolehkan ciri seperti sembang, notifikasi langsung, dan papan pemuka langsung, menggunakan struktur NestJS yang sama (DI, decorator).

## Mentakrifkan gateway

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

Gateway menggunakan `@SubscribeMessage("event")` untuk mengendalikan event masuk (seakan `@Post` untuk HTTP) dan `server` yang disuntik untuk **emit** event kembali kepada klien — `server.emit` menyiarkan kepada semua orang.

## Hook kitaran hayat sambungan

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

Gateway boleh bertindak balas terhadap klien yang menyambung dan memutuskan sambungan — berguna untuk penjejakan kehadiran dan pembersihan.

## Menyasarkan klien dan room tertentu

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

**Room** mengumpulkan klien (cth. sebuah ruang sembang, kolaborator sesuatu dokumen), membolehkan anda menyiarkan kepada subset tertentu dan bukannya semua orang — penting untuk ciri masa nyata berskop.

## Gateway menggunakan semula ciri 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.
```

## Menskala 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.)
```

## Mengapa ia penting

WebSocket gateway ialah cara NestJS menyokong **ciri dua hala masa nyata** — sembang, notifikasi langsung, kehadiran, penyuntingan kolaboratif, papan pemuka langsung, interaksi berbilang pemain — yang model request-response REST tidak dapat sediakan (pelayan boleh menolak ke klien, bukan sekadar membalas permintaan).

Memahaminya ialah pengetahuan peringkat senior yang berharga untuk membina aplikasi interaktif moden.

Kekuatan utama ialah gateway muat dengan struktur biasa NestJS: ia adalah provider yang menyokong **dependency injection** dan boleh menggunakan **guard, pipe, interceptor, dan filter** sama seperti controller HTTP, jadi corak dan organisasi kod yang sama terpakai pada masa nyata seperti pada REST.

Mengetahui cara mengendalikan event (`@SubscribeMessage`), menyiarkan kepada klien (`server.emit`), menggunakan **room** untuk menskopkan siaran kepada subset yang relevan (ruang sembang, kolaborator dokumen), dan menguruskan kitaran hayat sambungan (kehadiran, pembersihan) meliputi toolkit masa nyata yang praktikal.

Yang sangat penting ialah **pertimbangan penskalaan**: sambungan WebSocket bersifat stateful dan terikat pada satu instance pelayan, jadi menskala secara mendatar memerlukan **adapter Redis** untuk menyelaraskan siaran/room merentas instance (satu perangkap biasa — seperti sesi, keadaan masa nyata tidak boleh berada dalam memori satu proses apabila menjalankan berbilang instance).

Ini ialah keupayaan yang penting dan semakin relevan untuk membina pengalaman masa nyata dan interaktif yang dijangkakan oleh pengguna moden, dan integrasi NestJS yang kemas menjadikannya mudah diakses sambil menggunakan semula struktur rangka kerja itu.