Cache ve stale time

Stale-While-Revalidate

TanStack Query'nin cache modeli HTTP'deki stale-while-revalidate fikrine dayanır: elinizde veri varsa, eski olsa bile hemen gösterin; arka planda yenisini getirin, gelince değiştirin.¹ Kullanıcı yükleme ekranı yerine son bilinen veriyi görür, ekran birkaç yüz milisaniye sonra kendiliğinden güncellenir.

Bunu iki ayar yönetir: verinin ne zaman eskidiğini söyleyen staleTime ve kullanılmayan verinin ne zaman silineceğini söyleyen gcTime.

staleTime ve gcTime

TkDodo'nun özeti: veri tazeyken her zaman yalnızca cache'ten gelir, ağa istek gitmez. Eskiyse yine cache'ten gelir ama belirli anlarda arka planda yenilenir.¹² gcTime'a nadiren dokunursunuz; değiştirmek istediğiniz neredeyse her zaman staleTime'dır.² gcTime v5'ten önce cacheTime adını taşıyordu; eski yazılarda bu adı görürsünüz.²

Bir sorgunun hayatı, doküman örneğinin kısaltılmış haliyle:³

1. ["products"] kullanan bir component açılır. Cache boştur; yükleme gösterilir, istek atılır, sonuç cache'e yazılır.

2. Aynı anahtarı kullanan ikinci bir component açılır. Veri cache'ten anında gelir. staleTime: 0 olduğu için arka planda bir istek daha atılır.

3. İki component de kapanır. Sorgu inactive olur ve 5 dakikalık gcTime sayacı başlar.

4. 5 dakika dolmadan component tekrar açılırsa veri cache'ten gelir, arka planda yenilenir.

5. 5 dakika içinde kimse kullanmazsa veri silinir. Sonraki açılış yükleme ekranıyla başlar.

staleTime Seçmek

staleTime: 0 varsayılanı veriyi güncel tutmaya göre seçilmiştir, istek sayısına göre değil. İlk kez kullanan herkesin sorduğu soru budur: "Veriyi iki saniye önce çektim, neden yine istek gidiyor?"¹ Cevap koşullu açılan ikinci bir component'tir; kütüphane onu yeni bir mount olarak görür ve eski veriyi yeniler.

Çözüm otomatik yenilemeyi kapatmak ya da veriyi props'la taşımak değil, verinin ne kadar süre geçerli sayılacağını söylemektir:¹

// Tüm uygulama için
new QueryClient({
  defaultOptions: { queries: { staleTime: 30 * 1000 } },
});

// Bir sorgu için
queryOptions({
  queryKey: ["categories"],
  queryFn: fetchCategories,
  staleTime: 10 * 60 * 1000, // kategoriler nadiren değişir
});

Kaba bir rehber:

Infinity ile 'static' arasında bir fark var: Infinity olan bir sorgu invalidateQueries ile yine yenilenir; 'static' olan yenilenmez.⁴

Yenileme Ne Zaman Olur

Eski bir sorgu üç anda arka planda yenilenir:⁴

TkDodo'nun en sevdiği tetikleyici sekmeye dönüştür. Geliştirirken "fazla" görünür çünkü sürekli sekme değiştirirsiniz; production'da ise uzun süre başka sekmede kalmış bir kullanıcının dönüşüdür.¹ Bu bayrakları kapatmak yerine staleTime ile ayarlamak önerilen yoldur.⁴

Veriyi düzenli aralıklarla yenilemek için refetchInterval kullanın. Bu ayar staleTime'dan bağımsız çalışır:⁴⁵

useQuery({
  ...orderQueries.status(orderId),
  // sipariş teslim edilene kadar her 5 saniyede bir
  refetchInterval: (query) =>
    query.state.data?.status === "delivered" ? false : 5000,
});

false döndürmek polling'i durdurur. Sekme arka plana geçince polling de varsayılan olarak durur; arka planda da sürmesi için refetchIntervalInBackground: true verin.⁵

initialData ve placeholderData

Bazen sorgu açıldığında elinizde gösterilecek bir şey vardır. İki seçenek farklı davranır:⁶⁷

TkDodo'nun tercihi: bir sorguyu başka bir sorgudan doldururken initialData, diğer her şey için placeholderData.⁷ Ürün listesinden detay sayfasına geçerken liste verisini başlangıç olarak kullanmak tipik bir örnek:⁶

const queryClient = useQueryClient();

useQuery({
  ...productQueries.detail(id),
  initialData: () =>
    queryClient
      .getQueryData(productQueries.list(category).queryKey)
      ?.find((product) => product.id === id),
  initialDataUpdatedAt: () =>
    queryClient.getQueryState(productQueries.list(category).queryKey)?.dataUpdatedAt,
});

initialDataUpdatedAt, başlangıç verisinin ne zaman çekildiğini söyler. Liste staleTime'dan eskiyse detay arka planda yenilenir; yoksa istek atılmaz.⁶ placeholderData'nın sayfalamadaki kullanımı Sayfalama ve sonsuz liste dersinde.

Kendin Dene

• staleTime: 0 ile bir listeyi açın, başka bir sayfaya gidip geri dönün. Devtools'ta sorgu hangi durumlardan geçiyor?

• Aynı denemeyi staleTime: 60 * 1000 ile tekrarlayın. Network sekmesinde fark ne?

• Bir component'i kapatın ve Devtools'ta sorgunun inactive olduğunu görün. gcTime: 5000 verip 5 saniye sonra ne olduğuna bakın.

• Bir sipariş durumu ekranına refetchInterval ekleyin. Sahte API üçüncü istekte delivered dönsün; polling duruyor mu?

Detaylı Öğrenmek İçin

• Yazı: TkDodo, "React Query as a State Manager"; stale-while-revalidate, akıllı yenilemeler ve staleTime ayarlamak.¹

• Resmi doküman: "Caching Examples"; bir sorgunun mount, inactive ve garbage collection adımları.³

• Yazı: TkDodo, "Placeholder and Initial Data in React Query"; iki seçeneğin cache ve observer düzeyindeki farkı.⁷