Зелёный ответ PATCH не меняет кеш чтения автоматически. Mutation и query — разные записи: сервер уже сохранил имя, а компонент всё ещё подписан на detail-key с id или list-key с filters со старым объектом. Нужна явная политика синхронизации.
До правки откройте Query Devtools и Network. Если после mutation refetch вообще не запускается, ищите несовпадение ключа или пропущенный callback. Если GET запускается, но возвращает старое, проблема может быть в backend/CDN. Если свежий GET пришёл, а затем UI откатился, исследуйте конкурентный запрос или локальную запись кеша.
Четыре отметки восстанавливают временную шкалу
| Момент | Что записать | Какой вывод |
|---|---|---|
| До mutation | queryKey и dataUpdatedAt | Какую запись видит компонент |
| Ответ mutation | status, id, version, payload | Что подтвердил сервер |
| onSuccess/onSettled | точные keys и Promise | Запущена ли синхронизация |
| Refetch | request start/end и response version | Свеж ли источник |
| После render | cache 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 на серверной стороне.
Проверка результата включает карточку и все списки
- Изменить поле из карточки и дождаться завершения mutation callback.
- Проверить detail query, отфильтрованный список и счётчики.
- Смоделировать медленный GET, который начался до PATCH.
- Вернуть 500 от mutation и убедиться, что optimistic snapshot откатился.
- Открыть вторую вкладку или повторно смонтировать экран после gc/staleTime.
- Сравнить version ответа с тем, что лежит в cache entry.
Фикс считается готовым, когда серверный успех отражается во всех связанных keys, mutation не объявляется завершённой раньше выбранной синхронизации, старый fetch не откатывает интерфейс, а ошибка восстанавливает согласованный snapshot. Для разбора приложите фабрику query keys, mutation callbacks и временную шкалу запросов без токенов.