safeFetch 유틸함수 만들기(2): safeFetch 함수 작성

 

✔️ SafeFetchOptions를 정의하여 RequestInit(method, headers, ...) 외 추가적인 옵션을 활용하여 fetch한다.
✔️ safeFetch에서는 HTTP 상태 코드 체크, 본문 및 에러 길이 검사, content type 검사, 파싱 에러 검사 등을 진행하여 안전한 fetch를 진행하며, 안정적인 에러를 던진다.

목차

1. SafeFetchOptions : safeFetch가 받을 추가 옵션

2. safeFetch() : 각종 에러 처리를 하여 안전한 fetch를 하는 함수

 

 

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

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

 

---

1. SafeFetchOptions : safeFetch가 받을 추가 옵션

safeFetch에 추가 기능을 설정할 수 있도록 만든 옵션 타입이다.

기본 fetch()의 RequestInit 옵션은 단순 요청 설정만 가능하지만, 실제 사용할 때는

추가적인 안정성,검증,보안,디버깅 기능이 필요하기 때문에 확장된 옵션을 작성했다.

 

✅ RequestInit이란?
브라우저 Fetch API의 표준 타입으로, fetch()의 두번째 인자에 들어가는 모든 옵션 집합이다.
method, headers, body, signel, credentials, mode, cache, redirect, referrer, referrerPolicy, integrity, keepalive 등이 포함된다.

 

 

export interface SafeFetchOptions extends RequestInit {
  timeout?: number;
  expectJson?: boolean;
  maxResponseBytes?: number;
  maxErrorBodyBytes?: number;
}

• timeout : 요청이 지정 시간 timeout 내에 끝나지 않았을 경우 TimeoutError를 발생시키기 위한 조건
• expectJson : true일 경우, Content-Type: application/json 여부를 검사한다.
  대부분의 API는 JSON을 내려주지만, 예외적으로 텍스트나 파일을 주는 경우도 있기 때문에 사전검증 요소를 넣는다.
• maxResponseBytes : 응답 본문 길이를 검사하여 지정한 바이트 수를 초과할 경우, 안전상 이유로 요청을 실패 처리한다.
  서버 오류나 악의적 응답으로 매우 큰 데이터를 받을 경우, 메모리 급증, 브라우저 탭 다운, 성능 이슈 등이 발생할 수 있기 때문에 이를 사전 방어하는 옵션이다.
• maxErrorBodyBytes : 파싱 실패시 ParseError.raw에 포함할 본문 최대 길이를 제한한다.
  parse 에러로 인해 받은 raw body를 그대로 넣으면 로그가 너무 커져 저장 비용이 증가하고 콘솔이 난잡해질 수 있기 때문이다.

 

---

2. safeFetch() : 각종 에러 처리를 하여 안전한 fetch를 하는 함수

드디어 safeFetch를 작성할 차례가 왔다.

 

2-1. 함수 선언부

export async function safeFetch<T = unknown>(url: string, options: SafeFetchOptions = {}): Promise<T>
  { ... }

우선 함수 선언부는 이와 같이 작성된다.

url, options를 props로 받아 네트워크 요청을 하고, 성공 시 제네릭 T 타입의 값을 비동기로 반환하거나 에러를 던지는 동작을 수행한다.

이 때 options는 위에서 정의했던 SafeFetchOptions 타입이며, 기본값은 빈 객체이다.

 

✅ T(제네릭)이란?
T는 호출자가 기대하는 응답 데이터의 타입을 나타내는 타입 매개변수이다.
만약 safeFetch<User>라고 호출하면 TS는 T 자리에 User를 넣어 safeFetch가 Promise<User>를 반환하는 것으로 간주하여 타입 검사를 진행한다.

type User = { id: string; name: string };
const user = await safeFetch<User>('/api/me');

단, T는 컴파일 시의 도움으로, 런타임에서 실제로 서버가 올바른 User 형식을 보냈는지는 검증하지 않는다.
런타임 검증을 하고싶다면 zod와 같은 라이브러리를 함께 사용해야한다.

 

 

 

2-2. options 초기화

const {
    timeout = 10_000,
    expectJson = true,
    maxResponseBytes,
    maxErrorBodyBytes = 1024 * 8, // 에러시에 로깅할 최대 바이트
    ...fetchOptions
  } = options;

함수가 시작하면 options를 초기화부터 한다.

• timeout : 요청 타임아웃(ms)으로, 기본값은 10초이다.
• expectJson : 기본적으로 JSON 응답을 기대한다.
• maxResponseBytes : 존재 시, 응답 크기 제한 검사에 사용한다. (기본값은 없음)
• maxErrorBodyBytes : 에러 로깅 시 포함할 최대 바이트이다. (기본값 8KB)
• ...fetchOptions : RequestInit에서 받은 나머지 옵션(method, headers,body, credentials emd)들이다.

이 때 fetchOptions에 signal이 들어있다면 이전에 작성한 controller.signal로 덮어쓰게 되므로 이부분에 대한 규칙을 정해야한다.

 

✅ 함수 시그니처에서 빈 객체를 기본값으로 주고 실제 디폴트 값 지정을 함수 내부에서 한 이유
SafeFetchOptions에만 해당하는 옵션과 RequestInit 옵션을 자연스럽게 분리할 수 있다.
실제로 위 코드를 보면 timeout, expectJson, maxResponseBytes, maxErrorBodyBytes와 fetchOptions로 구조분해를 했다. 이를 통해 라이브러리 자체 확장 옵션과 Fetch에 그대로 전달하는 fetchOptions를 명확하게 나눌 수 있다.

 

 

2-3. AbortController 생성 및 타임아웃 설정

const controller = new AbortController();
const id = setTimeout(() => controller.abort(), timeout);

• controller : new AbortController()로 요청을 취소할 수 있는 컨트롤러를 만든다.
• id : setTimeout()이 반환하는 타이머 핸들을 저장하는 변수이다.
  setTimeout()은 숫자, 혹은 Timeout 객체를 반환한다. 타이머를 취소하기 위해 이 값을 보관해두는 것이다.
  지정한 timeout 이후에 setTimeout으로 controller.abort()를 실행하여 강제종료를 한다.
  여기서 선언한 id는 이후 finally에서 clearTimeout(id)로 반드시 해제해야 메모리/타이밍 이슈를 막는다.

 

2-4. try문 실행

이제부터 나올 try문이 좀 긴데 내용을 보면 대강 아래와 같이 진행된다.

1. fetch 호출 → res = await fetch( ... )

2. HTTP 상태 코드 체크 → if (!res.ok) { ... }

3. Content가 있을 경우 Length 검사 → if (typeof maxResponseBytes === 'number') { ... }

4. JSON 기대 시 Content-Type 검사 → if (expectJson) { ... }

5. JSON 파싱 → try { ... }

 

1. fetch 호출

try {
    const res = await fetch(url, { ...fetchOptions, signal: controller.signal });

• fetchOptions를 전달하며 signal로 AbortController를 연결한다.
• await을 걸어서 응답을 기다리며, 이 단계에서 에러가 나면 catch에서 처리한다.

2. HTTP 상태 코드 체크

if (!res.ok) {
      // 에러 바디 읽기 (작게 제한)
      let bodyText: string | undefined;
      try {
        const text = await res.text();
        bodyText = text.length > maxErrorBodyBytes ? text.slice(0, maxErrorBodyBytes) + '…' : text;
      } catch {
        bodyText = undefined;
      }
      throw new FetchError(`Request failed with status ${res.status}`, {
        status: res.status,
        body: bodyText,
        contentType: res.headers.get('content-type'),
      });
    }

fetch로 응답(res)을 받아왔는데 res.ok가 false이면 서버가 오류를 반환한 것으로, FetchError를 던진다.

• res.text() : 에러 바디를 문자열로 읽어 디버깅용으로 일부를 저장한다.
  이 때 body가 너무 길 경우, maxErrorBodyBytes만큼 자른다.
• throw new FetchError : 응답으로 받은 status, body, contentType을 포함한 커스텀 에러를 던진다.

 

3. Content가 있을 경우 Length 검사

if (typeof maxResponseBytes === 'number') {
      const cl = res.headers.get('content-length');
      if (cl && !isNaN(Number(cl)) && Number(cl) > maxResponseBytes) {
        throw new FetchError(`Response too large: ${cl} bytes`, {
          contentType: res.headers.get('content-type'),
        });
      }
    }

maxResponseBytes를 지정했을 경우 실행되는 코드이다.

Content-Length 헤더를 읽었을 때 응답이 너무 크면 실패 처리를 한다.

• cl : 응답 중 'content-length' 헤더의 값을 cl에 저장한다.
• cl이 너무 크거나 maxResponseBytes보다 크다면 message, content-type을 지정하여 FetchError를 던진다.

단, Content-Length 헤더는 항상 존재하지 않는다. 헤더가 없을 경우 이 검사는 무시된다.

 

✅ 어떤 경우에 Content-Length 헤더가 없는 걸까
1. 청크 전송
: HTML/1.1에서 본문 길이를 미리 알 수 없을 때 데이터를 조각(chunk) 단위로 보낸 후 마지막에 종료 신호를 보낸다.
2. 스트리밍 응답 (Server-Sent Events, Web-ready JSON stream 등)
3. gzip 등의 압축된 응답을 흘려 보내는 경우 : 압축 전 원본 크기를 서버가 모를 수 있음
4. 프록시/리버스 프록시가 content-length를 제거하는 경우

 

 

 

4. JSON 기대 시 Content-Type 검사

const contentType = res.headers.get('content-type');
    if (expectJson) {
      if (!contentType || !contentType.includes('application/json')) {
        // 일부 API는 애매하게 application/json; charset=utf-8 으로 오므로 includes 사용
        const snippet = await res.clone().text().catch(() => undefined);
        throw new FetchError('Invalid content-type, expected JSON', {
          contentType,
          body: snippet ? snippet.slice(0, maxErrorBodyBytes) : undefined,
        });
      }
    }

expectJson이 true일 경우, Content-Type에 application/json이 포함되었는지 확인하고, 없으면 FetchError를 던진다.

• 일부 API는 application/json; charset=utf-8과 같이 파라미터가 붙어올 수도 있기에 includes를 사용한다.
• 타입이 불일치하면 디버깅용으로 일부 body(snippet)를 읽어서 FetchError에 body로 넣는다.
• 이 때 res.text(), res.json()은 body를 소비하기 때문에 진단용으로 body를 읽을 때는 clone()을 사용하는 것이 좋다.

 

5. JSON 파싱

try {
      const json = (await res.json()) as T;    // 제네릭 T로 반환
      return json;
    } catch (err) {
      let raw: string | undefined;  // 파싱 실패시 원본 일부를 추출해서 포함
      try {
        raw = await res.text();
      } catch {
        raw = undefined;
      }
      throw new ParseError('Failed to parse JSON response', raw?.slice(0, maxErrorBodyBytes));
    }
  }

• const json : await을 걸고 JSON을 파싱한다. 성공하면 제네릭 T로 캐스팅하여 반환한다.
• 파싱 실패 시 catch로 잡아서 ParseError에 raw를 담아 던진다.

 

2-5. catch (err)

catch (err) {
    if (err instanceof Error && (err.name === 'AbortError' || (err as any).name === 'TimeoutError')) {
      throw new TimeoutError(`Request to ${url} aborted after ${timeout}ms`);
    }
    if (err instanceof FetchError || err instanceof ParseError || err instanceof TimeoutError) {
      throw err;
    }
    throw new FetchError(String(err instanceof Error ? err.message : err), { contentType: null });
  }

총 세 종류의 에러를 던지고 있다.

• AbortError, TimeoutError
  AbortController.abort()로 인한 오류는 브라우저/Node에서 AbortError로 감지한다.
  Abort 상황은 타임아웃으로 해석하기에 같이 TimeoutError로 던진다.
• FetchError, ParseError, TimeoutError
  커스텀 에러일 경우 그대로 다시 던진다.
  커스텀 에러는 우리가 원하는 정보를 포함시키도록 이미 만진 에러인데 FetchError로 또 감싸면 유실될 수 있기 때문이다.
• Error
  그 외 알 수 없는 오류는 FetchError로 래핑해서 던진다.

 

 

2-6. finally

finally {
    clearTimeout(id);
  }
}

타임아웃 타이머를 정리하여 메모리/타이밍 누수를 방지한다.