01 Express.js란 무엇인가?

🍽️ 음식점 비유로 이해하기

Node.js가 원재료(식재료)라면, Express.js는 주방 설비(가스레인지, 오븐, 도마 등)입니다.
원재료만으로도 요리를 만들 수 있지만, 주방 설비가 있으면 훨씬 빠르고 효율적으로 만들 수 있죠!

📊 Express.js vs 순수 Node.js 비교

🏢 Express.js를 사용하는 기업들

02 설치와 프로젝트 구조

🔧 프로젝트 초기 세팅

# 1. 프로젝트 폴더 생성
mkdir express-masterclass && cd express-masterclass

# 2. npm 초기화 (package.json 생성)
npm init -y

# 3. Express 설치
npm install express

# 4. 개발용 도구들 설치
npm install -D nodemon    # 파일 변경 시 자동 재시작

# 5. 필수 미들웨어들 설치
npm install dotenv cors helmet morgan

# 6. 버전 확인
node -e "console.log(require('./node_modules/express/package.json').version)"

📁 현업 표준 프로젝트 구조

express-masterclass/
├── src/
│   ├── routes/          # URL 경로 정의
│   │   ├── index.js     # 루트 라우터 (모든 라우터 통합)
│   │   ├── auth.routes.js
│   │   ├── user.routes.js
│   │   └── post.routes.js
│   ├── controllers/     # 요청/응답 처리
│   │   ├── auth.controller.js
│   │   ├── user.controller.js
│   │   └── post.controller.js
│   ├── services/        # 핵심 비즈니스 로직 (DB 접근 등)
│   │   ├── auth.service.js
│   │   └── user.service.js
│   ├── middleware/      # 미들웨어 함수들
│   │   ├── auth.middleware.js
│   │   ├── validate.middleware.js
│   │   └── error.middleware.js
│   ├── models/          # 데이터 모델 (DB 스키마)
│   ├── utils/           # 유틸리티 함수들
│   │   ├── ApiError.js  # 커스텀 에러 클래스
│   │   └── catchAsync.js
│   └── app.js           # Express 앱 설정
├── .env                 # ⚠️ 절대 Git에 올리지 않음!
├── .env.example         # 환경변수 예시 (팀원 공유용)
├── .gitignore
├── server.js            # 서버 시작점
└── package.json

📝 기본 설정 파일들

src/app.js

const express = require('express');
const cors = require('cors');
const helmet = require('helmet');
const morgan = require('morgan');
const routes = require('./routes');
const errorHandler = require('./middleware/error.middleware');

const app = express();

// ====== 보안 미들웨어 ======
app.use(helmet());              // 보안 HTTP 헤더 설정
app.use(cors({
  origin: process.env.CLIENT_URL || 'http://localhost:3001',
  credentials: true,         // 쿠키 허용
}));

// ====== 요청 파싱 미들웨어 ======
app.use(express.json({ limit: '10mb' }));        // JSON body 파싱
app.use(express.urlencoded({ extended: true }));  // form data 파싱

// ====== 로깅 미들웨어 ======
if (process.env.NODE_ENV !== 'test') {
  app.use(morgan('dev'));           // GET /api/users 200 15ms
}

// ====== 라우터 연결 ======
app.use('/api', routes);

// ====== 에러 핸들러 (반드시 마지막에!) ======
app.use(errorHandler);

module.exports = app;

03 라우팅 완전 정복

📊 HTTP 메서드와 CRUD 매핑

🔑 라우터 파라미터 3가지

const express = require('express');
const router = express.Router();

// 1. Route Parameters (:id) — URL 경로값
// GET /api/users/42
router.get('/:id', (req, res) => {
  const userId = req.params.id;          // '42' (문자열!)
  const numId = Number(userId);           // 42 (숫자로 변환)
  res.json({ userId: numId });
});

// 2. Query String (?page=1) — 쿼리값
// GET /api/users?page=2&limit=10&search=홍길동
router.get('/', (req, res) => {
  const {
    page = 1,         // 기본값 1
    limit = 10,        // 기본값 10
    search = '',       // 기본값 빈 문자열
    sort = 'createdAt', // 정렬 기준
  } = req.query;
  res.json({ page: Number(page), limit: Number(limit), search, sort });
});

// 3. Request Body — POST/PUT/PATCH 데이터
// POST /api/users Body: {"name":"홍길동","email":"hong@e.com"}
router.post('/', (req, res) => {
  const { name, email, password } = req.body;  // express.json() 필요!
  if (!name || !email) {
    return res.status(400).json({ error: 'name과 email은 필수입니다' });
  }
  res.status(201).json({ message: '생성 완료', user: { name, email } });
});

💡 router.route() 체이닝으로 코드 줄이기

// ❌ 중복 경로 반복 (나쁜 방법)
router.get('/:id', getUser);
router.put('/:id', updateUser);
router.delete('/:id', deleteUser);

// ✅ 체이닝으로 묶기 (좋은 방법)
router.route('/')
  .get(getAllUsers)
  .post(createUser);

router.route('/:id')
  .get(getUser)
  .put(updateUser)
  .patch(patchUser)
  .delete(deleteUser);

04 미들웨어 완전 정복

🏗️ 미들웨어 실행 흐름

📋 미들웨어 5가지 종류

💻 JWT 인증 미들웨어 직접 만들기 (현업 필수!)

// middleware/auth.middleware.js
const jwt = require('jsonwebtoken');

/**
 * JWT 인증 미들웨어
 * Authorization: Bearer <token> 헤더에서 토큰 검증
 */
const authenticate = (req, res, next) => {
  try {
    const authHeader = req.headers.authorization;
    if (!authHeader || !authHeader.startsWith('Bearer ')) {
      return res.status(401).json({
        success: false,
        message: '인증 토큰이 필요합니다',
      });
    }
    const token = authHeader.split(' ')[1];  // 'Bearer ' 이후 토큰만 추출
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;  // ⭐ 다음 핸들러에서 req.user로 접근 가능!
    next();              // ⭐ 다음 미들웨어/라우터로 이동
  } catch (err) {
    res.status(401).json({
      success: false,
      message: '유효하지 않은 토큰입니다',
    });
  }
};

/**
 * 권한 체크 미들웨어 (RBAC: Role-Based Access Control)
 * authenticate 이후에만 사용!
 */
const authorize = (...roles) => {
  return (req, res, next) => {
    if (!roles.includes(req.user.role)) {
      return res.status(403).json({
        success: false,
        message: '접근 권한이 없습니다',
      });
    }
    next();
  };
};

// 사용 예시:
// router.delete('/:id', authenticate, authorize('ADMIN'), deleteUser);

module.exports = { authenticate, authorize };

⚡ 자주 쓰는 서드파티 미들웨어 정리

05 요청/응답 처리 심화

📥 요청(Request) 객체 완전 분석

app.get('/debug', (req, res) => {
  console.log(req.method);              // 'GET'
  console.log(req.url);                 // '/debug?test=1'
  console.log(req.path);                // '/debug' (query 제외)
  console.log(req.params);              // { id: '42' } — URL 파라미터
  console.log(req.query);               // { test: '1' } — 쿼리스트링
  console.log(req.body);                // { name: '홍길동' } — Body 데이터
  console.log(req.headers);             // 모든 요청 헤더
  console.log(req.cookies);             // 쿠키 (cookie-parser 필요)
  console.log(req.ip);                  // 클라이언트 IP 주소
  console.log(req.user);                // 인증 미들웨어에서 설정한 사용자
  console.log(req.get('Content-Type'));  // 특정 헤더 값 조회
  console.log(req.is('application/json')); // Content-Type 확인
});

📤 응답(Response) 메서드 완전 정리

// 1. JSON 응답 (API에서 가장 많이 사용)
res.status(200).json({ success: true, data: user });

// 2. 파일 다운로드
res.download('/path/to/file.pdf', 'report.pdf');

// 3. 리다이렉트
res.redirect(301, 'https://newdomain.com');  // 영구 이동
res.redirect('/login');                      // 임시 이동 (302)

// 4. 쿠키 설정 (httpOnly로 XSS 방어)
res.cookie('refreshToken', token, {
  httpOnly: true,    // JS 접근 차단 (XSS 방어)
  secure: true,      // HTTPS에서만 전송
  sameSite: 'strict', // CSRF 방어
  maxAge: 7 * 24 * 60 * 60 * 1000, // 7일
});

// 5. 상태 코드만 전송
res.sendStatus(204);  // 204 No Content (DELETE 성공 시)

📊 HTTP 상태 코드 완전 정리 (현업 필수 암기!)

🎯 표준 API 응답 형식 (현업 표준)

// utils/response.js — 일관된 응답 형식
const successResponse = (res, data, message = '성공', statusCode = 200) => {
  return res.status(statusCode).json({
    success: true,
    message,
    data,
    timestamp: new Date().toISOString(),
  });
};

const paginatedResponse = (res, data, total, page, limit) => {
  return res.status(200).json({
    success: true,
    data,
    pagination: {
      total,
      page: Number(page),
      limit: Number(limit),
      totalPages: Math.ceil(total / limit),
      hasNext: page * limit < total,
    },
  });
};

module.exports = { successResponse, paginatedResponse };

06 MVC 패턴 & 구조 설계

🏗️ MVC 역할 분리

💻 MVC 패턴 실전 코드

routes/user.routes.js — URL 연결만!

const express = require('express');
const router = express.Router();
const userController = require('../controllers/user.controller');
const { authenticate } = require('../middleware/auth.middleware');

router.route('/')
  .get(userController.getAllUsers)
  .post(authenticate, userController.createUser);

router.route('/:id')
  .get(userController.getUserById)
  .put(authenticate, userController.updateUser)
  .delete(authenticate, userController.deleteUser);

module.exports = router;

controllers/user.controller.js — req/res 처리

const userService = require('../services/user.service');
const catchAsync = require('../utils/catchAsync');

// ✅ catchAsync 래퍼로 try-catch 없이 에러 처리
const getAllUsers = catchAsync(async (req, res) => {
  const { page = 1, limit = 10, search } = req.query;
  const result = await userService.findAllUsers({ page, limit, search });
  res.json({ success: true, ...result });
});

const getUserById = catchAsync(async (req, res) => {
  const user = await userService.findUserById(req.params.id);
  res.json({ success: true, data: user });
});

const createUser = catchAsync(async (req, res) => {
  const user = await userService.createUser(req.body);
  res.status(201).json({ success: true, data: user });
});

module.exports = { getAllUsers, getUserById, createUser };

services/user.service.js — 비즈니스 로직

const bcrypt = require('bcryptjs');
const prisma = require('../db/prisma');
const { ApiError } = require('../utils/ApiError');

const findAllUsers = async ({ page, limit, search }) => {
  const skip = (page - 1) * limit;
  const where = search
    ? { OR: [
        { name: { contains: search } },
        { email: { contains: search } },
      ]}
    : {};

  // Promise.all로 병렬 처리 (성능 최적화!)
  const [users, total] = await Promise.all([
    prisma.user.findMany({
      where, skip: Number(skip), take: Number(limit),
      select: { id: true, name: true, email: true, createdAt: true },
    }),
    prisma.user.count({ where }),
  ]);
  return { data: users, total, page: Number(page), totalPages: Math.ceil(total / limit) };
};

const findUserById = async (id) => {
  const user = await prisma.user.findUnique({
    where: { id: Number(id) },
    select: { id: true, name: true, email: true },
  });
  if (!user) throw new ApiError(404, '사용자를 찾을 수 없습니다');
  return user;
};

module.exports = { findAllUsers, findUserById };

07 REST API 설계 원칙

📐 REST URL 설계 원칙 (좋은 예 vs 나쁜 예)

📋 게시판 REST API 설계 완성 예시

08 유효성 검사 & 에러 처리

🛡️ Joi로 유효성 검사 (실전 패턴)

# 설치
npm install joi

// middleware/validate.middleware.js
const Joi = require('joi');

const schemas = {
  register: Joi.object({
    name: Joi.string().min(2).max(50).required()
      .messages({ 'any.required': '이름은 필수입니다' }),
    email: Joi.string().email().required()
      .messages({ 'string.email': '유효한 이메일 형식이 아닙니다' }),
    password: Joi.string()
      .pattern(new RegExp('^(?=.*[a-z])(?=.*[0-9]).{8,}$'))
      .required()
      .messages({ 'string.pattern.base': '비밀번호는 영문+숫자 8자 이상' }),
  }),
  createPost: Joi.object({
    title: Joi.string().min(1).max(200).required(),
    content: Joi.string().min(10).required(),
    tags: Joi.array().items(Joi.string()).max(5),
  }),
};

const validate = (schemaName) => (req, res, next) => {
  const { error, value } = schemas[schemaName].validate(req.body, { abortEarly: false });
  if (error) {
    const errors = error.details.map(d => d.message);
    return res.status(422).json({ success: false, errors });
  }
  req.body = value;  // 정제된 데이터로 교체
  next();
};

module.exports = { validate };

💥 글로벌 에러 핸들러 (완전 버전)

// utils/ApiError.js
class ApiError extends Error {
  constructor(statusCode, message, isOperational = true) {
    super(message);
    this.statusCode = statusCode;
    this.isOperational = isOperational;
  }
}

// utils/catchAsync.js — try-catch 없이 async 에러 처리!
const catchAsync = (fn) => (req, res, next) => {
  Promise.resolve(fn(req, res, next)).catch(next);
};

// middleware/error.middleware.js — 반드시 4개 인자!
const errorHandler = (err, req, res, next) => {
  let { statusCode = 500, message } = err;

  // Prisma 에러 처리
  if (err.code === 'P2002') { statusCode = 409; message = '이미 존재하는 데이터'; }
  if (err.code === 'P2025') { statusCode = 404; message = '데이터를 찾을 수 없습니다'; }
  
  // JWT 에러 처리
  if (err.name === 'JsonWebTokenError') { statusCode = 401; message = '유효하지 않은 토큰'; }
  if (err.name === 'TokenExpiredError') { statusCode = 401; message = '토큰이 만료되었습니다'; }

  const isDev = process.env.NODE_ENV === 'development';
  res.status(statusCode).json({
    success: false,
    message: message || '서버 내부 오류',
    ...isDev && { stack: err.stack },  // 개발 환경에서만 스택 노출
  });
};

module.exports = errorHandler;

09 인증(JWT) 완전 구현

🔐 JWT 구조 이해

🔑 회원가입 & 로그인 완전 구현

# 필요 패키지
npm install jsonwebtoken bcryptjs

// services/auth.service.js
const bcrypt = require('bcryptjs');
const jwt = require('jsonwebtoken');

const register = async ({ name, email, password }) => {
  const existing = await prisma.user.findUnique({ where: { email } });
  if (existing) throw new ApiError(409, '이미 사용 중인 이메일입니다');
  
  // ⭐ 비밀번호는 절대 평문 저장 금지! bcrypt로 해시화
  const hashedPw = await bcrypt.hash(password, 12);  // saltRounds: 12 권장
  
  const user = await prisma.user.create({
    data: { name, email, password: hashedPw },
    select: { id: true, name: true, email: true },  // 비밀번호 제외!
  });
  return user;
};

const login = async ({ email, password }) => {
  const user = await prisma.user.findUnique({ where: { email } });
  
  // ⭐ 보안 팁: 이메일 없어도 같은 메시지 사용 (계정 존재 여부 노출 방지)
  if (!user) throw new ApiError(401, '이메일 또는 비밀번호가 올바르지 않습니다');
  
  const isMatch = await bcrypt.compare(password, user.password);
  if (!isMatch) throw new ApiError(401, '이메일 또는 비밀번호가 올바르지 않습니다');

  // Access Token (짧은 수명) + Refresh Token (긴 수명) 패턴
  const accessToken = jwt.sign(
    { userId: user.id, role: user.role },
    process.env.JWT_SECRET,
    { expiresIn: '15m' }   // ⭐ Access Token은 짧게!
  );
  const refreshToken = jwt.sign(
    { userId: user.id },
    process.env.JWT_REFRESH_SECRET,
    { expiresIn: '7d' }
  );
  return { accessToken, refreshToken, user: { id: user.id, name: user.name } };
};

10 보안 & 성능 최적화

🔒 보안 필수 체크리스트

⚡ Rate Limiting 실전 설정

const rateLimit = require('express-rate-limit');

// 전역 API Rate Limit
const globalLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,  // 15분
  max: 100,                  // 100번까지
  standardHeaders: true,
  message: { error: '너무 많은 요청입니다. 잠시 후 다시 시도해주세요.' },
});

// 로그인 전용 (더 엄격하게)
const loginLimiter = rateLimit({
  windowMs: 60 * 1000,    // 1분
  max: 5,                  // 5번까지
  skipSuccessfulRequests: true,  // 성공한 요청은 카운트 안함
});

app.use('/api', globalLimiter);
app.use('/api/v1/auth/login', loginLimiter);

🚀 성능 최적화 핵심 기법

// 1. 응답 압축 (gzip) - 네트워크 트래픽 ~70% 감소
const compression = require('compression');
app.use(compression());

// 2. N+1 문제 방지 (DB 쿼리 최적화)
// ❌ N+1 문제 (사용자 10명이면 쿼리 11번!)
const posts = await prisma.post.findMany();
for (const post of posts) {
  post.author = await prisma.user.findUnique({ where: { id: post.authorId } });
}

// ✅ include로 한 번에 조인 (쿼리 1번!)
const posts = await prisma.post.findMany({
  include: { author: { select: { name: true, email: true } } },
});

// 3. 병렬 처리로 응답 속도 향상
// ❌ 순차 처리 (총 600ms)
const user = await getUser();     // 200ms
const posts = await getPosts();   // 200ms
const stats = await getStats();   // 200ms

// ✅ 병렬 처리 (총 200ms — 3배 빠름!)
const [user, posts, stats] = await Promise.all([
  getUser(), getPosts(), getStats()
]);

11 실전 프로젝트: 블로그 API 완전 구현

🗄️ Prisma 스키마 설계

// prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        Int       @id @default(autoincrement())
  name      String
  email     String    @unique
  password  String
  role      Role      @default(USER)
  posts     Post[]
  comments  Comment[]
  likes     Like[]
  createdAt DateTime  @default(now())
  updatedAt DateTime  @updatedAt
}

model Post {
  id         Int       @id @default(autoincrement())
  title      String
  content    String    @db.Text
  published  Boolean   @default(false)
  viewCount  Int       @default(0)
  tags       String[]
  author     User      @relation(fields: [authorId], references: [id])
  authorId   Int
  comments   Comment[]
  likes      Like[]
  createdAt  DateTime  @default(now())
  updatedAt  DateTime  @updatedAt
}

model Comment {
  id        Int      @id @default(autoincrement())
  content   String
  post      Post     @relation(fields: [postId], references: [id], onDelete: Cascade)
  postId    Int
  author    User     @relation(fields: [authorId], references: [id])
  authorId  Int
  createdAt DateTime @default(now())
}

model Like {
  userId Int
  postId Int
  user   User @relation(fields: [userId], references: [id])
  post   Post @relation(fields: [postId], references: [id], onDelete: Cascade)
  @@id([userId, postId])  // 복합 기본키 (중복 좋아요 방지!)
}

enum Role { USER ADMIN }

📮 Postman API 테스트 시나리오 (전체 흐름)

# ============ 1. 회원가입 ============
POST http://localhost:3000/api/v1/auth/register
Content-Type: application/json
{
  "name": "홍길동",
  "email": "hong@example.com",
  "password": "password123"
}
# 응답: 201 { "success": true, "data": { "id": 1, "name": "홍길동", "email": "..." } }

# ============ 2. 로그인 → 토큰 저장 ============
POST http://localhost:3000/api/v1/auth/login
# 응답의 accessToken을 복사해서 다음 요청에 사용!

# ============ 3. 게시글 작성 (토큰 필요) ============
POST http://localhost:3000/api/v1/posts
Authorization: Bearer <accessToken>
{
  "title": "첫 번째 게시글",
  "content": "Express.js 너무 재밌다!",
  "tags": ["express", "nodejs"]
}

# ============ 4. 게시글 목록 (페이지네이션) ============
GET http://localhost:3000/api/v1/posts?page=1&limit=5&search=Express

# ============ 5. 댓글 작성 ============
POST http://localhost:3000/api/v1/posts/1/comments
Authorization: Bearer <accessToken>
{ "content": "좋은 글이네요!" }

# ============ 6. 좋아요 ============
POST http://localhost:3000/api/v1/posts/1/likes
Authorization: Bearer <accessToken>

📂 파일 업로드 구현 (Multer)

npm install multer

const multer = require('multer');

const storage = multer.diskStorage({
  destination: './uploads/',
  filename: (req, file, cb) => {
    cb(null, Date.now() + '-' + file.originalname);
  },
});

const upload = multer({
  storage,
  limits: { fileSize: 5 * 1024 * 1024 },  // 5MB 제한
  fileFilter: (req, file, cb) => {
    if (file.mimetype.startsWith('image/')) cb(null, true);
    else cb(new Error('이미지 파일만 업로드 가능합니다'));
  },
});

router.post('/upload', authenticate, upload.single('image'), (req, res) => {
  res.json({
    filename: req.file.filename,
    url: '/uploads/' + req.file.filename,
  });
});

12 테스트 코드 작성법

# 설치
npm install -D jest supertest

// __tests__/auth.test.js
const request = require('supertest');
const app = require('../src/app');

describe('Auth API', () => {
  const testUser = {
    name: '테스트 유저',
    email: 'test@example.com',
    password: 'password123',
  };

  describe('POST /api/v1/auth/register', () => {
    it('201 - 회원가입 성공', async () => {
      const res = await request(app)
        .post('/api/v1/auth/register')
        .send(testUser);

      expect(res.status).toBe(201);
      expect(res.body.success).toBe(true);
      expect(res.body.data.email).toBe(testUser.email);
      expect(res.body.data.password).toBeUndefined();  // 비밀번호 노출 방지 확인!
    });

    it('422 - 유효성 검사 실패', async () => {
      const res = await request(app)
        .post('/api/v1/auth/register')
        .send({ ...testUser, email: 'not-an-email' });
      expect(res.status).toBe(422);
    });

    it('409 - 중복 이메일', async () => {
      await request(app).post('/api/v1/auth/register').send(testUser);
      const res = await request(app).post('/api/v1/auth/register').send(testUser);
      expect(res.status).toBe(409);
    });
  });

  describe('POST /api/v1/auth/login', () => {
    it('200 - 로그인 성공, 토큰 반환', async () => {
      const res = await request(app)
        .post('/api/v1/auth/login')
        .send({ email: testUser.email, password: testUser.password });
      expect(res.status).toBe(200);
      expect(res.body.data).toHaveProperty('accessToken');
    });
  });
});

13 현업/면접 단골 Q&A

14 백엔드 개발자 학습 로드맵