[React-Query] mutate vs mutateAsync

🧩 React Query에서 mutate vs mutateAsync 차이 정리

React Query를 사용할 때 useMutation을 이용해 데이터를 등록하거나 수정할 때,
두 가지 방법 중 하나를 사용할 수 있습니다.

• 콜백 기반의 mutate
• Promise 기반의 mutateAsync

이번 글에서는 두 방식의 차이와 사용 예시를 간단히 정리해보겠습니다.

---

1️⃣ mutate — 콜백 기반의 빠른 실행 방식

const mutation = useMutation(updateUser)

mutation.mutate(data, {
  onSuccess: () => console.log("성공"),
  onError: () => console.log("실패"),
})

✅ 특징

• 콜백 기반으로 동작
• 호출 즉시 실행, 반환값 없음
• 성공/실패 처리는 onSuccess, onError로 처리

즉, 빠르게 mutation을 실행하고 결과는 콜백으로 처리하는 방식입니다.

💡 사용 예시

• 버튼 클릭 등 즉시 요청 후 UI 반영이 필요한 경우
• 비동기 결과를 기다리지 않고 즉각 실행이 필요한 경우

---

2️⃣ mutateAsync — Promise 기반의 async/await 방식

const mutation = useMutation(updateUser)

try {
  const result = await mutation.mutateAsync(data)
  console.log("성공", result)
} catch (e) {
  console.error("실패", e)
}

✅ 특징

• Promise 기반으로 작동
• await을 사용할 수 있어 비동기 흐름 제어에 유리
• 에러는 try / catch로 처리

즉, mutation의 결과를 직접 변수로 받아서 후속 로직에 사용할 수 있습니다.

💡 사용 예시

• mutation 결과를 기반으로 다음 비즈니스 로직을 처리해야 할 때
• 비동기 함수 내부에서 자연스러운 흐름 제어가 필요할 때

---

⚖️ 정리

구분	mutate	mutateAsync
기반	콜백 기반	Promise 기반
호출 시점	즉시 실행	async/await 사용 가능
반환값	없음	Promise 반환
에러 처리	onError 콜백	try/catch 블록
적합한 상황	UI 이벤트 중심	비동기 로직 중심

---

🎯 결론

• 단순 이벤트 트리거용이라면 → mutate
• async/await 코드 흐름에 맞게 처리하려면 → mutateAsync

두 방식 모두 동일한 기능을 수행하지만,
코드 스타일과 흐름 제어 방식이 다르므로 상황에 따라 적절히 선택하면 됩니다.