REST API 실전 프로젝트 완벽 가이드

실무에서 바로 사용할 수 있는 REST API 설계와 구현 방법을 단계별로 학습합니다. Express.js를 활용한 실전 프로젝트로 API 개발의 핵심 개념을 마스터하세요.

---

---

들어가며

이 글에서는 REST API 실전 프로젝트 완벽 가이드에 대해 상세히 알아보겠습니다. 총 12가지 주요 개념을 다루며, 각각의 개념에 대한 설명과 실제 코드 예제를 함께 제공합니다.

목차

1. Express_서버_기본_설정
2. RESTful_라우팅_구조
3. 컨트롤러_함수_구현
4. 에러_핸들링_미들웨어
5. 요청_유효성_검증
6. JWT_인증_구현
7. 페이지네이션_구현
8. CORS_설정
9. Rate_Limiting
10. API_응답_형식_표준화
11. 비동기_에러_처리_래퍼
12. API_버전_관리

---

1. Express 서버 기본 설정

개요

Express.js로 REST API 서버의 기본 구조를 설정합니다. 미들웨어와 라우팅을 포함한 서버 초기화 코드입니다.

코드 예제

const express = require('express');
const app = express();

app.use(express.json());
app.use(express.urlencoded({ extended: true }));

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

설명

Express 서버를 생성하고 JSON 파싱 미들웨어를 추가한 후 3000번 포트에서 서버를 실행합니다.

---

2. RESTful 라우팅 구조

개요

REST 원칙에 따라 CRUD 작업을 위한 라우팅을 설계합니다. HTTP 메서드와 URL 패턴을 올바르게 매핑합니다.

코드 예제

app.get('/api/users', getAllUsers);
app.get('/api/users/:id', getUserById);
app.post('/api/users', createUser);
app.put('/api/users/:id', updateUser);
app.delete('/api/users/:id', deleteUser);

설명

각 HTTP 메서드(GET, POST, PUT, DELETE)를 사용하여 사용자 리소스에 대한 CRUD 작업을 정의합니다.

---

3. 컨트롤러 함수 구현

개요

실제 비즈니스 로직을 처리하는 컨트롤러 함수를 작성합니다. 요청 처리와 응답 반환을 담당합니다.

코드 예제

const getAllUsers = async (req, res) => {
  try {
    const users = await User.find();
    res.status(200).json({ success: true, data: users });
  } catch (error) {
    res.status(500).json({ success: false, message: error.message });
  }
};

설명

비동기 함수로 데이터베이스에서 모든 사용자를 조회하고, 성공 시 200 상태코드와 함께 JSON 응답을 반환합니다.

---

4. 에러 핸들링 미들웨어

개요

API 전반에서 발생하는 에러를 중앙에서 처리하는 미들웨어입니다. 일관된 에러 응답 형식을 제공합니다.

코드 예제

const errorHandler = (err, req, res, next) => {
  const statusCode = err.statusCode || 500;
  res.status(statusCode).json({
    success: false,
    message: err.message,
    stack: process.env.NODE_ENV === 'development' ? err.stack : undefined
  });
};

설명

모든 에러를 캐치하여 상태코드와 메시지를 포함한 일관된 형식으로 응답하며, 개발 환경에서는 스택 트레이스도 포함합니다.

---

5. 요청 유효성 검증

개요

클라이언트로부터 받은 데이터의 유효성을 검증합니다. 잘못된 데이터로 인한 오류를 사전에 방지합니다.

코드 예제

const validateUser = (req, res, next) => {
  const { email, password } = req.body;
  if (!email || !password) {
    return res.status(400).json({ message: '이메일과 비밀번호는 필수입니다' });
  }
  if (!/^\S+@\S+\.\S+$/.test(email)) {
    return res.status(400).json({ message: '유효한 이메일을 입력하세요' });
  }
  next();
};

설명

미들웨어로 이메일과 비밀번호의 존재 여부와 형식을 검증하고, 유효하지 않으면 400 에러를 반환합니다.

---

6. JWT 인증 구현

개요

JSON Web Token을 사용하여 API 인증을 구현합니다. 토큰 생성과 검증으로 보안을 강화합니다.

코드 예제

const jwt = require('jsonwebtoken');

const generateToken = (userId) => {
  return jwt.sign({ id: userId }, process.env.JWT_SECRET, { expiresIn: '7d' });
};

const verifyToken = (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) return res.status(401).json({ message: '인증 토큰이 필요합니다' });
  try {
    req.user = jwt.verify(token, process.env.JWT_SECRET);
    next();
  } catch (error) {
    res.status(401).json({ message: '유효하지 않은 토큰입니다' });
  }
};

설명

JWT를 생성하는 함수와 요청 헤더에서 토큰을 추출하여 검증하는 미들웨어를 구현합니다.

---

7. 페이지네이션 구현

개요

대량의 데이터를 효율적으로 전달하기 위해 페이지네이션을 구현합니다. 쿼리 파라미터로 페이지와 크기를 제어합니다.

코드 예제

const getPaginatedUsers = async (req, res) => {
  const page = parseInt(req.query.page) || 1;
  const limit = parseInt(req.query.limit) || 10;
  const skip = (page - 1) * limit;

  const users = await User.find().skip(skip).limit(limit);
  const total = await User.countDocuments();

  res.json({ page, limit, total, data: users });
};

설명

쿼리 파라미터로 받은 페이지와 개수를 사용하여 데이터를 나눠서 조회하고, 전체 개수와 함께 응답합니다.

---

8. CORS 설정

개요

Cross-Origin Resource Sharing을 설정하여 다른 도메인에서의 API 접근을 허용합니다.

코드 예제

const cors = require('cors');

const corsOptions = {
  origin: ['http://localhost:3000', 'https://myapp.com'],
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  credentials: true
};

app.use(cors(corsOptions));

설명

특정 도메인과 HTTP 메서드만 허용하도록 CORS를 설정하여 보안을 유지하면서 크로스 도메인 요청을 처리합니다.

---

9. Rate Limiting

개요

API 요청 횟수를 제한하여 서버를 보호합니다. DDoS 공격이나 과도한 요청을 방지합니다.

코드 예제

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

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15분
  max: 100, // 최대 100회
  message: '너무 많은 요청이 발생했습니다. 잠시 후 다시 시도하세요.'
});

app.use('/api/', limiter);

설명

15분 동안 최대 100회의 요청만 허용하도록 제한하여 서버를 남용으로부터 보호합니다.

---

10. API 응답 형식 표준화

개요

모든 API 응답을 일관된 형식으로 반환하는 헬퍼 함수를 만듭니다. 클라이언트가 예측 가능한 응답을 받을 수 있습니다.

코드 예제

class ApiResponse {
  static success(res, data, message = 'Success', statusCode = 200) {
    return res.status(statusCode).json({
      success: true,
      message,
      data
    });
  }

  static error(res, message = 'Error', statusCode = 500) {
    return res.status(statusCode).json({
      success: false,
      message
    });
  }
}

설명

성공과 실패 응답을 일관된 형식으로 반환하는 클래스를 만들어 API 응답의 표준화를 달성합니다.

---

11. 비동기 에러 처리 래퍼

개요

async/await 함수에서 발생하는 에러를 자동으로 처리하는 래퍼 함수입니다. try-catch 반복을 줄입니다.

코드 예제

const asyncHandler = (fn) => (req, res, next) => {
  Promise.resolve(fn(req, res, next)).catch(next);
};

// 사용 예제
app.get('/api/users', asyncHandler(async (req, res) => {
  const users = await User.find();
  res.json({ success: true, data: users });
}));

설명

비동기 함수를 래핑하여 에러가 발생하면 자동으로 next()를 호출해 에러 핸들러로 전달합니다.

---

12. API 버전 관리

개요

API의 버전을 관리하여 하위 호환성을 유지하면서 새로운 기능을 추가합니다.

코드 예제

const v1Router = express.Router();
const v2Router = express.Router();

v1Router.get('/users', getAllUsersV1);
v2Router.get('/users', getAllUsersV2);

app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);

설명

URL 경로에 버전을 포함시켜 여러 버전의 API를 동시에 운영하고, 기존 클라이언트와의 호환성을 유지합니다.

---

마치며

이번 글에서는 REST API 실전 프로젝트 완벽 가이드에 대해 알아보았습니다. 총 12가지 개념을 다루었으며, 각각의 사용법과 예제를 살펴보았습니다.

관련 태그

#JavaScript #RESTful #Express #API Design #Middleware