Phaser Baduk Metaverse 프로젝트의 Node.js 백엔드 설정과 구성에 대해 자세히 설명합니다.

• 이 프로젝트는 Node.js를 기반으로 하며, 웹 페이지를 서버에서 렌더링하고 클라이언트와의 실시간 통신 기능을 제공합니다.
• 주요 기술 스택은 Express.js (웹 프레임워크)와 Socket.IO (실시간 통신 라이브러리)입니다.

Phaser Baduk Metaverse 프로젝트의 핵심 서버 파일인 server.js의 구조와 각 부분의 역할에 대해 설명합니다.

서버 구동에 필요한 Express, HTTP, Socket.IO 모듈을 불러오고, 애플리케이션 인스턴스를 초기화합니다.

javascript
const express = require('express'); // 웹 서버 프레임워크
const http = require('http');     // HTTP 서버 모듈
const socketIo = require('socket.io'); // 실시간 웹 소켓 라이브러리
const path = require('path');     // 파일 경로 처리 유틸리티

const app = express(); // Express 애플리케이션 생성
const server = http.createServer(app); // HTTP 서버 생성 (Express 앱을 기반으로)
const io = socketIo(server); // Socket.IO 서버 생성 (HTTP 서버에 연결)

클라이언트(프론트엔드)에 제공될 정적 파일(HTML, CSS, JS, 이미지 등)을 설정하고, 기본 경로에 대한 라우트를 정의합니다.

javascript
// 'public' 디렉토리에 있는 정적 파일들을 클라이언트에게 제공 (예: index.html, style.css)
app.use(express.static(path.join(__dirname, 'public')));

// 루트 경로('/')로 접근 시 'public' 디렉토리 내의 'index.html' 파일 전송
app.get('/', (req, res) => {
    res.sendFile(path.join(__dirname, 'public', 'index.html'));
});

클라이언트와 서버 간의 실시간 통신을 담당하는 Socket.IO 이벤트 핸들러를 설정합니다. 클라이언트 연결 및 게임 참여 이벤트를 처리합니다.

javascript
// Socket.IO 연결 이벤트 처리
io.on('connection', (socket) => {
    // 새로운 클라이언트가 연결될 때마다 실행
    console.log('새로운 클라이언트 연결:', socket.id);
    
    // 'join-game' 이벤트 수신 시 특정 게임방에 클라이언트 조인
    socket.on('join-game', (gameId) => {
        socket.join(gameId); // 해당 gameId를 가진 방에 소켓을 추가
        console.log(`플레이어가 게임 ${gameId}에 참가했습니다.`);
    });
    
    // 클라이언트 연결 해제 시 실행
    socket.on('disconnect', () => {
        console.log('클라이언트 연결 해제:', socket.id);
    });
});

환경 변수에서 포트 번호를 가져오거나 기본값(3000)을 사용하여 서버를 지정된 포트에서 실행합니다.

javascript
// 환경 변수에서 PORT를 가져오거나 기본값 3000 사용
const PORT = process.env.PORT || 3000;

// 서버를 지정된 포트에서 실행하고, 성공 시 콘솔에 메시지 출력
server.listen(PORT, () => {
    console.log(`서버가 포트 ${PORT}에서 실행 중입니다.`);
});

프로젝트에 필요한 라이브러리 및 스크립트를 정의하는 package.json 파일의 주요 내용을 설명합니다.

자주 사용되는 명령어를 단축하여 정의합니다.

{
  "name": "phaser-baduk-metaverse",
  "version": "1.0.0",
  "description": "Phaser.js 기반 바둑 메타버스 게임",
  "main": "server.js",
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js",
    "pm2": "pm2 start server.js"
  },
  "dependencies": {
    "express": "^4.18.2",
    "socket.io": "^4.7.2",
    "cors": "^2.8.5"
  },
  "devDependencies": {
    "nodemon": "^3.0.1"
  }
}

애플리케이션의 동작 방식을 제어하는 환경 변수 설정 및 서버 실행 방법을 설명합니다.

민감한 정보나 환경별로 달라지는 설정값은 '.env' 파일에 저장하여 관리합니다. 이 파일은 버전 관리 시스템에 포함되지 않도록 하는 것이 일반적입니다.

# .env 파일 예시
NODE_ENV=development // 현재 실행 환경 (development, production 등)
PORT=3000            // 서버가 사용할 포트 번호
DB_PATH=./db.json    // 데이터베이스 파일 경로

개발 및 프로덕션 환경에서 서버를 실행하는 방법을 설명합니다.

• 개발 모드: nodemon을 사용하여 코드 변경 시 서버가 자동으로 재시작됩니다.

bash
    npm run dev
    

• 프로덕션 모드: node 명령어로 직접 실행하며, 안정적인 서비스 운영에 적합합니다.

bash
    npm start
    

게임 및 사용자 관련 데이터를 저장하고 관리하는 db.json 파일의 구조를 설명합니다.

게임의 상태, 사용자 정보, 방 정보, 통계 등을 저장하는 데 사용될 수 있는 JSON 파일 구조입니다. 실제 프로젝트에서는 데이터베이스(예: MongoDB, PostgreSQL)를 사용할 수 있습니다.

{
  "games": {}, // 현재 진행 중이거나 완료된 게임 정보
  "users": {}, // 사용자 계정 및 프로필 정보
  "rooms": {}, // 생성된 게임 방 정보
  "statistics": { // 전반적인 게임 통계
    "totalGames": 0, // 총 게임 수
    "activePlayers": 0 // 현재 접속 중인 플레이어 수
  }
}

서버의 디버깅을 돕고, 예상치 못한 에러 발생 시 안정적으로 처리하는 방법에 대해 설명합니다.

개발 환경에서 상세한 로그를 출력하여 디버깅을 용이하게 합니다.

javascript
// Node.js 환경 변수 'NODE_ENV'가 'development'일 경우 상세 로그 출력
if (process.env.NODE_ENV === 'development') {
    console.log('🔧 개발 모드로 실행 중');
    // 현재 Node.js 프로세스의 메모리 사용량 출력
    console.log('📊 메모리 사용량:', process.memoryUsage());
}

처리되지 않은 예외(Exception)나 Promise 거부(Rejection)가 발생했을 때 애플리케이션이 비정상적으로 종료되는 것을 방지하고, 에러를 기록합니다.

javascript
// 처리되지 않은 동기 예외 발생 시 호출
process.on('uncaughtException', (err) => {
    console.error('❌ 처리되지 않은 예외:', err);
    process.exit(1); // 애플리케이션 종료 (상태 코드 1: 오류)
});

// 처리되지 않은 Promise 거부(reject) 발생 시 호출
process.on('unhandledRejection', (reason, promise) => {
    console.error('❌ 처리되지 않은 Promise 거부:', reason);
    // 이 경우 애플리케이션을 종료할지 여부는 상황에 따라 다를 수 있습니다.
});

Node.js 애플리케이션의 성능을 향상시키기 위한 기법들을 설명합니다.

주기적으로 가비지 컬렉션을 명시적으로 실행하여 메모리 사용량을 최적화할 수 있습니다. 이는 특히 메모리 누수가 의심될 때 유용합니다.

javascript
// 30초마다 가비지 컬렉션(GC)을 명시적으로 실행
setInterval(() => {
    // Node.js에서 'global.gc'를 사용하려면 'node --expose-gc' 옵션으로 실행해야 합니다.
    if (global.gc) {
        global.gc(); // 가비지 컬렉션 강제 실행
        console.log('🧹 가비지 컬렉션 실행');
    }
}, 30000); // 30000 밀리초 = 30초

Node.js는 단일 스레드 기반이지만, cluster 모듈을 사용하여 CPU 코어 수만큼 워커 프로세스를 생성하여 멀티코어 CPU의 이점을 활용하고, 서버의 안정성과 처리량을 향상시킬 수 있습니다.

const cluster = require('cluster'); // Node.js 클러스터 모듈
const numCPUs = require('os').cpus().length; // 시스템의 CPU 코어 수
 
// 현재 프로세스가 마스터 프로세스인지 확인
if (cluster.isMaster) {
    console.log(`마스터 프로세스 ${process.pid} 실행 중`);
 
    // CPU 코어 수만큼 워커 프로세스 생성
    for (let i = 0; i < numCPUs; i++) {
        cluster.fork(); // 새로운 워커 프로세스 생성
    }
 
    // 워커 프로세스가 종료될 때 (예: 예외 발생 또는 수동 종료)
    cluster.on('exit', (worker, code, signal) => {
        console.log(`워커 ${worker.process.pid} 종료 (코드: ${code}, 시그널: ${signal})`);
        cluster.fork(); // 안정적인 서비스를 위해 새로운 워커 재시작
    });
} else {
    // 워커 프로세스는 실제 서버 로직을 실행
    // 이 경우 'server.js' 파일이 워커 프로세스 내에서 다시 로드되어 서버가 실행됩니다.
    require('./server.js');
}

• Express.js 웹 프레임워크
• Socket.IO 실시간 통신
• PM2 프로세스 관리

— 이 페이지는 자동으로 생성되었습니다. —