🪵 6. 웹소켓 클라이언트 구현기: React 환경에서 효율적인 웹소켓 아키텍처

1. 문제 상황과 도전 과제

WebSocket과 React의 충돌

React의 선언적이고 단방향적인 데이터 흐름은 실시간 양방향 통신이 필요한 WebSocket과 자연스럽게 어우러지기 어렵습니다. 구체적인 문제점들을 살펴보겠습니다.

1.1. React의 생명주기와의 불일치

// ❌ 일반적으로 자주 보이는 잘못된 구현
const Component = () => {
  useEffect(() => {
    const socket = io('server-url');
    socket.on('event', handleEvent);

    return () => socket.disconnect();
  }, []);
  // 문제점:
  // 1. 컴포넌트 마운트마다 새로운 연결 생성
  // 2. 페이지 전환시 연결 끊김
  // 3. 다수 컴포넌트에서 중복 연결 가능성
};

1.2. 상태 관리의 복잡성

// ❌ Context API를 사용한 경우의 문제점
const SocketProvider = ({ children }) => {
  const [gameState, setGameState] = useState({});
  const [chatState, setChatState] = useState({});
  const [drawingState, setDrawingState] = useState({});

  useEffect(() => {
    socket.on('gameUpdate', setGameState);
    socket.on('chatUpdate', setChatState);
    socket.on('drawingUpdate', setDrawingState);
    // 문제점:
    // 1. Provider가 거대해짐
    // 2. 불필요한 리렌더링 발생
    // 3. 상태 업데이트 로직이 한 곳에 집중
  }, []);
};

2. 해결 방안: 계층형 아키텍처

위 문제들을 해결하기 위해 다음과 같은 4계층 아키텍처를 설계했습니다.

graph TD
    A[Socket Config] --> B[Socket Store]
    B --> C[Domain Store]
    C --> D[Custom Hooks]
    C --> E[Handlers]

    style A fill:#f9f,stroke:#333
    style B fill:#bbf,stroke:#333
    style C fill:#bfb,stroke:#333
    style D fill:#fb9,stroke:#333

Loading

설계 원칙

1. 관심사의 분리

   • Socket 로직을 4가지 핵심 영역으로 분리
     1. 상태 관리: Store와 액션을 통한 순수 상태 관리
     2. 연결 관리: 소켓 연결/재연결 생명주기 관리
     3. 요청 처리: 웹소켓 요청 핸들러 구현
     4. 응답 처리: 웹소켓 이벤트 구독 및 처리
   • 각 영역을 재사용 가능한 독립적인 모듈로 구성

2. 단일 책임 원칙

   • Socket Store
   • Domain Store
   • Custom Hooks + Handlers

3. 확장성을 고려한 설계

   enum SocketNamespace {
     GAME = 'game',
     DRAWING = 'drawing',
     CHAT = 'chat',
   }

   • 네임스페이스를 통한 기능별 소켓 분리
   • 새로운 기능 추가가 용이한 모듈러 구조
   • 각 도메인의 독립적인 확장 가능
   • 도메인별 개별 스케일링 지원

이러한 계층형 구조는 복잡한 실시간 기능을 관리하기 쉽게 만들며, 새로운 기능 추가나 기존 기능 수정이 용이한 확장 가능한 아키텍처를 제공합니다.

2.1. Socket Config: 기본 설정 계층

소켓 설정을 담은 계층입니다.

// socket.config.ts
export const SOCKET_CONFIG = {
  URL: import.meta.env.VITE_SOCKET_URL || '<http://localhost:3000>',
  PATHS: {
    [SocketNamespace.GAME]: '/game',
    [SocketNamespace.DRAWING]: '/drawing',
    [SocketNamespace.CHAT]: '/chat',
  },
  BASE_OPTIONS: {
    autoConnect: false,
    reconnection: true,
    reconnectionAttempts: 5,
  }
};

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

사용할 소켓 인스턴스와 연결 상태 관리를 담아 각 소켓의 상태를 파악하고, 공통 소켓 액션을 정의한 계층입니다.

// socket.store.ts
export const useSocketStore = create<SocketState>((set) => ({
  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 socket = socketCreators[namespace](auth);
      socket.connect();
      set(state => ({
        sockets: { ...state.sockets, [namespace]: socket }
      }));
    },
    // ...
  }
}));

2.3. Domain Store: 도메인별 상태 관리 계층

도메인별 상태 관리 계층입니다. 게임, 드로잉, 채팅 소켓의 부산물인 상태를 관리하는 계층입니다.

// gameSocket.store.ts
export const useGameSocketStore = create<GameState & GameActions>()(
  devtools(
    (set) => ({
      room: null,
      players: [],
      actions: {
        updateRoom: (room) => set({ room }),
        updatePlayers: (players) => set({ players }),
      }
    }),
    { name: 'GameStore' }
  )
);

2.4. Custom Hooks + Handlers: 컴포넌트 연동 계층

연결 로직 + 응답 이벤트 등록을 담은 Custom Hooks와 요청 이벤트 함수를 담아낸 Handlers를 구현한 계층입니다.

컴포넌트 수준의 소켓 이벤트 처리를 구현해 호출만으로 컴포넌트에 쉽게 연동하도록 계층을 구현했습니다.

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

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

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

    // 2. 이벤트 리스너 설정
    const handlers = {
      joinedRoom: (response: JoinRoomResponse) => {
        gameActions.updateRoom(response.room);
        gameActions.updatePlayers(response.players);
      },
      // ...
    };

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

    return () => {
      // 3. 클린업
      socketActions.disconnect(SocketNamespace.GAME);
    };
  }, [roomId]);

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

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

// socket 요청만 처리하는 핸들러
export const gameSocketHandlers = {
  joinRoom: (request: JoinRoomRequest): Promise<JoinRoomResponse> => {
    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);
    });
  },
};

export type GameSocketHandlers = typeof gameSocketHandlers;

3. 실제 적용: Layout 기반 구현

레이아웃에 계층형 아키텍처를 실제로 적용해 구현해보겠습니다.

// GameLayout.tsx
const GameLayout = () => {
  const { isConnected } = useGameSocket();

  // 연결 상태에 따른 UI 처리
  if (!isConnected) {
    return <LoadingSpinner message="연결 중..." />;
  }

  return (
    <div className="flex min-h-screen flex-col">
      <header>
        <Logo variant="side" />
      </header>

      <main className="mx-auto">
        <div className="flex">
          {/* 플레이어 목록 */}
          <PlayerList />

          {/* 게임 영역 */}
          <section className="flex-1">
            <Outlet />
          </section>

          {/* 채팅 영역 */}
          <Chat />
        </div>
      </main>
    </div>
  );
};

1. 생명주기 관리 단순화
   • Layout 수준에서 소켓 연결 관리
   • 하위 라우트 전환 시에도 연결 유지
2. 상태 공유 최적화
   • 필요한 컴포넌트만 상태 구독
   • Props drilling 방지
3. 사용자 경험 향상
   • 연결 상태에 따른 일관된 UI
   • 페이지 전환 시 끊김없는 실시간 기능

4. 결론 및 이점

이러한 저만의 계층형 아키텍처 설계의 주요 이점은 아래와 같습니다.

• 유지보수성: 각 계층의 역할이 명확하게 분리되어 있어 코드 관리가 용이
• 재사용성: 커스텀 훅을 통해 웹소켓 로직을 쉽게 재사용
• 확장성: 새로운 소켓 기능 추가가 용이한 구조
• 타입 안전성: TypeScript와 Socket.IO의 타입 시스템 활용

이 아키텍처는 실시간 게임, 채팅, 협업 도구 등 WebSocket이 필요한 React 애플리케이션에서 확장 가능하고 유지보수하기 쉽게 의도를 담아 만들었습니다.

참고: Zustand를 통한 계층형 아키텍처 구현 배경

상태 관리 라이브러리 선택 과정

1. 로컬 상태 관리의 한계

// ❌ 컴포넌트 내 로컬 상태 관리의 문제점
const GameRoom = () => {
  const [socket, setSocket] = useState<Socket | null>(null);
  const [gameState, setGameState] = useState({});
  const [connected, setConnected] = useState(false);

  // 문제점:
  // 1. 상태 전파를 위한 Props Drilling
  // 2. 컴포넌트 간 상태 동기화 어려움
  // 3. 페이지 새로고침 시 상태 유실
  return <GameComponent socket={socket} gameState={gameState} />;
};

• Props Drilling: 여러 단계의 컴포넌트를 거쳐 소켓과 상태를 전달해야 함
• 상태 동기화: 여러 페이지에서 동일한 소켓 이벤트를 처리할 때 상태 동기화가 복잡해짐
• 영속성: 페이지 새로고침이나 네비게이션 시 상태 유지가 어려움
• 디버깅: 상태 변화를 추적하고 디버깅하기 어려움
• 테스트: 컴포넌트와 소켓 로직이 강하게 결합되어 테스트가 어려움

2. Context API의 한계

// ❌ Context API 사용 시의 문제점
const SocketProvider = ({ children }) => {
  const [gameState, setGameState] = useState({});

  useEffect(() => {
    // 모든 이벤트 핸들러가 한 곳에 집중
    socket.on('gameStart', onGameStart);
    socket.on('playerJoin', onPlayerJoin);
    socket.on('drawing', onDrawing);
    // ... 계속되는 이벤트 핸들러들
  }, []);

  // 문제점:
  // 1. Provider가 비대해짐
  // 2. 불필요한 리렌더링 발생
  // 3. 기능별 분리가 어려움
  return (
    <SocketContext.Provider value={{ socket, gameState }}>
      {children}
    </SocketContext.Provider>
  );
};

• 이벤트 관리 복잡성: 많은 이벤트를 한 곳에서 관리하면서 코드가 비대해짐
• 상태 업데이트 최적화: Context API 특성상 Provider 안에서 특정 이벤트로 인한 상태 업데이트가 불필요한 리렌더링 유발
• 코드 분할: 기능별로 Context를 분리하면 Provider 중첩이 심해짐

3. Zustand를 선택한 이유

1. 효율적인 상태 구독 ✅ 필요한 상태만 선택적으로 구독

   const Room = () => {
     // 특정 상태만 구독하여 불필요한 리렌더링 방지
     const room = useGameStore((state) => state.room);
     const updateRoom = useGameStore((state) => state.actions.updateRoom);
   
     useEffect(() => {
       socket.on('roomUpdate', updateRoom);
     }, []);
   };

2. 계층형 구조에 적합한 API ✅ 스토어 간 상태 공유 및 조합이 자유로움

   const useGameStore = create<GameState>()((set, get) => ({
     room: null,
     players: [],
     actions: {
       // 다른 스토어의 상태 참조 가능
       updateRoom: (room) => {
         set({ room });
         get().actions.syncWithSocket(room);
       }
     }
   }));

3. 개발 생산성

   • TypeScript 지원이 우수
   • DevTools를 통한 상태 디버깅
   • 미들웨어를 통한 기능 확장

4. 번들 크기

   • 작은 번들 크기 (Redux: ~22KB, MobX: ~16KB, Zustand: ~1KB)
   • 최소한의 보일러플레이트

5. 학습 곡선: ✅ 직관적인 API

const useStore = create((set) => ({
  socket: null,
  connect: () => set({ socket: io() }),
  disconnect: () => set({ socket: null })
}));

이러한 이유로 Zustand를 사용한 계층형 아키텍처가 WebSocket 통신과 상태 관리를 효과적으로 다룰 수 있는 최적의 선택이었습니다.