safeFetch 유틸함수 만들기(1) : Error 클래스 정의

safeFetch 유틸함수 만들기(1) : Error 클래스 정의

2025. 12. 12. 00:30ㆍTrouble Shooting & Issues/Linkiving

✔️ FetchError : 응답 받는 중 발생한 에러 클래스 생성
✔️ TimeoutError : 지정된 시간 내 응답을 받지 못했을 때 발생하는 에러 클래스 생성
✔️ ParseError : 응답은 받았으나, 파싱 중 발생한 에러 클래스 생성
✔️ Error를 상속받으며, constructor 생성자 함수로 super(message)로 표준 에러 초기화, 각 클래스에 맞는 인스턴스 지정을 한다.

1. safeFetch: 서버용 안전한 fetch 함수

이건 사실 여기저기 알아보기보다는 이전에 주먹구구로 작성했던 기억을 바탕으로 ai 기반으로 시도해보는 것이다.

우선 당장 api에 약하기도 하고.. 쓸모가 없을지라도 하나하나 자세하게 알아보면서 수정하거나 없애거나 라이브러리를 사용하거나 추가하거나 할 수 있을 것이다.

우선 에러가 발생했을 경우, 에러 바디를 세팅하는 Error 클래스들을 작성해보자.

2. FetchError : 응답 받는 중 발생한 에러

HTTP 응답이 ok가 아니거나(200~299 범위가 아님) 네트워크 에러를 범주화할 때 사용하는 오류이다.

상태 코드(status), 응답 본문 일부(body), Content-Type(contentType)과 같은 추가 메타를 담는다.

FetchError가 잡는 예시 상황으로는 아래와 같은 경우들이 있을 것이다.

백엔드(외부 API)에서 오류 상태 코드가 왔을 경우
→ 404 Not Found (요청 오류)
→ 500 Internal Server Error (서버 오류)
→ 429 (요청 과다)
응답 Content-Type이 예상한 형식이 아닐 때
→ JSON 형식 응답을 기대했는데 text/html이 오는 오류

✅ HTML이 떨어지는 오류
API 서버에 JSON을 요청했는데, 비정상적으로 HTML 문서 응답을 받을 수도 있다.
⋅ API 서버 내부 오류로 500 Error Page(HTML)이 반환됨
⋅ 인증 실패 시 로그인 페이지(HTML)을 강제로 리다이렉트하여 반환
⋅ nginx 등 중간 프록시 서버가 HTML 에러 페이지를 반환

이런 경우 클라이언트는 아래와 같은 HTML을 받을 수 있다.
<!DOCTYPE html>
<html>
<body>500 Internal Server Error</body>
</html>

이럴 경우 res.json()을 수행하면 파싱 오류가 발생할 수 있고, Content-Type이 text/html로, 잘못된 응답임을 확인할 수 있다.

코드

export class FetchError extends Error {
  public status?: number;
  public body?: string;
  public contentType?: string | null;
  constructor(message: string, opts?: { status?: number; body?: string; contentType?: string | null }) {
    super(message);
    this.name = 'FetchError';
    this.status = opts?.status;
    this.body = opts?.body;
    this.contentType = opts?.contentType ?? null;
  }
}

Error : Error를 상속받아 표준 에러 관련 00을 사용할 수 있다.
status, body, contentType : 인스턴스 필드를 선언했다.
응답을 받아오는 도중 에러가 발생한다면 그건 상태코드, 응답 본문, content type으로부터 왜 발생했는지 확인할 수 있기 때문에 세 가지를 선언했다.
constructor(...) {... : 에러 생성자를 정의한다.
message : Error의 기본 메세지
opts : 위에서 정의한 인스턴스
super(message) : 부모 클래스인 Error의 생성자를 호출하여 message, 스택 트레이스 등의 표준 에러 초기화를 한다.
this.name : Error.name을 명시적으로 설정한다. 로깅/분기에서 err.name으로 에러 타입을 판별할 때 사용한다.
추후 handleError와 같은 유틸 함수를 작성할 때 (err instanceof FetchError)와 같은 식으로 사용할 수 있다.
this.status : opts가 있을 경우 status 값을 할당하고, 없으면 undefined로 남는다.
this.body : 에러 응답 본문을 할당한다. (디버깅, 모니터링에 사용한다)
this.contentType : contentType을 할당하되, 없을 경우 null을 명시적으로 넣어 헤더가 없음을 표시한다.

✅ JS 클래스 문법 생성자
이 FetchError라는 클래스가 처음 만들어질 때 호출되는 함수(즉, 초기 세팅을 하는 함수)가 생성자이다.
클래스의 인스턴스를 초기화하는 방식을 정의한다.
이 생성자는 인자로 message, opts를 받아서 초기 세팅을 진행한다.

* super() : 부모 클래스의 생성자를 호출하는 기능을 한다.
FetchError는 Error를 상속하므로 Error의 기본 기능인 stack trace, message 저장 등의 Error 초기화 과정을 먼저 수행한다.

* this : 현재 만들고 있는 해당 에러 인스턴스인 자기 자신을 가리킨다.
새로 생성한 이 객체의 name, status, body, contentType을 지정하는 것이다.

3. TimeoutError : 응답이 지정된 시간 내에 오지 않았을 때의 에러

요청이 AbortController 등에 의해 취소되었을 때 던지는 오류이다.

fetch는 기본적으로 타임아웃이 없기때문에 지정한 시간 안에 응답을 받지 못하면 AbortController로 강제 종료하고, 그 때 발생한 오류를 잡는 것이다.

✅ AbortController란?
브라우저와 Node 환경에서 지원되는 요청 취소 API이다.
fetch 요청에 연결하면 AbortController가 특정 시점에 요청을 강제로 중단할 수 있다.
대표적 용도로는 아래와 같이 있다.
⋅ 타임아웃 : 일정 시간 내 응답이 없으면 요청 취소
⋅ 중복 요청 취소 : 검색 자동완성처럼 이전 요청을 취소
⋅ 컴포넌트 언마운트(cleanup) 시 네트워크 요청 취소

코드

export class TimeoutError extends Error {
  constructor(message = 'Request timed out') {
    super(message);
    this.name = 'TimeoutError';
  }
}

constructor: 생성자는 메세지를 선택적으로 받으며, 기본값은 'Request timed out'이다.
super(message) : 부모인 Error의 생성자를 호출해 message와 스택을 초기화한다.
this.name : name을 설정하여 타입 판별을 쉽게 하도록 한다.
instanceof 검사로도 해당 에러가 TimeoutError임을 구분할 수 있다.
예를 들어 아래와 같이 활용할 수 있다.
if (err.name === 'TimeoutError')

4. ParseError : 응답은 받았으나, 파싱 중 발생한 에러

응답을 정상적으로 받아왔으나, JSON으로 파싱하는 단계에서 실패했을 때 던지는 오류이다.

파싱 실패 원인 추적을 위해 원본문 일부를 포함할 수 있다.

JSON 형식이 깨져있는 경우
응답이 빈 문자열인 경우
서버가 잘못된 포맷을 반환한 경우

export class ParseError extends Error {
  public raw?: string;
  constructor(message = 'Failed to parse response', raw?: string) {
    super(message);
    this.name = 'ParseError';
    this.raw = raw;
  }
}

public raw? : 파싱 실패 시 원시 응답 텍스트를 담는 필드로, 디버깅을 위해 정의한다.
기본 메세지는 'Failed to parse response'이며, 두번째 인자로 원본문의 일부를 받을 수 있다.
super(message) : 기본 Error 초기화를 수행한다.
this.name : 'ParseError'로 에러 네임을 설정해 에러 판별 및 로깅 표준화를 돕는다.
this.raw : 원본문을 인스턴스에 보관하여 호출부가 상세 내용을 확인할 수 있도록 한다.

5. 노션 문서화

작성해보니 문서화를 해두면 좋겠다는 생각이 들어, 노션 페이지를 생성하고 적어봤다.

'Trouble Shooting & Issues > Linkiving' 카테고리의 다른 글

Docker 설치해서 백엔드 로컬로 로그인 테스트하기 [Linkiving] (0)	2026.02.27
safeFetch 유틸함수 만들기(2): safeFetch 함수 작성 (0)	2025.12.12
Next.js app router로 api 함수 작성하기 (0)	2025.11.27
[Next.js] 사용자가 입력한 링크의 썸네일 가져오기 (0)	2025.11.17
인터렉션이 가능한 태그 중첩 안시키기 (0)	2025.11.05

🥔 감자의 오묘한 개발 🥔