Оптимистичные шаблоны с React Query и Zustand

Хук useMutation в React Query предоставляет встроенную инфраструктуру для оптимистичных обновлений с помощью трёх функций обратного вызова жизненного цикла: 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 оптимистичные обновления выполняются просто: создайте действие updateItem(id, changes), которое сразу обновляет элемент в хранилище, а затем вызывает API. Если API возвращает ошибку, вызовите другое действие revertItem(id, previousState). Синхронные обновления состояния в Zustand делают оптимистичный шаг мгновенным.

При оптимистичном обновлении глубоко вложенного состояния Zustand используйте функцию produce из Immer для удобной записи изменений: 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 и архитектура серверных действий. Выбирайте подход в зависимости от слоя данных: ручной — для простого локального состояния, React Query — для REST API, useOptimistic — для RSC и серверных действий.

При выборе оптимистичного подхода учитывайте архитектуру приложения. Если вы используете React Query во всём приложении, его подход с onMutate последователен и учитывает кэш. Если для глобального состояния вы используете Zustand, естественно подойдёт подход на основе действий. Если вы работаете с React 19 и серверными действиями, идиоматичным выбором будет useOptimistic. Сочетание подходов в одном приложении распространено и допустимо.

Что должна возвращать функция обратного вызова onMutate в React Query, чтобы обеспечить откат в onError?

React Query useMutation использует onMutate (отменяет запросы, создаёт снимок, применяет оптимистичное обновление и возвращает контекст), onError (восстанавливает снимок из контекста) и onSettled (делает запрос недействительным, чтобы повторно получить данные). Оптимистичные обновления Zustand сразу вызывают действие изменения состояния, а затем API и выполняют откат при ошибке. React 19 useOptimistic обеспечивает автоматический откат в серверных действиях. Выбирайте подход, соответствующий архитектуре слоя данных.