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

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

주요 특징:

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

Express.js 프로젝트의 기본 구조:

• `server.js` - 메인 서버 파일
• `routes/` - 라우트(URL 경로) 관리 폴더
• `controllers/` - 비즈니스 로직 관리 폴더
• `middleware/` - 미들웨어(중간 처리) 폴더
• `public/` - 클라이언트에게 제공할 파일들

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

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');

각 모듈의 역할:

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

const app = express();
const PORT = process.env.PORT || 3000;

설명:

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

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

이 설정의 목적:

• 웹사이트 보안을 강화합니다
• 악성 스크립트 실행을 방지합니다
• 허용된 리소스만 로드할 수 있게 합니다

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

CORS란?

• 다른 도메인에서의 접근을 제어하는 보안 정책
• 개발 환경에서는 로컬호스트 허용
• 운영 환경에서는 특정 도메인만 허용

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

설명:

• `compression` - 파일 크기를 줄여서 전송 속도 향상
• `rateLimit` - 한 번에 너무 많은 요청을 보내는 것을 방지

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

설명:

• `express.json()` - JSON 형태의 데이터를 파싱
• `express.urlencoded()` - 폼 데이터를 파싱
• `limit: '10mb'` - 최대 10MB까지 허용

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

설명:

• `public` 폴더의 파일들을 웹에서 접근 가능하게 함
• `maxAge: '1d'` - 파일을 1일간 캐시
• `etag: true` - 파일 변경 감지를 위한 태그 사용

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

설명:

• 모든 요청에 대해 로그를 남김
• 요청 시간, 방법(GET, POST 등), URL을 기록
• 디버깅에 매우 유용

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

설명:

• `/api/games` - 게임 관련 API
• `/api/users` - 사용자 관련 API
• `/api/statistics` - 통계 관련 API

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

설명:

• 루트 경로(`/`)로 접근하면 `index.html` 파일을 제공
• 웹사이트의 첫 페이지

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

설명:

• 존재하지 않는 페이지에 접근할 때 실행
• 404 상태 코드와 에러 메시지 반환

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

설명:

• 서버에서 발생하는 모든 에러를 처리
• 에러 로그를 콘솔에 출력
• 클라이언트에게는 일반적인 에러 메시지 전송

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

설명:

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

// 게임 목록 조회
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
        });
    }
});

설명:

• `GET /api/games` - 모든 게임 목록을 조회
• `try-catch` - 에러 처리를 위한 구문
• 성공 시 게임 목록과 총 개수 반환
• 실패 시 에러 메시지 반환

// 새 게임 생성
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
        });
    }
});

설명:

• `POST /api/games` - 새로운 게임을 생성
• `auth` - 인증된 사용자만 접근 가능
• `req.body` - 클라이언트가 보낸 데이터
• `201` - 생성 성공 상태 코드

// 특정 게임 조회
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
        });
    }
});

설명:

• `GET /api/games/:gameId` - 특정 게임 정보 조회
• `req.params.gameId` - URL에서 게임 ID 추출
• 게임이 없으면 404 에러 반환

// 게임 참가
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
        });
    }
});

설명:

• `POST /api/games/:gameId/join` - 특정 게임에 참가
• `req.params.gameId` - URL에서 게임 ID
• `req.body.playerName` - 요청 본문에서 플레이어 이름

// 게임 이동 기록
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
        });
    }
});

설명:

• `POST /api/games/:gameId/move` - 게임에서 돌을 놓음
• `x, y` - 바둑판의 좌표
• `player` - 플레이어 정보

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

설명:

• 지정된 포트에서 서버를 시작
• 서버 시작 시 콘솔에 메시지 출력

module.exports = app;

설명:

• 다른 파일에서 이 앱을 사용할 수 있도록 내보내기
• 테스트나 다른 서버에서 사용할 때 필요

1단계: 프로젝트 초기화

npm init -y npm install express

2단계: 기본 서버 파일 생성 (app.js)

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}에서 실행 중입니다.`);
});

3단계: 서버 실행

node app.js

4단계: 테스트

• 브라우저에서 `http://localhost:3000` 접속
• `http://localhost:3000/api/users` 접속

• 항상 `helmet` 미들웨어를 사용하세요
• 민감한 정보는 환경 변수로 관리하세요
• 입력 데이터를 검증하세요
• HTTPS를 사용하세요

• `compression` 미들웨어 사용
• 정적 파일 캐싱 설정
• 데이터베이스 연결 풀 사용
• 불필요한 미들웨어 제거

• 로깅 미들웨어 사용
• 에러 처리 미들웨어 추가
• 개발 환경에서는 상세한 에러 메시지 표시
• 프로덕션에서는 일반적인 에러 메시지 표시

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

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

추천 학습 순서:

1. [[wiki:it:dream_of_enc:metaverse:nodejs|🟢 Node.js 백엔드 설정]]
2. [[wiki:it:dream_of_enc:metaverse:socketio|🔌 Socket.IO 실시간 통신]]
3. [[wiki:it:dream_of_enc:metaverse:game_logic|🧠 바둑 게임 로직]]

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