React Query와 Zustand의 낙관적 패턴

React Query의 useMutation 훅은 세 가지 수명 주기 콜백을 통해 낙관적 업데이트를 위한 기본 기능을 제공합니다. onMutate는 변경 작업 전에 실행되며 컨텍스트 객체를 반환하고, onError는 실패할 때 실행되며 컨텍스트를 전달받고, onSettled는 성공 또는 실패할 때 실행됩니다. 이 구조는 낙관적 패턴을 위해 특별히 설계되었습니다.

onMutate에서는 세 단계를 수행합니다. 먼저 영향을 받는 데이터에 대한 진행 중인 쿼리를 취소하고(await queryClient.cancelQueries({ queryKey })), 현재 캐시의 스냅샷을 저장한 다음(queryClient.getQueryData(queryKey)), 캐시에 낙관적 업데이트를 적용합니다(queryClient.setQueryData(queryKey, updater)). 스냅샷을 컨텍스트로 반환하십시오.

onError 콜백은 오류, 변경 작업 변수, 그리고 onMutate에서 반환된 컨텍스트를 전달받습니다. 컨텍스트를 사용해 롤백하십시오. queryClient.setQueryData(queryKey, context.previousData)를 사용합니다. 컨텍스트는 onMutate에서 저장한 스냅샷과 onError에서 수행하는 롤백을 연결하는 다리입니다.

onSettled 콜백은 성공 또는 실패 여부와 관계없이 실행됩니다. 이를 사용해 쿼리를 다시 조회하고 서버 상태와 동기화하십시오. queryClient.invalidateQueries({ queryKey })를 사용합니다. 이렇게 하면 성공한 변경 작업(서버가 데이터를 변환했을 수 있음)이든 실패한 변경 작업(롤백 완료)이든 관계없이 모든 변경 작업 후 결국 서버의 실제 상태와 일치하게 됩니다.

실용적인 예로 할 일의 완료 상태를 전환하는 경우를 살펴보겠습니다. onMutate에서 할 일 목록의 스냅샷을 저장한 다음 캐시에서 특정 할 일을 수정합니다. onError에서는 컨텍스트의 스냅샷을 복원합니다. onSettled에서는 할 일 쿼리를 무효화하여 다시 조회합니다. 사용자는 전환 결과를 즉시 확인하고, 서버와의 동기화는 백그라운드에서 이루어집니다.

Zustand 저장소에서는 낙관적 업데이트가 간단합니다. 항목을 저장소에서 즉시 수정한 다음 API를 호출하는 updateItem(id, changes) 작업을 만듭니다. API 호출이 실패하면 다른 작업인 revertItem(id, previousState)를 호출합니다. Zustand의 동기식 상태 업데이트 덕분에 낙관적 단계가 즉시 수행됩니다.

Zustand 상태를 깊게 중첩된 형태로 낙관적으로 수정할 때는 깔끔한 변경을 위해 Immer의 produce를 사용하십시오. set(produce(state => { state.items[id] = { ...state.items[id], ...changes } }))처럼 작성할 수 있습니다. Immer는 변경 가능한 문법으로 불변 업데이트를 처리하므로 복잡한 중첩 상태 변경을 읽기 쉽고 안전하게 만들어 줍니다.

React 19에서는 서버 작업 내 낙관적 업데이트를 위한 내장 훅으로 useOptimistic(state, updateFn)를 도입했습니다. const [optimisticState, addOptimistic] = useOptimistic(items, (state, newItem) => [...state, newItem])와 같이 사용할 수 있습니다. addOptimistic(newItem)을 호출하면 서버 작업이 비동기적으로 실행되는 동안 사용자 인터페이스가 즉시 업데이트됩니다.

useOptimistic은 롤백을 자동으로 처리합니다. 서버 작업이 성공하거나 오류와 함께 완료되면 React는 낙관적 상태를 되돌리고 서버의 실제 상태를 적용합니다. 수동 롤백 로직을 작성할 필요가 없습니다. React가 해당 작업의 Suspense 경계 안에서 낙관적 업데이트의 수명 주기를 관리합니다.

수동 낙관적 업데이트는 완전한 제어가 가능하지만 반복적인 코드가 필요합니다. React Query의 onMutate/onError/onSettled는 쿼리 캐시와 통합되어 자동 동기화를 제공합니다. useOptimistic은 서버 작업에 가장 간단하지만 React 19와 서버 작업 아키텍처가 필요합니다. RSC/서버 작업에는 useOptimistic을 사용하는 방식이 적합합니다. 데이터 계층에 따라 선택하십시오. 간단한 로컬 상태에는 수동 방식, REST API에는 React Query, RSC/서버 작업에는 useOptimistic을 사용하면 됩니다.

낙관적 패턴을 선택할 때는 아키텍처를 고려하십시오. 앱 전체에서 React Query를 사용한다면 onMutate 패턴이 일관되고 캐시를 인식하므로 적합합니다. 전역 상태에 Zustand를 사용한다면 작업 기반 패턴이 자연스럽게 맞습니다. React 19에서 서버 작업을 사용한다면 useOptimistic이 관용적인 선택입니다. 하나의 앱에서 여러 패턴을 섞어 사용하는 것은 흔하며 허용되는 방식입니다.

React Query에서 onError로 롤백할 수 있도록 하려면 onMutate 콜백이 무엇을 반환해야 합니까?

React Query useMutation은 onMutate(쿼리 취소, 스냅샷 저장, 낙관적 업데이트 적용, 컨텍스트 반환), onError(컨텍스트에서 스냅샷 복원), onSettled(무효화하여 다시 조회)를 사용합니다. Zustand의 낙관적 업데이트는 상태 작업을 즉시 호출한 다음 API를 호출하고, 실패하면 되돌립니다. React 19의 useOptimistic은 서버 작업 내에서 자동 롤백을 제공합니다. 데이터 계층 아키텍처에 맞는 패턴을 선택하십시오.