Fetch 비동기 통신과 Tanstack Query v5 완전 정복 ✍️

0. Overview 🌀

프론트엔드 개발을 하다 보면, 서버와 데이터를 주고받는 비동기 통신은 피할 수 없는 과제입니다. 사용자가 버튼을 클릭하면 새로운 데이터를 받아오고, 폼을 제출하면 데이터를 서버에 저장하며, 페이지를 이동하면 다시 서버로부터 데이터를 가져와야 하는 일이 반복되기 때문입니다. 이때 자바스크립트는 fetch() API를 통해 비동기 HTTP 요청을 처리하고, 이를 통해 프론트엔드와 백엔드가 소통하게 됩니다.

---

하지만 실제 서비스에서는 단순히 데이터를 가져오는 것 이상이 필요합니다. 예를 들어 이런 상황들을 생각해 볼 수 있습니다.

• 이미 받아온 데이터를 또다시 요청하지 않도록 캐싱하고 싶다.
• 네트워크가 불안정한 경우 요청을 자동으로 재시도하고 싶다.
• 여러 컴포넌트가 같은 데이터를 공유할 수 있어야 한다.
• 데이터를 수정한 뒤에, 관련된 목록 데이터를 자동으로 최신화하고 싶다.
• 서버 상태와 클라이언트 상태를 따로 관리하는 게 아니라, 서버 상태 자체를 관리하는 도구가 있었으면 좋겠다.

---

위 문제들을 Fetch만으로는 해결하기 어렵습니다. 그렇기 때문에 TanStack Query(구 React Query)가 등장하게 되었습니다.

TanStack Query는 단순한 데이터 요청 라이브러리가 아니라, 서버 상태를 관리하는 강력한 도구입니다. 클라이언트 애플리케이션에서 서버와 관련된 데이터를 가져오고, 캐싱하고, 동기화하고, 백그라운드에서 업데이트하며, 오류를 처리하는 등 복잡한 로직을 간단하게 관리할 수 있도록 도와줍니다.

1. Fetch 비동기 통신 🌀

1-1. Promise와 async / await 🎯

1-1-1. Promise 🟣

Promise는 자바스크립트 비동기 처리에 사용되는 객체입니다. 객체는 데이터 묶음이죠. 비동기 처리에 사용되는 데이터 묶음이 Promise입니다.

비동기 처리란, '특정 코드의 실행이 완료될 때까지 기다리지 않고, 다음 코드를 먼저 수행하는 자바스크립트의 특성'을 의미합니다. 닭가슴살을 에어프라이어로 15분 동안 굽는다고 하면, 에어프라이어 조리가 끝날 때까지 기다리지 않고 그 시간 동안 파스타를 만들 수 있겠죠. '에어프라이어 조리가 완료될 때까지 기다리지 않고 파스타를 만드는 것'이 비동기 처리입니다.

---

Promise는 주로 서버에서 받아온 데이터를 화면에 표시할 때 사용합니다.

$.get('url 주소/products/1', function(response) {
  // ...
});

위 API가 실행되면, 서버로 "데이터를 하나 보내주세요."라는 요청을 보내게 됩니다. 그런데 데이터를 받아오기도 전에, 마치 데이터를 다 받아온 것처럼 화면에 데이터를 표시하려고 하면 오류가 발생하거나 빈 화면이 나오겠죠. 이와 같은 문제를 해결하기 위한 방법 중 하나로 Promise를 활용하게 됩니다.

---

Promise는 세 가지 상태(states)를 갖습니다.

1. Pending(대기): 비동기 처리 로직이 아직 완료되지 않은 상태
2. Fulfilled(이행): 비동기 처리가 완료되어 Promise가 결과 값을 반환한 상태
3. Rejected(실패): 비동기 처리가 실패하거나 오류가 발생한 상태

---

Pending(대기) 🏷️

new Promise() 메서드를 호출하는 순간 Pending 상태가 됩니다.

new Promise();

new Promise() 메서드를 호출할 때 콜백 함수를 선언할 수 있는데요, 콜백 함수의 인자는 resolve와 reject입니다.

new Promise(function(resolve, reject) {
  // ...
});

---

Fulfilled(이행) 🏷️

콜백 함수의 인자 resolve를 아래와 같이 실행하면 Fulfilled 상태가 되죠.

new Promise(function(resolve, reject) {
  resolve();
});

Fulfilled 상태가 되면 Promise는 결과값을 반환합니다. 해당 반환값에 대해서 then() 메서드를 적용하여 반환값을 받을 수 있습니다.

function getData() {
  return new Promise(function(resolve, reject) {
    var data = 100;
    resolve(data);
  });
}

// resolve()의 결과 값 data를 resolvedData로 받음
getData().then(function(resolvedData) {
  console.log(resolvedData); // 100
});

---

Rejected(실패) 🏷️

new Promise()를 생성할 때 선언한 콜백 함수의 인자 중 하나인 reject를 호출하면 Rejected 상태가 됩니다.

new Promise(function(resolve, reject) {
  reject();
});

Rejected 상태가 되면, 실패의 이유를 catch() 메서드로 받을 수 있습니다.

function getData() {
  return new Promise(function(resolve, reject) {
    reject(new Error("Request is failed"));
  });
}

// reject()의 결과 값 Error를 err에 받음
getData().then().catch(function(err) {
  console.log(err); // Error: Request is failed
});

1-1-2. async / await 🟣

async / await는 위에서 설명한 Promise를 더 편하게 사용하기 위한 자바스크립트 문법입니다.

async 🏷️

async 키워드는 function 앞에 위치합니다.

async function f() {
  return 1;
}

function 앞에 async를 붙이면, 해당 함수는 항상 Promise를 반환합니다. Promise가 아닌 값을 반환하더라도, Fulfilled 상태의 Promise로 감싸 '이행된 Promise'가 반환되도록 합니다.

async function f() {
  return 1;
}

f().then(alert); // 1

명시적으로 Promise를 반환하는 것도 가능한데, 결과는 동일합니다.

async function f() {
  return Promise.resolve(1);
}

f().then(alert); // 1

---

await 🏷️

await는 async 함수 안에서만 동작하는 키워드입니다.

자바스크립트는 await 키워드를 만나면, Promise가 처리될 때까지 기다립니다. 결과는 그 이후에 반환되는데요. 1초 후 이행되는 Promise 예시를 통해 awiat의 동작을 살펴보겠습니다.

async function f() {

  let promise = new Promise((resolve, reject) => {
    setTimeout(() => resolve("완료!"), 1000)
  });

  let result = await promise; // 프라미스가 이행될 때까지 기다림 (*)

  alert(result); // "완료!"
}

f();

함수를 호출하고, 함수 본문이 실행되는 도중에 (*) 부분에서 실행이 잠시 '중단'되었다가 Promise가 처리되면 실행이 재개됩니다. await는 말 그대로 Promise가 처리될 때까지 함수 실행을 기다리게 만듭니다. Promise가 처리되길 기다리는 동안에, 엔진이 다른 일을 할 수 있기 때문에 CPU 리소스가 낭비되지 않습니다. Promise.then()보다 가독성이 좋고 쓰기도 쉽다는 장점 또한 있습니다.

⚠️ Promise와 async / await 요약
Promise는 비동기 처리에 사용되는 객체로, 작업의 상태(대기, 이행, 실패)를 관리합니다. 이를 더 간결하게 작성할 수 있도록 async/await 문법이 도입되었으며, 이는 비동기 코드를 마치 동기 코드처럼 읽기 쉽게 만들어줍니다.

1-2. Fetch API 사용하기 🎯

1-2-1. Fetch의 정의와 기본 사용법 🟣

Fetch API는 HTTP Request를 보내고 그에 대한 Response를 처리하기 위한 JavaScript 인터페이스를 제공합니다.

fetch() 함수를 호출하여 Request를 보냅니다. 요청할 URL을 담은 문자열이나 Request 객체를 첫 번째 인자로 넘기고, 선택적으로 Request를 구성하는 옵션 객체를 두 번째 인자로 넘길 수 있습니다.

fetch() 함수는 Promise를 반환합니다. 이후 Response 객체에 대해 적절한 메서드를 호출하여 Request의 상태를 확인하고, Response 본문을 텍스트 또는 JSON과 같은 다양한 형식으로 추출할 수 있습니다.

---

async function getData() {
  const url = "https://example.org/products.json";
  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`Response status: ${response.status}`);
    }

    const json = await response.json();
    console.log(json);
  } catch (error) {
    console.error(error.message);
  }
}

1-2-2. 응답 처리: json() 메서드 🟣

json() 메서드는 응답(Response) 데이터를 JSON 문자열에서 자바스크립트 객체로 파싱(parsing) 해주는 비동기 메서드입니다. 즉, 서버로부터 받은 문자열 형태의 JSON 데이터를 자바스크립트 객체로 변환해 주는 역할을 합니다.

Fetch API로 서버에 요청을 보내면, 서버는 일반적으로 문자열 형태의 JSON을 응답 본문에 담아 보냅니다. 이는 HTTP 통신이 본질적으로 텍스트(혹은 바이너리) 기반의 바이트 스트림만 전달하기 때문입니다.

하지만 이 문자열을 자바스크립트 코드에서 직접 다루기는 불편하므로, 이를 자바스크립트 객체로 변환해야 하며, 이때 Response 객체의 json() 메서드를 사용합니다.

fetch('https://jsonplaceholder.typicode.com/users/1')
  .then(response => response.json()) // 응답을 JSON 문자열 → JS 객체로 변환
  .then(data => {
    console.log(data); // 변환된 자바스크립트 객체 출력
    console.log(data.name); // 객체의 특정 속성 접근
  });

위 코드에 대한 실행 결과는 다음과 같습니다.

{
  id: 1,
  name: "Leanne Graham",
  username: "Bret",
  email: "Sincere@april.biz",
  ...
}
Leanne Graham

1-2-3. 요청 데이터 변환: JSON.stringify(data) 🟣

JSON.stringify()는 자바스크립트 객체를 JSON 문자열로 변환하는 함수입니다. 즉, 자바스크립트 객체를 서버에 전송하기 적합한 문자열 형태로 바꿔주는 도구입니다.

fetch API를 사용해 클라이언트에서 서버로 데이터를 보낼 때, HTTP 통신은 텍스트(또는 바이너리) 기반의 바이트 스트림만 전송할 수 있습니다.

따라서 자바스크립트 객체를 그대로 보낼 수는 없고, 이를 JSON.stringify()를 사용해 JSON 문자열로 변환한 후 전송해야 합니다.

const user = {
  name: 'Alice',
  age: 25
};

const jsonString = JSON.stringify(user); // 객체 → JSON 문자열 변환
console.log(jsonString); 

// 서버로 전송 (예시용으로 실제 전송되진 않음)
fetch('https://example.com/api/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json' // JSON 형식임을 서버에 알림
  },
  body: jsonString // 문자열로 변환한 데이터를 전송
});

jsonString은 다음과 같습니다.

{"name":"Alice","age":25}

⚠️ Fetch API 사용하기 요약
Fetch API는 서버와의 통신을 위한 내장 함수로, 응답을 처리할 때는 json() 메서드를 사용해 JSON 문자열을 자바스크립트 객체로 변환합니다. 반대로 서버로 데이터를 보낼 때는 JSON.stringify()를 사용해 객체를 문자열로 변환합니다.

1-3. 오류 처리: try…catch 🎯

try...catch는 코드 실행 중 에러가 발생해도 프로그램이 멈추지 않도록 처리하는 문법입니다. 즉, 에러를 잡아서 원하는 방식으로 처리할 수 있게 해주는 도구입니다.

기본 구조는 다음과 같습니다.

try {
  // 오류가 발생할 수 있는 코드
} catch (error) {
  // 예외가 발생했을 때 실행되는 코드
} finally {
  // 예외 발생 여부와 관계없이 항상 실행되는 코드
}

전에 작성했던 코드입니다.

const user = {
  name: 'Alice',
  age: 25
};

const jsonString = JSON.stringify(user); // 객체 → JSON 문자열 변환
console.log(jsonString); 

// 서버로 전송 (예시용으로 실제 전송되진 않음)
fetch('https://example.com/api/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json' // JSON 형식임을 서버에 알림
  },
  body: jsonString // 문자열로 변환한 데이터를 전송
});

이제 위 코드에 try..catch를 적용해 보겠습니다.

const user = {
  name: 'Alice',
  age: 25
};

async function sendUserData() {
  try {
    const jsonString = JSON.stringify(user); // 객체 → JSON 문자열 변환
    console.log(jsonString);

    const response = await fetch('https://example.com/api/users', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json' // JSON 형식임을 서버에 알림
      },
      body: jsonString // 문자열로 변환한 데이터를 전송
    });

    if (!response.ok) {
      throw new Error(`서버 응답 오류: ${response.status} ${response.statusText}`);
    }

    const data = await response.json();
    console.log('서버 응답 데이터:', data);

  } catch (error) {
    console.error('데이터 전송 중 오류 발생:', error);
  }
}

sendUserData();

데이터 전송 중 발생 가능한 오류를 catch로 처리하는 모습을 확인할 수 있습니다.

⚠️ 오류 처리: try…catch 요약
비동기 통신 과정에서 발생할 수 있는 오류는 try...catch 구문을 통해 효과적으로 관리할 수 있으며, 이를 통해 애플리케이션이 예외 상황에서도 중단되지 않고 적절히 대응할 수 있습니다.

2. TanStack Query v5 🌀

Promise와 async/await, Fetch API, 그리고 에러 처리에 대해 살펴봤습니다.

하지만 fetch는 단순히 서버에 요청을 보내고, 응답을 받는 역할만 하는 API입니다. 반면에 TanStack Query는 흔히 서버 상태를 효율적으로 관리해 주는 도구라고 불리죠. 그런데 여기서 말하는 ‘서버 상태 관리(Server State Management)’가 정확히 무엇을 의미하는지부터 짚고 넘어갈 필요가 있습니다. 저는 정의가 명확하지 않으면 후속 작업을 잘 못하는 편이기 때문입니다.

---

서버 상태 관리란, 서버에서 받아온 데이터를 애플리케이션 내에서 효율적으로 저장하고, 업데이트하며, 여러 화면이나 컴포넌트에서 일관된 최신 데이터를 사용할 수 있도록 관리하는 작업을 말합니다. fetch나 axios는 단지 요청과 응답의 기능만 제공할 뿐이지만, 서버 상태 관리는 이 데이터를 언제 다시 불러와야 할지, 로딩이나 에러 상태는 어떻게 처리할지, 여러 컴포넌트에서 어떻게 일관되게 공유할지까지 포함합니다.

즉, 서버 상태 관리란 서버로부터 받은 데이터에 관한 응용이라고 할 수 있습니다. TanStack Query는 이 복잡한 과정을 대신 처리해 주기 위해 이미 다양한 기능을 갖춘 도구입니다.

2-1. staleTime / cacheTime 🎯

리눅스를 개발한 리누스 토발즈 형님은 "나쁜 프로그래머는 코드에 집착하고, 훌륭한 프로그래머는 데이터 구조와 그 관계에 집중한다."라고 말씀하셨죠. 서버로부터 데이터를 받아서 처리할 것인데, 우선 데이터 자체의 상태에 대한 공부가 필요하다는 생각이 들었더랬죠. 그 시작이 staleTime과 cacheTime입니다.

2-1-1. staleTime 🟣

staleTime은 useQuery 훅에서 사용하는 속성입니다. useQuery 훅은 뒤에서 자세히 다룰 예정입니다.

staleTime은 데이터가 fresh 하다고 간주되는 시간을 의미합니다. 우리가 알고 있는 fresh가 맞습니다. 데이터가 fresh 한 상태일 때는, 쿼리가 다시 마운트 되더라도 네트워크 요청을 트리거 하지 않습니다. 아직 잘 모르겠는데요. GPT한테 물어보니, 쿼리는 서버로부터 데이터를 가져오는 요청(fetch)을 추상화한 단위라고 합니다. 쉽게 설명해달라고 했는데 답변을 보니 싸이코패스임이 틀림없다는 사실을 알 수 있습니다.

---

편의점 직원(aka. 편돌이)가 되었다고 가정해 보죠. 편돌이 원민관씨는 서울우유의 유통기한을 확인하라는 점장님의 업무 지시를 받았습니다. 여기서 유통기한이 8일이라면, 5일차 까지는 신선한 상태라고 생각해 봅시다. 여기서의 5일이 staleTime입니다.

const { data } = useQuery({
  queryKey: ['products'],
  queryFn: fetchMilk,
  staleTime: 1000 * 60 * 60 * 24 * 5, // 5일 (ms 기준)
});

2-1-2. cacheTime(gcTime) 🟣

cacheTime은 v5에서 gcTime으로 명칭이 변경되었습니다. 설명을 할 때에는 cacheTime이라는 명칭을 사용하겠습니다.

cacheTime은 유통기한 8일을 의미합니다. 즉, 8일이 지나면 가비지 컬렉터에 의해 캐시에서 데이터가 제거됩니다.

const { data } = useQuery({
  queryKey: ['products'],
  queryFn: fetchMilk,
  staleTime: 1000 * 60 * 60 * 24 * 5, // 5일 (ms 기준)
  gcTime: 1000 * 60 * 60 * 24 * 8, // 8일 (ms 기준)
});

---

8일이 지나면 편돌이 원민관씨는 서울우유를 폐기 상품으로 등록해야 합니다. 그런데 3일이 궁금합니다.

신선하지 않은 우유인데(=5일이 경과된 우유) 폐기 상품이 되지는 않은(=8일이 경과되지 않은) 우유는 어떻게 처리될까요?

우선 stale 한, 즉 신선하지 않은 우유이기 때문에 쿼리가 마운트 되면 네트워크 요청을 트리거 하게 됩니다. 단, 3일 동안 별도의 요청이 없다면 8일 경과 후에 캐시가 완전히 삭제됩니다.

⚠️ staleTime / cacheTime 요약
staleTime은 데이터가 '신선'하다고 간주되는 시간으로, 이 시간 동안은 재요청이 발생하지 않습니다. cacheTime(v5에서는 gcTime)은 사용하지 않는 데이터가 캐시에 남아있는 시간으로, 이 시간이 지나면 메모리에서 제거됩니다. 두 설정을 적절히 조합하여 애플리케이션의 성능과 사용자 경험을 최적화할 수 있습니다.

2-2. useQuery 🎯

useQuery()는, 서버로부터 데이터를 조회할 때 사용합니다. 후술하겠지만, 조회가 아닌 변경 작업을 할 때에는 useMutation()을 사용합니다.

2-2-1. queryKey 🟣

queryKey는 useQuery에서 가장 중요한 매개변수 중 하나로, 쿼리를 고유하게 식별하는 역할을 합니다. TanStack Query는 이 키를 사용하여 내부적으로 캐싱, 중복 제거, 업데이트 등을 관리합니다.

---

queryKey의 기본 형태 🏷️

queryKey는 문자열, 숫자, 또는 객체를 포함한 '배열 형태'로 정의합니다.

// 기본 문자열 키
const { data } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos
});

---

파라미터를 포함한 키 🏷️

동적 파라미터를 포함하는 데이터를 가져올 때는 해당 값을 queryKey에 포함시킵니다.

// 특정 할 일 항목 가져오기
const { data: todoItem } = useQuery({
  queryKey: ['todo', todoId],
  queryFn: () => fetchTodoById(todoId)
});

이렇게 구성하면 todoId가 변경될 때마다 쿼리가 자동으로 다시 실행됩니다.

---

필터나 정렬 조건을 포함한 키 🏷️

필터나 정렬 조건과 같은 복잡한 매개변수는 객체 형태로 포함시킵니다.

// 상태와 우선순위로 필터링된 할 일 목록
const { data: filteredTodos } = useQuery({
  queryKey: ['todos', { status, priority, page }],
  queryFn: () => fetchTodosByFilter({ status, priority, page })
});

---

queryKey의 중요성 🏷️

queryKey는 단순한 식별자 이상의 역할을 합니다.

1. 캐시 관리: 동일한 queryKey를 가진 쿼리는 캐시를 공유합니다.
2. 자동 리페칭: queryKey가 변경되면 쿼리가 자동으로 다시 실행됩니다.
3. 쿼리 무효화: invalidateQueries를 사용해 특정 패턴의 queryKey를 가진 모든 쿼리를 무효화할 수 있습니다.

// 'todos'로 시작하는 모든 쿼리 무효화
queryClient.invalidateQueries({ queryKey: ['todos'] });

// 특정 할 일 항목 관련 쿼리만 무효화
queryClient.invalidateQueries({ queryKey: ['todo', todoId] });

---

queryKey 구조화 전략 🏷️

효율적인 queryKey 구조화를 위한 몇 가지 전략이 있습니다.

1. 계층적 구조 사용: 첫 번째 요소는 엔티티 타입, 이후 요소는 식별자나 관계를 나타냅니다.

['users']                           // 사용자 목록
['users', userId]                   // 특정 사용자
['users', userId, 'projects']       // 특정 사용자의 프로젝트
['users', userId, 'projects', projectId]  // 특정 사용자의 특정 프로젝트

2. 객체 사용: 필터, 정렬, 페이지네이션 등의 변수는 객체로 그룹화합니다.

['posts', { filters: { status, category }, sort, page }]

이러한 전략은 쿼리 관리를 더 쉽게 만들고, 관련 쿼리를 효과적으로 무효화할 수 있게 해줍니다.

2-2-2. queryFn 🟣

queryFn은 useQuery의 또 다른 필수 매개변수로, 실제로 데이터를 가져오는 비동기 함수입니다. 이 함수는 Promise를 반환해야 하며, 서버나 다른 데이터 소스에서 데이터를 요청하고 결과를 반환하는 역할을 합니다.

---

기본 구현 🏷️

queryFn의 가장 기본적인 형태는 Promise를 반환하는 함수입니다.

const { data } = useQuery({
  queryKey: ['todos'],
  queryFn: async () => {
    const response = await fetch('https://api.example.com/todos');
    if (!response.ok) {
      throw new Error('Network response was not ok');
    }
    return response.json();
  }
});

axios, fetch 등 원하는 방식으로 데이터를 가져올 수 있습니다.

---

queryFn에 전달되는 매개변수 활용 🏷️

TanStack Query v5에서 queryFn은 유용한 메타데이터를 포함한 객체를 자동으로 매개변수로 받습니다.

const { data } = useQuery({
  queryKey: ['todos', { status, page }],
  queryFn: async ({ queryKey, signal, meta }) => {
    // queryKey에서 필요한 정보 추출
    const [_key, { status, page }] = queryKey;
    
    // 요청 취소를 위한 AbortSignal 사용
    const response = await fetch(
      `https://api.example.com/todos?status=${status}&page=${page}`,
      { signal }
    );
    
    if (!response.ok) {
      throw new Error('Network response was not ok');
    }
    
    return response.json();
  },
  meta: { authRequired: true }
});

---

오류 처리 🏷️

queryFn에서 발생한 오류는 자동으로 포착되어 쿼리의 error 상태로 설정됩니다.

const { data, error, isError } = useQuery({
  queryKey: ['todos'],
  queryFn: async () => {
    const response = await fetch('https://api.example.com/todos');
    if (!response.ok) {
      throw new Error(`Error ${response.status}: ${response.statusText}`);
    }
    return response.json();
  }
});

// 오류 발생 시 처리
if (isError) {
  return <div>Error: {error.message}</div>;
}

---

쿼리 함수 추상화 🏷️

복잡한 애플리케이션에서는 쿼리 함수를 별도의 모듈로 추출하여 재사용성을 높일 수 있습니다.

// api.js
export const fetchTodos = async ({ queryKey }) => {
  const [_key, { status, page }] = queryKey;
  const response = await fetch(
    `https://api.example.com/todos?status=${status}&page=${page}`
  );
  if (!response.ok) {
    throw new Error('Network response was not ok');
  }
  return response.json();
};

// TodoList.jsx
const { data } = useQuery({
  queryKey: ['todos', { status, page }],
  queryFn: fetchTodos
});

이런 방식으로 API 호출 로직을 컴포넌트에서 분리할 수 있어, 코드 관리와 테스트가 용이해집니다.

---

의존적 쿼리 구현 🏷️

queryFn은 이전 쿼리의 결과에 의존하여 데이터를 가져올 수도 있습니다.

// 먼저 사용자 정보를 가져옴
const { data: user } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUserById(userId)
});

// 사용자 정보가 있을 때만 프로젝트 정보를 가져옴
const { data: projects } = useQuery({
  queryKey: ['projects', user?.id],
  queryFn: () => fetchProjectsByUserId(user.id),
  enabled: !!user // user가 있을 때만 활성화
});

이처럼 enabled 옵션을 활용하면 의존성 체인을 효과적으로 관리할 수 있습니다.

⚠️ useQuery 요약
useQuery는 TanStack Query의 핵심 훅으로, 서버 데이터 조회와 상태 관리를 담당합니다. queryKey는 배열 형태의 고유 식별자로, 캐싱 및 자동 리페칭의 기준이 되며, 계층적 구조와 객체를 활용해 효율적으로 구성할 수 있습니다. queryFn은 데이터를 가져오는 비동기 함수로, 내장된 파라미터(queryKey, signal)를 활용해 동적 데이터 페칭과 오류 처리를 구현할 수 있습니다. 이 두 요소를 적절히 구성하면 복잡한 데이터 요구사항도 효과적으로 처리할 수 있습니다.

2-3. useMutation 🎯

useMutation은 TanStack Query에서 서버 데이터를 변경하는 작업을 처리하는 훅입니다. 데이터를 생성, 업데이트, 삭제하는 등의 작업에 사용되며, useQuery와 달리 자동으로 실행되지 않고 명시적인 호출을 통해 실행됩니다.

2-3-1. 기본 사용법 🟣

useMutation의 가장 기본적인 형태는 mutationFn을 매개변수로 받습니다. 이 함수는 서버에 데이터를 변경하는 비동기 함수여야 합니다.

기본 구현 🏷️

const { mutate, isPending, isError, isSuccess, error } = useMutation({
  mutationFn: async (newTodo) => {
    const response = await fetch('https://api.example.com/todos', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(newTodo)
    });
    
    if (!response.ok) {
      throw new Error('Network response was not ok');
    }
    
    return response.json();
  }
});

// 변이 실행하기
const handleSubmit = () => {
  mutate({ title: 'Buy groceries', completed: false });
};

useMutation에서 반환되는 주요 값:

• mutate: 변이를 실행하는 함수
• isPending: 변이가 진행 중인지 여부
• isError: 변이가 오류 상태인지 여부
• isSuccess: 변이가 성공 상태인지 여부
• error: 오류 발생 시 에러 객체
• data: 성공 시 서버 응답 데이터

---

변이 함수 전달 방식 🏷️

변이 함수는 다양한 방식으로 구현할 수 있습니다:

// 함수 직접 정의
const mutation = useMutation({
  mutationFn: (newTodo) => addTodo(newTodo)
});

// 또는 더 간단하게
const mutation = useMutation({
  mutationFn: addTodo
});

2-3-2. 변이 생명주기와 콜백 🟣

useMutation은 변이의 다양한 단계에서 작업을 수행할 수 있는 여러 콜백 함수를 제공합니다.

주요 콜백 함수 🏷️

const queryClient = useQueryClient();

const { mutate } = useMutation({
  mutationFn: addTodo,
  
  // 변이 시작 전
  onMutate: async (newTodo) => {
    // 관련 쿼리 취소
    await queryClient.cancelQueries({ queryKey: ['todos'] });
    
    // 이전 상태 백업
    const previousTodos = queryClient.getQueryData(['todos']);
    
    // 낙관적 업데이트
    queryClient.setQueryData(['todos'], old => [...old, newTodo]);
    
    // 롤백을 위한 컨텍스트 반환
    return { previousTodos };
  },
  
  // 변이 성공 시
  onSuccess: (data, variables, context) => {
    // data: 서버 응답 데이터
    // variables: mutate에 전달된 변수
    // context: onMutate에서 반환된 값
    
    // 성공 메시지 표시
    toast.success('할 일이 추가되었습니다!');
    
    // 필요 시 특정 쿼리 무효화
    queryClient.invalidateQueries({ queryKey: ['todos'] });
  },
  
  // 변이 실패 시
  onError: (error, variables, context) => {
    // 낙관적 업데이트 롤백
    if (context?.previousTodos) {
      queryClient.setQueryData(['todos'], context.previousTodos);
    }
    
    // 오류 메시지 표시
    toast.error(`오류 발생: ${error.message}`);
  },
  
  // 성공 또는 실패 후 항상 실행
  onSettled: (data, error, variables, context) => {
    // 항상 쿼리 무효화
    queryClient.invalidateQueries({ queryKey: ['todos'] });
    
    // 이후 작업 수행
    console.log('변이 완료');
  }
});

이 콜백 함수들을 사용하면 변이의 전체 생명주기에 걸쳐 세밀한 제어가 가능합니다.

2-3-3. 낙관적 업데이트 구현 🟣

낙관적 업데이트는 서버 응답을 기다리지 않고 UI를 즉시 업데이트하여 사용자 경험을 개선하는 기법입니다.

낙관적 업데이트의 주요 단계 🏷️

1. 현재 상태 백업: 롤백을 위해 현재 상태를 저장
2. 캐시 즉시 업데이트: 예상 결과로 UI 업데이트
3. 오류 시 롤백: 실패할 경우 이전 상태로 되돌림

const queryClient = useQueryClient();

const { mutate } = useMutation({
  mutationFn: async (todo) => {
    const response = await fetch(`https://api.example.com/todos/${todo.id}`, {
      method: 'PATCH',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ completed: todo.completed })
    });
    
    if (!response.ok) {
      throw new Error('Failed to update todo');
    }
    
    return response.json();
  },
  
  // 낙관적 업데이트 구현
  onMutate: async (updatedTodo) => {
    // 진행 중인 쿼리 취소
    await queryClient.cancelQueries({ queryKey: ['todos'] });
    
    // 이전 상태 백업
    const previousTodos = queryClient.getQueryData(['todos']);
    
    // 캐시 업데이트
    queryClient.setQueryData(['todos'], old => 
      old.map(todo => 
        todo.id === updatedTodo.id 
          ? { ...todo, completed: updatedTodo.completed } 
          : todo
      )
    );
    
    return { previousTodos };
  },
  
  // 오류 발생 시 롤백
  onError: (err, updatedTodo, context) => {
    // 이전 상태로 복원
    queryClient.setQueryData(['todos'], context.previousTodos);
    toast.error('할 일 업데이트에 실패했습니다.');
  },
  
  // 무조건 쿼리 무효화
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: ['todos'] });
  }
});

// 사용 예시
const toggleTodoCompletion = (todoId, isCompleted) => {
  mutate({ id: todoId, completed: isCompleted });
};

2-3-4. mutate 함수의 활용 🟣

mutate 함수는 다양한 방식으로 활용될 수 있으며, 필요에 따라 추가적인 옵션을 전달할 수 있습니다.

기본 호출 방식 🏷️

// 단순 호출
mutate(newTodo);

// 성공/실패 핸들러 포함 호출
mutate(newTodo, {
  onSuccess: (data) => {
    // 이 핸들러는 전역 onSuccess 후에 실행됨
    console.log('Todo 추가 성공:', data);
    
    // 추가 작업 수행 (예: 폼 초기화, 화면 전환 등)
    resetForm();
    navigate('/todos');
  },
  onError: (error) => {
    console.error('Todo 추가 실패:', error);
    // 사용자에게 특정 오류 메시지 표시
  }
});

---

mutateAsync 활용 🏷️

비동기 흐름 제어가 필요한 경우 mutateAsync를 사용할 수 있습니다:

const { mutateAsync } = useMutation({
  mutationFn: addTodo
});

const handleSubmit = async () => {
  try {
    // mutateAsync는 Promise를 반환
    const newTodo = await mutateAsync({ title: 'Buy milk', completed: false });
    console.log('새 할 일이 추가됨:', newTodo);
    
    // 성공 후 추가 작업
    await saveToLocalStorage(newTodo);
    
    // 다른 변이 연속 실행
    await updateUserStats();
    
  } catch (error) {
    console.error('오류 발생:', error);
  }
};

2-3-5. 쿼리 무효화와 업데이트 전략 🟣

변이 후 관련 데이터를 최신 상태로 유지하기 위한 여러 전략이 있습니다.

직접 쿼리 무효화 🏷️

가장 단순한 방법은 관련 쿼리를 무효화하여 리페칭을 트리거 하는 것입니다:

const { mutate } = useMutation({
  mutationFn: addTodo,
  onSuccess: () => {
    // 'todos'로 시작하는 모든 쿼리 무효화
    queryClient.invalidateQueries({ queryKey: ['todos'] });
  }
});

---

쿼리 직접 업데이트 🏷️

때로는 서버 응답을 사용하여 캐시를 직접 업데이트하는 것이 효율적일 수 있습니다:

const { mutate } = useMutation({
  mutationFn: addTodo,
  onSuccess: (newTodo) => {
    // 기존 'todos' 쿼리 데이터 가져오기
    const previousTodos = queryClient.getQueryData(['todos']);
    
    // 새 할 일을 포함하여 캐시 업데이트
    if (previousTodos) {
      queryClient.setQueryData(['todos'], [...previousTodos, newTodo]);
    }
    
    // 새 할 일의 상세 쿼리 미리 채우기
    queryClient.setQueryData(['todo', newTodo.id], newTodo);
  }
});

---

서로 다른 전략 결합 🏷️

복잡한 애플리케이션에서는 여러 전략을 결합하는 것이 유용할 수 있습니다:

const { mutate } = useMutation({
  mutationFn: updateTodo,
  onSuccess: (updatedTodo) => {
    // 1. 업데이트된 할 일의 상세 쿼리 직접 업데이트
    queryClient.setQueryData(['todo', updatedTodo.id], updatedTodo);
    
    // 2. 목록 쿼리를 직접 업데이트 (특정 조건에 맞는 경우)
    queryClient.setQueriesData({ queryKey: ['todos'] }, (old) => {
      if (!old) return old;
      return old.map(todo => 
        todo.id === updatedTodo.id ? updatedTodo : todo
      );
    });
    
    // 3. 관련 쿼리 무효화 (필터링된 목록 등)
    queryClient.invalidateQueries({
      queryKey: ['todos'],
      // 특정 쿼리만 무효화
      predicate: (query) => 
        query.queryKey.length > 1 && 
        typeof query.queryKey[1] === 'object'
    });
  }
});

이러한 다양한 전략을 상황에 맞게 활용하면 효율적이고 일관된 상태 관리를 구현할 수 있습니다.

⚠️ useMutation 요약
useMutation은 서버 데이터를 변경하는 작업을 위한 훅으로, mutationFn을 통해 실제 API 호출을 정의하고 mutate 함수로 실행합니다. 생명주기 콜백(onMutate, onSuccess, onError, onSettled)을 활용한 낙관적 업데이트를 통해 즉각적인 UI 응답을 제공하고, queryClient의 다양한 메서드(invalidateQueries, setQueryData)를 사용해 관련 쿼리를 효율적으로 갱신할 수 있습니다. 이러한 기능들을 활용하면 복잡한 데이터 변경 시나리오에서도 일관된 상태 관리와 향상된 사용자 경험을 제공할 수 있습니다.

3. Conclusion 🌀

프론트엔드 개발에서 비동기 통신은 단순한 데이터 교환을 넘어 전체 애플리케이션 구조와 사용자 경험에 영향을 미치는 핵심 요소입니다. 기본 JavaScript의 Promise와 async/await, 그리고 Fetch API는 비동기 통신의 기초를 제공하지만, 실제 서비스에는 더 복잡한 요구사항이 따릅니다. TanStack Query는 이러한 고급 요구사항을 충족시키는 강력한 도구로, 데이터 캐싱과 상태 관리를 통해 개발자 경험과 애플리케이션 성능을 모두 향상시킵니다.

---

TanStack Query의 staleTime/gcTime으로 데이터 생명주기를 관리하고, queryKey를 통해 효율적인 캐싱 전략을 구현하며, useQuery와 useMutation으로 데이터 조회와 변경을 직관적으로 처리할 수 있습니다. 낙관적 업데이트, 자동 리페칭, 의존적 쿼리와 같은 고급 기능은 복잡한 데이터 흐름을 간소화하고 사용자에게 더 유려한 경험을 제공합니다. 결국 Fetch API에서 TanStack Query로의 전환은 단순히 도구를 바꾸는 것이 아니라, 서버 상태를 바라보는 관점 자체를 전환하는 패러다임의 변화라고 할 수 있겠습니다.

---

Reference:
1. https://joshua1988.github.io/web-development/javascript/promise-for-beginners/
2. https://ko.javascript.info/async-await
3. https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
4. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch
5. https://developer.mozilla.org/en-US/docs/Web/API/Response/json
6. https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults
7. https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults
8. https://tanstack.com/query/latest/docs/framework/react/guides/query-keys
9. https://tanstack.com/query/latest/docs/framework/react/guides/query-functions
10. https://tanstack.com/query/latest/docs/framework/react/reference/useQuery
11. https://tanstack.com/query/latest/docs/framework/react/reference/useMutation