====== 🚀 Express.js 웹 프레임워크 ======

Phaser Baduk Metaverse 프로젝트의 ''Express.js'' 웹 프레임워크 구현에 대해 설명합니다.

----
===== 1. Express.js란 무엇인가요? =====

''Express.js''는 ''Node.js''를 위한 빠르고 유연한 웹 애플리케이션 프레임워크입니다. 웹 서버를 쉽게 만들 수 있게 해주는 도구라고 생각하시면 됩니다.

**주요 특징:**
  * 웹 서버를 빠르게 만들 수 있습니다.
  * ''RESTful API''를 쉽게 구현할 수 있습니다.
  * 정적 파일(''HTML'', ''CSS'', 이미지 등)을 제공할 수 있습니다.
  * 미들웨어를 통해 기능을 확장할 수 있습니다.

----
===== 2. 프로젝트 구조 이해하기 =====

**Express.js 프로젝트의 기본 구조:**
  * ''server.js'' - 메인 서버 파일
  * ''routes/'' - 라우트(URL 경로) 관리 폴더
  * ''controllers/'' - 비즈니스 로직 관리 폴더
  * ''middleware/'' - 미들웨어(중간 처리) 폴더
  * ''public/'' - 클라이언트에게 제공할 파일들

----
===== 3. 기본 서버 설정 =====

==== 1) 필요한 모듈 불러오기 ====

먼저 필요한 모듈들을 불러옵니다:

<file javascript>
const express = require('express');
const path = require('path');
const cors = require('cors');
const helmet = require('helmet');
const compression = require('compression');
const rateLimit = require('express-rate-limit');
</file>

**각 모듈의 역할:**
  * ''express'' - 웹 서버 프레임워크
  * ''path'' - 파일 경로 처리
  * ''cors'' - 다른 도메인에서의 접근 허용
  * ''helmet'' - 보안 강화
  * ''compression'' - 파일 압축
  * ''rateLimit'' - 요청 제한

==== 2) Express 앱 생성 ====

<file javascript>
const app = express();
const PORT = process.env.PORT || 3000;
</file>

**설명:**
  * ''app'' - Express 애플리케이션 인스턴스
  * ''PORT'' - 서버가 실행될 포트 번호 (기본값: 3000)

==== 3) 보안 미들웨어 설정 ====

<file javascript>
app.use(helmet({
    contentSecurityPolicy: {
        directives: {
            defaultSrc: ["'self'"],
            styleSrc: ["'self'", "'unsafe-inline'"],
            scriptSrc: ["'self'", "'unsafe-inline'"],
            imgSrc: ["'self'", "data:", "https:"],
            connectSrc: ["'self'", "ws:", "wss:"]
        }
    }
}));
</file>

**이 설정의 목적:**
  * 웹사이트 보안을 강화합니다.
  * 악성 스크립트 실행을 방지합니다.
  * 허용된 리소스만 로드할 수 있게 합니다.

==== 4) CORS 설정 ====

<file javascript>
app.use(cors({
    origin: process.env.NODE_ENV === 'production' 
        ? ['https://yourdomain.com'] 
        : ['http://localhost:3000', 'http://localhost:8080'],
    credentials: true
}));
</file>

**CORS란?**
  * 다른 도메인에서의 접근을 제어하는 보안 정책입니다.
  * 개발 환경에서는 ''localhost:3000'', ''localhost:8080''을 허용합니다.
  * 운영 환경에서는 특정 도메인(''https://yourdomain.com'')만 허용합니다.

==== 5) 압축 및 요청 제한 설정 ====

<file javascript>
// 압축 미들웨어
app.use(compression());

// 요청 제한 설정
const limiter = rateLimit({
    windowMs: 15 * 60 * 1000, // 15분
    max: 100, // IP당 최대 100개 요청
    message: '너무 많은 요청이 발생했습니다. 잠시 후 다시 시도해주세요.'
});
app.use('/api/', limiter);
</file>

**설명:**
  * ''compression'' - 파일 크기를 줄여서 전송 속도를 향상시킵니다.
  * ''rateLimit'' - 한 번에 너무 많은 요청을 보내는 것을 방지합니다.

==== 6) 데이터 파싱 설정 ====

<file javascript>
// JSON 파싱 미들웨어
app.use(express.json({ limit: '10mb' }));
app.use(express.urlencoded({ extended: true, limit: '10mb' }));
</file>

**설명:**
  * ''express.json()'' - ''JSON'' 형태의 데이터를 파싱합니다.
  * ''express.urlencoded()'' - 폼 데이터를 파싱합니다.
  * ''limit: '10mb''' - 최대 ''10mb''까지 허용합니다.

==== 7) 정적 파일 서빙 설정 ====

<file javascript>
// 정적 파일 서빙
app.use(express.static(path.join(__dirname, 'public'), {
    maxAge: '1d',
    etag: true
}));
</file>

**설명:**
  * ''public'' 폴더의 파일들을 웹에서 접근 가능하게 합니다.
  * ''maxAge: '1d''' - 파일을 1일간 캐시합니다.
  * ''etag: true'' - 파일 변경 감지를 위한 태그를 사용합니다.

==== 8) 로깅 미들웨어 ====

<file javascript>
// 로깅 미들웨어
app.use((req, res, next) => {
    console.log(`${new Date().toISOString()} - ${req.method} ${req.url}`);
    next();
});
</file>

**설명:**
  * 모든 요청에 대해 로그를 남깁니다.
  * 요청 시간, 방법(''GET'', ''POST'' 등), ''URL''을 기록합니다.
  * 디버깅에 매우 유용합니다.

----
===== 4. 라우트 설정 =====

==== 1) 라우트 파일 불러오기 ====

<file javascript>
// 라우트 설정
app.use('/api/games', require('./routes/games'));
app.use('/api/users', require('./routes/users'));
app.use('/api/statistics', require('./routes/statistics'));
</file>

**설명:**
  * ''/api/games'' - 게임 관련 ''API''
  * ''/api/users'' - 사용자 관련 ''API''
  * ''/api/statistics'' - 통계 관련 ''API''

==== 2) 메인 페이지 라우트 ====

<file javascript>
// 메인 페이지
app.get('/', (req, res) => {
    res.sendFile(path.join(__dirname, 'public', 'index.html'));
});
</file>

**설명:**
  * 루트 경로(''/ '')로 접근하면 ''index.html'' 파일을 제공합니다.
  * 웹사이트의 첫 페이지입니다.

----
===== 5. 에러 처리 =====

==== 1) 404 에러 처리 ====

<file javascript>
// 404 에러 처리
app.use((req, res) => {
    res.status(404).json({ error: '페이지를 찾을 수 없습니다.' });
});
</file>

**설명:**
  * 존재하지 않는 페이지에 접근할 때 실행됩니다.
  * ''404'' 상태 코드와 에러 메시지를 반환합니다.

==== 2) 서버 에러 처리 ====

<file javascript>
// 에러 핸들링 미들웨어
app.use((err, req, res, next) => {
    console.error('서버 에러:', err);
    res.status(500).json({ error: '서버 내부 오류가 발생했습니다.' });
});
</file>

**설명:**
  * 서버에서 발생하는 모든 에러를 처리합니다.
  * 에러 로그를 콘솔에 출력합니다.
  * 클라이언트에게는 일반적인 에러 메시지를 전송합니다.

----
===== 6. 게임 라우트 예제 =====

==== 1) 게임 라우트 기본 구조 ====

<file javascript>
const express = require('express');
const router = express.Router();
const BadukGameController = require('../controllers/BadukGameController');
const auth = require('../middleware/auth');
</file>

**설명:**
  * ''express.Router()'' - 라우터 객체 생성
  * ''BadukGameController'' - 게임 관련 비즈니스 로직
  * ''auth'' - 인증 미들웨어

==== 2) 게임 목록 조회 ====

<file javascript>
// 게임 목록 조회
router.get('/', async (req, res) => {
    try {
        const games = await BadukGameController.getGameList(req.query);
        res.json({
            success: true,
            data: games,
            total: games.length
        });
    } catch (error) {
        res.status(500).json({
            success: false,
            error: error.message
        });
    }
});
</file>

**설명:**
  * ''GET /api/games'' - 모든 게임 목록을 조회합니다.
  * ''try-catch'' - 에러 처리를 위한 구문입니다.
  * 성공 시 게임 목록과 총 개수를 반환합니다.
  * 실패 시 에러 메시지를 반환합니다.

==== 3) 새 게임 생성 ====

<file javascript>
// 새 게임 생성
router.post('/', auth, async (req, res) => {
    try {
        const { gameType, settings } = req.body;
        const game = await BadukGameController.createGame(req.user.id, gameType, settings);
        
        res.status(201).json({
            success: true,
            data: game
        });
    } catch (error) {
        res.status(400).json({
            success: false,
            error: error.message
        });
    }
});
</file>

**설명:**
  * ''POST /api/games'' - 새로운 게임을 생성합니다.
  * ''auth'' - 인증된 사용자만 접근 가능합니다.
  * ''req.body'' - 클라이언트가 보낸 데이터입니다.
  * ''201'' - 생성 성공 상태 코드입니다.

==== 4) 특정 게임 조회 ====

<file javascript>
// 특정 게임 조회
router.get('/:gameId', async (req, res) => {
    try {
        const game = await BadukGameController.getGame(req.params.gameId);
        
        if (!game) {
            return res.status(404).json({
                success: false,
                error: '게임을 찾을 수 없습니다.'
            });
        }
        
        res.json({
            success: true,
            data: game
        });
    } catch (error) {
        res.status(500).json({
            success: false,
            error: error.message
        });
    }
});
</file>

**설명:**
  * ''GET /api/games/:gameId'' - 특정 게임 정보를 조회합니다.
  * ''req.params.gameId'' - ''URL''에서 게임 ''ID''를 추출합니다.
  * 게임이 없으면 ''404'' 에러를 반환합니다.

==== 5) 게임 참가 ====

<file javascript>
// 게임 참가
router.post('/:gameId/join', auth, async (req, res) => {
    try {
        const { gameId } = req.params;
        const { playerName } = req.body;
        
        const result = await BadukGameController.joinGame(gameId, req.user.id, playerName);
        
        res.json({
            success: true,
            data: result
        });
    } catch (error) {
        res.status(400).json({
            success: false,
            error: error.message
        });
    }
});
</file>

**설명:**
  * ''POST /api/games/:gameId/join'' - 특정 게임에 참가합니다.
  * ''req.params.gameId'' - ''URL''에서 게임 ''ID''를 가져옵니다.
  * ''req.body.playerName'' - 요청 본문에서 플레이어 이름을 가져옵니다.

==== 6) 게임 이동 기록 ====

<file javascript>
// 게임 이동 기록
router.post('/:gameId/move', auth, async (req, res) => {
    try {
        const { gameId } = req.params;
        const { x, y, player } = req.body;
        
        const result = await BadukGameController.makeMove(gameId, req.user.id, x, y, player);
        
        res.json({
            success: true,
            data: result
        });
    } catch (error) {
        res.status(400).json({
            success: false,
            error: error.message
        });
    }
});
</file>

**설명:**
  * ''POST /api/games/:gameId/move'' - 게임에서 돌을 놓습니다.
  * ''x, y'' - 바둑판의 좌표입니다.
  * ''player'' - 플레이어 정보입니다.

----
===== 7. 서버 실행 =====

==== 1) 서버 시작 ====

<file javascript>
// 서버 시작
app.listen(PORT, () => {
    console.log(`서버가 포트 ${PORT}에서 실행 중입니다.`);
    console.log(`http://localhost:${PORT}에서 접속하세요.`);
});
</file>

**설명:**
  * 지정된 포트에서 서버를 시작합니다.
  * 서버 시작 시 콘솔에 메시지를 출력합니다.

==== 2) 모듈 내보내기 ====

<file javascript>
module.exports = app;
</file>

**설명:**
  * 다른 파일에서 이 앱을 사용할 수 있도록 내보냅니다.
  * 테스트나 다른 서버에서 사용할 때 필요합니다.

----
===== 8. 실습 예제 =====

==== 1) 간단한 Express 서버 만들기 ====

**1단계: 프로젝트 초기화**
<file bash>
npm init -y
npm install express
</file>

**2단계: 기본 서버 파일 생성 (''app.js'')**
<file javascript>
const express = require('express');
const app = express();
const PORT = 3000;

// JSON 파싱 미들웨어
app.use(express.json());

// 간단한 라우트
app.get('/', (req, res) => {
    res.json({ message: '안녕하세요! Express 서버입니다.' });
});

app.get('/api/users', (req, res) => {
    res.json([
        { id: 1, name: '김철수' },
        { id: 2, name: '이영희' }
    ]);
});

// 서버 시작
app.listen(PORT, () => {
    console.log(`서버가 포트 ${PORT}에서 실행 중입니다.`);
});
</file>

**3단계: 서버 실행**
<file bash>
node app.js
</file>

**4단계: 테스트**
  * 브라우저에서 ''http://localhost:3000'' 접속
  * ''http://localhost:3000/api/users'' 접속

----
===== 9. 주의사항과 팁 =====

==== 1) 보안 주의사항 ====
  * 항상 ''helmet'' 미들웨어를 사용하세요.
  * 민감한 정보는 환경 변수로 관리하세요.
  * 입력 데이터를 검증하세요.
  * ''HTTPS''를 사용하세요.

==== 2) 성능 최적화 ====
  * ''compression'' 미들웨어를 사용하세요.
  * 정적 파일 캐싱을 설정하세요.
  * 데이터베이스 연결 풀을 사용하세요.
  * 불필요한 미들웨어를 제거하세요.

==== 3) 디버깅 팁 ====
  * 로깅 미들웨어를 사용하세요.
  * 에러 처리 미들웨어를 추가하세요.
  * 개발 환경에서는 상세한 에러 메시지를 표시하세요.
  * 프로덕션에서는 일반적인 에러 메시지를 표시하세요.

----
===== 10. 다음 단계 =====

''Express.js'' 기본을 배웠다면 다음을 학습해보세요:

  * **''Socket.IO''** - 실시간 통신 구현
  * **데이터베이스 연동** - ''MongoDB'', ''MySQL'' 등
  * **인증 시스템** - ''JWT'', ''Passport.js'' 등
  * **파일 업로드** - ''Multer'' 미들웨어
  * **''API'' 문서화** - ''Swagger'' 등

**추천 학습 순서:**
  - [[wiki:it:dream_of_enc:metaverse:nodejs|🟢 Node.js 백엔드 설정]]
  - [[wiki:it:dream_of_enc:metaverse:socketio|🔌 Socket.IO 실시간 통신]]
  - [[wiki:it:dream_of_enc:metaverse:game_logic|🧠 바둑 게임 로직]]

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