Головна / Статті

Основи 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. Анулювання запиту сигналізує про те, що дані в кеші застаріли.

Коли ці зв’язки стають зрозумілими, бібліотеку значно легше аналізувати.