대부분의 최신 웹 앱은 항상 서버와 통신합니다. JavaScript Fetch API는 이를 수행하는 표준 방법이며 브라우저와 Node.js 18 이상에 내장되어 있으므로 설치할 것이 없습니다.

기본 사용에는 두 줄이 필요하지만 많은 자습서는 여기서 멈추고 실제 버그를 일으키는 부분인 오류 처리를 생략합니다. 우리는 Node.js 24의 소규모 로컬 서버에 대해 이 가이드의 예제를 테스트했으며 표시된 출력은 해당 실행에서 나온 것입니다. 코드에서 example.com은 자신의 API를 나타냅니다. Promise가 처음이라면 JavaScript Promise 설명부터 시작하세요.

가져오기 API란 무엇입니까?

Fetch는 HTTP 요청을 만들기 위한 약속 기반 인터페이스입니다. 이는 이전의 콜백 기반 XMLHttpRequest을 대체했으며 이제 많은 프로젝트에서 간단한 호출을 위해 라이브러리를 추가하는 대신 이를 사용합니다.

GET 요청

Fetch는 기본적으로 GET 요청을 수행합니다. 두 단계가 있으며 각 단계에는 await이 필요합니다. 먼저 응답 헤더가 도착한 다음 본문을 읽습니다.

const response = await fetch("https://example.com/users/1");
const user = await response.json();

console.log(user);

// { id: 1, name: 'Asha' }

본문이 크고 헤더보다 늦게 도착할 수 있기 때문에 두 단계가 존재합니다. 브라우저 스크립트에서 최상위 await에는 모듈이 필요하므로 일반적으로 이를 async 함수 안에 넣습니다. JavaScript 비동기/대기 가이드를 참조하세요.

응답 객체

본문을 읽기 전에 응답을 검사할 수 있습니다.

console.log(response.status, response.ok, response.headers.get("content-type"));

// 200 true application/json

본문은 한 번만 읽을 수 있습니다. 테스트에서 json()을 두 번째로 호출하는 데 실패했습니다.

await res.json();
await res.json();

// TypeError: Body is unusable: Body has already been read

두 번 읽어야 하는 경우 먼저 response.clone()을 호출하세요.

큰 놀라움: 404는 던지지 않습니다.

이것이 이 글에서 가장 중요한 내용입니다. 존재하지 않는 사용자를 요청했습니다.

const res = await fetch("https://example.com/users/999");
console.log(res.status, res.ok);

// 404 false

예외는 발생하지 않았습니다. 가져오기에 관한 한 요청은 작동했습니다. 서버에 도달하여 응답했습니다. Promise는 네트워크 오류와 같이 사용 가능한 응답이 전혀 도착하지 않는 경우에만 거부합니다. 따라서 이와 같은 코드에는 숨겨진 버그가 있습니다.

try {
  const res = await fetch(url);
  const data = await res.json();   // may be an error payload
  showUser(data);                  // runs anyway for 404 and 500
} catch (error) {
  showError();                     // does not run for 404 or 500
}

각 코드의 의미를 알아보려면 HTTP 상태 코드 치트 시트를 확인하세요.

재사용 가능한 도우미

어디서나 해당 확인을 반복하지 마십시오. 한 번 포장하세요.

async function getJson(url, options) {
  const response = await fetch(url, options);
  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }
  return response.json();
}

try {
  await getJson("https://example.com/users/999");
} catch (error) {
  console.log("caught:", error.message);
}

// caught: Request failed with status 404

이제 HTTP 오류와 네트워크 오류는 모두 동일하게 종료됩니다catch. 이 작은 기능은 모든 프로젝트에서 사용할 가치가 있습니다. 실제 버전은 응답 본문에서 오류 메시지를 읽고 구문 분석할 JSON이 없는 204 No Content 응답을 처리할 수도 있습니다.

JSON 데이터 게시

옵션 개체를 두 번째 인수로 전달합니다. JSON의 경우 데이터를 문자열로 변환하고 헤더를 설정하는 두 가지 작업을 직접 수행해야 합니다.

const created = await getJson("https://example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Ben" }),
});

console.log(created);

// { id: 2, name: 'Ben', type: 'application/json' }

테스트 서버는 수신한 콘텐츠 유형을 다시 에코하여 헤더가 도착했음을 확인했습니다. 헤더를 잊어버리는 것은 혼란스러운 서버 오류의 일반적인 원인입니다. 많은 프레임워크가 JSON이 선언될 때만 구문 분석하기 때문입니다. 양식이나 파일을 업로드하려면 FormData 개체를 본문으로 전달하고 Content-Type을 설정하지 않습니다. 브라우저가 경계 값 자체를 추가해야 하기 때문입니다.

기타 방법 및 옵션

REST와 다른 API 스타일 중에서 선택하시겠습니까? REST와 GraphQL을 비교하면 fetch가 각각에 얼마나 적합한지 알 수 있습니다.

쿼리 문자열

특수 문자로 인해 쿼리 문자열이 끊어지므로 텍스트를 결합하여 쿼리 문자열을 작성하지 마십시오. URLSearchParams이 인코딩을 처리합니다.

const params = new URLSearchParams({ q: "red shoes", page: 2 });
console.log(params.toString());

// q=red+shoes&page=2

await getJson(`https://example.com/search?${params}`);

// { q: 'red shoes', page: '2' }

서버가 red shoes을(를) 올바르게 수신했으며 공간이 복원되었습니다.

시간 초과 및 취소

별도로 지정하지 않는 한 Fetch는 느린 서버에서 오랜 시간을 기다립니다. AbortSignal.timeout()은 한계를 설정합니다. 테스트 엔드포인트는 200밀리초 제한에 대해 2초가 걸렸습니다.

try {
  await fetch("https://example.com/slow", { signal: AbortSignal.timeout(200) });
} catch (error) {
  console.log(error.name);
}

// TimeoutError

예를 들어 사용자가 페이지를 떠나거나 새 검색어를 입력할 때 수동으로 취소하려면 AbortController을 사용하세요.

const controller = new AbortController();
const pending = fetch("https://example.com/slow", { signal: controller.signal });

controller.abort();

try {
  await pending;
} catch (error) {
  console.log(error.name);
}

// AbortError

한 번에 여러 요청을 실행하려면 Promise.all을 사용하세요. 이는 한 번에 하나씩 기다리는 것보다 훨씬 빠릅니다.

const [user, search] = await Promise.all([
  getJson("https://example.com/users/1"),
  getJson("https://example.com/search?q=a&page=1"),
]);

모든 종류의 실패

다음은 실행에서 각 실패의 모습과 이를 구별하는 방법입니다.

마지막 행은 프로덕션에서 일반적입니다. 502를 반환하는 프록시는 종종 HTML 오류 페이지를 보냅니다. 우리는 이것을 재현했고, res.json()은 SyntaxError를 던졌습니다. 구문 분석하기 전에 response.ok을 확인하면 혼란스러운 구문 분석 오류가 아니라 실제 문제를 보고한다는 의미입니다.

CORS 및 자격 증명

브라우저에서 한 원본에서 다른 원본으로의 요청에는 원본 간 리소스 공유 규칙인 CORS가 적용됩니다. Access-Control-Allow-Origin라는 오류가 표시되면 수정 사항은 서버에 속하며 사이트를 허용해야 합니다. JavaScript에서는 실패가 일반 TypeError으로만 표시되므로 실제 이유는 브라우저 콘솔을 살펴보세요. Node.js는 CORS를 적용하지 않으므로 스크립트에서 작동하는 요청이 브라우저에서 계속 실패할 수 있습니다.

기본적으로 브라우저는 교차 출처 요청에 대해 쿠키를 보내지 않습니다. 필요한 경우 credentials: "include"을 설정하고 서버에서 허용하는지 확인하십시오. 누구나 읽을 수 있으므로 브라우저 JavaScript에 비밀 API 키를 넣지 마십시오. 서버에 보관하세요.

일반적인 실수

• 확인하지 않음 response.ok. 오류 응답은 성공으로 처리됩니다.
• 두 번째 await. response.json()을 잊어버리면 약속도 반환됩니다.
• JSON.stringify를 잊어버림. 몸체가 [object Object]을 보내는 것처럼 객체를 전달합니다.
• Content-Type를 FormData으로 설정합니다. 경계가 무너지므로 그대로 두세요.
• 시간 초과가 없습니다. 요청이 정지되면 페이지 스피너가 무기한 실행될 수 있습니다.
• 빈 응답에 대해 JSON을 구문 분석합니다. 204에는 본문이 없으며 json()가 발생합니다.

마무리

기본 규칙을 기억하면 가져오기는 간단합니다. 응답은 성공과 동일하지 않습니다. 작은 도우미를 프로젝트에 복사하고 시간 초과를 추가하고 실패 경로를 테스트하세요. 다음 단계에서는 API에서 데이터를 로드하고 명확한 오류 메시지를 표시하며 사용자가 느린 검색을 취소할 수 있는 작은 페이지를 구축합니다.

자주 묻는 질문

계속 학습하세요