blog.dopana

Quay lại

Tập trung vào cách hiểu đơn giản và ứng dụng thực tế của TanStack Query trong React, đặc biệt là client-side cache.

TL;DR: @tanstack/react-query không chỉ là thư viện gọi API. Nó có thể đóng vai trò như một client-side server-state cache, giúp cache dữ liệu API, tránh request lặp lại, tự refetch khi cần và quản lý trạng thái loading/error rất tiện lợi.

Vấn đề: Request API trùng lặp#

Khi xây dựng một ứng dụng React, chúng ta thường gặp một vấn đề khá phổ biến:

API trả về dữ liệu rồi, vậy lần sau có cần gọi API lại không?

Ví dụ một trang có API:

GET /api/users/123
text

Nếu component A gọi API này, sau đó component B cũng cần thông tin user 123, cách làm truyền thống có thể khiến cả hai component đều gọi API.

Component AGET /api/users/123Component BGET /api/users/123

Điều này tạo ra request dư thừa.

Một giải pháp là tự xây dựng cache:

cache.ts
const cache = new Map()
ts

Nhưng khi ứng dụng lớn lên, việc tự quản lý cache sẽ nhanh chóng trở nên phức tạp.

Đây là lúc TanStack Query trở nên hữu ích.

TanStack Query là gì?#

TanStack Query, trước đây thường được biết đến với tên React Query, là thư viện chuyên quản lý server state trong frontend.

Package dành cho React là:

terminal
npm install @tanstack/react-query
bash

Điểm quan trọng là:

TanStack Query không đơn thuần là một thư viện fetch() API.

Nó cung cấp một hệ thống để:

  • fetch data
  • cache data
  • deduplicate request
  • refetch data
  • retry request
  • quản lý loading/error
  • invalidate cache
  • optimistic update
  • pagination
  • infinite query
  • background refetch

Server State và Client State khác nhau thế nào?#

Đây là khái niệm quan trọng nhất để hiểu TanStack Query.

Client State#

Là state thuộc về UI/application.

Ví dụ:

ThemeToggle.tsx
const [isOpen, setIsOpen] = useState(false)
tsx

Hoặc:

ThemeToggle.tsx
const [theme, setTheme] = useState("dark")
tsx

Dữ liệu này thuộc về frontend.

Server State#

Là dữ liệu đến từ backend.

Ví dụ:

user.json
{
  "id": 123,
  "name": "John",
  "email": "john@example.com"
}
json

Frontend không thực sự sở hữu dữ liệu này.

Backend mới là nguồn dữ liệu chính.

APIServer(nguồn dữ liệu chính)TanStack QueryCacheComponent AComponent B

TanStack Query được thiết kế chủ yếu để giải quyết loại state này.

[!NOTE] ELI5: Client State giống như công tắc đèn trong nhà bạn — bạn toàn quyền bật/tắt. Server State giống như thời tiết ngoài trời — bạn chỉ có thể “xem” qua cửa sổ (API), không sở hữu nó, và nó có thể thay đổi bất cứ lúc nào.

Không nên nhầm TanStack Query với Redux#

Một cách hiểu đơn giản:

Redux/Zustand
    ↓
Client State

TanStack Query
    ↓
Server State
text

Ví dụ:

ui-store.ts
{
  sidebarOpen: true,
  theme: "dark"
}
ts

phù hợp với Zustand/Redux.

Trong khi:

server-state.ts
{
  users: [...],
  posts: [...],
  products: [...],
  profile: {...}
}
ts

nếu dữ liệu đến từ API thì TanStack Query thường phù hợp hơn.

Tất nhiên hai loại state có thể cùng tồn tại trong một ứng dụng.

Cache hoạt động như thế nào?#

Ví dụ:

UserProfile.tsx
const { data } = useQuery({
  queryKey: ["user", userId],
  queryFn: () => fetchUser(userId),
})
tsx

TanStack Query sử dụng:

queryKey
ts

để xác định dữ liệu nào đang được cache.

Ví dụ:

["user", 123]
text

và:

["user", 456]
text

là hai cache entry khác nhau.

Có thể hình dung:

Query Cache

"user", 123
    ↓
{ id: 123, name: "John" }

"user", 456
    ↓
{ id: 456, name: "Alice" }

"posts", 123
    ↓
[ ... ]
text

[!TIP] Hãy nghĩ queryKey như mã số tủ đồ ở siêu thị: mỗi key mở đúng một ngăn chứa dữ liệu. Key khác nhau → ngăn khác nhau, không bao giờ lẫn lộn.

Ví dụ cơ bản#

Đầu tiên tạo QueryClient.

App.tsx
import {
  QueryClient,
  QueryClientProvider,
} from "@tanstack/react-query"

const queryClient = new QueryClient()

export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <MyApp />
    </QueryClientProvider>
  )
}
tsx

Sau đó sử dụng query:

Điểm đáng chú ý là:

queryKey: ["user", userId]
ts

chính là identity của cache.

[!NOTE] Từ TanStack Query v5, trạng thái loading ban đầu là isPending (thay cho isLoading ở v4), và cacheTime được đổi tên thành gcTime. Các ví dụ trong bài dùng API v5.

Khi component thứ hai gọi cùng API#

Giả sử có:

<UserProfile userId={123} />
tsx

ở component A.

Sau đó component B cũng sử dụng:

<UserProfile userId={123} />
tsx

TanStack Query biết rằng:

["user", 123]
text

đã tồn tại trong Query Cache.

Vì vậy component B thấy dữ liệu có sẵn ngay lập tức thay vì hiện màn hình loading trắng.

Component Amount trướcQuery Cache['user', 123]Component Bmount sauAPI Request(chỉ khi cần)

Đây là một trong những điểm mạnh lớn của TanStack Query.

[!NOTE] Mặc định staleTime là 0, nghĩa là dữ liệu cache được coi là stale ngay lập tức. Component B vẫn thấy dữ liệu cũ ngay tức thì (không loading), đồng thời TanStack Query refetch ngầm dưới nền để cập nhật — pattern này gọi là stale-while-revalidate.

Request Deduplication#

Một tình huống rất thường gặp:

Component A ─┐
             │
Component B ─┼──→ GET /api/user/123
             │
Component C ─┘
text

Nếu cả ba component cùng mount gần như đồng thời, bạn không muốn gửi:

GET /api/user/123
GET /api/user/123
GET /api/user/123
text

TanStack Query có cơ chế chia sẻ/deduplicate request dựa trên query key.

Về mặt concept:

Component AQuery Cache['user', 123]Component BComponent C1 API Request duy nhất

staleTime – dữ liệu được xem là cũ sau bao lâu?#

Đây là một option rất quan trọng.

Ví dụ:

UsersList.tsx
useQuery({
  queryKey: ["users"],
  queryFn: fetchUsers,
  staleTime: 60_000,
})
tsx

Có nghĩa là dữ liệu được coi là fresh trong 60 giây.

Trong khoảng thời gian đó, nếu component khác sử dụng:

["users"]
ts

TanStack Query có thể sử dụng cache hiện tại thay vì refetch ngay lập tức.

Ví dụ:

00s  API request
     ↓
     cache

10s  component B
     ↓
     dùng cache

30s  component C
     ↓
     dùng cache

60s  cache trở thành stale
text

staleTime không phải thời gian xóa cache#

Đây là một nhầm lẫn rất phổ biến.

Ví dụ:

staleTime: 60_000
ts

không có nghĩa:

Sau 60 giây cache bị xóa.

Nó chỉ có nghĩa:

Sau 60 giây, dữ liệu được coi là stale.

Dữ liệu vẫn có thể nằm trong cache.

[!WARNING] Nhầm lẫn phổ biến nhất khi học TanStack Query: staleTime là “dữ liệu còn tươi bao lâu”, KHÔNG phải “cache tồn tại bao lâu”. Hết staleTime thì dữ liệu chỉ bị đánh dấu cũ — lần dùng tiếp theo sẽ refetch ngầm, chứ cache không bị xóa.

gcTime#

TanStack Query còn có:

gcTime
ts

trước đây thường được gọi là:

cacheTime
text

Nó liên quan đến thời gian dữ liệu không còn được sử dụng trước khi được garbage collect.

Ví dụ:

UsersList.tsx
useQuery({
  queryKey: ["users"],
  queryFn: fetchUsers,
  staleTime: 60_000,
  gcTime: 5 * 60_000,
})
tsx

Có thể hiểu đơn giản:

staleTime
    ↓
Bao lâu dữ liệu được xem là fresh?

gcTime
    ↓
Bao lâu cache inactive được giữ lại?
text

Hai khái niệm này khác nhau.

[!NOTE] Mặc định: staleTime là 0 (stale ngay), gcTime là 5 phút (giữ cache inactive 5 phút sau khi component cuối cùng unmount). Hai con số này giải thích hầu hết hành vi “lạ” mà người mới gặp phải.

Một cấu hình thực tế#

Ví dụ API sản phẩm:

ProductsList.tsx
const productsQuery = useQuery({
  queryKey: ["products"],
  queryFn: fetchProducts,
  staleTime: 5 * 60 * 1000,
  gcTime: 30 * 60 * 1000,
})
tsx

Có thể hiểu:

5 phút
↓
data được xem là fresh

30 phút
↓
inactive cache có thể được garbage collect
text

Điều này đặc biệt hữu ích với những dữ liệu ít thay đổi.

Ví dụ:

  • danh sách quốc gia
  • category
  • school list
  • configuration
  • product catalog
  • master data

[!TIP] Quy tắc ngón tay cái: dữ liệu càng ít thay đổi thì staleTime càng dài. Danh sách quốc gia có thể để staleTime: Infinity; bảng giá realtime thì để vài giây hoặc dùng refetch interval.

Cache không có nghĩa là dữ liệu luôn mới#

Đây là điểm rất quan trọng.

Giả sử:

Backend
  ↓
User name = "John"
text

Frontend cache:

User name = "John"
text

Sau đó server thay đổi:

Backend
  ↓
User name = "Mike"
text

Cache phía frontend vẫn có thể đang chứa:

John
text

Vì vậy client-side cache luôn có trade-off:

Performance
    ↕
Freshness
text

Muốn giảm API request:

staleTime ↑
text

Muốn dữ liệu cập nhật thường xuyên:

staleTime ↓
text

Refetch dữ liệu#

TanStack Query có thể refetch trong nhiều tình huống.

Ví dụ khi user quay lại browser tab:

UsersList.tsx
useQuery({
  queryKey: ["users"],
  queryFn: fetchUsers,
  refetchOnWindowFocus: true,
})
tsx

Concept:

User rời tabServer thay đổi dữ liệuUser quay lại tabTanStack Query tự refetch

Điều này giúp ứng dụng có cảm giác dữ liệu luôn được cập nhật mà developer không cần tự viết event listener.

[!NOTE] refetchOnWindowFocus mặc định đã là true — đây là một trong những “important defaults” gây bất ngờ: chuyển tab qua lại là app tự gọi API. Nếu thấy request “tự nhiên xuất hiện” trong DevTools, thì đây chính là thủ phạm.

Invalidate Cache#

Đây là một tính năng cực kỳ hữu ích khi làm CRUD.

Ví dụ:

GET /users
POST /users
text

Sau khi tạo user:

api.ts
await createUser(data)
ts

có thể invalidate:

UsersList.tsx
queryClient.invalidateQueries({
  queryKey: ["users"],
})
ts

TanStack Query sẽ biết query:

["users"]
text

đã trở nên stale và có thể refetch.

Flow:

POST /userstạo thành cônginvalidate ['users']query thành stalerefetchUI cập nhật

Mutation#

TanStack Query cũng có useMutation().

CreateUser.tsx
const mutation = useMutation({
  mutationFn: createUser,
})
tsx

Sử dụng:

CreateUser.tsx
mutation.mutate({
  name: "John",
})
tsx

Ví dụ hoàn chỉnh:

UsersList.tsx
const queryClient = useQueryClient()

const mutation = useMutation({
  mutationFn: createUser,

  onSuccess: () => {
    queryClient.invalidateQueries({
      queryKey: ["users"],
    })
  },
})
tsx

Đây là pattern rất phổ biến:

MutationInvalidateRefetchUpdate UI

Optimistic Update#

Một tính năng nâng cao hơn là Optimistic Update.

Ví dụ user click:

❤️ Like
text

Thay vì:

Click
 ↓
API request
 ↓
Server response
 ↓
Update UI
text

có thể làm:

Click
 ↓
Update UI ngay
 ↓
API request
 ↓
Success → giữ nguyên
Failure → rollback
text

Người dùng sẽ cảm thấy ứng dụng nhanh hơn.

Ví dụ:

User click Like10 → 11 ngay lập tứcPOST /likesuccess → giữ nguyênerror → rollback về 10

Đây là một trong những use case mà việc tự xây cache/state management trở nên phức tạp khá nhanh.

TanStack Query có lưu cache vào LocalStorage không?#

Mặc định:

Không.

Query cache chủ yếu nằm trong memory.

Ví dụ:

Browser
   └─JavaScript Memory
           └─TanStack Query Cache
text

Reload trang:

F5
 ↓
JavaScript memory mất
 ↓
Query cache mất
text

Nếu muốn persist cache, TanStack Query có thể kết hợp với persistence mechanism như:

localStorage
IndexedDB
text

để tạo persistent cache.

Điều này phù hợp với các ứng dụng muốn giữ một số server state sau khi reload/offline.

TanStack Query có phải HTTP Cache không?#

Không nên đánh đồng hai thứ này.

Có ít nhất hai lớp cache khác nhau:

Browser / HTTP Cache
        ↓
HTTP response caching

TanStack Query
        ↓
Application-level server-state cache
text

Ví dụ:

React ComponentTanStack Query Cachefetch()Browser HTTP CacheNetworkBackend

TanStack Query hiểu được:

queryKey
staleTime
invalidation
mutation
query state
ts

Trong khi HTTP cache dựa trên các cơ chế HTTP như:

Cache-Control
ETag
Last-Modified
Age
text

Hai hệ thống có thể hoạt động cùng nhau.

So sánh với tự viết cache#

Không dùng TanStack Query:

cache.ts
const cache = new Map()

async function getUser(id: number) {
  if (cache.has(id)) {
    return cache.get(id)
  }

  const data = await fetch(`/api/users/${id}`)
    .then(res => res.json())

  cache.set(id, data)

  return data
}
ts

Ban đầu nhìn khá đơn giản.

Nhưng sau đó bạn sẽ phải giải quyết:

❓ Cache bao lâu?
❓ Cache stale khi nào?
❓ Khi nào refetch?
❓ Retry?
❓ Loading?
❓ Error?
❓ Deduplicate?
❓ Mutation?
❓ Invalidate?
❓ Pagination?
❓ Infinite scroll?
❓ Optimistic update?
❓ Garbage collection?
❓ Concurrent request?
❓ Offline?
text

Lúc này Map() đơn giản ban đầu đã biến thành một hệ thống cache hoàn chỉnh.

TanStack Query giải quyết phần lớn những vấn đề đó.

TanStack Query vs Zustand#

Một kiến trúc React thường có thể sử dụng cả hai:

React AppClient StateZustand — UI stateServer StateTanStack Query — API cache

Ví dụ Zustand:

ui-store.ts
{
  sidebarOpen: true,
  selectedTheme: "dark"
}
ts

TanStack Query:

server-state.ts
{
  users: [...],
  posts: [...],
  profile: {...}
}
ts

Không nhất thiết phải chọn một trong hai.

TanStack Query vs SWR#

Một lựa chọn phổ biến khác trong React/Next.js là SWR.

Concept của cả hai khá giống nhau:

React
 ├─TanStack Query
 └─SWR
text

Cả hai đều giải quyết:

  • fetching
  • caching
  • revalidation
  • server state

TanStack Query thường cung cấp hệ thống query/mutation và các khả năng quản lý server state rộng hơn, trong khi SWR có API khá tối giản.

Vì vậy nếu application có nhiều:

CRUD
Mutation
Pagination
Infinite Query
Optimistic Update
Cache Invalidation
Complex Server State
text

thì TanStack Query là một lựa chọn đáng cân nhắc.

Khi nào nên dùng TanStack Query?#

TanStack Query đặc biệt phù hợp với:

Dashboard
Admin panel
E-commerce
CRM
SaaS
Social network
Healthcare application
Education platform
text

đặc biệt khi application có rất nhiều API.

Ví dụ:

/users
/users/:id
/courses
/courses/:id
/students
/students/:id
/reports
/notifications
text

Thay vì mỗi component tự quản lý:

fetch
loading
error
cache
refetch
text

có thể để TanStack Query quản lý server state.

Khi nào không nhất thiết cần TanStack Query?#

Nếu application cực kỳ đơn giản:

SimpleData.tsx
const [data, setData] = useState()

useEffect(() => {
  fetch("/api/data")
    .then(...)
}, [])
tsx

và chỉ có vài API request thì thêm một thư viện có thể không mang lại nhiều lợi ích.

Tương tự, nếu framework đã cung cấp một cơ chế server-data fetching/cache rất mạnh và application chủ yếu dùng server components, cần cân nhắc kiến trúc tổng thể trước khi thêm client-side query library.

Một kiến trúc thực tế#

Với một React SPA lớn, có thể tổ chức:

src/
├─api/
│   ├─users.ts
│   ├─courses.ts
│   └─reports.ts
├─queries/
│   ├─users.ts
│   ├─courses.ts
│   └─reports.ts
├─components/
│   ├─UserList.tsx
│   └─CourseList.tsx
└─query-client.ts
text

Ví dụ:

queries/users.ts
// queries/users.ts

export const usersQuery = () => ({
  queryKey: ["users"],
  queryFn: fetchUsers,
})
ts

Component:

UserList.tsx
const { data, isPending } = useQuery(
  usersQuery()
)
tsx

Điều này giúp API logic không bị trộn lẫn quá nhiều với UI.

Một pattern quan trọng: Query Key#

Khi sử dụng TanStack Query, nên thiết kế query key có cấu trúc.

Ví dụ:

["users"]
ts
["users", userId]
ts
["users", { page: 1, search: "john" }]
ts

Có thể hình dung:

users
├─users/123
├─users/456
└─users?page=1&search=john
text

Query key càng được thiết kế nhất quán thì việc:

invalidateQueries()
ts

và quản lý cache càng dễ.

[!TIP] Thiết kế query key theo hierarchy từ tổng quát đến chi tiết: ["users"] → ["users", id] → ["users", { page, search }]. Nhờ đó invalidateQueries({ queryKey: ["users"] }) sẽ invalidate cả cây con — đúng như cách bạn xóa cả thư mục thay vì từng file.

Một ví dụ đầy đủ#

Flow lúc này rất rõ:

ComponentuseQuery()Query CacheAPI → ServerMutationPOST /usersinvalidate ['users']refetchQuery Cache → UI updated

Kết luận#

Nếu mục tiêu của bạn là client-side cache cho dữ liệu API trong React, thì @tanstack/react-query là một lựa chọn rất đáng cân nhắc.

Điểm quan trọng nhất cần nhớ không phải là:

“TanStack Query là thư viện fetch API.”

Mà là:

TanStack Query là một hệ thống quản lý server state và cache ở phía client.

Nó đặc biệt hữu ích khi application bắt đầu có nhiều API và các vấn đề như:

API request duplication
        +
Caching
        +
Stale data
        +
Refetch
        +
Mutation
        +
Cache invalidation
        +
Optimistic update
text

thay vì tự xây dựng tất cả bằng useEffect + useState + Map, bạn có thể để TanStack Query đảm nhiệm phần server-state này.

Một kiến trúc React hiện đại có thể đơn giản hóa thành:

UI stateZustand / useStateServer stateTanStack QueryHTTP cacheBrowser / CDNPersistent dataBackend / Database

Đó cũng là cách nhìn giúp tránh việc dùng Redux/Zustand để lưu toàn bộ dữ liệu API một cách không cần thiết.

Tài liệu tham khảo#