Главная / Статьи

Основы TanStack Query: запросы, кэширование, мутации и аннулирование

Узнайте, как useQuery, queryKey, staleTime, gcTime, useMutation и invalidation взаимодействуют друг с другом для управления состоянием сервера в React без необходимости написания собственных функций fetch.

Издатель: REACTAPP.TOP7 мин чтения1663 слов

Источники: Started with React Query

TanStack Query, ранее известный как React Query, отвечает за управление данными, поступающими с сервера. Название изменилось, поскольку библиотека теперь работает не только в React, но и в Svelte, Vue и Solid. Кратко её можно описать как менеджер состояния для серверного состояния.

Серверное состояние против клиентского состояния

Серверное состояние — это данные, исходящие из бэкенда или внешнего API: пользователи, товары, публикации, комментарии. Оно находится вне приложения, поэтому приложение не контролирует его полностью. Оно может изменяться без ведома приложения, могло устареть, и к нему можно получить доступ только с помощью асинхронного запроса.

Клиентское состояние принадлежит самому приложению. Например, наличие открытого модального окна существует только в браузере, как показано в примере const [isModalOpen, setIsModalOpen] = useState(false). Zustand, Redux и Jotai — это распространённые инструменты для управления таким типом состояния.

Ручной подход и его стоимость

Без библиотеки получение информации о пользователях обычно начинается с трех состояний.

const [users, setUsers] = useState([])
const [loading, setLoading] = useState(false)
const [error, setError] = useState(null)

Затем загрузку выполняет спецэффект.

useEffect(() => {
  async function fetchUsers() {
    try {
      setLoading(true)      const res = await fetch(
        "https://jsonplaceholder.typicode.com/users"
      )      const data = await res.json()      setUsers(data)
    } catch (err) {
      setError(err)
    } finally {
      setLoading(false)
    }
  }  fetchUsers()

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

То же самое с запросом

Один единственный хук заменяет всю шаблонную рутину.

function Users() {
  const {
    data,
    isLoading,
    error
  } = useQuery({
    queryKey: ["users"],
    queryFn: fetchUsers
  })

Затем компонент разветвляется в зависимости от статуса.

  if (isLoading) {
    return <p>Loading...</p>
  }  if (error) {
    return <p>Something went wrong</p>
  }  return (
    <ul>
      {data.map(user => (
        <li key={user.id}>
          {user.name}
        </li>
      ))}
    </ul>
  )
}

TanStack Query обеспечивает управление инфраструктурой, связанной с серверными данными. Его главное преимущество по сравнению с использованием useEffect и useState — встроенная кэширование. Как только данные поступают, они сохраняются в кэше и могут быть использованы повторно, что сокращает количество ненужных запросов к API. Статусы загрузки, успешного выполнения и ошибок отслеживаются автоматически, поэтому не требуется вручную писать и поддерживать какую-либо логику.

Настройка

Установите пакет.

npm install @tanstack/react-query

Затем создайте QueryClient и передайте его приложению.

const queryClient = new QueryClient();

root.render(
<QueryClientProvider client={queryClient}>
    <App />
</QueryClientProvider>
);

Чтение данных с useQuery

Хук useQuery отвечает за операции чтения, то есть за любые действия по получению данных с сервера. Простой вызов выглядит следующим образом:

const { data,
isPending,
error } = useQuery({
 queryKey: ["users"],
 queryFn: fetchUsers
 })

Этот метод принимает объект с параметрами, среди которых наиболее важны два свойства: queryFn и queryKey.

queryFn — это функция, к которой обращается TanStack Query для получения данных. Она возвращает данные напрямую или в виде Promise, а в случае ошибки должна выбросить исключение или вернуть отклонённый Promise.

async function fetchUsers() {
  const res = await fetch("/api/users")

  if (!res.ok) {
    throw new Error("Failed to fetch users")
  }

  return res.json()
}

Затем он подключается к крючку:

useQuery({
  queryKey: ["users"],
  queryFn: fetchUsers
})

queryKey уникально идентифицирует запрос и его сохранённые в кэше данные. Переменные, используемые в queryFn, как правило, должны входить в состав ключа. Например, ["users"] может означать всех пользователей, ["todo", 1] — задачу с ID 1, а ["products", "laptops"] — ноутбуки.

Хук возвращает объект с информацией о статусе запроса (загрузка, ошибка или успех), данными и функциями для повторной загрузки.

Как помогает кэш

Именно здесь библиотека проявляет свою ценность. Загруженные данные автоматически сохраняются и повторно используются для избежания избыточных запросов, что улучшает производительность и сокращает время отображения результатов.

Предположим, компонент A запрашивает ["users"]. TanStack Query загружает данные и сохраняет их в кэше. Позже компонент B запрашивает тот же ключ, и библиотека замечает, что данные уже находятся в кэше. Вместо того чтобы каждый компонент хранил свою собственную копию, TanStack Query управляет одной копией состояния сервера в кэше. Это одно из главных отличий этой библиотеки от простой функции fetch().

staleTime и gcTime

staleTime отвечает на один вопрос: как долго эти данные должны считаться актуальными?

useQuery({
  queryKey: ["users"],
  queryFn: fetchUsers,
  staleTime: 60,000 // 60 seconds
})

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

Игнорирование факта устаревания приводит к ненужным запросам при повторном посещении страницы пользователем.

User visits page
       ↓
Fetch users
       ↓
User navigates away
       ↓
User comes back
       ↓
Fetch users again

Если ничего не изменилось, второй запрос теряет смысл. Более длительное окно свежести позволяет избежать этого:

staleTime: 5 * 60 * 1000

Это помечает данные как свежие на пять минут. Помните, что staleTime контролирует срок свежести и не является интервалом повторного загрузки.

Также существует gcTime — время сбора мусора. Оно определяет, как долго неактивные, незамеченные закэшированные данные остаются в памяти перед тем, как их удалят.

useQuery({
  queryKey: ["users"],
  queryFn: fetchUsers,
  gcTime: 60000
})

Подводя итог, staleTime определяет, как долго данные остаются актуальными, а gcTime — как долго остаются неприменяемые записи кэша. Они решают разные проблемы.

Повторное получение данных

Устаревшие запросы могут быть повторно загружены при инициализации компонента, при возвращении фокуса на окне или при восстановлении сетевого соединения, причем эти действия можно настроить. Также доступна возможность ручного повторного получения данных.

const { refetch } = useQuery(...)
refetch()

Также возможен опрос.

useQuery({
  queryKey: ["users"],
  queryFn: fetchUsers,
  refetchInterval: 30,000
})

Пока запрос активен, он обновляется примерно каждые 30 секунд. При обновлении устаревшие данные заменяются на свежие данные с сервера.

Изменение данных с помощью useMutation

До сих пор рассматривались операции по чтению данных. Создание, обновление или удаление данных (POST, PUT, PATCH, DELETE) осуществляется с помощью хука useMutation. В качестве примера приведён процесс создания пользователя. Сначала создаётся функция мутации.

async function createUser(user) {
  const response = await fetch(
    "https://jsonplaceholder.typicode.com/users",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify(user),
    }
  );

  if (!response.ok) {
    throw new Error("Failed to create user");
  }

  return response.json();
}

Затем он передаётся в useMutation.

import { useMutation } from "@tanstack/react-query";

function CreateUser() {
  const mutation = useMutation({
    mutationFn: createUser,
  });

  return (
    <button
      onClick={() =>
        mutation.mutate({
          name: "John Doe",
          email: "john@example.com",
        })
      }
      disabled={mutation.isPending}
    >
      {mutation.isPending ? "Creating..." : "Create User"}
    </button>
  );
}

export default CreateUser;

Нажатие кнопки запускает мутацию с помощью mutation.mutate().

Button click
    ↓
mutation.mutate(user)
    ↓
createUser(user)
    ↓
POST request
    ↓
Server

Обратите внимание, что функция createUser() никогда не вызывается напрямую. Компонент вызывает mutation.mutate(), а TanStack Query выполняет эту функцию.

Мутации, как и запросы, имеют флаги состояния.

const {
  mutate,
  isPending,
  isSuccess,
  isError,
  error,
  data,
} = useMutation({
  mutationFn: createUser,
});

Они управляют интерфейсом пользователя.

<button
  onClick={() => mutate({ userName: "delfina ghimire" })}
  disabled={isPending}
>
  {isPending ? "Creating..." : "Create user"}
</button>

После запуска функции mutate() мутация проходит через несколько состояний:

  • isPending: мутация выполняется.
  • isSuccess: она завершилась успешно.
  • isError: она потерпела неудачу.
  • data: результат успешной мутации.
  • error: детали неудачи.
  • mutate: функция-триггер, принимающая параметры для функции мутации.

Это облегчает предоставление обратной связи во время создания, обновления или удаления данных.

QueryClient и аннулирование

QueryClient — это центральный объект, который управляет кэшем и координирует поведение запросов и мутаций. Он создается с помощью new QueryClient(), а внутри компонента к нему обращаются через useQueryClient(). Он поддерживает аннулирование запросов, обновление данных в кэше, удаление данных из кэша, сброс запросов и предзагрузку. Типичный вызов выглядит так: queryClient.invalidateQueries({ queryKey: ["users"] }).

Аннулирование особенно важно после мутаций. Когда мутация изменяет данные на сервере, связанные запросы могут содержать устаревшие результаты, и их аннулирование помечает их как устаревшие, чтобы их можно было заново загрузить. Предположим, что в кэше хранятся два пользователя:

[
  { id: 1, userName: "delfina ghimire" },
  { id: 2, userName: "spiderman ghimire" },
]

Затем создается новый пользователь.

mutation.mutate({
  userName: "ironman ghimire",
});

На сервере теперь трое пользователей, но в кэше по-прежнему отображается двое. Запрос ["users"] можно пометить как устаревший. Сначала получаем клиент:

const queryClient = useQueryClient();

Затем мутация аннулируется при успехе.

const mutation = useMutation({
  mutationFn: createUser,
  onSuccess: () => {
    queryClient.invalidateQueries({
      queryKey: ["users"],
    });
  },
});

Процесс происходит следующим образом:

Create Users (Mutation)
     ↓
Server data changes
     ↓
Invalidate ["users"]
     ↓
Query becomes stale
     ↓
Refetch
     ↓
UI gets fresh data

Чтобы различать эти понятия: invalidate отмечает кэшированные данные как устаревшие, а refetch сразу же загружает их заново. Аннулирование действующего запроса обычно приводит к автоматической повторной загрузке.

Общая картина

Все элементы связаны в единую картину:

  1. TanStack Query управляет серверными данными.
  2. Чтение данных осуществляется с помощью useQuery.
  3. Загруженные данные хранятся в кэше запросов.
  4. staleTime определяет, когда кэшированные данные считаются актуальными.
  5. gcTime определяет, как долго остаются неприменяемые записи кэша.
  6. Повторная загрузка определяет момент, когда данные загружаются заново.
  7. Создание, обновление и удаление данных происходят через useMutation.
  8. QueryClient координирует запросы, мутации и кэш.
  9. Аннулирование запроса сигнализирует о том, что кэшированные данные устарели.

Когда эти взаимосвязи становятся ясными, понимание библиотеки значительно упрощается.