차이

문서의 선택한 두 판 사이의 차이를 보여줍니다.

--- wiki:it:dream_of_enc:metaverse:nodejs [2025/07/28 05:57] – 만듦 - 바깥 편집 127.0.0.1
+++ wiki:it:dream_of_enc:metaverse:nodejs [2025/07/30 06:43] (현재) – 바깥 편집 127.0.0.1
@@ 줄 1: / 줄 1: @@
 ====== 🟢 Node.js 백엔드 설정 ======
-Phaser Baduk Metaverse 프로젝트의 Node.js 백엔드 설정과 구성에 대해 설명합니다.
+Phaser Baduk Metaverse 프로젝트의 ''Node.js'' 백엔드 설정과 구성에 대해 자세히 설명합니다.
-===== 📋 개요 =====
+----
+===== 1. Node.js란 무엇인가요? =====
-이 프로젝트는 Node.js를 기반으로 한 서버 사이드 렌더링과 실시간 통신을 제공합니다.
+''Node.js''는 ''JavaScript''를 서버에서 실행할 수 있게 해주는 런타임 환경입니다. 웹 브라우저에서만 실행되던 ''JavaScript''를 서버에서도 실행할 수 있게 해줍니다.
-===== 🏗️ 서버 구조 =====
+**주요 특징:**
+  * ''JavaScript''로 서버를 만들 수 있습니다.
+  * 비동기 처리에 강점이 있습니다.
+  * ''npm''을 통해 다양한 패키지를 사용할 수 있습니다.
+  * 빠른 개발이 가능합니다.
-**메인 서버 파일 (server.js):**
+----
-<code javascript>
+===== 2. 프로젝트 개요 =====
+이 프로젝트는 ''Node.js''를 기반으로 하며, 웹 페이지를 서버에서 렌더링하고 클라이언트와의 실시간 통신 기능을 제공합니다.
+**주요 기술 스택:**
+  * **''Express.js''** - 웹 프레임워크
+  * **''Socket.IO''** - 실시간 통신 라이브러리
+  * **''PM2''** - 프로세스 관리 도구
+----
+===== 3. 서버 구조 및 주요 파일 =====
+Phaser Baduk Metaverse 프로젝트의 핵심 서버 파일인 ''server.js''의 구조와 각 부분의 역할에 대해 설명합니다.
+==== 1) 초기 설정 및 모듈 불러오기 ====
+서버 구동에 필요한 모듈들을 불러오고, 애플리케이션 인스턴스를 초기화합니다.
+<file javascript>
+const express = require('express'); // 웹 서버 프레임워크
+const http = require('http');     // HTTP 서버 모듈
+const socketIo = require('socket.io'); // 실시간 웹 소켓 라이브러리
+const path = require('path');     // 파일 경로 처리 유틸리티
+</file>
+**각 모듈의 역할:**
+  * ''express'' - 웹 서버를 쉽게 만들 수 있는 프레임워크
+  * ''http'' - ''HTTP'' 서버를 생성하는 기본 모듈
+  * ''socket.io'' - 실시간 양방향 통신을 위한 라이브러리
+  * ''path'' - 파일 경로를 안전하게 처리하는 유틸리티
+==== 2) 애플리케이션 인스턴스 생성 ====
+<file javascript>
+const app = express(); // Express 애플리케이션 생성
+const server = http.createServer(app); // HTTP 서버 생성 (Express 앱을 기반으로)
+const io = socketIo(server); // Socket.IO 서버 생성 (HTTP 서버에 연결)
+</file>
+**설명:**
+  * ''app'' - ''Express'' 애플리케이션 객체
+  * ''server'' - ''HTTP'' 서버 객체 (''Express'' 앱을 기반으로 생성)
+  * ''io'' - ''Socket.IO'' 서버 객체 (''HTTP'' 서버에 연결)
+==== 3) 정적 파일 서빙 및 라우팅 ====
+클라이언트(프론트엔드)에 제공될 정적 파일(''HTML'', ''CSS'', ''JS'', 이미지 등)을 설정하고, 기본 경로에 대한 라우트를 정의합니다.
+<file javascript>
+// 'public' 디렉토리에 있는 정적 파일들을 클라이언트에게 제공
+app.use(express.static(path.join(dirname, 'public')));
+// 루트 경로('/')로 접근 시 'public' 디렉토리 내의 'index.html' 파일 전송
+app.get('/', (req, res) => {
+    res.sendFile(path.join(dirname, 'public', 'index.html'));
+});
+</file>
+**설명:**
+  * ''express.static()'' - 정적 파일을 웹에서 접근 가능하게 합니다.
+  * ''path.join(dirname, 'public')'' - 현재 디렉토리의 ''public'' 폴더 경로입니다.
+  * ''app.get('/')'' - 루트 경로로 접근했을 때 실행되는 함수입니다.
+==== 4) Socket.IO 이벤트 처리 ====
+클라이언트와 서버 간의 실시간 통신을 담당하는 ''Socket.IO'' 이벤트 핸들러를 설정합니다.
+<file 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);
+    });
+});
+</file>
+**설명:**
+  * ''io.on('connection')'' - 새로운 클라이언트가 연결될 때 실행됩니다.
+  * ''socket.on('join-game')'' - 클라이언트가 게임 참가 요청을 보낼 때 실행됩니다.
+  * ''socket.join(gameId)'' - 특정 게임방에 소켓을 추가합니다.
+  * ''socket.on('disconnect')'' - 클라이언트 연결이 끊어질 때 실행됩니다.
+==== 5) 서버 포트 설정 및 실행 ====
+환경 변수에서 포트 번호를 가져오거나 기본값(3000)을 사용하여 서버를 지정된 포트에서 실행합니다.
+<file javascript>
+// 환경 변수에서 PORT를 가져오거나 기본값 3000 사용
+const PORT = process.env.PORT || 3000;
+// 서버를 지정된 포트에서 실행하고, 성공 시 콘솔에 메시지 출력
+server.listen(PORT, () => {
+    console.log(`서버가 포트 ${PORT}에서 실행 중입니다.`);
+    console.log(`http://localhost:${PORT}에서 접속하세요.`);
+});
+</file>
+**설명:**
+  * ''process.env.PORT'' - 환경 변수에서 포트 번호를 가져옵니다.
+  * ''|| 3000'' - 환경 변수가 없으면 기본값 3000을 사용합니다.
+  * ''server.listen()'' - 서버를 지정된 포트에서 시작합니다.
+  * 콜백 함수는 서버 시작 성공 시 실행되는 함수입니다.
+----
+===== 4. 의존성 관리 (package.json) =====
+프로젝트에 필요한 라이브러리 및 스크립트를 정의하는 ''package.json'' 파일의 주요 내용을 설명합니다.
+==== 1) 프로젝트 정보 ====
+^ 키 ^ 설명 ^
+| name | 프로젝트 이름 |
+| version | 프로젝트 버전 |
+| description | 프로젝트에 대한 간략한 설명 |
+| main | 프로젝트의 진입점 파일 (여기서는 ''server.js'') |
+==== 2) 스크립트 ====
+자주 사용되는 명령어를 단축하여 정의합니다.
+^ 스크립트 ^ 설명 ^ 명령어 ^
+| start | 프로덕션 환경에서 서버를 시작합니다. | ''node server.js'' |
+| dev | 개발 환경에서 ''nodemon''을 사용하여 서버를 시작합니다. 코드 변경 시 자동 재시작됩니다. | ''nodemon server.js'' |
+| pm2 | ''PM2''를 사용하여 서버를 시작합니다. (프로세스 관리용) | ''pm2 start server.js'' |
+==== 3) 의존성 목록 ====
+^ 의존성 ^ 버전 ^ 설명 ^
+| express | 4.18.2 | Node.js 웹 애플리케이션 프레임워크 |
+| socket.io | 4.7.2 | 실시간 양방향 웹 소켓 통신 라이브러리 |
+| cors | 2.8.5 | 교차 출처 리소스 공유 (CORS) 미들웨어 |
+| helmet | 7.0.0 | 보안 헤더 설정 미들웨어 |
+| compression | 1.7.4 | 응답 압축 미들웨어 |
+| express-rate-limit | 6.7.0 | 요청 제한 미들웨어 |
+==== 4) 개발 의존성 목록 ====
+^ 의존성 ^ 버전 ^ 설명 ^
+| nodemon | 2.0.22 | 개발 시 코드 변경 감지하여 서버 자동 재시작 |
+| jest | 29.5.0 | JavaScript 테스트 프레임워크 |
+| supertest | 6.3.3 | HTTP 테스트 라이브러리 |
+----
+===== 5. 환경 설정 =====
+==== 1) 환경 변수 설정 ====
+프로젝트 루트에 ''.env'' 파일을 생성하여 환경 변수를 설정합니다:
+<file bash>
+# 서버 포트 설정
+PORT=3000
+# 데이터베이스 연결 정보
+MONGODB_URI=mongodb://localhost:27017/baduk_metaverse
+# JWT 시크릿 키
+JWT_SECRET=your-secret-key-here
+# 환경 설정
+NODE_ENV=development
+</file>
+**주요 환경 변수:**
+  * ''PORT'' - 서버가 실행될 포트 번호
+  * ''MONGODB_URI'' - ''MongoDB'' 데이터베이스 연결 문자열
+  * ''JWT_SECRET'' - ''JWT'' 토큰 암호화에 사용할 시크릿 키
+  * ''NODE_ENV'' - 현재 환경 (''development''/''production'')
+==== 2) 환경 변수 사용법 ====
+<file javascript>
+// dotenv 패키지를 사용하여 .env 파일 로드
+require('dotenv').config();
+// 환경 변수 사용
+const PORT = process.env.PORT || 3000;
+const MONGODB_URI = process.env.MONGODB_URI;
+const JWT_SECRET = process.env.JWT_SECRET;
+</file>
+**설명:**
+  * ''require('dotenv').config()'' - ''.env'' 파일을 로드합니다.
+  * ''process.env.변수명'' - 환경 변수 값을 가져옵니다.
+  * ''|| 기본값'' - 환경 변수가 없을 때 기본값을 사용합니다.
+----
+===== 6. 프로젝트 구조 =====
+**권장하는 프로젝트 폴더 구조:**
+<file>
+baduk-metaverse/
+├── server.js              # 메인 서버 파일
+├── package.json           # 프로젝트 설정 파일
+├── .env                   # 환경 변수 파일
+├── .gitignore            # Git 무시 파일 목록
+├── public/               # 정적 파일 폴더
+│   ├── index.html        # 메인 HTML 파일
+│   ├── css/              # CSS 파일들
+│   ├── js/               # 클라이언트 JavaScript 파일들
+│   └── images/           # 이미지 파일들
+├── routes/               # 라우트 파일들
+│   ├── games.js          # 게임 관련 라우트
+│   ├── users.js          # 사용자 관련 라우트
+│   └── statistics.js     # 통계 관련 라우트
+├── controllers/          # 컨트롤러 파일들
+│   ├── BadukGameController.js
+│   ├── UserController.js
+│   └── StatisticsController.js
+├── models/               # 데이터 모델 파일들
+│   ├── BadukGame.js
+│   ├── User.js
+│   └── BadukGameState.js
+├── middleware/           # 미들웨어 파일들
+│   ├── auth.js           # 인증 미들웨어
+│   └── errorHandler.js   # 에러 처리 미들웨어
+├── utils/                # 유틸리티 파일들
+│   ├── BadukMoveValidator.js
+│   └── helpers.js
+└── tests/                # 테스트 파일들
+    ├── server.test.js
+    └── game.test.js
+</file>
+**각 폴더의 역할:**
+  * ''public/'' - 클라이언트에게 제공할 파일들
+  * ''routes/'' - ''URL'' 경로별 처리 로직
+  * ''controllers/'' - 비즈니스 로직 처리
+  * ''models/'' - 데이터 구조 정의
+  * ''middleware/'' - 요청 처리 중간 단계
+  * ''utils/'' - 공통 유틸리티 함수들
+  * ''tests/'' - 테스트 코드들
+----
+===== 7. 개발 환경 설정 =====
+==== 1) Node.js 설치 ====
+**Windows에서 Node.js 설치:**
+  * ''Node.js'' 공식 웹사이트 (''https://nodejs.org'') 방문
+  * ''LTS'' 버전 다운로드 및 설치
+  * 설치 완료 후 터미널에서 확인:
+<file bash>
+node --version
+npm --version
+</file>
+==== 2) 프로젝트 초기화 ====
+<file bash>
+# 새 폴더 생성 및 이동
+mkdir baduk-metaverse
+cd baduk-metaverse
+# npm 프로젝트 초기화
+npm init -y
+# 필요한 패키지 설치
+npm install express socket.io cors helmet compression express-rate-limit
+# 개발용 패키지 설치
+npm install --save-dev nodemon
+</file>
+==== 3) 기본 서버 파일 생성 ====
+''server.js'' 파일을 생성하고 기본 코드를 작성합니다:
+<file javascript>
 const express = require('express');
 const http = require('http');
@@ 줄 21: / 줄 305: @@
 // 정적 파일 서빙
-app.use(express.static(path.join(__dirname, 'public')));
+app.use(express.static(path.join(dirname, 'public')));
-// 라우트 설정
+// 기본 라우트
 app.get('/', (req, res) => {
-    res.sendFile(path.join(__dirname, 'public', 'index.html'));
+    res.sendFile(path.join(dirname, 'public', 'index.html'));
 });
-// Socket.IO 이벤트 처리
+// Socket.IO 연결 처리
 io.on('connection', (socket) => {
     console.log('새로운 클라이언트 연결:', socket.id);
-    socket.on('join-game', (gameId) => {
-        socket.join(gameId);
-        console.log(`플레이어가 게임 ${gameId}에 참가했습니다.`);
-    });
     socket.on('disconnect', () => {
@@ 줄 42: / 줄 321: @@
 });
+// 서버 시작
 const PORT = process.env.PORT || 3000;
 server.listen(PORT, () => {
     console.log(`서버가 포트 ${PORT}에서 실행 중입니다.`);
 });
-</code>
+</file>
-===== 📦 의존성 관리 =====
+==== 4) package.json 스크립트 설정 ====
-**package.json 주요 의존성:**
+<file json>
-<code json>
 {
-  "name": "phaser-baduk-metaverse",
+  "name": "baduk-metaverse",
   "version": "1.0.0",
-  "description": "Phaser.js 기반 바둑 메타버스 게임",
+  "description": "Phaser Baduk Metaverse 프로젝트",
   "main": "server.js",
   "scripts": {
     "start": "node server.js",
     "dev": "nodemon server.js",
-    "pm2": "pm2 start server.js"
+    "test": "jest"
   },
   "dependencies": {
     "express": "^4.18.2",
     "socket.io": "^4.7.2",
-    "cors": "^2.8.5"
+    "cors": "^2.8.5",
+    "helmet": "^7.0.0",
+    "compression": "^1.7.4",
+    "express-rate-limit": "^6.7.0"
   },
   "devDependencies": {
-    "nodemon": "^3.0.1"
+    "nodemon": "^2.0.22",
+    "jest": "^29.5.0"
   }
 }
-</code>
+</file>
-===== 🔧 환경 설정 =====
+----
+===== 8. 서버 실행 및 테스트 =====
-**환경 변수 설정:**
+==== 1) 개발 모드로 서버 실행 ====
-<code bash>
-# .env 파일
-NODE_ENV=development
-PORT=3000
-DB_PATH=./db.json
-</code>
-**개발 환경 실행:**
+<file bash>
-<code bash>
-# 개발 모드 (nodemon 사용)
 npm run dev
+</file>
-# 프로덕션 모드
+**설명:**
+  * ''nodemon''을 사용하여 서버를 실행합니다.
+  * 코드 변경 시 자동으로 서버가 재시작됩니다.
+  * 개발 중에 매우 유용합니다.
+==== 2) 프로덕션 모드로 서버 실행 ====
+<file bash>
 npm start
-</code>
+</file>
-===== 🗄️ 데이터 관리 =====
+**설명:**
+  * ''node''를 사용하여 서버를 실행합니다.
+  * 코드 변경 시 수동으로 서버를 재시작해야 합니다.
+  * 실제 서비스 환경에서 사용합니다.
-**게임 데이터 저장소 (db.json):**
+==== 3) 서버 테스트 ====
-<code json>
-{
-  "games": {},
-  "users": {},
-  "rooms": {},
-  "statistics": {
-    "totalGames": 0,
-    "activePlayers": 0
-  }
-}
-</code>
-===== 🔍 디버깅 =====
+**브라우저에서 테스트:**
+  * 브라우저 열기
+  * ''http://localhost:3000'' 접속
+  * 서버가 정상적으로 응답하는지 확인
-**로그 레벨 설정:**
+**터미널에서 테스트:**
-<code javascript>
+<file bash>
-// 개발 환경에서 상세 로그 출력
+curl http://localhost:3000
-if (process.env.NODE_ENV === 'development') {
+</file>
-    console.log('🔧 개발 모드로 실행 중');
-    console.log('📊 메모리 사용량:', process.memoryUsage());
-}
-</code>
-**에러 핸들링:**
+----
-<code javascript>
+===== 9. 디버깅 및 로깅 =====
-process.on('uncaughtException', (err) => {
-    console.error('❌ 처리되지 않은 예외:', err);
+==== 1) 콘솔 로깅 ====
-    process.exit(1);
+<file javascript>
+// 기본 로깅
+console.log('일반 메시지');
+console.error('에러 메시지');
+console.warn('경고 메시지');
+// 객체 로깅
+const gameData = { id: 1, name: '바둑 게임' };
+console.log('게임 데이터:', gameData);
+// 시간과 함께 로깅
+console.log(`${new Date().toISOString()} - 서버 시작됨`);
+</file>
+==== 2) 로깅 미들웨어 ====
+<file javascript>
+// 요청 로깅 미들웨어
+app.use((req, res, next) => {
+    console.log(`${new Date().toISOString()} - ${req.method} ${req.url}`);
+    next();
 });
-process.on('unhandledRejection', (reason, promise) => {
+// 에러 로깅 미들웨어
-    console.error('❌ 처리되지 않은 Promise 거부:', reason);
+app.use((err, req, res, next) => {
+    console.error('서버 에러:', err);
+    res.status(500).json({ error: '서버 내부 오류가 발생했습니다.' });
 });
-</code>
+</file>
+==== 3) 디버깅 도구 ====
+**Node.js 내장 디버거 사용:**
+<file bash>
+node --inspect server.js
+</file>
+**Chrome DevTools에서 디버깅:**
+  * Chrome 브라우저 열기
+  * %%chrome://inspect%% 접속
+  * "Open dedicated DevTools for Node" 클릭
+----
+===== 10. 성능 최적화 =====
+==== 1) 압축 설정 ====
+<file javascript>
+const compression = require('compression');
+// 응답 압축 미들웨어
+app.use(compression());
+</file>
+==== 2) 캐싱 설정 ====
+<file javascript>
+// 정적 파일 캐싱
+app.use(express.static(path.join(dirname, 'public'), {
+    maxAge: '1d', // 1일간 캐시
+    etag: true    // ETag 사용
+}));
+</file>
+==== 3) 요청 제한 ====
+<file javascript>
+const rateLimit = require('express-rate-limit');
+// API 요청 제한
+const limiter = rateLimit({
+    windowMs: 15 * 60 * 1000, // 15분
+    max: 100, // IP당 최대 100개 요청
+    message: '너무 많은 요청이 발생했습니다.'
+});
+app.use('/api/', limiter);
+</file>
+----
+===== 11. 보안 설정 =====
+==== 1) Helmet 미들웨어 ====
-===== 🚀 성능 최적화 =====
+<file javascript>
+const helmet = require('helmet');
-**메모리 관리:**
+// 보안 헤더 설정
-<code javascript>
+app.use(helmet({
-// 주기적인 메모리 정리
+    contentSecurityPolicy: {
-setInterval(() => {
+        directives: {
-    if (global.gc) {
+            defaultSrc: ["'self'"],
-        global.gc();
+            styleSrc: ["'self'", "'unsafe-inline'"],
-        console.log('🧹 가비지 컬렉션 실행');
+            scriptSrc: ["'self'", "'unsafe-inline'"],
+            imgSrc: ["'self'", "data:", "https:"],
+            connectSrc: ["'self'", "ws:", "wss:"]
+        }
     }
-}, 30000); // 30초마다
+}));
-</code>
+</file>
-**클러스터 모드:**
+==== 2) CORS 설정 ====
-<code javascript>
-const cluster = require('cluster');
-const numCPUs = require('os').cpus().length;
-if (cluster.isMaster) {
+<file javascript>
-    console.log(`마스터 프로세스 ${process.pid} 실행 중`);
+const cors = require('cors');
+// CORS 설정
+app.use(cors({
+    origin: process.env.NODE_ENV === 'production'
+        ? ['https://yourdomain.com']
+        : ['http://localhost:3000'],
+    credentials: true
+}));
+</file>
+==== 3) 입력 데이터 검증 ====
+<file javascript>
+// 입력 데이터 검증 예제
+app.post('/api/games', (req, res) => {
+    const { gameType, settings } = req.body;
-    // 워커 프로세스 생성
+    // 필수 필드 검증
-    for (let i = 0; i < numCPUs; i++) {
+    if (!gameType) {
-        cluster.fork();
+        return res.status(400).json({ error: '게임 타입이 필요합니다.' });
     }
-    cluster.on('exit', (worker, code, signal) => {
+    // 데이터 타입 검증
-        console.log(`워커 ${worker.process.pid} 종료`);
+    if (typeof gameType !== 'string') {
-        cluster.fork(); // 새로운 워커 생성
+        return res.status(400).json({ error: '게임 타입은 문자열이어야 합니다.' });
-    });
+    }
-} else {
-    // 워커 프로세스에서 서버 실행
+    // 추가 처리...
-    require('./server.js');
+});
-}
+</file>
-</code>
-===== 📚 관련 문서 =====
+----
+===== 12. 다음 단계 =====
-  * [[wiki:it:dream_of_enc:metaverse:express|Express.js 웹 프레임워크]]
+''Node.js'' 기본을 배웠다면 다음을 학습해보세요:
-  * [[wiki:it:dream_of_enc:metaverse:socketio|Socket.IO 실시간 통신]]
-  * [[wiki:it:dream_of_enc:metaverse:pm2|PM2 프로세스 관리]]
+  * **''Express.js''** - 웹 프레임워크 심화 학습
+  * **''Socket.IO''** - 실시간 통신 구현
+  * **데이터베이스 연동** - ''MongoDB'', ''MySQL'' 등
+  * **인증 시스템** - ''JWT'', ''Passport.js'' 등
+  * **테스트 작성** - ''Jest'', ''Mocha'' 등
+**추천 학습 순서:**
+  - [[wiki:it:dream_of_enc:metaverse:express|🚀 Express.js 웹 프레임워크]]
+  - [[wiki:it:dream_of_enc:metaverse:socketio|🔌 Socket.IO 실시간 통신]]
+  - [[wiki:it:dream_of_enc:metaverse:pm2|⚡ PM2 프로세스 관리]]
 ---
 //이 페이지는 자동으로 생성되었습니다.//
+---