Асаліны TanStack Query: запыты, кэшаванне, мутацыі і анавалідаванне
Дазвольце дазнаць, як useQuery, queryKey, staleTime, gcTime, useMutation і invalidation саюзуюцца для керавання станам сервера ў React без неабяжнага выкарыстоўвання fetch эфектаў.
Крыніцы: 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, а у разе неудачы ён павінен выклікнуць або вярнуць атрыбут rejected 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"] — ноутбукі.
Хук вяртае об’ект з статусам запіту (завантажэнне, адказ пра адказ чы успех), дадзенымі і функцыямі для паўторнага завантажэння.
Як дапамагае кэш
Сюды і прыносіць бібліятэка сваю цэннасць. Завантажаныя дадзеныя автаматычна зберагаюцца і выкарыстоўваюцца знову, каб утрымацься ад зайвых запытоў, што паўлічвае працэсавую скорасць і скарацвае час адображэння рэзультатаў.
Компанент А запрашвае ["users"]. TanStack Query запрашвае і зберагае гэты рэзультат у кэшы. Пазней компанент Б таксама запрашвае гэты ключ, і бібліятэка заўважае, што даныя вялікі ўжо кэшаваныя. У працоўку замест таго, каб кожны компанент трываў сабе свой экземпляр, 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 негайна ўтварае ўпорадкуванне з іх новым завантажэнням. Анулюванне актыўнага запіту зазвычай спрыяе аўтаматычнаму новаму завантажэнню.
Весь картэнак
Усе эты элементы складаюць адну цяглую картыну:
- TanStack Query караце працу з данымі на серверы.
- Чытанне дадзеных адбываецца за дапамогою
useQuery. - Завантажаныя дадзеныя зберагаюцца ў кэшы запітаў.
staleTimeвяршыць прыняцце рашэння, калі даныя з кэша лягчаюць счыляцца за свежыя.gcTimeвяршыць прыняцце рашэння, як давго застарэлыя ентры кэша застаюцца без вікорыстання.- Працэс перзавантажэння дадзеных вяршыць прыняцце рашэння, калі іх празначаецца зноў завантажыць.
- Стварэнне, адчыненне і выдаленне дадзеных адбываецца праз
useMutation. - QueryClient коордынуе запіты, мутацыі і кэш.
- Анулюванне запіта сігналізуе пра тое, што даныя з кэша ўстарэлі.
Калі гэтыя зв’язкі ясны, бібліятэку стае набагато лёгкая для розумення.