Зелёный ответ PATCH не меняет кеш чтения автоматически. Mutation и query — разные записи: сервер уже сохранил имя, а компонент всё ещё подписан на detail-key с id или list-key с filters со старым объектом. Нужна явная политика синхронизации.

До правки откройте Query Devtools и Network. Если после mutation refetch вообще не запускается, ищите несовпадение ключа или пропущенный callback. Если GET запускается, но возвращает старое, проблема может быть в backend/CDN. Если свежий GET пришёл, а затем UI откатился, исследуйте конкурентный запрос или локальную запись кеша.

Четыре отметки восстанавливают временную шкалу

МоментЧто записатьКакой вывод
До mutationqueryKey и dataUpdatedAtКакую запись видит компонент
Ответ mutationstatus, id, version, payloadЧто подтвердил сервер
onSuccess/onSettledточные keys и PromiseЗапущена ли синхронизация
Refetchrequest start/end и response versionСвеж ли источник
После rendercache data и selected dataНет ли transform/memo ошибки

Строковый ключ projects и массив с этим значением в старом коде могут относиться к разным API поколений. Для v5 используйте object-синтаксис и реальные массивы ключей. Параметры фильтра, tenant и id должны быть одинаково представлены при создании и поиске query.

Инвалидация ждёт связанные запросы

const queryClient = useQueryClient()

const updateProject = useMutation({
  mutationFn: patchProject,
  onSuccess: async (saved, variables) => {
    await Promise.all([
      queryClient.invalidateQueries({
        queryKey: ['project', variables.id],
      }),
      queryClient.invalidateQueries({
        queryKey: ['projects'],
      }),
    ])
  },
})

TanStack Query отмечает совпавшие queries устаревшими и активные обычно перезапрашивает. Возврат Promise из `onSuccess` удерживает mutation в pending до завершения callback. Это полезно, если форма не должна закрываться раньше, чем зависимый экран получил новое состояние.

Полный ответ mutation можно положить без второго GET

const mutation = useMutation({
  mutationFn: patchProject,
  onSuccess: (saved) => {
    queryClient.setQueryData(['project', saved.id], saved)
    queryClient.setQueriesData({ queryKey: ['projects'] }, (old) =>
      old ? { ...old, items: old.items.map((p) =>
        p.id === saved.id ? saved : p
      ) } : old
    )
  },
})

Так можно делать, когда сервер возвращает полное каноническое представление: id, нормализованные поля, version и вычисляемые значения. Не собирайте его из отправленного payload, если сервер меняет slug, права, время или статус. Обновление должно быть иммутабельным: мутированный объект может не вызвать ожидаемое уведомление подписчиков.

Старый GET не должен победить optimistic update

Гонка выглядит так: GET старой версии уже летит, пользователь сохраняет новую, optimistic update меняет кеш, затем старый GET завершается и перезаписывает запись. Перед optimistic update официальная схема отменяет совпавшие queries, сохраняет snapshot, записывает временное значение и при ошибке откатывает. После settled выполняется инвалидация для сверки с сервером.

  • Отменяйте только связанные keys, а не весь QueryClient.
  • Храните rollback snapshot внутри context конкретной mutation.
  • Не делайте optimistic update для операции с непредсказуемым серверным результатом без явного placeholder.
  • Проверяйте несколько одновременных mutations одной сущности.
  • Отделяйте isPending mutation от isFetching фонового query.
  • Если backend читает из replica, учитывайте задержку read-after-write на серверной стороне.

Проверка результата включает карточку и все списки

  1. Изменить поле из карточки и дождаться завершения mutation callback.
  2. Проверить detail query, отфильтрованный список и счётчики.
  3. Смоделировать медленный GET, который начался до PATCH.
  4. Вернуть 500 от mutation и убедиться, что optimistic snapshot откатился.
  5. Открыть вторую вкладку или повторно смонтировать экран после gc/staleTime.
  6. Сравнить version ответа с тем, что лежит в cache entry.

Фикс считается готовым, когда серверный успех отражается во всех связанных keys, mutation не объявляется завершённой раньше выбранной синхронизации, старый fetch не откатывает интерфейс, а ошибка восстанавливает согласованный snapshot. Для разбора приложите фабрику query keys, mutation callbacks и временную шкалу запросов без токенов.

Проверенные источники