Успешная mutation меняет сервер, но не обязана менять каждый список в кеше клиента. Apollo автоматически обновит уже известную сущность, если ответ содержит её `__typename`, идентификатор и изменённые поля. Новый объект при этом может появиться как отдельная запись, но Apollo не угадает, в какой список ROOT_QUERY его нужно добавить.

Сначала выясните, что именно не изменилось: поле существующей карточки, состав списка, счётчик или результат с аргументами фильтра. Это разные записи кеша. Попытка лечить всё одним `refetchQueries` может скрыть неверную нормализацию и добавить лишние сетевые запросы.

Проверьте ответ mutation до работы с React

СлучайЧто должен вернуть серверЧто ещё требуется
Обновление существующего объекта__typename, keyFields и изменённые поляСовпадение cache ID с объектом query
Добавление объектаПолный новый объект с идентификаторомДобавить Reference в нужное поле списка
Удаление объектаИдентификатор удалённой сущностиУбрать Reference из списков и при необходимости evict
Изменение агрегатаНовое значение счётчика либо данные для расчётаОбновить поле, которое реально читает компонент

Если mutation возвращает только `success: true`, клиенту нечего записать в нормализованную сущность. Если возвращается объект без ключевого поля, он может остаться вложенным результатом операции, а не совпасть с записью, которую наблюдает query. Проверьте typePolicies и `keyFields`, особенно если идентификатор называется не `id` или составной.

Новый объект нужно включить в список

Функция `update` выполняется после записи результата mutation в кеш и даёт доступ к `cache.modify`. Запишите фрагмент, получите Reference и верните новый массив для точного поля списка. Не мутируйте `existing` через push: кеш ожидает новое значение, а неизменная ссылка затрудняет обнаружение обновления.

const [addTask] = useMutation(ADD_TASK, {
  update(cache, { data }) {
    const task = data?.addTask;
    if (!task) return;

    const ref = cache.writeFragment({
      data: task,
      fragment: gql`fragment NewTask on Task { id title done }`,
    });

    cache.modify({
      fields: {
        tasks(existing = []) {
          return [...existing, ref];
        },
      },
    });
  },
});

Название `tasks` должно совпадать с полем кеша, а не обязательно с именем React-компонента. Если query вызывается с аргументами, в кеше могут существовать несколько вариантов одного поля. Решите, какие фильтры должны получить новый объект. Без этой политики легко добавить задачу и в «Завершённые», и в «Активные» или, наоборот, не добавить никуда.

Когда refetchQueries уместнее ручной записи

Перечитывание подходит, если сервер применяет сложную сортировку, права, вычисляемые поля или меняет несколько связанных наборов, которые трудно точно повторить на клиенте. Укажите конкретные активные запросы и при необходимости дождитесь их завершения. Цена решения — дополнительный сетевой обмен и промежуточное состояние загрузки.

Не используйте `network-only` mutation как попытку отключить проблему: по документации Apollo результат такой mutation всё равно пишется в кеш, в отличие от `no-cache`. И наоборот, `no-cache` лишает автоматической нормализации, поэтому UI придётся синхронизировать другим способом.

Удаление проверяйте во всех представлениях

После удаления серверной записи очистите ссылки на неё из списков. Один и тот же объект может находиться в «Все», результатах поиска и списке проекта. `cache.evict` удаляет сущность, но бизнес-логика полей должна корректно отфильтровать ссылки; полезно проверить каждый открытый экран без полной перезагрузки страницы.

  • Сравните cache ID до и после mutation.
  • Убедитесь, что компонент читает то поле, которое меняет update.
  • Проверьте аргументы списка и typePolicies merge/read.
  • Не маскируйте ошибку принудительным reload браузера.
  • Для optimisticResponse используйте ту же форму и идентификаторы, что у реального ответа.

Минимальный тест фиксирует правильную границу

Оставьте один query, одну mutation и отображение JSON результата. Сначала проверьте изменение существующего объекта, затем отдельно добавление в список. После клика интерфейс должен обновиться без reload; после ответа сервера optimistic-объект не должен дублироваться. Если refetch возвращает правильные данные, а `update` нет, ошибка почти наверняка в адресации кеша, а не в React.

Для разбора сохраните query, mutation response, typePolicies и снимок соответствующих записей Apollo DevTools. Токены, cookies и пользовательские данные удалите. Такой набор показывает, знает ли кеш объект и кто наблюдает изменяемое поле.

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