🪵 6. 웹소켓 클라이언트 코드 분석 및 공유

개요

웹소켓 클라이언트 구현을 분석하고 공유하기 위한 문서입니다. 실시간 멀티플레이어 게임을 위한 안정적이고 확장 가능한 웹소켓 아키텍처를 아래와 같이 구성했습니다.

├── stores/socket/          # 소켓 관련 전역 상태 관리
│   ├── socket.config.ts    # 소켓 설정 및 타입
│   ├── socket.store.ts     # 전역 소켓 관리 store
│   ├── gameSocket.store.ts # 게임 상태 관리
│   └── chatSocket.store.ts # 채팅 상태 관리
│
├── hooks/socket/           # 소켓 관련 커스텀 훅
│   ├── useGameSocket.ts    # 게임 소켓 훅
│   ├── useDrawingSocket.ts # 드로잉 소켓 훅
│   └── useChatSocket.ts    # 채팅 소켓 훅
│
└── handlers/socket/        # 소켓 이벤트 핸들러
    ├── gameSocket.handler.ts
    ├── drawingSocket.handler.ts
    └── chatSocket.handler.ts

이 글은 웹소켓 클라이언트 구현기: React 환경에서 효율적인 웹소켓 아키텍처를 전제로 설명하고 있습니다.

위 글에서 설명한 계층형 아키텍처를 실제 코드로 어떻게 구현했는지 살펴보겠습니다. 특히 각 계층의 실제 구현 방식과 해결한 기술적 과제들을 중점적으로 다루겠습니다. drawing 등 다른 도메인을 가진 소켓들은 현재 다 구조가 같아 도메인 상태 관리, 응답 이벤트 등록 커스텀 훅, 요청 핸들러는 게임 도메인만 예시를 보여드리겠습니다.

주요 컴포넌트 설명

1. Socket Config(기본 설정 계층): `socket.config.ts`

Socket Config 계층은 웹소켓 연결의 기본 설정과 타입을 정의하는 핵심 계층입니다.

이 계층에서는 소켓 연결에 필요한 모든 기본 설정값과 타입 정의를 중앙화해 관리합니다. Socket Store 등에서 사용할 설정들의 원천이 되고, Socket.IO 클라이언트의 동작 방식을 결정하는 기준이 됩니다.

주요 특징

설정의 중앙화
- 환경변수를 통한 서버 URL 관리
- 재연결 정책 통합 관리
- 네임스페이스별 경로 정의
타입 시스템 기반
- 열거형을 통한 네임스페이스 관리
- const assertion을 통한 설정값 타입 추론
- 타입 안전한 설정 접근

명시적인 연결 정책

BASE_OPTIONS: {
  autoConnect: false,// 명시적인 연결 관리
  reconnection: true,// 자동 재연결 활성화
  reconnectionAttempts: 5,// 최대 재시도 횟수
  reconnectionDelay: 1000,// 재연결 간격(ms)
}

유지보수성
- 설정값 변경 시 단일 지점 수정
- 공통 설정의 중복 제거
- 설정 변경 이력 추적 용이
확장 가능한 구조
- 새로운 네임스페이스 추가 용이
- 설정 옵션 확장 가능
- Socket.IO 옵션 커스터마이징 지원

1.1 기본 설정 구조화

// 웹소켓 네임스페이스 정의
export enum SocketNamespace {
  GAME = 'game',
  DRAWING = 'drawing',
  CHAT = 'chat',
}

// 기본 설정 상수화
export const SOCKET_CONFIG = {
  URL: import.meta.env.VITE_SOCKET_URL || '<http://localhost:3000>',
  BASE_OPTIONS: {
    autoConnect: false,  // 수동 연결 관리
    reconnection: true,  // 자동 재연결 활성화
    reconnectionAttempts: 5,
    reconnectionDelay: 1000,
  },
  PATHS: {
    [SocketNamespace.GAME]: '/game',
    [SocketNamespace.DRAWING]: '/drawing',
    [SocketNamespace.CHAT]: '/chat',
  },
} as const;

1.2 타입 안전성 강화

// 인증 정보 타입 정의
export interface SocketAuth {
  roomId: string;
  playerId: string;
}

// 네임스페이스별 인증 요구사항
export const NAMESPACE_AUTH_REQUIRED: Record<SocketNamespace, boolean> = {
  [SocketNamespace.GAME]: false,    // 초기 연결은 인증 불필요
  [SocketNamespace.DRAWING]: true,  // 드로잉/채팅은 인증 필수
  [SocketNamespace.CHAT]: true,
} as const;

// 타입 매핑
type SocketType = GameSocket | DrawingSocket | ChatSocket;
type NamespaceSocketMap = {
  [SocketNamespace.GAME]: GameSocket;
  [SocketNamespace.DRAWING]: DrawingSocket;
  [SocketNamespace.CHAT]: ChatSocket;
};

1.3 소켓 생성 로직

const createSocket = <T extends SocketType>(
  namespace: SocketNamespace,
  auth?: SocketAuth
): T => {
  const options = auth
    ? { ...SOCKET_CONFIG.BASE_OPTIONS, auth }
    : SOCKET_CONFIG.BASE_OPTIONS;

  return io(
    `${SOCKET_CONFIG.URL}${SOCKET_CONFIG.PATHS[namespace]}`,
    options
  ) as T;
};

export const socketCreators = {
  [SocketNamespace.GAME]: () =>
    createSocket<GameSocket>(SocketNamespace.GAME),
  [SocketNamespace.DRAWING]: (auth) =>
    createSocket<DrawingSocket>(SocketNamespace.DRAWING, auth),
  [SocketNamespace.CHAT]: (auth) =>
    createSocket<ChatSocket>(SocketNamespace.CHAT, auth),
};

2. Socket Store: 전역 연결 관리 계층

애플리케이션의 모든 WebSocket 연결을 중앙에서 관리하는 전역 상태 관리 계층입니다.

Zustand를 사용해 구현했고, 각 네임스페이스(게임, 드로잉, 채팅)별 소켓 인스턴스와 연결 상태를 추적하고 관리합니다.

이 계층은 소켓 연결의 생명주기를 책임져 실시간 통신의 기반이 되는 소켓 연결을 안정적이고 예측 가능한 방식으로 관리합니다. 또한, 다른 계층에서 소켓 인스턴스를 안전하게 사용할 수 있도록 보장합니다.

주요 특징

상태 구조

sockets: {
  game: Socket | null,     // 게임 소켓 인스턴스
  drawing: Socket | null,  // 드로잉 소켓 인스턴스
  chat: Socket | null      // 채팅 소켓 인스턴스
}

네임스페이스별 소켓 인스턴스 관리
연결 상태의 실시간 추적
null 안전성을 위한 타입 설계

연결 생명주기 관리

connect: (namespace, auth?) => {
  // 중복 연결 방지
  if (currentSocket?.connected) return;

  // 인증 검증
  if (NAMESPACE_AUTH_REQUIRED[namespace] && !auth) {
    console.error(`Auth required for ${namespace}`);
    return;
  }

  // 소켓 생성 및 연결
  const socket = socketCreators[namespace](auth);
  socket.connect();
}

연결 중복 방지
인증 요구사항 자동 검증
연결 상태 자동 업데이트

이벤트 처리

socket.on('connect', () => {
  set(state => ({
    connected: { ...state.connected, [namespace]: true }
  }));
});

socket.on('disconnect', () => {
  set(state => ({
    connected: { ...state.connected, [namespace]: false }
  }));
});

연결/해제 이벤트 자동 처리
상태 업데이트 자동화
일관된 이벤트 핸들링

리소스 관리

disconnect: (namespace) => {
  const socket = get().sockets[namespace];
  if (socket) {
    socket.disconnect();
    // 상태 정리
  }
}

명시적인 연결 해제
리소스 누수 방지
클린업 정리 자동화

확장성
- 새로운 네임스페이스 추가 용이
- 기존 기능 수정 없이 기능 확장 가능
- 타입 시스템을 통한 안전한 확장

Zustand Store 구현: `socket.store.ts`

interface SocketState {
  sockets: Record<SocketNamespace, Socket | null>;
  connected: Record<SocketNamespace, boolean>;
  actions: {
    connect: (namespace: SocketNamespace, auth?: SocketAuth) => void;
    disconnect: (namespace: SocketNamespace) => void;
    disconnectAll: () => void;
  };
}

export const useSocketStore = create<SocketState>((set, get) => ({
  sockets: {
    [SocketNamespace.GAME]: null,
    [SocketNamespace.DRAWING]: null,
    [SocketNamespace.CHAT]: null,
  },
  connected: {
    [SocketNamespace.GAME]: false,
    [SocketNamespace.DRAWING]: false,
    [SocketNamespace.CHAT]: false,
  },
  actions: {
    connect: (namespace, auth?) => {
      // 이미 연결된 소켓은 재사용
      const currentSocket = get().sockets[namespace];
      if (currentSocket?.connected) return;

      // 인증 요구사항 검증
      if (NAMESPACE_AUTH_REQUIRED[namespace] && !auth) {
        console.error(`Auth required for ${namespace}`);
        return;
      }

      const socket = socketCreators[namespace](auth);

      // 연결 상태 관리
      socket.on('connect', () => {
        set(state => ({
          connected: {
            ...state.connected,
            [namespace]: true
          }
        }));
      });

      socket.on('disconnect', () => {
        set(state => ({
          connected: {
            ...state.connected,
            [namespace]: false
          }
        }));
      });

      socket.connect();

      set(state => ({
        sockets: {
          ...state.sockets,
          [namespace]: socket
        }
      }));
    },

    disconnect: (namespace) => {
      const socket = get().sockets[namespace];
      if (socket) {
        socket.disconnect();
        set(state => ({
          sockets: {
            ...state.sockets,
            [namespace]: null
          },
          connected: {
            ...state.connected,
            [namespace]: false
          }
        }));
      }
    },

    disconnectAll: () => {
      Object.values(SocketNamespace).forEach(namespace => {
        get().actions.disconnect(namespace);
      });
    }
  }
}));

참고: disconnectAll은 현재 사용하지 않지만 추후 사용할 것을 대비해 미리 구현해놓은 상태입니다.

3. Domain Store(도메인별 상태 관리 계층)

Domain Store 계층은 각 도메인(게임, 드로잉, 채팅)별 상태를 관리하는 계층입니다. Socket Store가 연결을 관리한다면, Domain Store는 해당 소켓을 통해 주고받는 데이터와 상태를 관리합니다.

게임 도메인을 예시로 들면, 방 정보, 플레이어 목록, 게임 설정 등 게임 진행에 필요한 상태를 저장하고 업데이트합니다.drawing 등 다른 도메인을 가진 소켓들은 현재 다 구조가 같아 도메인 상태 관리, 커스텀 훅, 핸들러는 게임 도메인만 예시를 보여드리겠습니다.

주요 특징

도메인별 상태 구조화

interface GameState {
  room: Room | null;          // 현재 게임방 정보
  roomSettings: RoomSettings | null;  // 게임 설정
  players: Player[];          // 참가자 목록
  currentPlayerId: string | null;  // 현재 플레이어 식별자
}

도메인 특화된 상태 정의
null 안전성 고려
명확한 타입 정의

액션 중심 상태 관리

interface GameActions {
  updateRoom: (room: Room) => void;
  updatePlayers: (players: Player[]) => void;
  removePlayer: (playerId: string) => void;
  reset: () => void;
}

명시적인 액션 정의
단일 책임을 가진 함수들
예측 가능한 상태 변화

초기 상태 분리

const initialState: GameState = {
  room: null,
  roomSettings: null,
  players: [],
  currentPlayerId: null,
};

상태 초기화 용이
리셋 기능 구현 간편화
테스트 용이성

디버깅 지원

export const useGameSocketStore = create<GameState & { actions: GameActions }>()(
  devtools(
    (set) => ({
      // store 구현
    }),
    { name: 'GameSocketStore' }
  )
);

Redux DevTools 통합
상태 변화 추적
액션 히스토리 확인

불변성 보장

removePlayer: (playerId) => set(state => ({
  players: state.players.filter(p => p.playerId !== playerId)
}))

상태 업데이트의 안전성
참조 투명성 유지
리렌더링 최적화

`gameSocket.store.ts` 구현

interface GameState {
  room: Room | null;
  roomSettings: RoomSettings | null;
  players: Player[];
  currentPlayerId: string | null;
}

interface GameActions {
  updateRoom: (room: Room) => void;
  updateRoomSettings: (settings: RoomSettings) => void;
  updatePlayers: (players: Player[]) => void;
  updateCurrentPlayerId: (currentPlayerId: string) => void;
  removePlayer: (playerId: string) => void;
  reset: () => void;
}

const initialState: GameState = {
  room: null,
  roomSettings: null,
  players: [],
  currentPlayerId: null,
};

export const useGameSocketStore = create<GameState & { actions: GameActions }>()(
  devtools(
    (set) => ({
      ...initialState,
      actions: {
        updateRoom: (room) => set({ room }),
        updateRoomSettings: (settings) =>
          set({ roomSettings: settings }),
        updatePlayers: (players) => set({ players }),
        updateCurrentPlayerId: (currentPlayerId) =>
          set({ currentPlayerId }),
        removePlayer: (playerId) =>
          set(state => ({
            players: state.players.filter(
              p => p.playerId !== playerId
            )
          })),
        reset: () => set(initialState)
      }
    }),
    { name: 'GameSocketStore' }
  )
);

4. Custom Hooks(컴포넌트 연동 계층)

Custom Hooks 계층은 컴포넌트와 WebSocket 로직을 연결하는 브릿지 역할을 합니다. Socket Store와 Domain Store의 기능을 통합해 컴포넌트에서 사용하기 쉬운 인터페이스를 제공합니다.

특히 복잡한 소켓 생명주기 관리, 재연결 처리, 이벤트 핸들링을 추상화해 컴포넌트에서는 단순히 훅을 사용하는 것만으로 실시간 기능을 활용할 수 있도록 합니다.

주요 특징

자동 재연결 메커니즘

typescript
Copy
// 재연결 처리
const savedPlayerId = playerIdStorageUtils.getPlayerId(roomId);
if (savedPlayerId) {
  gameSocketHandlers
    .reconnect({ playerId: savedPlayerId, roomId })
    .catch(error => {
      console.error('Reconnection failed:', error);
      playerIdStorageUtils.removePlayerId(roomId);
    });
} else {
  playerIdStorageUtils.removeAllPlayerIds();
  gameSocketHandlers.joinRoom({ roomId }).catch(console.error);
}

localStorage를 통한 세션 유지
실패 시 자동 폴백
에러 복구 메커니즘

이벤트 핸들러 중앙화

const handlers = {
  joinedRoom: (response: JoinRoomResponse) => {
    const { room, roomSettings, players, playerId } = response;
    gameActions.updateRoom(room);
    gameActions.updateRoomSettings(roomSettings);
    gameActions.updatePlayers(players);
    if (playerId) {
      playerIdStorageUtils.setPlayerId(roomId, playerId);
      gameActions.updateCurrentPlayerId(playerId);
    }
  },
// ... 다른 이벤트 핸들러들
};

// 일괄 등록
Object.entries(handlers).forEach(([event, handler]) => {
  socket.on(event, handler);
});
// 일괄 해제
return () => {
  Object.entries(handlers).forEach(([event, handler]) => {
    socket.off(event, handler);
  });
};

이벤트 핸들러 통합 관리, 등록 및 해제 로직 등록
일관된 상태 업데이트
코드 중복 방지

자원 관리

return () => {
  socketActions.disconnect(SocketNamespace.GAME);
  playerIdStorageUtils.removePlayerId(roomId);
};

자동 정리(cleanup)
메모리 누수 방지
상태 초기화

컴포넌트 인터페이스 단순화

// 컴포넌트에서의 사용
const GameRoom = () => {
  const { isConnected, actions } = useGameSocket();

  if (!isConnected) {
    return <LoadingSpinner />;
  }

  return <GameUI />;
};

선언적 인터페이스
연결 상태 자동 관리
간단한 액션 호출

상태 통합

// store들의 통합
const { sockets, connected, actions: socketActions } = useSocketStore();
const { actions: gameActions } = useGameSocketStore();

여러 store의 통합
단일 접근점 제공
상태 동기화 보장

`useGameSocket.ts` 구현

export const useGameSocket = () => {
  const { roomId } = useParams<{ roomId: string }>();
  const { sockets, connected, actions: socketActions } = useSocketStore();
  const { actions: gameActions } = useGameSocketStore();

  useEffect(() => {
    if (!roomId) return;

    // 소켓 연결 설정
    socketActions.connect(SocketNamespace.GAME);

    // 재연결 처리
    const savedPlayerId = playerIdStorageUtils.getPlayerId(roomId);
    if (savedPlayerId) {
      gameSocketHandlers
        .reconnect({ playerId: savedPlayerId, roomId })
        .catch(error => {
          console.error('Reconnection failed:', error);
          playerIdStorageUtils.removePlayerId(roomId);
        });
    } else {
      playerIdStorageUtils.removeAllPlayerIds();
      gameSocketHandlers.joinRoom({ roomId }).catch(console.error);
    }

    // 이벤트 리스너 설정
    const socket = sockets.game;
    if (!socket) return;

    const handlers = {
      joinedRoom: (response: JoinRoomResponse) => {
        const { room, roomSettings, players, playerId } = response;
        gameActions.updateRoom(room);
        gameActions.updateRoomSettings(roomSettings);
        gameActions.updatePlayers(players);
        if (playerId) {
          playerIdStorageUtils.setPlayerId(roomId, playerId);
          gameActions.updateCurrentPlayerId(playerId);
        }
      },
      playerJoined: (response: JoinRoomResponse) => {
        const { room, roomSettings, players } = response;
        gameActions.updateRoom(room);
        gameActions.updateRoomSettings(roomSettings);
        gameActions.updatePlayers(players);
      },
      playerLeft: (response: PlayerLeftResponse) => {
        const { leftPlayerId, players } = response;
        gameActions.removePlayer(leftPlayerId);
        gameActions.updatePlayers(players);
      }
    };

    Object.entries(handlers).forEach(([event, handler]) => {
      socket.on(event, handler);
    });

    return () => {
      socketActions.disconnect(SocketNamespace.GAME);
      playerIdStorageUtils.removePlayerId(roomId);
    };
  }, [roomId]);

  return {
    isConnected: connected.game,
    actions: gameActions
  };
};

Socket Handlers(컴포넌트 연동 계층)

Socket Handlers 계층은 서버로의 이벤트 발신을 담당하는 순수 함수들의 모음입니다.

컴포넌트나 Custom Hooks에서 서버로 이벤트를 보낼 때 사용되고, Promise 기반의 비동기 처리와 타입 안전성을 제공합니다. 각 핸들러는 하나의 특정 이벤트 발신을 담당하고, 에러 처리와 타입 검증을 일관되게 처리합니다.

주요 특징

Promise 기반 비동기 처리로 구현
타입 안전한 이벤트 발신

Socket Store와의 긴밀한 통합, 전역 상태 접근

const socket = useSocketStore.getState().sockets.game;

중앙화된 요청 관리

에러 핸들링 통합

const socket = useSocketStore.getState().sockets.game;
if (!socket) throw new Error('Socket not connected');

`gameSocket.handler.ts` 구현

import type { 
  JoinRoomRequest, 
  JoinRoomResponse, 
  ReconnectRequest 
} from '@troublepainter/core';
import { useSocketStore } from '@/stores/socket/socket.store';

export const gameSocketHandlers = {
  joinRoom: (request: JoinRoomRequest): Promise<void> => {
    const socket = useSocketStore.getState().sockets.game;
    if (!socket) throw new Error('Socket not connected');

    return new Promise(() => {
      socket.emit('joinRoom', request);
    });
  },

  reconnect: (request: ReconnectRequest): Promise<void> => {
    const socket = useSocketStore.getState().sockets.game;
    if (!socket) throw new Error('Socket not connected');

    return new Promise(() => {
      socket.emit('reconnect', request);
    });
  },

  // 예시: 응답 처리를 위한 콜백이 필요한 이벤트 핸들러
  updatePlayerStatus: async (request: ReadyRequest): Promise<void> => {
    const socket = useSocketStore.getState().sockets.game;
    if (!socket) throw new Error('Socket not connected');

    return new Promise((resolve, reject) => {
      socket.emit('updatePlayerStatus', request, (error?: SocketError) => {
        if (error) {
          reject(error);
        } else {
          resolve();
        }
      });
    });
  },
};

export type GameSocketHandlers = typeof gameSocketHandlers;

현재 우리 웹소켓 서버 특성상 요청 시 응답이 오지 않고, 에러는 error 이벤트로만 오기 때문에 따로 요청 후 응답이나 에러를 관리하고 있지 않아 이런 형태로 만들었습니다.

결론

명확한 책임 분리: 계층화된 구조
- Store → Hooks → Handlers 의 명확한 책임 분리
- 설정, 상태 관리, 비즈니스 로직이 분리됨
- 각 계층이 단일 책임을 가짐
- 관심사 분리를 통한 코드 재사용성 향상
타입 안전성
- TypeScript와 [Socket.IO](http://socket.io/) 타입 통합
- 공유 타입 정의를 통한 클라이언트-서버 일관성
확장 가능한 구조
- 새로운 네임스페이스 추가 용이
- 공통 로직의 추상화 + 설정의 중앙화로 재사용성 증가
- 기존 코드 수정 최소화
상태 관리 전략
- zustand를 활용한 예측 가능한 상태 관리
- 도메인별 독립적인 상태 관리
- devtools 통합으로 디버깅 용이
에러 처리
- 중앙화된 에러 핸들링, error 이벤트로만 처리
- 재연결 메커니즘
- 사용자 피드백 통합

😎 웨베베베벱

👮🏻 팀 규칙

💻 프로젝트

🪵 웨베벱 기술로그

1. 개발 환경 세팅 및 프로젝트 문서화
- TypeDoc 배포하기
- Storybook PR Preview 및 배포하기

2. 실시간 통신

3. 인프라 및 CI/CD

4. 라이브러리 없이 Canvas 구현하기

5. 캔버스 동기화를 위한 수제 CRDT 구현기

6. 컴포넌트 패턴부터 웹소켓까지, 효율적인 FE 설계

7. 트러블 슈팅 및 성능/UX 개선

기술 로그 챕터 설명

🪄 데모 공유

🔄 스프린트 기록

WEEK 01

WEEK 02

WEEK 03

WEEK 04

WEEK 05

WEEK 06

WEEK 06 주간 계획
WEEK 06 데일리 스크럼
WEEK 06 주간 회고

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🪵 6. 웹소켓 클라이언트 코드 분석 및 공유

개요

주요 컴포넌트 설명

1. Socket Config(기본 설정 계층): `socket.config.ts`

주요 특징

1.1 기본 설정 구조화

1.2 타입 안전성 강화

1.3 소켓 생성 로직

2. Socket Store: 전역 연결 관리 계층

주요 특징

Zustand Store 구현: `socket.store.ts`

3. Domain Store(도메인별 상태 관리 계층)

주요 특징

`gameSocket.store.ts` 구현

4. Custom Hooks(컴포넌트 연동 계층)

주요 특징

`useGameSocket.ts` 구현

Socket Handlers(컴포넌트 연동 계층)

주요 특징

`gameSocket.handler.ts` 구현

결론

😎 웨베베베벱

👮🏻 팀 규칙

💻 프로젝트

🪵 웨베벱 기술로그

🪄 데모 공유

🔄 스프린트 기록

📗 회의록

Clone this wiki locally

🪵 6. 웹소켓 클라이언트 코드 분석 및 공유

개요

주요 컴포넌트 설명

1. Socket Config(기본 설정 계층): socket.config.ts

주요 특징

1.1 기본 설정 구조화

1.2 타입 안전성 강화

1.3 소켓 생성 로직

2. Socket Store: 전역 연결 관리 계층

주요 특징

Zustand Store 구현: socket.store.ts

3. Domain Store(도메인별 상태 관리 계층)

주요 특징

gameSocket.store.ts 구현

4. Custom Hooks(컴포넌트 연동 계층)

주요 특징

useGameSocket.ts 구현

Socket Handlers(컴포넌트 연동 계층)

주요 특징

gameSocket.handler.ts 구현

결론

😎 웨베베베벱

👮🏻 팀 규칙

💻 프로젝트

🪵 웨베벱 기술로그

🪄 데모 공유

🔄 스프린트 기록

📗 회의록

Clone this wiki locally

1. Socket Config(기본 설정 계층): `socket.config.ts`

Zustand Store 구현: `socket.store.ts`

`gameSocket.store.ts` 구현

`useGameSocket.ts` 구현

`gameSocket.handler.ts` 구현