WebSocket gateway로 실시간 기능은 어떻게 구축하나요?

Question

Accepted Answer

NestJS는 **WebSocket gateway**를 통해 **실시간, 양방향 통신**을 지원합니다 — `@WebSocketGateway()`로 데코레이트된 클래스로 WebSocket 연결과 메시지를 처리합니다(보통 Socket.IO 위에서). 채팅, 실시간 알림, 실시간 대시보드 같은 기능을 가능하게 하며, 동일한 NestJS 구조(DI, decorator)를 사용합니다.

## gateway 정의하기

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

@WebSocketGateway({ cors: true })
export class ChatGateway {
  @WebSocketServer()
  server: Server;                        // Socket.IO 서버 인스턴스

// 클라이언트의 'message' 이벤트 처리
  @SubscribeMessage("message")
  handleMessage(@MessageBody() data: { text: string }) {
    // 연결된 모든 클라이언트에 브로드캐스트
    this.server.emit("message", data);   // 모두가 메시지를 받음
  }
}
```

gateway는 들어오는 이벤트를 처리하기 위해 `@SubscribeMessage("event")`(HTTP의 `@Post`와 유사)를 사용하고, 주입된 `server`를 통해 클라이언트에 이벤트를 **emit**합니다 — `server.emit`은 모두에게 브로드캐스트합니다.

## 연결 생명주기 hook

```ts
export class ChatGateway implements OnGatewayConnection, OnGatewayDisconnect {
  handleConnection(client: Socket) {
    console.log(`Client connected: ${client.id}`);   // 사용자 참여
  }
  handleDisconnect(client: Socket) {
    console.log(`Client disconnected: ${client.id}`); // 사용자 떠남 — 정리
  }
}
```

gateway는 클라이언트가 연결되고 연결 해제되는 것에 반응할 수 있습니다 — 접속 상태 추적과 정리에 유용합니다.

## 특정 클라이언트와 room 대상 지정

```ts
@SubscribeMessage("joinRoom")
handleJoin(@ConnectedSocket() client: Socket, @MessageBody() room: string) {
  client.join(room);                              // 클라이언트를 room에 추가
}

@SubscribeMessage("roomMessage")
sendToRoom(@MessageBody() data: { room: string; text: string }) {
  this.server.to(data.room).emit("message", data.text);   // 그 room에만 emit
  // client.emit(...) → 그 클라이언트만; server.emit(...) → 모두
}
```

**Room**은 클라이언트를 그룹화하여(예: 채팅방, 문서의 협업자) 모두가 아닌 특정 부분 집합에 브로드캐스트하게 합니다 — 범위가 지정된 실시간 기능에 필수적입니다.

## gateway는 NestJS 기능을 재사용합니다

```text
gateway는 provider입니다 → dependency injection을 지원하고(service 주입),
HTTP controller처럼 guard, pipe, interceptor, filter를 사용할 수 있습니다.
→ REST와 동일한 구조/패턴이 실시간에도 적용됩니다.
```

## WebSocket 확장

```text
⚠️ WebSocket 연결은 STATEFUL이며 하나의 서버 인스턴스에 존재합니다.
여러 인스턴스에 걸쳐 확장하려면 Redis 어댑터(socket.io-redis)를 사용하여
브로드캐스트/room이 모든 인스턴스에서 작동하게 하세요. (session처럼, 수평
확장 시 한 프로세스의 메모리에 상태를 두지 마세요.)
```

## 왜 중요한가

WebSocket gateway는 NestJS가 **실시간, 양방향 기능**을 지원하는 방법입니다 — 채팅, 실시간 알림, 접속 상태, 협업 편집, 실시간 대시보드, 멀티플레이어 상호작용 — REST의 요청-응답 모델이 제공할 수 없는 것입니다(서버가 요청에 응답만 하는 것이 아니라 클라이언트에 푸시할 수 있음).

이를 이해하는 것은 현대적인 대화형 애플리케이션을 구축하는 데 가치 있는 시니어 수준 지식입니다.

핵심 강점은 gateway가 NestJS의 친숙한 구조에 맞는다는 것입니다: gateway는 **dependency injection**을 지원하는 provider이며 HTTP controller처럼 **guard, pipe, interceptor, filter**를 사용할 수 있으므로, 동일한 패턴과 코드 구성이 REST에서처럼 실시간에도 적용됩니다.

이벤트를 처리하고(`@SubscribeMessage`), 클라이언트에 브로드캐스트하고(`server.emit`), **room**을 사용하여 관련 부분 집합(채팅방, 문서 협업자)으로 브로드캐스트 범위를 지정하고, 연결 생명주기(접속 상태, 정리)를 관리하는 방법을 아는 것이 실무적인 실시간 도구 세트를 다룹니다.

결정적으로 중요한 것은 **확장 고려사항**입니다: WebSocket 연결은 stateful이고 단일 서버 인스턴스에 묶여 있으므로, 수평 확장하려면 인스턴스 전반에 걸쳐 브로드캐스트/room을 조정하기 위한 **Redis 어댑터**가 필요합니다(흔한 함정 — session처럼, 여러 인스턴스를 실행할 때 실시간 상태는 한 프로세스의 메모리에 있을 수 없습니다).

이는 현대 사용자가 기대하는 실시간, 대화형 경험을 구축하는 중요하고 점점 더 관련되는 능력이며, NestJS의 깔끔한 통합은 프레임워크의 구조를 재사용하면서 이를 접근 가능하게 만듭니다.