TK-FB-Project/api.hyungi.net/utils/errors.js

/**
 * 커스텀 에러 클래스
 *
 * 애플리케이션 전체에서 사용하는 표준화된 에러 클래스들
 *
 * @author TK-FB-Project
 * @since 2025-12-11
 */

/**
 * 기본 애플리케이션 에러 클래스
 * 모든 커스텀 에러의 부모 클래스
 */
class AppError extends Error {
  /**
   * @param {string} message - 에러 메시지
   * @param {number} statusCode - HTTP 상태 코드
   * @param {string} code - 에러 코드 (예: 'VALIDATION_ERROR')
   * @param {object} details - 추가 세부 정보
   */
  constructor(message, statusCode = 500, code = 'INTERNAL_ERROR', details = null) {
    super(message);
    this.name = this.constructor.name;
    this.statusCode = statusCode;
    this.code = code;
    this.details = details;
    this.isOperational = true; // 운영 에러 (예상된 에러)

    Error.captureStackTrace(this, this.constructor);
  }

  /**
   * JSON 형태로 에러 정보 반환
   */
  toJSON() {
    return {
      name: this.name,
      message: this.message,
      statusCode: this.statusCode,
      code: this.code,
      details: this.details
    };
  }
}

/**
 * 검증 에러 (400 Bad Request)
 * 입력값 검증 실패 시 사용
 */
class ValidationError extends AppError {
  /**
   * @param {string} message - 에러 메시지
   * @param {object} details - 검증 실패 세부 정보
   */
  constructor(message = '입력값이 올바르지 않습니다', details = null) {
    super(message, 400, 'VALIDATION_ERROR', details);
  }
}

/**
 * 인증 에러 (401 Unauthorized)
 * 인증이 필요하거나 인증 실패 시 사용
 */
class AuthenticationError extends AppError {
  /**
   * @param {string} message - 에러 메시지
   */
  constructor(message = '인증이 필요합니다') {
    super(message, 401, 'AUTHENTICATION_ERROR');
  }
}

/**
 * 권한 에러 (403 Forbidden)
 * 권한이 부족할 때 사용
 */
class ForbiddenError extends AppError {
  /**
   * @param {string} message - 에러 메시지
   */
  constructor(message = '권한이 없습니다') {
    super(message, 403, 'FORBIDDEN');
  }
}

/**
 * 리소스 없음 에러 (404 Not Found)
 * 요청한 리소스를 찾을 수 없을 때 사용
 */
class NotFoundError extends AppError {
  /**
   * @param {string} message - 에러 메시지
   * @param {string} resource - 찾을 수 없는 리소스명
   */
  constructor(message = '리소스를 찾을 수 없습니다', resource = null) {
    super(message, 404, 'NOT_FOUND', resource ? { resource } : null);
  }
}

/**
 * 충돌 에러 (409 Conflict)
 * 중복된 리소스 등 충돌 발생 시 사용
 */
class ConflictError extends AppError {
  /**
   * @param {string} message - 에러 메시지
   * @param {object} details - 충돌 세부 정보
   */
  constructor(message = '이미 존재하는 데이터입니다', details = null) {
    super(message, 409, 'CONFLICT', details);
  }
}

/**
 * 서버 에러 (500 Internal Server Error)
 * 예상하지 못한 서버 오류 시 사용
 */
class InternalServerError extends AppError {
  /**
   * @param {string} message - 에러 메시지
   */
  constructor(message = '서버 오류가 발생했습니다') {
    super(message, 500, 'INTERNAL_SERVER_ERROR');
  }
}

/**
 * 데이터베이스 에러 (500 Internal Server Error)
 * DB 관련 오류 시 사용
 */
class DatabaseError extends AppError {
  /**
   * @param {string} message - 에러 메시지
   * @param {Error} originalError - 원본 DB 에러
   */
  constructor(message = '데이터베이스 오류가 발생했습니다', originalError = null) {
    super(
      message,
      500,
      'DATABASE_ERROR',
      originalError ? { originalMessage: originalError.message } : null
    );
    this.originalError = originalError;
  }
}

/**
 * 외부 API 에러 (502 Bad Gateway)
 * 외부 서비스 호출 실패 시 사용
 */
class ExternalApiError extends AppError {
  /**
   * @param {string} message - 에러 메시지
   * @param {string} service - 외부 서비스명
   */
  constructor(message = '외부 서비스 호출에 실패했습니다', service = null) {
    super(message, 502, 'EXTERNAL_API_ERROR', service ? { service } : null);
  }
}

/**
 * 타임아웃 에러 (504 Gateway Timeout)
 * 요청 처리 시간 초과 시 사용
 */
class TimeoutError extends AppError {
  /**
   * @param {string} message - 에러 메시지
   * @param {number} timeout - 타임아웃 시간 (ms)
   */
  constructor(message = '요청 처리 시간이 초과되었습니다', timeout = null) {
    super(message, 504, 'TIMEOUT_ERROR', timeout ? { timeout } : null);
  }
}

module.exports = {
  AppError,
  ValidationError,
  AuthenticationError,
  ForbiddenError,
  NotFoundError,
  ConflictError,
  InternalServerError,
  DatabaseError,
  ExternalApiError,
  TimeoutError
};