🚀 Express.js 웹 프레임워크

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란?

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

// 압축 미들웨어
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. 🟢 Node.js 백엔드 설정
2. 🔌 Socket.IO 실시간 통신
3. 🧠 바둑 게임 로직

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