blog.dopana

Quay lại

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/123
text

Nế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() hay axios. 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:

Ban đầ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.

Hệ thống BackendỨng dụng ReactServer State (TanStack Query)Client State (Zustand / useState)So huu boi FrontendSnapshot duoc cacheTheme: 'dark' / 'light'Modal open: true / falseTab đang chọn: 2Thông tin User profileDanh sách đơn hàngSản phẩm trong giỏ hàngDatabase or REST Server

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:

App.tsx
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>
  )
}
tsx

Trong component, ta gọi useQuery:

queryKey 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: [ ... ]
text

Nế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:

3 Component Mount Đồng ThờiRemote API ServerRemote API ServerTanStack Query Cache LayerTanStack Query Cache LayeruseQueryuseQueryuseQueryChỉ bắn duy nhất 1 NetworkRequestTrả về JSON PayloadPhân phối đồng thời cho cả 3RenderRenderRenderComponent HeaderComponent SidebarComponent MainContentqueryKey: ['user', 123]Deduplication Engine (Chờ 1Promise)GET /api/users/123

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ínhTên cũÝ nghĩa thực sựMặc định
staleTimestaleTimeDữ 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
gcTimecacheTimeDữ 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ớ RAM
text

[!TIP] Nhớ quy tắc vàng: staleTime: 60000 KHÔ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):

queries/categories.ts
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
}
typescript

6. Đá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 = 0
text

Nế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 đang stale.
  • 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.

POST api users200 SuccessinvalidateQueries1. User nhấn Tạo User2. useMutation3. Server lưu vào DB4. onSuccess callback5. Đánh dấu users là stale6. Tự động Refetch ngầm7. Giao diện tự động cập nhật

Ví dụ triển khai chuẩn:

8. 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ũ:

9. 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:

1. Tầng Ứng Dụng (React Memory)3. Tầng Hạ Tầng Mạng3. Tầng Hạ Tầng Mạng2. Tầng Trình Duyệt (Network Stack)2. Tầng Trình Duyệt (Network Stack)useQueryCache Miss or RevalidateCache MissForward304 or 200 OKJSON ObjectRe-render tự độngReact ComponentTanStack Query Cachefetch() / XMLHttpRequestHTTP Disk / Memory Cache(ETag, max-age)CDN Edge CachingBackend Server / Database
Tiêu chíTanStack QueryHTTP Cache Trình Duyệt
Vị tríJavaScript RAM Memory của ứng dụngTầng mạng (Network stack) của trình duyệt
Phạm vi hiểu biếtHiể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 đổiKhông có khái niệm re-render UI
DeduplicationChia sẻ 1 in-flight Promise giữa nhiều componentCó thể gửi nhiều request đồng thời nếu cùng thời điểm
Mutation & RollbackCó Optimistic updates, cache rollback, invalidationHoà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:

queries/userKeys.ts
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,
}
typescript

Nhờ 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:

  1. Sự khác biệt giữa Client State (Zustand/useState) và Server State (TanStack Query).
  2. Định danh cache bằng queryKey.
  3. Ranh giới giữa staleTime (tươi mới) và gcTime (giải phóng bộ nhớ).
  4. 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.

Tài Liệu Tham Khảo#