🚀 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) 필요한 모듈 불러오기

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

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 - 요청 제한

2) Express 앱 생성

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

설명:

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

3) 보안 미들웨어 설정

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

이 설정의 목적:

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

4) CORS 설정

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)만 허용합니다.

5) 압축 및 요청 제한 설정

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

설명:

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

6) 데이터 파싱 설정

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

설명:

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

7) 정적 파일 서빙 설정

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

설명:

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

8) 로깅 미들웨어

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

설명:

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

4. 라우트 설정

1) 라우트 파일 불러오기

// 라우트 설정
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

2) 메인 페이지 라우트

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

설명:

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

5. 에러 처리

1) 404 에러 처리

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

설명:

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

2) 서버 에러 처리

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

설명:

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

6. 게임 라우트 예제

1) 게임 라우트 기본 구조

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

설명:

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

2) 게임 목록 조회

// 게임 목록 조회
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 - 에러 처리를 위한 구문입니다.
성공 시 게임 목록과 총 개수를 반환합니다.
실패 시 에러 메시지를 반환합니다.

3) 새 게임 생성

// 새 게임 생성
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 - 생성 성공 상태 코드입니다.

4) 특정 게임 조회

// 특정 게임 조회
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 에러를 반환합니다.

5) 게임 참가

// 게임 참가
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 - 요청 본문에서 플레이어 이름을 가져옵니다.

6) 게임 이동 기록

// 게임 이동 기록
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 - 플레이어 정보입니다.

7. 서버 실행

1) 서버 시작

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

설명:

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

2) 모듈 내보내기

module.exports = app;

설명:

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

8. 실습 예제

1) 간단한 Express 서버 만들기

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 접속

9. 주의사항과 팁

1) 보안 주의사항

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

2) 성능 최적화

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

3) 디버깅 팁

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

10. 다음 단계

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

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

추천 학습 순서:

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

Dream of E&C - Wiki

목차

🚀 Express.js 웹 프레임워크

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

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

3. 기본 서버 설정

1) 필요한 모듈 불러오기

2) Express 앱 생성

3) 보안 미들웨어 설정

4) CORS 설정

5) 압축 및 요청 제한 설정

6) 데이터 파싱 설정

7) 정적 파일 서빙 설정

8) 로깅 미들웨어

4. 라우트 설정

1) 라우트 파일 불러오기

2) 메인 페이지 라우트

5. 에러 처리

1) 404 에러 처리

2) 서버 에러 처리

6. 게임 라우트 예제

1) 게임 라우트 기본 구조

2) 게임 목록 조회

3) 새 게임 생성

4) 특정 게임 조회

5) 게임 참가

6) 게임 이동 기록

7. 서버 실행

1) 서버 시작

2) 모듈 내보내기

8. 실습 예제

1) 간단한 Express 서버 만들기

9. 주의사항과 팁

1) 보안 주의사항

2) 성능 최적화

3) 디버깅 팁

10. 다음 단계