useQuery ve query key

İlk Sorgu

useQuery en az iki şey ister: veriyi tanımlayan bir query key ve veriyi getiren bir query function:¹

import { useQuery } from "@tanstack/react-query";

type Product = { id: number; name: string; price: number };

async function fetchProducts(): Promise<Product[]> {
  const response = await fetch("/api/products");
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}

export function ProductList() {
  const { data, isPending, isError, error } = useQuery({
    queryKey: ["products"],
    queryFn: fetchProducts,
  });

  if (isPending) return <p>Yükleniyor...</p>;
  if (isError) return <p>Hata: {error.message}</p>;

  return <ul>{data.map((p) => <li key={p.id}>{p.name}</li>)}</ul>;
}

isPending ve isError kontrolünden sonra TypeScript data'nın tanımlı olduğunu bilir; data! yazmanız gerekmez.¹²

Query function'ın iki kuralı var:³

• Hata fırlatmalı. Kütüphane hatayı yalnızca fırlatılan ya da reddedilen bir Promise'ten anlar. fetch 404 ya da 500 cevabında hata fırlatmaz; response.ok'u kendiniz kontrol edin.

• undefined döndürmemeli. undefined dönen sorgu başarısız sayılır. "Veri yok" demek istiyorsanız null döndürün.

status ve fetchStatus

Sonuç nesnesinde iki ayrı durum var. status veriyle ilgilidir: elinizde veri var mı? fetchStatus query function'la ilgilidir: şu an çalışıyor mu?¹

İkisi bağımsızdır. success durumundaki bir sorgu arka planda yenilenirken fetching olur. Veri bekleyen bir sorgu internet yoksa pending ama paused kalır.¹ Türetilmiş bayraklar bu ikisinden gelir:

TkDodo, kontrol sırasının önemli olduğunu hatırlatır. Arka plandaki bir yenileme başarısız olursa sorgu hem error durumundadır hem de eski veriyi taşır. Önce hatayı kontrol ederseniz kullanıcının baktığı liste, birkaç saniyelik tekrar denemeden sonra bir hata ekranına dönüşür. Bu yüzden çoğu ekranda önce veriye bakmayı önerir:⁴

if (data) return <ProductTable products={data} />;
if (error) return <p>Hata: {error.message}</p>;
return <p>Yükleniyor...</p>;

Hangi sıranın doğru olduğu ekrana bağlıdır. Önemli olan, error'un "veri yok" demek olmadığını bilmektir.

Query Key Bir Bağımlılık Dizisidir

Cache, query key'e göre tutulur. Anahtar bir dizidir ve JSON.stringify ile serileştirilebilen her şeyi içerebilir.⁵ Query function'ın kullandığı ve değişebilen her değişken anahtara girmelidir:⁵

function ProductList({ category }: { category: string }) {
  const { data } = useQuery({
    queryKey: ["products", category],
    queryFn: () => fetchProducts(category),
  });
  // ...
}

category değişince anahtar değişir, kütüphane bunu yeni bir cache girdisi olarak görür ve veriyi getirir. Eski kategoriye dönerseniz veri cache'ten anında gelir.⁵ TkDodo bunu useEffect'in bağımlılık dizisine benzetir: anahtar, sorgunun neye bağlı olduğunu söyler.⁶ Bir değişkeni anahtara eklemeyi unutursanız exhaustive-deps lint kuralı uyarır.⁵

Anahtarlar deterministik olarak hash'lenir. Nesnelerin içindeki sıra önemsizdir, dizideki sıra önemlidir:⁵

// Aynı sorgu
["products", { page: 1, sort: "price" }]
["products", { sort: "price", page: 1 }]

// Farklı sorgular
["products", 1, "price"]
["products", "price", 1]

Anahtarları Düzenlemek

Anahtarları genelden özele kurun. Böylece tek bir ön ekle ilgili tüm sorguları hedefleyebilirsiniz:⁸

["products"]                                 // ürünlerle ilgili her şey
["products", "list", { category: "shoes" }]  // bir liste
["products", "detail", 42]                   // bir ürün

invalidateQueries({ queryKey: ["products"] }) hepsini, ["products", "list"] yalnızca listeleri hedefler. Anahtarı her yerde elle yazmak hataya açıktır; tek bir yerde üretmek için queryOptions ve select dersine geçin.

İsteği İptal Etmek

Query function bir signal alır. Bunu fetch'e verirseniz anahtar değiştiğinde ya da component kaldırıldığında artık gerekmeyen istek iptal edilir:⁹¹⁰

useQuery({
  queryKey: ["products", category],
  queryFn: async ({ signal }) => {
    const response = await fetch(`/api/products?category=${category}`, { signal });
    if (!response.ok) throw new Error(`Request failed: ${response.status}`);
    return response.json() as Promise<Product[]>;
  },
});

signal'ı kullanmazsanız istek iptal edilmez; tamamlanır ve sonucu cache'e yazılır. Component tekrar açılınca veri hazır olduğu için bu da çoğu zaman işe yarar.⁹

Query function'a gelen bağlam nesnesi signal'ın yanında queryKey, client ve meta'yı da taşır.³

Kendin Dene

• Bir kategori listesi ve ürün listesi kurun. Kategori değiştirip geri dönün; Devtools'ta kaç cache girdisi görüyorsunuz?

• Anahtardan category'yi çıkarın. Ekranda ne değişiyor, lint kuralı ne diyor?

• queryFn'e signal ekleyin ve Network sekmesinde kategoriyi hızlı değiştirin. İptal edilen istekleri görüyor musunuz?

• if (error) kontrolünü if (data)'nın önüne alın, sonra API'yi ikinci istekte hata verecek şekilde değiştirip sekmeye geri dönün.

Detaylı Öğrenmek İçin

• Resmi doküman: "Queries", "Query Keys" ve "Query Functions" sayfaları; durumlar, anahtar kuralları ve bağlam nesnesi.¹⁵³

• Yazı: TkDodo, "Effective React Query Keys"; anahtar yapısı ve hiyerarşi.⁸

• Yazı: TkDodo, "Status Checks in React Query"; arka plan hatalarında neden önce veriye bakmak gerekir.⁴