🚀 TanStack Query로 서버 상태 관리하기 – useMutation

React 애플리케이션에서 서버 상태를 효율적으로 관리하는 방법 중 하나는 TanStack Query를 사용하는 것입니다.
오늘은 서버 데이터를 업데이트할 때 유용한 useMutation 훅을 살펴보고, 제가 실수했던 경험을 공유하려 합니다.

---

🎯 TanStack Query란?

TanStack Query(구 React Query)는 서버 상태 관리 라이브러리로, 다음과 같은 핵심 기능을 제공합니다:

✔ 데이터 페칭(Fetching) 및 캐싱 – API 데이터를 자동으로 캐싱하여 불필요한 네트워크 요청을 줄입니다.
✔ 자동 갱신(Refetching) – 데이터가 변경되면 자동으로 최신 상태로 동기화됩니다.
✔ 전역 상태 동기화 – 여러 컴포넌트에서 같은 데이터를 공유할 때 편리합니다.
✔ 로딩 & 에러 핸들링 – 로딩, 성공, 에러 상태를 자동으로 관리합니다.

💡 예를 들어, 버튼을 눌러 API 데이터를 업데이트할 때, useMutation을 활용하면 깔끔하게 처리할 수 있습니다.

---

🛠️ useMutation 기본 사용법

useMutation 훅은 데이터를 변경하는 API 요청(POST, PUT, DELETE) 을 관리할 때 사용됩니다.

📌 useMutation을 사용하는 이유

• useQuery는 데이터를 가져올 때 사용하지만,
• useMutation은 데이터를 변경(업데이트, 삭제, 추가) 할 때 사용합니다.

✅ 기본 코드 예제

아래는 useMutation을 사용하여 특정 데이터를 업데이트하는 예제입니다.

import { useMutation, useQueryClient } from "@tanstack/react-query";
import React from "react";
import { updateTestResultVisibility } from "../api/testResults";
import Button from "../components/Button";

const Example = ({ result }) => {
  const queryClient = useQueryClient();

  // ✅ useMutation을 사용하여 데이터 업데이트
  const visibleToggleMutation = useMutation({
    mutationFn: updateTestResultVisibility, // API 호출 함수
    onSuccess: () => {
      // 🔄 성공하면 캐시를 무효화하여 최신 데이터 가져오기
      queryClient.invalidateQueries({ queryKey: ["testResults"] });
    },
  });

  return (
    <Button
      primary="true"
      text={result.visibility ? "비공개로 전환" : "공개로 전환"}
      onClickFunc={() =>
        visibleToggleMutation.mutate({
          id: result.id,
          visibility: !result.visibility, // 현재 상태 반전
        })
      }
    />
  );
};

export default Example;

---

⚠️ 내가 범한 실수와 수정 방법

사실 처음에는 아래처럼 mutate에 두 개의 인자를 전달했었습니다.

// ❌ 잘못된 코드: 두 번째 인자는 옵션으로 인식됨
visibleToggleMutation.mutate(result.id, !result.visibility);

이렇게 작성하면 두 번째 인자가 mutation의 옵션으로 해석되어 API에 제대로 전달되지 않습니다.
useMutation의 mutate 함수는 "하나의 값만" 받도록 설계되어 있기 때문입니다.

🔥 올바른 수정 코드

// ✅ 올바른 코드: 객체로 묶어서 전달
visibleToggleMutation.mutate({
  id: result.id,
  visibility: !result.visibility,
});

이제 API에 올바른 값이 전달되면서 버튼 클릭 시 즉시 반영되고, 최신 상태가 유지됩니다. 🎉

---

🏆 정리

✔ useMutation은 데이터를 변경(업데이트, 삭제, 추가)할 때 사용
✔ mutate 함수는 하나의 객체를 전달해야 한다.
✔ onSuccess에서 queryClient.invalidateQueries(["testResults"])를 호출하면 데이터가 자동으로 최신 상태로 갱신

---

🚀 React 프로젝트에서 TanStack Query를 적극 활용하면, API 상태 관리가 더욱 편리해집니다.
앞으로도 다양한 상황에서 useMutation을 활용해보세요! 😆🔥