TanStack Query + Zustand 낙관적 업데이트 — useMutation · onMutate · queryOptions 실전 가이드

사용자 액션 발생
  → [즉시] UI에 낙관적 반영 (TQ 캐시 직접 조작 또는 Zustand)
  → [비동기] 서버로 실제 요청 전송 (useMutation)
      → 성공: onSuccess로 임시 ID 교체 → onSettled에서 invalidateQueries
      → 실패: 이전 상태로 롤백 (스냅샷 복원 또는 Zustand revert 함수 호출)

// queries/todos.ts
import { queryOptions } from '@tanstack/react-query'
import { fetchTodo, fetchTodos } from '../api/todos' // fetch wrapper 또는 axios instance
 
export const todoQueries = {
  all: () =>
    queryOptions({
      queryKey: ['todos'],
      queryFn: fetchTodos,
    }),
  detail: (id: string) =>
    queryOptions({
      queryKey: ['todos', id],
      queryFn: () => fetchTodo(id),
    }),
}

// hooks/useTodoMutation.ts
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { todoQueries } from '../queries/todos'
import type { NewTodo, Todo } from '../types/todo' // 도메인 타입 선언 위치
 
function useAddTodo() {
  const queryClient = useQueryClient()
 
  return useMutation({
    mutationKey: ['todos'],
    mutationFn: (newTodo: NewTodo) => api.addTodo(newTodo), // api: fetch wrapper 또는 axios instance
 
    onMutate: async (newTodo) => {
      // 1. 진행 중인 리페치 취소 — 이걸 빠뜨리면 낙관적 업데이트가 백그라운드 리페치에
      //    즉시 덮어씌워집니다. 실무에서 이 줄 누락으로 30분 디버깅한 적 있습니다...
      await queryClient.cancelQueries(todoQueries.all())
 
      // 2. 실패 시 롤백을 위한 이전 상태 스냅샷 저장
      const previousTodos = queryClient.getQueryData(todoQueries.all().queryKey)
 
      // 3. 낙관적 캐시 업데이트 — 서버 응답 전에 UI에 즉시 반영
      //    tempId를 context에 함께 전달해 onSuccess에서 서버 ID로 교체할 때 사용합니다
      const tempId = `temp-${Date.now()}`
      queryClient.setQueryData(
        todoQueries.all().queryKey,
        (old: Todo[] | undefined) => [
          ...(old ?? []),
          { ...newTodo, id: tempId, status: 'pending' as const },
        ]
      )
 
      return { previousTodos, tempId }
    },
 
    onSuccess: (serverTodo, _newTodo, context) => {
      // 4. 서버에서 받은 실제 ID로 임시 항목 교체
      //    이 단계를 빠뜨리면 temp-xxx ID가 남아 이후 수정·삭제 뮤테이션이 실패합니다
      queryClient.setQueryData(
        todoQueries.all().queryKey,
        (old: Todo[] | undefined) =>
          (old ?? []).map((todo) =>
            todo.id === context?.tempId ? serverTodo : todo
          )
      )
    },
 
    onError: (_err, _newTodo, context) => {
      // 5. 실패 시 이전 상태로 정확히 롤백
      queryClient.setQueryData(
        todoQueries.all().queryKey,
        context?.previousTodos
      )
    },
 
    onSettled: () => {
      // 6. 성공/실패 무관하게 서버 데이터로 최종 동기화
      queryClient.invalidateQueries(todoQueries.all())
    },
  })
}

// store/cartStore.ts
import { create } from 'zustand'
import type { CartItem } from '../types/cart'
 
interface CartStore {
  optimisticItems: CartItem[]  // 서버 확인 전 임시 항목 (서버 데이터 복사본이 아님)
  isOptimisticUpdating: boolean
  addItemOptimistic: (item: CartItem) => void
  revertAddItem: (itemId: string) => void
  settleOptimistic: () => void // 뮤테이션 완료 후 낙관적 상태 초기화
}
 
const useCartStore = create<CartStore>((set) => ({
  optimisticItems: [],
  isOptimisticUpdating: false,
 
  addItemOptimistic: (item) =>
    set((state) => ({
      optimisticItems: [...state.optimisticItems, item],
      isOptimisticUpdating: true,
    })),
 
  revertAddItem: (itemId) =>
    set((state) => ({
      optimisticItems: state.optimisticItems.filter((i) => i.id !== itemId),
      isOptimisticUpdating: false,
    })),
 
  settleOptimistic: () =>
    set({ optimisticItems: [], isOptimisticUpdating: false }),
}))

// hooks/useCartMutation.ts
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { useCartStore } from '../store/cartStore'
import type { CartItem } from '../types/cart'
 
function useAddToCart() {
  const { addItemOptimistic, revertAddItem, settleOptimistic } = useCartStore()
  const queryClient = useQueryClient()
 
  return useMutation({
    mutationFn: (item: CartItem) => api.addToCart(item),
 
    onMutate: (item) => {
      // Zustand로 즉각 UI 반영 — 모든 구독 컴포넌트에 즉시 전달됩니다
      addItemOptimistic(item)
      return { itemId: item.id }
    },
 
    onError: (_err, _item, context) => {
      // 실패 시 낙관적으로 추가된 항목 제거
      if (context) revertAddItem(context.itemId)
    },
 
    onSettled: () => {
      // 낙관적 상태 초기화 — 이 시점부터 TQ 서버 데이터가 진실의 원천
      settleOptimistic()
      queryClient.invalidateQueries({ queryKey: ['cart'] })
    },
  })
}

// CartDisplay.tsx
import { useQuery } from '@tanstack/react-query'
import { useCartStore } from '../store/cartStore'
 
function CartDisplay() {
  const { data: serverCart } = useQuery({ queryKey: ['cart'], queryFn: fetchCart })
  const { optimisticItems, isOptimisticUpdating } = useCartStore()
 
  // 낙관적 업데이트 중: 서버 데이터 + 낙관적 항목을 합쳐 보여줌
  // 완료 후: TQ 서버 데이터만 사용
  const displayItems = isOptimisticUpdating
    ? [...(serverCart?.items ?? []), ...optimisticItems]
    : serverCart?.items ?? []
 
  return <CartList items={displayItems} />
}

// QueryClient 설정 시 todos 뮤테이션 전역 기본값 설정
// (보통 앱 초기화 파일 또는 QueryClient 생성 직후에 작성합니다)
queryClient.setMutationDefaults(['todos'], {
  onMutate: async () => {
    // 어떤 todos 뮤테이션이든 시작 전에 진행 중인 리페치를 취소
    await queryClient.cancelQueries(todoQueries.all())
  },
  onSettled: async () => {
    // 다른 todos 뮤테이션이 아직 진행 중이라면 재검증을 미룹니다
    // 마지막 뮤테이션이 끝날 때 한 번만 서버 동기화 — 불필요한 리페치를 줄입니다
    if (!queryClient.isMutating({ mutationKey: ['todos'] })) {
      await queryClient.invalidateQueries(todoQueries.all())
    }
  },
})