Client-side Cache trong React với TanStack Query
Hiểu sâu về client-side cache trong React: staleTime, gcTime, deduplication, cache invalidation và optimistic updates với TanStack Query.
Khi xây dựng một ứng dụng React, chúng ta thường gặp phải một câu hỏi muôn thuở: “API đã trả về dữ liệu rồi, vậy khi sang màn hình khác hoặc mở component khác, có cần gọi lại API không?”
Hãy tưởng tượng một trang web có endpoint GET /api/users/123. Component thông tin cá nhân (Header) cần thông tin user đó, component trang tài khoản (Profile Content) cũng cần, rồi component danh sách hoạt động gần đây (Activity Feed) lại cần tiếp.
Component Header ──→ GET /api/users/123
Component Profile ──→ GET /api/users/123
Component ActivityFeed ──→ GET /api/users/123textNếu theo cách tiếp cận truyền thống dùng useEffect kết hợp useState, mỗi khi một component mount, nó lại bắn một request ra server. Kết quả là mạng nghẽn vì hàng loạt request trùng lặp, giao diện nhấp nháy spinner liên tục, và server phải gánh tải vô ích.
[!NOTE] TL;DR:
@tanstack/react-query(tiền thân là React Query) không chỉ đơn thuần là thư viện thay thếfetch()hayaxios. Nó thực chất là một Client-side Server-State Cache (bộ nhớ đệm trạng thái máy chủ phía client), tự động lưu trữ, chia sẻ dữ liệu API giữa các component, khử trùng lặp request (deduplication), quản lý vòng đời dữ liệu (fresh/stale), và hỗ trợ cập nhật giao diện mượt mà (optimistic update).
1. Vấn đề cốt lõi: Nỗi đau tự làm Cache (DIY Cache)#
Khi nhận thấy vấn đề gọi lặp request, phản xạ tự nhiên của nhiều lập trình viên là tự chế bộ nhớ đệm:
const userCache = new Map<number, Promise<User> | User>()
export async function getUser(userId: number): Promise<User> {
if (userCache.has(userId)) {
return userCache.get(userId)!
}
const promise = fetch(`/api/users/${userId}`)
.then((res) => res.json())
.then((data) => {
userCache.set(userId, data)
return data
})
userCache.set(userId, promise)
return promise
}typescriptBan đầu nhìn có vẻ tinh gọn. Nhưng khi ứng dụng phát triển thực tế, một bộ cache tự chế bằng Map() nhanh chóng đẩy bạn vào “vũng bùn” của hàng tá bài toán nan giải:
- Bao lâu thì dữ liệu hết hạn? (Stale expiration)
- Khi nào cần refetch ngầm dưới background?
- Nếu user vừa sửa tên thì làm sao thông báo cho mọi component đang hiển thị? (Cache invalidation)
- Quản lý trạng thái loading, error, retry khi rớt mạng ra sao?
- Xử lý race condition khi user đổi trang liên tục thế nào?
- Khi user rời khỏi trang 30 phút, bộ nhớ có bị rò rỉ (memory leak) vì Map giữ object mãi không xóa? (Garbage collection)
- Xử lý phân trang (pagination) và cuộn vô tận (infinite scroll) như thế nào?
Một Map() đơn giản ban đầu sẽ buộc bạn phải viết lại 80% tính năng của một thư viện cache hoàn chỉnh. Đây chính là lúc TanStack Query phát huy sức mạnh.
2. Mô hình tư duy (ELI5): Server State vs. Client State#
Để hiểu TanStack Query, điều tối quan trọng là phải phân biệt được hai loại trạng thái trong ứng dụng frontend.
Giải thích như cho một đứa trẻ 10 tuổi (ELI5)#
- Client State (Trạng thái Client): Giống như cuốn sổ tay ghi chú đặt trên bàn học của bạn. Bạn muốn vẽ gì, mở trang nào, đổi bút màu gì thì bạn toàn quyền quyết định. Không ai ở bên ngoài can thiệp. Ví dụ: menu đang mở hay đóng, theme sáng hay tối, form input đang nhập dở.
- Server State (Trạng thái Server): Giống như một cuốn sách bạn mượn ở thư viện công cộng. Bạn chỉ đang cầm một bản sao tạm thời (snapshot). Ở thư viện, thủ thư hoặc độc giả khác có thể đã cập nhật nội dung mới hoặc sách đã bị mượn mất mà bạn không hề hay biết!
[!WARNING] Frontend không thực sự sở hữu Server State. Nguồn chân lý duy nhất (Single Source of Truth) luôn nằm ở cơ sở dữ liệu của backend. Vì vậy, dữ liệu API trên frontend luôn có nguy cơ bị cũ (stale) ngay từ giây phút nó vừa tải xong.
Đó là lý do tại sao không nên nhồi nhét dữ liệu API vào Redux hay Zustand. Redux và Zustand được sinh ra cho Client State đồng bộ, còn TanStack Query được thiết kế chuyên biệt để làm bộ đệm trung gian cho Server State bất đồng bộ.
3. Cơ chế hoạt động của TanStack Query Cache#
Hãy bắt đầu với ví dụ cơ bản. Trước tiên, bọc ứng dụng trong QueryClientProvider:
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { UserProfile } from './UserProfile'
const queryClient = new QueryClient()
export function App() {
return (
<QueryClientProvider client={queryClient}>
<UserProfile userId={123} />
</QueryClientProvider>
)
}tsxTrong component, ta gọi useQuery:
import { useQuery } from '@tanstack/react-query'
interface User {
id: number
name: string
email: string
}
async function fetchUser(userId: number): Promise<User> {
const res = await fetch(`/api/users/${userId}`)
if (!res.ok) throw new Error('Không thể tải thông tin user')
return res.json()
}
export function UserProfile({ userId }: { userId: number }) {
const { data, isPending, error } = useQuery({
queryKey: ['user', userId],
queryFn: () => fetchUser(userId),
})
if (isPending) return <div className="skeleton">Đang tải...</div>
if (error) return <div className="alert-error">Lỗi: {error.message}</div>
return (
<div className="card">
<h2>{data.name}</h2>
<p>{data.email}</p>
</div>
)
}tsxqueryKey chính là định danh (Identity) của Cache#
TanStack Query lưu trữ các truy vấn trong một bộ nhớ đệm dạng cây/bảng băm dựa vào queryKey. Mảng này được tuần tự hóa (deterministic serialization) để làm khóa:
['user', 123] ──→ Cache entry A: { id: 123, name: 'John' }
['user', 456] ──→ Cache entry B: { id: 456, name: 'Alice' }
['posts', 123] ──→ Cache entry C: [ ... ]textNếu hai component ở hai nhánh cây DOM hoàn toàn độc lập cùng gọi useQuery với queryKey: ['user', 123], TanStack Query sẽ nhận diện ngay lập tức rằng khóa này đã tồn tại trong bộ đệm và tái sử dụng dữ liệu!
4. Khử trùng lặp Request (Request Deduplication)#
Một kịch bản rất phổ biến: Bạn mở một trang Dashboard phức tạp gồm 3 component con cùng hiển thị dữ liệu của người dùng hiện tại:
Nếu không có cơ chế khử trùng lặp, trình duyệt sẽ gửi đi 3 network request y hệt nhau. TanStack Query thông minh gom các lời gọi cùng queryKey đang diễn ra (in-flight request) lại và chỉ gửi đúng một HTTP request. Cả ba component sẽ cùng chia sẻ chung một Promise và render kết quả cùng lúc khi request hoàn thành.
5. staleTime vs. gcTime: Hiểu đúng điểm gây nhầm lẫn số 1#
Đây là nơi hầu hết lập trình viên mới tiếp cận TanStack Query hay hiểu sai nhất.
| Thuộc tính | Tên cũ | Ý nghĩa thực sự | Mặc định |
|---|---|---|---|
staleTime | staleTime | Dữ liệu được coi là “còn tươi mới” (fresh) trong bao lâu trước khi trở thành “cũ” (stale)? | 0 ms |
gcTime | cacheTime | Dữ liệu không còn component nào sử dụng (inactive) sẽ được lưu lại trong RAM bao lâu trước khi bị Garbage Collector giải phóng? | 5 * 60 * 1000 (5 phút) |
00s: Fetch dữ liệu hoàn tất ──→ Data Fresh
│
│ (Trong khoảng staleTime: component mount sẽ lấy thẳng cache, không gọi lại API)
▼
60s: Hết staleTime ──────────→ Data trở thành Stale (vẫn còn trong cache!)
│
│ (User chuyển trang, không còn component nào subscribe ['users'])
▼
70s: Query chuyển sang Inactive ──→ Bắt đầu đếm ngược gcTime (5 phút)
│
▼
370s: Hết gcTime ────────────→ Dữ liệu chính thức bị xóa khỏi bộ nhớ RAMtext[!TIP] Nhớ quy tắc vàng:
staleTime: 60000KHÔNG có nghĩa là sau 60 giây cache sẽ bị xóa! Nó chỉ có nghĩa là sau 60 giây, dữ liệu bị đánh dấu là “đã cũ”. Lần tới khi user tương tác hoặc component mount, TanStack Query sẽ phục vụ dữ liệu cũ đó ngay lập tức (để UI không bị trắng) và âm thầm tải dữ liệu mới từ backend về để cập nhật (mô hình Stale-While-Revalidate).
Cấu hình thực tế cho dữ liệu ít thay đổi#
Với các dữ liệu danh mục tĩnh hoặc ít biến động (danh sách quốc gia, quyền hạn người dùng, cấu hình hệ thống):
export const categoriesQueryOptions = {
queryKey: ['categories'],
queryFn: fetchCategories,
staleTime: 10 * 60 * 1000, // Coi là tươi mới trong 10 phút
gcTime: 60 * 60 * 1000, // Giữ trong RAM 60 phút nếu user rời trang
}typescript6. Đánh đổi (Trade-off): Hiệu năng vs. Độ tươi mới#
Client-side cache luôn đi kèm một bài toán đánh đổi kinh điển:
Hiệu năng tối đa (Ít gọi API) ◄───────────► Dữ liệu luôn mới nhất (Real-time)
staleTime lớn staleTime = 0textNếu server đổi tên user từ "John" sang "Mike", nhưng phía client đang đặt staleTime: 10 phút, client vẫn sẽ yên trí hiển thị "John" cho đến khi hết hạn hoặc có sự kiện kích hoạt refetch.
Để giữ cho dữ liệu luôn tiệm cận thời gian thực mà không làm phiền trải nghiệm người dùng, TanStack Query cung cấp các cơ chế tự động Background Refetching:
refetchOnWindowFocus(mặc định:true): Khi người dùng chuyển sang tab khác rồi quay lại ứng dụng, TanStack Query sẽ tự động làm mới các query đangstale.refetchOnReconnect(mặc định:true): Tự động tải lại dữ liệu khi thiết bị có mạng trở lại.refetchOnMount(mặc định:true): Tự động fetch lại nếu query đã stale khi component vừa mount.
7. Cập nhật dữ liệu với Mutation và Cache Invalidation#
Khi thực hiện thao tác thay đổi dữ liệu (Create, Update, Delete), chúng ta sử dụng useMutation kết hợp với queryClient.invalidateQueries.
Ví dụ triển khai chuẩn:
import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
export function UserManagement() {
const queryClient = useQueryClient()
// 1. Lấy danh sách
const { data: users, isPending } = useQuery({
queryKey: ['users'],
queryFn: async () => {
const res = await fetch('/api/users')
return res.json()
},
staleTime: 60_000,
})
// 2. Mutation thêm mới
const addMutation = useMutation({
mutationFn: async (newUser: { name: string }) => {
const res = await fetch('/api/users', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(newUser),
})
if (!res.ok) throw new Error('Không thể tạo người dùng')
return res.json()
},
onSuccess: () => {
// Đánh dấu toàn bộ query có prefix ['users'] cần refetch
queryClient.invalidateQueries({ queryKey: ['users'] })
},
})
if (isPending) return <div>Đang tải danh sách...</div>
return (
<div>
<ul>
{users?.map((u: { id: number; name: string }) => (
<li key={u.id}>{u.name}</li>
))}
</ul>
<button
type="button"
disabled={addMutation.isPending}
onClick={() => addMutation.mutate({ name: 'Thành viên mới' })}
>
{addMutation.isPending ? 'Đang thêm...' : 'Thêm thành viên'}
</button>
</div>
)
}tsx8. Cập nhật giao diện tức thì: Optimistic Update#
Trong các tính năng tương tác nhanh như nút “Thả tim” (Like) hay toggle trạng thái công việc (Todo checkbox), việc chờ server phản hồi 300ms–1s sẽ khiến ứng dụng có cảm giác chậm chạp và giật lag.
Optimistic Update cho phép chúng ta cập nhật giao diện ngay lập tức, đồng thời bắn API ngầm. Nếu server thất bại, hệ thống sẽ tự động khôi phục (rollback) về trạng thái cũ:
import { useMutation, useQueryClient } from '@tanstack/react-query'
interface Post {
id: number
title: string
likes: number
}
export function useLikePost(postId: number) {
const queryClient = useQueryClient()
return useMutation({
mutationFn: async () => {
const res = await fetch(`/api/posts/${postId}/like`, { method: 'POST' })
if (!res.ok) throw new Error('Like thất bại')
return res.json()
},
// Chạy trước khi mutationFn được kích hoạt
onMutate: async () => {
// 1. Hủy bỏ mọi refetch đang diễn ra để tránh ghi đè optimistic update
await queryClient.cancelQueries({ queryKey: ['post', postId] })
// 2. Lưu lại snapshot của dữ liệu hiện tại để rollback nếu lỗi
const previousPost = queryClient.getQueryData<Post>(['post', postId])
// 3. Cập nhật cache ngầm ngay lập tức
queryClient.setQueryData<Post>(['post', postId], (old) => {
if (!old) return old
return { ...old, likes: old.likes + 1 }
})
// 4. Trả về context chứa snapshot
return { previousPost }
},
// Nếu có lỗi, phục hồi dữ liệu từ snapshot
onError: (_err, _variables, context) => {
if (context?.previousPost) {
queryClient.setQueryData(['post', postId], context.previousPost)
}
},
// Luôn luôn đồng bộ lại với server sau khi hoàn tất (dù thành công hay thất bại)
onSettled: () => {
queryClient.invalidateQueries({ queryKey: ['post', postId] })
},
})
}tsx9. Phân biệt: TanStack Query vs. HTTP Browser Cache#
Nhiều người thắc mắc: “Trình duyệt đã có HTTP Cache với Cache-Control, ETag rồi, tại sao lại cần thêm TanStack Query?”
Thực tế, chúng là hai lớp phòng thủ độc lập nằm ở hai tầng khác nhau trong kiến trúc:
| Tiêu chí | TanStack Query | HTTP Cache Trình Duyệt |
|---|---|---|
| Vị trí | JavaScript RAM Memory của ứng dụng | Tầng mạng (Network stack) của trình duyệt |
| Phạm vi hiểu biết | Hiểu vòng đời React (component mount/unmount, re-render) | Chỉ hiểu URL, Headers và phương thức HTTP (GET, POST) |
| Khả năng phản ứng (Reactivity) | Tự kích hoạt React re-render khi dữ liệu thay đổi | Không có khái niệm re-render UI |
| Deduplication | Chia sẻ 1 in-flight Promise giữa nhiều component | Có thể gửi nhiều request đồng thời nếu cùng thời điểm |
| Mutation & Rollback | Có Optimistic updates, cache rollback, invalidation | Hoàn toàn không hỗ trợ |
Hai hệ thống này tương hỗ lẫn nhau: HTTP Cache giúp tiết kiệm băng thông mạng (với mã 304 Not Modified), còn TanStack Query đảm bảo trải nghiệm người dùng mượt mà, không giật lag.
10. Tổ chức dự án thực tế: Pattern Query Key Factory#
Trong dự án thực tế, viết trực tiếp các mảng ký tự tùy ý như ['users', id, 'posts'] rải rác khắp nơi rất dễ dẫn đến lỗi gõ sai chính tả hoặc không thể quản lý khi cần invalidate hàng loạt.
Hãy áp dụng pattern Query Key Factory:
export const userKeys = {
all: ['users'] as const,
lists: () => [...userKeys.all, 'list'] as const,
list: (filters: { page: number; search?: string }) =>
[...userKeys.lists(), filters] as const,
details: () => [...userKeys.all, 'detail'] as const,
detail: (id: number) => [...userKeys.details(), id] as const,
}typescriptNhờ cấu trúc hình cây này:
- Muốn xóa toàn bộ cache liên quan đến users:
queryClient.invalidateQueries({ queryKey: userKeys.all }) - Muốn chỉ xóa danh sách mà giữ lại chi tiết:
queryClient.invalidateQueries({ queryKey: userKeys.lists() }) - Muốn truy vấn cụ thể một user:
queryKey: userKeys.detail(userId)
11. Khi nào nên dùng và Khi nào KHÔNG cần?#
Rất nên dùng TanStack Query#
- Ứng dụng quản trị (Dashboard, Admin portal), SaaS, CRM, sàn thương mại điện tử.
- Các ứng dụng có lượng tương tác dữ liệu lớn, nhiều quan hệ dữ liệu liên kết chéo giữa các màn hình.
- Ứng dụng Single Page Application (SPA) viết bằng React thuần, Vite, Next.js (Client Components).
Chưa nhất thiết phải dùng#
- Trang tĩnh (Static landing pages) chỉ gọi đúng 1 API lấy form liên hệ.
- Ứng dụng chủ yếu dựa vào kiến trúc React Server Components (RSC) thuần túy với Next.js App Router, nơi dữ liệu được fetch và cache trực tiếp tại tầng máy chủ (Server Data Cache).
12. Tổng kết#
Bản chất của TanStack Query không phải là “công cụ gọi API”, mà là hệ thống quản trị bộ nhớ đệm cho dữ liệu bất đồng bộ phía client.
Khi nắm vững được:
- Sự khác biệt giữa Client State (Zustand/useState) và Server State (TanStack Query).
- Định danh cache bằng
queryKey. - Ranh giới giữa
staleTime(tươi mới) vàgcTime(giải phóng bộ nhớ). - Quy trình bất biến Mutation ➔ Invalidate ➔ Refetch.
Bạn sẽ không còn phải vất vả đối phó với những lỗi bất đồng bộ khó chịu, đồng thời mang lại trải nghiệm nhanh chóng, mượt mà vượt bậc cho người dùng.