Fetch API와 AJAX

8장에서는 최신 ECMAScript 문법으로 더 간결하고 안전한 코드를 쓰는 방법을 익혔습니다. 9장 웹 API와 브라우저 기능에서는 언어를 넘어, 브라우저가 제공하는 웹 API(Web API)를 실제로 써 봅니다. DOM과 이벤트, 스토리지, 네트워크 통신은 모두 웹 API 위에서 동작하며, 그 시작은 서버와 데이터를 주고받는 AJAX와 Fetch API입니다.

웹 페이지는 처음 열 때 서버에서 HTML, CSS, 자바스크립트를 받아 옵니다. 하지만 그 뒤 버튼을 누르거나 검색할 때마다 페이지 전체를 다시 받을 필요는 없는 경우가 많습니다. 페이지를 새로고침하지 않고 필요한 데이터만 비동기로 주고받는 방식을 AJAX(Asynchronous JavaScript and XML)라고 합니다. 이름에 XML이 들어 있지만 지금은 JSON 형식을 훨씬 많이 쓰며, 핵심은 페이지 전체가 아니라 필요한 데이터만 교환한다는 점입니다. 예전에는 XMLHttpRequest가 중심이었고, 지금은 Promise를 기반으로 하는 Fetch API가 기본 선택입니다.

실습 API 준비

외부 공개 API의 상태에 결과가 흔들리지 않도록, 이 글의 실습은 내 컴퓨터에서 실행하는 목(mock) API 서버 http://localhost:4000을 기준으로 합니다. 4000번은 목 API, 4100번은 별도 백엔드나 실시간 서버처럼 포트를 나눠 두면 여러 트랙을 함께 공부할 때 충돌을 줄일 수 있습니다.

새 폴더에 다음 내용으로 db.json을 만듭니다. /posts/1과 /users/1은 있고 /users/999는 없는 조건입니다.

{
  "posts": [{ "id": 1, "title": "첫 글", "body": "본문", "userId": 1 }],
  "users": [{ "id": 1, "name": "민지" }]
}

그 폴더의 터미널에서 다음 명령으로 json-server를 실행합니다. 이 글은 json-server 1.x를 기준으로 하며, 글을 쓰는 시점의 npm 최신 버전은 1.0.0-beta.15이고 Node.js 22.12 이상이 필요합니다.

npx json-server db.json --port 4000

json-server 1.x는 db.json이 바뀌면 자동으로 다시 읽으므로, 예전 버전의 --watch 옵션은 더 이상 필요 없습니다. 서버가 뜨면 브라우저에서 http://localhost:4000/posts가 배열을, /posts/1이 글 객체를, /users/1이 사용자 객체를 돌려주는지 먼저 확인하세요. 서버가 실행되지 않은 상태에서 요청 코드만 반복하면, 네트워크 실패인지 데이터 문제인지 구별하기 어렵습니다. 뒤의 POST 실습은 db.json의 내용을 바꾸므로, 처음 결과와 다시 비교하려면 이 초기 데이터로 되돌립니다.

XMLHttpRequest

XMLHttpRequest(XHR)는 AJAX의 전통적인 구현입니다. 이벤트 콜백으로 결과를 받아 코드가 길어지고 콜백이 중첩되기 쉬웠지만, 웹 애플리케이션의 시대를 연 기술입니다.

// fetch가 없던 시절의 XMLHttpRequest 사용 예시 (간략)
function fetchDataXHR() {
    const xhr = new XMLHttpRequest();
    xhr.open('GET', 'http://localhost:4000/posts/1'); // 요청 초기화
    xhr.onload = function() { // 응답을 받았을 때
        if (xhr.status >= 200 && xhr.status < 300) {
            console.log("XHR 응답 성공:", JSON.parse(xhr.responseText));
        } else {
            console.error("XHR 응답 실패:", xhr.status);
        }
    };
    xhr.onerror = function() { // 요청 실패 (네트워크 오류 등)
        console.error("XHR 네트워크 오류 발생");
    };
    xhr.send(); // 요청 전송
}
fetchDataXHR();

요청을 초기화하고, 응답과 오류에 각각 콜백을 등록하고, 상태 코드로 성공인지 직접 판단한 뒤, 응답 문자열을 JSON.parse()로 직접 바꿔야 합니다. 이 과정을 Promise로 간단하게 만든 것이 Fetch API입니다.

Fetch API

Fetch API는 Promise를 기반으로 네트워크 요청을 보내는 인터페이스입니다. XMLHttpRequest보다 쓰기 쉽고, 요청과 응답을 Request, Response 같은 객체로 다룰 수 있습니다.

fetch()의 기본 사용법

fetch()는 첫 번째 인수로 요청할 URL을 받고 Promise를 돌려줍니다. 이 Promise는 응답 헤더가 도착하면 Response 객체로 이행됩니다. Response에는 상태 코드와 헤더 같은 응답 정보가 담겨 있고, 본문(body)의 데이터는 response.json()이나 response.text() 같은 메서드를 한 번 더 호출해 읽습니다. 이 메서드들도 본문을 다 읽을 때까지 기다리는 Promise를 돌려줍니다.

// GET 요청 예시
fetch('http://localhost:4000/posts/1') // Promise 반환
    .then(response => {
        // 응답 상태 확인: response.ok는 200-299 상태 코드를 나타냄
        if (!response.ok) {
            throw new Error(`HTTP 오류! 상태: ${response.status}`);
        }
        // 응답 본문을 JSON으로 파싱 (Promise 반환)
        return response.json();
    })
    .then(data => {
        console.log("Fetch GET 응답 데이터:", data);
    })
    .catch(error => {
        console.error("Fetch 요청 실패:", error);
    });

가장 주의할 점은 fetch()가 언제 거부되는지입니다. fetch()의 Promise는 네트워크 오류, CORS 실패, 요청 취소, 잘못된 요청 구성처럼 응답 자체를 받지 못했을 때만 거부됩니다. 404(Not Found)나 500(Internal Server Error) 같은 HTTP 오류 응답은 서버가 응답을 보낸 것이므로 Promise가 거부되지 않고, 대신 response.ok가 false가 됩니다. response.ok는 상태 코드가 200~299일 때만 true이므로, HTTP 오류를 처리하려면 항상 response.ok를 확인해야 합니다.

HTTP 메서드와 요청 옵션

fetch()의 두 번째 인수로 옵션 객체를 넘겨 요청을 설정할 수 있습니다. 다음은 새 글을 만드는 POST 요청입니다.

// POST 요청 예시
const newPost = {
    title: '새로운 게시물',
    body: '이것은 Fetch API로 작성된 새로운 게시물 내용입니다.',
    userId: 1,
};

fetch('http://localhost:4000/posts', {
    method: 'POST', // HTTP 메서드 지정
    headers: {
        'Content-Type': 'application/json; charset=UTF-8', // 요청 헤더 지정
    },
    body: JSON.stringify(newPost), // 전송할 데이터 (JSON.stringify로 문자열화)
})
    .then(response => {
        if (!response.ok) {
            throw new Error(`HTTP 오류! 상태: ${response.status}`);
        }
        return response.json();
    })
    .then(data => {
        console.log("Fetch POST 응답 데이터 (생성된 게시물):", data);
    })
    .catch(error => {
        console.error("Fetch POST 요청 실패:", error);
    });

json-server는 POST 요청으로 만든 글을 201 Created 상태와 함께 돌려주며, 새 글에는 서버가 정한 id가 붙습니다. 실행한 뒤 db.json을 열어 보면 새 글이 추가되어 있습니다.

자주 쓰는 옵션은 다음과 같습니다. method는 GET, POST, PUT, DELETE 같은 HTTP 메서드로 기본값은 GET입니다. headers는 Content-Type이나 Authorization 같은 요청 헤더이고, body는 POST나 PUT과 함께 보낼 데이터로 JSON.stringify()로 만든 문자열이나 FormData 객체를 넣습니다. mode는 cors(기본값), no-cors, same-origin 가운데 하나로 CORS 처리 방식을, credentials는 omit, same-origin(기본값), include 가운데 하나로 쿠키 같은 인증 정보를 보낼지를 정합니다. 그 밖에 캐시 정책을 정하는 cache, 요청을 취소할 때 쓰는 signal 등이 있습니다.

옵션은 덤으로 붙이는 설정이 아니라, 요청의 목적과 데이터 형식, 인증 정보를 보낼 범위, 취소 조건을 서버와 맞추는 일입니다. 예를 들어 JSON을 보내면서 Content-Type을 빠뜨리면 서버가 본문을 JSON으로 읽지 못할 수 있습니다.

async/await와 함께 쓰기

7장에서 배운 async/await를 쓰면 fetch() 코드를 위에서 아래로 읽히게 쓸 수 있고, 오류도 try...catch 하나로 처리할 수 있습니다. 다음 함수는 요청, 상태 코드 확인, 본문 읽기를 차례로 진행하며, 어느 단계에서 오류가 나도 catch로 모여 null을 돌려줍니다. 404 같은 오류 응답은 fetch()가 스스로 거부하지 않으므로, response.ok를 확인해 직접 throw하는 줄이 있어야 catch로 넘어간다는 점을 보세요.

async function fetchUserData(userId) {
    try {
        const response = await fetch(`http://localhost:4000/users/${userId}`);

        if (!response.ok) {
            throw new Error(`사용자 데이터를 불러오는 데 실패했습니다. ${response.status}`);
        }

        const userData = await response.json();
        console.log("사용자 데이터:", userData);
        return userData;
    } catch (error) {
        console.error("데이터 로딩 중 오류 발생:", error);
        return null;
    }
}

fetchUserData(1); // ID가 1인 사용자 데이터 가져오기
fetchUserData(999); // 존재하지 않는 사용자 (오류 처리 테스트)

fetchUserData(1)은 사용자 객체를 출력하고, fetchUserData(999)는 json-server가 404를 돌려주므로 response.ok가 false가 되어 “데이터 로딩 중 오류 발생”을 출력한 뒤 null을 돌려줍니다. 두 요청은 동시에 진행되므로 어느 로그가 먼저 나올지는 정해져 있지 않습니다. 결과를 읽을 때는 로그의 순서가 아니라, 각 호출이 요청한 ID와 성공 여부를 짝지어 봐야 합니다.

요청 취소: AbortController

검색어가 바뀌었거나 사용자가 화면을 떠나 이전 요청이 필요 없어졌다면 요청을 취소하는 편이 좋습니다. AbortController를 만들고 그 signal을 fetch()의 옵션으로 넘긴 뒤, controller.abort()를 호출하면 진행 중인 요청이나 본문 읽기가 중단됩니다.

const controller = new AbortController();
const signal = controller.signal;

async function fetchWithCancellation(url) {
    try {
        const response = await fetch(url, { signal });
        if (!response.ok) {
            throw new Error(`HTTP 오류! 상태: ${response.status}`);
        }
        const data = await response.json();
        console.log("데이터 로드 성공:", data);
        return data;
    } catch (error) {
        if (error.name === 'AbortError') {
            console.log("Fetch 요청이 취소되었습니다.");
        } else {
            console.error("Fetch 요청 오류:", error);
        }
        return null;
    }
}

// 50ms 후에 요청 취소를 시도하는 예시
const longRunningFetch = fetchWithCancellation('http://localhost:4000/posts/1');

setTimeout(() => {
    controller.abort(); // 요청 취소
}, 50); // 먼저 완료되면 취소되지 않을 수 있음

취소되면 fetch()나 response.json()의 Promise가 name이 "AbortError"인 오류로 거부되므로, catch에서 다른 오류와 구별해 처리합니다. 이 예제는 50밀리초 뒤에 취소를 시도하는데, 로컬 서버가 그보다 먼저 응답을 끝내면 취소할 것이 없어 정상 결과가 출력됩니다. 이미 끝난 요청은 되돌릴 수 없으며, 서버가 이미 처리한 POST 요청을 취소해도 서버의 데이터가 원래대로 돌아오지는 않습니다.

응답을 단계별로 검사하기

위 그림의 위쪽은 화면이 fetch()를 호출한 뒤의 두 가지 대안을 보여 줍니다. 서버에 요청이 가서 HTTP 응답이 돌아오면 fetch()는 Response로 이행하고, 네트워크 오류처럼 응답을 받지 못하면 거부됩니다. 한 요청이 두 경로를 모두 거치지는 않습니다.

아래쪽은 응답을 받은 경우에만 적용하는 목록 검사 순서입니다. 먼저 HTTP 상태가 성공인지, 다음으로 Content-Type 헤더가 JSON 형식인지 확인합니다. 그다음 response.json()으로 본문을 읽는데, 본문의 JSON 문법이 틀렸다면 이 단계에서 거부됩니다. 마지막으로 결과가 배열이고 각 항목에 ID와 제목이 있는지 검사합니다. 모두 통과하면 글이 있을 때는 success, 빈 배열이면 empty 화면을 보여 주고, 중간에 실패하면 어디서 실패했는지 구별해 오류 화면을 보여 줍니다.

그림 아래의 설명처럼 Response를 받았다는 것이 HTTP 요청의 성공을 뜻하지는 않습니다. 전송, HTTP 상태, 응답 형식, 데이터 구조를 각각 확인해야 합니다. 또 204(No Content)처럼 본문이 없는 응답을 돌려주는 API라면, 본문을 읽지 않는 규칙을 따로 정해야 합니다.

다음 함수는 이 순서대로 /posts 목록 응답을 읽습니다. 이 화면에는 ID와 제목만 필요하므로 그 두 필드와 배열인지만 검사하며, 게시물의 모든 업무 규칙을 검증하지는 않습니다.

async function readPosts(response) {
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const type = response.headers.get('content-type') ?? '';
    if (!/^application\/json(?:\s*;|\s*$)/i.test(type)) {
        throw new Error('JSON 응답 형식이 아닙니다.');
    }
    const data = await response.json();
    const validPost = post => post !== null && typeof post === 'object'
        && (typeof post.id === 'number' || typeof post.id === 'string')
        && typeof post.title === 'string';
    if (!Array.isArray(data) || !data.every(validPost)) {
        throw new Error('글 목록의 구조가 다릅니다.');
    }
    return data;
}

async function showPosts() {
    try {
        const response = await fetch('http://localhost:4000/posts');
        const posts = await readPosts(response);
        console.log(posts.length === 0 ? 'empty' : 'success', posts);
    } catch (error) {
        console.log('error', error.message);
    }
}

초기 데이터로 showPosts()를 호출하면 success와 글 한 개를 출력합니다. 같은 함수라도 응답에 따라 실패하는 단계가 다릅니다. 404 응답은 HTTP 상태 검사에서, 상태가 200이지만 본문이 [{처럼 잘린 응답은 JSON 읽기에서, 상태가 200이고 본문이 {}인 응답은 배열 검사에서 실패합니다. 세 경우 모두 오류 화면이 될 수 있지만 고쳐야 할 곳은 서로 다르므로, 오류 메시지로 단계를 구별해 둡니다. Content-Type 검사는 응답 형식의 단서일 뿐이며, 헤더가 JSON이라고 해서 본문의 JSON 문법이 올바르다는 보장은 아닙니다.

화면 상태와 함께 설계하기

실제 화면에서 Fetch 코드는 요청만 보내고 끝나지 않습니다. 로딩 중, 성공, 빈 결과, 오류 같은 화면 상태와 함께 설계해야 안정적으로 동작합니다.

위 그림은 한 요청의 화면 상태가 바뀌는 과정입니다. 요청 전의 idle 상태에서 요청을 시작하면 pending이 되고, 새 signal을 준비하며 이 요청의 번호를 현재 번호로 정합니다. 응답을 검증한 결과 글이 있으면 success, 빈 배열이면 empty, 통신이나 HTTP 상태, 본문 검사에서 실패하면 error, 현재 요청을 취소하면 canceled가 됩니다.

어느 상태에서든 새로 요청을 시작하면 다시 pending으로 돌아갑니다. 중요한 점은 완료된 요청이 화면을 바꿀 수 있는 것은 그 요청의 번호가 현재 번호와 같을 때뿐이라는 것입니다. 이전 요청이 뒤늦게 성공하거나 실패해도, 그 결과는 버려지고 새 요청의 pending이나 결과를 덮어쓰지 않습니다. AbortController로 이전 요청을 취소하더라도, 화면을 바꿀 권한은 번호로 한 번 더 확인합니다.

다음 함수는 같은 목록 화면에서 요청을 바꿀 때 이 규칙을 구현합니다. 요청마다 새 AbortController를 만들어 이전 요청을 취소하고, 완료되었을 때는 자기 번호가 현재 번호인지 확인합니다.

function createPostsLoader(show, request = fetch) {
    let current = 0;
    let previous;

    async function load(url) {
        const token = ++current;
        previous?.abort();
        const controller = new AbortController();
        previous = controller;
        show('pending');
        try {
            const response = await request(url, { signal: controller.signal });
            const posts = await readPosts(response);
            if (token !== current) return;
            if (controller.signal.aborted) { show('canceled'); return; }
            show(posts.length === 0 ? 'empty' : 'success', posts);
        } catch (error) {
            if (token !== current) return;
            show(controller.signal.aborted ? 'canceled' : 'error', error.message);
        }
    }

    return { load, cancel: () => previous?.abort() };
}

const loader = createPostsLoader((state, value) => console.log(state, value));
// 준비된 Mock API에서 실행: loader.load('http://localhost:4000/posts');

token은 화면을 바꿀 권한이 어느 요청에 있는지를 앱이 직접 기록하는 번호이고, AbortSignal은 요청을 중단하는 수단입니다. 둘을 함께 쓰는 이유는, 취소를 무시하는 요청 함수가 있거나 취소 직전에 응답이 끝나는 경우에도 오래된 결과가 화면을 덮지 않게 하기 위해서입니다. 두 번째 인수 request는 기본으로 fetch를 쓰지만, 테스트에서 응답을 흉내 내는 함수로 바꿔 넣을 수 있게 열어 둔 것입니다. 이 코드는 서버가 이미 처리한 POST를 되돌리지는 않습니다.

CORS

Fetch로 다른 출처(origin)의 자원에 접근할 때는 CORS(Cross-Origin Resource Sharing)를 이해해야 합니다. 브라우저는 보안을 위해 동일 출처 정책(same-origin policy)을 따릅니다. 출처는 프로토콜, 호스트, 포트의 조합이며, 셋이 모두 같아야 같은 출처입니다.

http://example.com:8080/path와 http://example.com:8080/anotherpath는 경로만 다르므로 같은 출처입니다. 반면 호스트가 다른 http://sub.example.com, 프로토콜이 다른 https://example.com, 포트가 다른 http://example.com:3000은 모두 다른 출처입니다. 그래서 편집기의 로컬 서버가 http://localhost:5500에서 연 페이지가 http://localhost:4000의 목 API를 호출하는 것도 다른 출처 요청입니다.

브라우저는 다른 출처의 응답을 스크립트가 읽게 해 줄지를 서버가 보낸 Access-Control-Allow-Origin 같은 CORS 헤더로 판단합니다. json-server 1.x는 CORS 헤더를 기본으로 보내므로 이 글의 실습은 그대로 동작합니다. 직접 만든 서버라면 허용할 출처를 서버에서 설정해야 합니다.

fetch()의 mode를 no-cors로 바꾸면 CORS 문제가 해결될 것 같지만 그렇지 않습니다. no-cors 모드는 쓸 수 있는 메서드와 헤더가 제한되고, 다른 출처의 응답을 불투명(opaque) 응답으로 줍니다. 불투명 응답은 스크립트에 상태 0과 읽을 수 없는 빈 본문으로 보이므로, 다른 출처의 JSON을 읽는 목적에는 쓸 수 없습니다.

더 깊이: Network 패널에 OPTIONS 요청이 먼저 보이는 이유

다른 출처로 JSON을 POST하면 Network 패널에 실제 요청보다 먼저 OPTIONS 메서드의 요청이 하나 보이기도 합니다. 이것을 사전 요청(preflight request)이라고 합니다. HTML 폼은 fetch()가 생기기 전부터 어느 출처로든 단순한 모양의 요청을 보낼 수 있었으므로, 브라우저는 폼 제출처럼 보이는 요청에는 서버가 이미 대비하고 있다고 보고 바로 보냅니다. 그 밖의 요청은 서버가 받아들이는지 먼저 묻는 것입니다.

MDN은 단순 요청(simple request)의 조건을 다섯 가지로 드는데, fetch()로 보내는 요청에서 주로 갈리는 것은 다음 세 가지입니다. 메서드가 GET, HEAD, POST 가운데 하나여야 하고, 직접 붙인 헤더가 Accept, Content-Type 같은 허용 목록 안에 있어야 하며, Content-Type은 application/x-www-form-urlencoded, multipart/form-data, text/plain 가운데 하나여야 합니다. 그래서 Content-Type: application/json을 붙인 POST나 PUT, DELETE, Authorization 헤더를 쓰는 요청은 모두 사전 요청을 거칩니다. 사전 요청에는 Access-Control-Request-Method와 Access-Control-Request-Headers가 담기고, 서버가 Access-Control-Allow-Methods와 Access-Control-Allow-Headers로 허용해야 실제 요청이 나갑니다.

사전 요청은 요청마다 왕복을 하나 더 하므로, 서버는 Access-Control-Max-Age로 허용 결과를 몇 초 동안 캐시해도 되는지 알려 줄 수 있습니다. 쿠키를 함께 보내려고 credentials: 'include'를 쓴다면, 서버는 Access-Control-Allow-Credentials: true를 보내고 Access-Control-Allow-Origin에 * 대신 정확한 출처를 적어야 합니다. 자세한 조건은 MDN의 CORS 설명에 있습니다.

정리

• AJAX는 페이지 전체를 새로고침하지 않고 필요한 데이터만 비동기로 주고받는 방식이며, 지금은 Promise 기반의 Fetch API를 기본으로 씁니다.
• fetch()는 응답을 받지 못했을 때만 거부되고, 404나 500 같은 HTTP 오류는 response.ok가 false인 응답으로 이행되므로 직접 확인해야 합니다.
• 응답을 받으면 HTTP 상태, 응답 형식, JSON 문법, 데이터 구조를 차례로 검사하고, 실패한 단계를 구별해 처리합니다.
• 두 번째 인수의 옵션으로 메서드, 헤더, 본문, CORS 모드, 인증 정보, 취소 신호를 정합니다.
• AbortController로 필요 없어진 요청을 취소하고, 요청 번호로 현재 요청의 결과만 화면에 반영해 오래된 응답이 새 화면을 덮지 않게 합니다.
• 다른 출처의 응답을 읽으려면 서버가 CORS 헤더로 허용해야 하며, no-cors 모드는 응답을 읽을 수 없게 만들 뿐입니다.

연습 문제

1. 늦게 도착한 이전 요청

createPostsLoader()로 만든 로더에서 첫 요청 A가 pending인 동안 요청 B를 시작했습니다. B는 상태 200과 JSON 배열 []로 먼저 끝나고, A는 취소를 무시하는 요청 함수 때문에 상태 200과 글 한 개를 뒤늦게 돌려줬다고 가정합니다. 최종 화면 상태는 무엇일까요? 또 다른 실험에서 현재 요청 C가 상태 200과 JSON 본문 {}를 돌려주면 어디서 실패할까요?

2. 거부와 HTTP 오류

json-server를 실행한 상태에서 fetchUserData(999)를 호출할 때와, 서버를 끈 상태에서 fetchUserData(1)을 호출할 때 각각 어느 줄에서 오류가 생길까요? 두 경우 모두 catch로 가는데, 원인을 어떻게 구별할 수 있을까요?

3. no-cors로 바꾸면

http://localhost:5500에서 연 페이지가 CORS 헤더를 보내지 않는 다른 서버에 fetch(url, { mode: "no-cors" })를 보냈습니다. 받은 response의 type, status, ok는 무엇이고, await response.json()은 어떻게 될까요?

Response를 받는 시점과 본문을 읽는 시점의 차이는 Fetch 표준의 본문 규칙에서, 요청 옵션과 오류 처리는 MDN의 Fetch API 사용하기 문서에서 확인할 수 있습니다.

다음 글 로컬 스토리지와 세션 스토리지에서는 서버 대신 브라우저에 데이터를 저장하는 웹 스토리지 API를 살펴봅니다.