🔧 useMutation

useMutation은 서버 데이터를 생성, 수정, 삭제하는 작업을 처리하기 위한 TanStack Query 훅입니다.

일반적으로 useQuery는 **데이터 조회(GET)**에 사용되지만
useMutation은 데이터 변경(POST, PUT, PATCH, DELETE) 작업을 처리합니다.

1️⃣ useMutation 필요성

React Query에서 데이터를 조회할 때는 useQuery를 사용합니다.

useQuery({
  queryKey: ["posts"],
  queryFn: fetchPosts
})

하지만 서버 데이터를 변경하는 작업은 다음과 같은 특징이 있습니다.

POST /posts
PUT /posts/1
DELETE /posts/1

문제점

• 데이터 변경 요청은 자동 실행되면 안 됨
• 사용자 이벤트에 의해 실행되어야 함
• 변경 후 기존 데이터 캐시 업데이트 필요

👉 이 문제를 해결하는 것이 useMutation

2️⃣ 기본 구조

const { mutate, isPending, isSuccess, isError } = useMutation({
  mutationFn: (newPost) => createPost(newPost)
})

🔹 주요 반환 값

3️⃣ 사용 예시

const createPost = async (post) => {
  const response = await fetch("/posts", {
    method: "POST",
    body: JSON.stringify(post),
    headers: {
      "Content-Type": "application/json"
    }
  })

  return response.json()
}

const { mutate } = useMutation({
  mutationFn: createPost
})

실행

<button onClick={() => mutate({ title: "Hello" })}>
  Create Post
</button>

👉 mutate()를 호출할 때 mutation이 실행됩니다.

4️⃣ Mutation 상태

useMutation도 상태 값을 제공합니다.

예

if (isPending) {
  return <Spinner />
}

5️⃣ 주요 옵션

🔹 onSuccess

mutation이 성공했을 때 실행됩니다.

useMutation({
  mutationFn: createPost,
  onSuccess: () => {
    console.log("post created")
  }
})

🔹 onError

mutation 실패 시 실행됩니다.

useMutation({
  mutationFn: createPost,
  onError: (error) => {
    console.log(error)
  }
})

🔹 onSettled

성공/실패 여부와 관계없이 실행됩니다.

useMutation({
  mutationFn: createPost,
  onSettled: () => {
    console.log("mutation finished")
  }
})

6️⃣ Query Invalidation

데이터 변경 후에는 기존 캐시 데이터를 다시 가져와야 하는 경우가 많습니다.

예

게시글 생성
→ posts 목록 변경
→ posts query 다시 요청 필요

이때 사용하는 것이 Query Invalidation입니다.

queryClient.invalidateQueries()

예

import { useQueryClient } from "@tanstack/react-query"

const queryClient = useQueryClient()

const mutation = useMutation({
  mutationFn: createPost,
  onSuccess: () => {
    queryClient.invalidateQueries(["posts"])
  }
})

👉 mutation 성공 후 posts query를 다시 요청합니다.

7️⃣ Mutation 흐름

사용자 이벤트 발생
      ↓
mutate() 호출
      ↓
mutationFn 실행
      ↓
서버 요청
      ↓
isPending = true
      ↓
요청 성공
      ↓
isSuccess = true
      ↓
onSuccess 실행
      ↓
query invalidation
      ↓
관련 query refetch

✍️ 한 줄 정리

useMutation은 서버 데이터를 생성, 수정, 삭제하는 작업을 처리하는 TanStack Query 훅이며, mutation 실행 후에는 invalidateQueries를 통해 관련 쿼리를 다시 가져오는 패턴을 자주 사용합니다.