Suspense ve hata yönetimi

Hatayı Göstermenin Üç Yolu

TkDodo TanStack Query'de hatayı ele almanın üç yolunu sayar ve bunları karıştırarak kullanmayı önerir:¹

error alanını önceki derslerde kullandınız. Bu derste diğer ikisi var.

Global Toast

v5 ile useQuery'nin onSuccess, onError ve onSettled callback'leri kaldırıldı. Mutation'larda duruyorlar.² Sorgu başına callback, aynı sorguyu kullanan her component'te ayrı ayrı çalıştığı için aynı hata için üç toast gösterebiliyordu.¹

Doğru yer QueryCache'tir. Buradaki callback her istek için bir kez çalışır ve defaultOptions gibi ezilemez:¹

import { QueryCache, QueryClient } from "@tanstack/react-query";

const queryClient = new QueryClient({
  queryCache: new QueryCache({
    onError: (error, query) => {
      // Yalnızca arka plan yenilemesi başarısız olduysa toast göster
      if (query.state.data !== undefined) {
        toast.error(`Veri güncellenemedi: ${error.message}`);
      }
    },
  }),
});

TkDodo'nun tercihi: ekranda zaten veri varsa (arka plan yenilemesi başarısız olmuşsa) eski veriyi bozmadan bir toast göster; ilk yüklemedeki hatayı ise component'te ya da Error Boundary'de göster.¹ Hata izleme kodu için de en iyi yer burasıdır.

throwOnError ile Error Boundary

Varsayılan olarak hata error alanına yazılır, fırlatılmaz. throwOnError: true verirseniz hata render sırasında fırlatılır ve en yakın Error Boundary yakalar (bkz. Suspense ve hata sınırları).³ Fonksiyon da verebilirsiniz; örneğin yalnızca sunucu hatalarını sınıra taşıyıp 4xx'leri yerinde göstermek için:¹

useQuery({
  ...productQueries.detail(id),
  throwOnError: (error) => error instanceof HttpError && error.status >= 500,
});

Error Boundary'deki "Tekrar dene" butonu sınırı sıfırlar ama sorgu hâlâ hata durumundadır; tekrar render olduğunda hemen yine fırlatır. Sorgunun da sıfırlanması için QueryErrorResetBoundary kullanın:³

import { QueryErrorResetBoundary } from "@tanstack/react-query";
import { ErrorBoundary } from "react-error-boundary";

<QueryErrorResetBoundary>
  {({ reset }) => (
    <ErrorBoundary
      onReset={reset}
      fallbackRender={({ resetErrorBoundary }) => (
        <div>
          <p>Ürün yüklenemedi.</p>
          <button onClick={() => resetErrorBoundary()}>Tekrar dene</button>
        </div>
      )}
    >
      <ProductDetail id={id} />
    </ErrorBoundary>
  )}
</QueryErrorResetBoundary>;

useSuspenseQuery

useSuspenseQuery, yükleme ve hata durumunu React'e bırakır: veri yokken component askıya alınır ve en yakın <Suspense>'in fallback'i görünür; hata olursa Error Boundary yakalar.³

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

function ProductDetail({ id }: { id: number }) {
  const { data: product } = useSuspenseQuery(productQueries.detail(id));
  //            ^? Product (undefined değil)
  return <h1>{product.name}</h1>;
}

<Suspense fallback={<ProductSkeleton />}>
  <ProductDetail id={id} />
</Suspense>;

data her zaman tanımlıdır; isPending ve isError kontrolü gerekmez.³ Karşılığında bazı şeylerden vazgeçersiniz:³

Anahtar değişince (ör. sayfa numarası) ekranın fallback'e dönmesini istemiyorsanız state güncellemesini startTransition ile sarın. React eski içeriği yeni veri gelene kadar ekranda tutar.³⁴

Bir sorguyu Suspense sınırının üstünde başlatmak için usePrefetchQuery var. Böylece sınırın altındaki component render olmadan istek yola çıkar:⁶

function ProductPage({ id }: { id: number }) {
  usePrefetchQuery(reviewQueries.list(id));

  return (
    <Suspense fallback={<ProductSkeleton />}>
      <ProductDetail id={id} />
      <ReviewList productId={id} />
    </Suspense>
  );
}

Hangisi Ne Zaman

Hata tipini tüm uygulama için değiştirmek isterseniz Register arayüzünü genişletin. defaultError: unknown derseniz her kullanım yerinde hatayı daraltmak zorunda kalırsınız:⁷

declare module "@tanstack/react-query" {
  interface Register {
    defaultError: HttpError;
  }
}

Kendin Dene

• Ürün API'sini her ikinci istekte hata verecek şekilde değiştirin. QueryCache onError ile toast gösterin; ilk yüklemedeki hatada toast çıkmadığını doğrulayın.

• ProductDetail'i useSuspenseQuery'ye çevirin. QueryErrorResetBoundary olmadan "Tekrar dene"ye basın; ne oluyor?

• Aynı component'e iki useSuspenseQuery koyun ve Network sekmesinde sırayla çalıştıklarını görün. useSuspenseQueries ile düzeltin.

Detaylı Öğrenmek İçin

• Yazı: TkDodo, "React Query Error Handling"; error alanı, global callback'ler ve Error Boundary'yi birlikte kullanmak.¹

• Resmi doküman: "Suspense"; useSuspenseQuery, throwOnError varsayılanı ve hata sınırlarını sıfırlamak.³

• Yazı: TkDodo, "Breaking React Query's API on purpose"; sorgu callback'lerinin neden kaldırıldığı.²