Series: TanStack Router Lesson 63

External data loading — Loader ichida TanStack Query ishlatish

TanStack Router loaderlarida tashqi API'lar bilan ishlash: 3 bosqichli arxitektura, GitHub API misoli, rate-limitlarni tejash, ensureQueryData va React Router bilan taqqos.

63-dars

External data loading — Loader ichida TanStack Query ishlatish

Veb-ilovalarda ko‘pincha faqat o‘zimizning backendimiz bilan emas, balki Uchinchi tomon tashqi API'lari (Third-Party APIs) bilan ishlashga to‘g‘ri keladi: GitHub API, Stripe to‘lov tizimi, ob-havo xizmati, Google Maps yoki sun'iy intellekt xizmatlari.

Tashqi manbalar bilan ishlashda ikkita katta to‘siq mavjud:

  1. So‘rovlar soni cheklovi (Rate Limiting): Ko‘p tashqi xizmatlar soatiga ma'lum miqdordagi (masalan, 60 ta) bepul so‘rov beradi. Ortiqcha har bir so‘rov 429 xatosiga olib keladi.
  2. Tarmoq kechikishi va beqarorligi: Tashqi serverlar geografik jihatdan uzoqda joylashgan bo‘lishi yoki vaqtincha sekin ishlashi mumkin.

TanStack Router loader'i ichida TanStack Query (ensureQueryData) ishlatish bu muammolarni ildizidan hal qiladi.


1. Hayotiy o‘xshatish: Xorijiy tovarlar do‘koni va Bojxona ombori

Tasavvur qiling, siz chet eldan keltiriladigan qimmatbaho Shveysariya soatlarini sotuvchi do‘kon egasisiz (Tashqi API):

  • Xomashyoviy yondashuv (Har safar to‘g‘ridan-to‘g‘ri so‘rov): Do‘konga xaridor kirib soat so‘ragan zahoti, siz Shveysariyaga samolyotda uchib ketasiz. Yo‘l uzoq, qimmat va chiptalar soni cheklangan (Rate-Limit tugab qoladi). Xaridor esa haftalab kutadi.
  • TanStack Query usuli (Bojxona ombori kesh): Do‘koningiz yonida maxsus muzlatgichli omborxona (Query Cache) mavjud. Xaridor kelganda siz avval omborni tekshirasiz (ensureQueryData). Agar tovar omborda bor bo‘lsa, uni 1 soniyada xaridorga topshirasiz (0 ms kutish, 0 ta tashqi so‘rov). Faqat omborda tovar qolmagandagina Shveysariyadan buyurtma qilib, omborga olib kelasiz.

2. Tashqi API bilan ishlashning 3 bosqichli toza arxitekturasi

Kodni tartibli, sinovchan (testable) va kengayuvchan saqlash uchun quyidagi 3 qatlamli strukturadan foydalanamiz:

[ 1. API Fetcher Service ]  ──>  [ 2. Query Options Factory ]  ──>  [ 3. Route Loader (ensureQueryData) ]

1-qadam va 2-qadam: Fetcher va Query Options (src/queries/githubUser.ts)

// src/queries/githubUser.ts
import { queryOptions } from '@tanstack/react-query'

export interface GitHubUser {
  login: string
  name: string
  avatar_url: string
  bio: string
  public_repos: number
  followers: number
}

// 1. Tashqi API so'rovini bajaruvchi sof funksiya
async function fetchGitHubUser(username: string): Promise<GitHubUser> {
  const res = await fetch(`https://api.github.com/users/${username}`)

  if (res.status === 404) {
    throw new Error('Foydalanuvchi GitHub bazasidan topilmadi')
  }

  if (res.status === 429) {
    throw new Error('GitHub API so‘rovlar limiti tugadi. Birozdan so‘ng urinib ko‘ring.')
  }

  if (!res.ok) {
    throw new Error('Tashqi tarmoqda kutilmagan xatolik yuz berdi')
  }

  return res.json()
}

// 2. Qayta ishlatiluvchi Query Options fabrikasi
export const githubUserQueryOptions = (username: string) =>
  queryOptions({
    queryKey: ['github-user', username.toLowerCase()],
    queryFn: () => fetchGitHubUser(username),
    staleTime: 1000 * 60 * 15, // 15 daqiqa davomida tashqi API'ga qayta so'rov ketmaydi!
    gcTime: 1000 * 60 * 60,    // 1 soat xotirada saqlanadi
    retry: 1,                  // Xatolik yuz berganda 1 marta qayta urinib ko'radi
  })

3-qadam: Route Loader ichida qo‘llash (src/routes/users/$username.tsx)

// src/routes/users/$username.tsx
import { createFileRoute } from '@tanstack/react-router'
import { useSuspenseQuery } from '@tanstack/react-query'
import { githubUserQueryOptions } from '../../queries/githubUser'

export const Route = createFileRoute('/users/$username')({
  // 3. Loader ichida kesh tekshiriladi / to'ldiriladi
  loader: async ({ context, params }) => {
    return context.queryClient.ensureQueryData(
      githubUserQueryOptions(params.username)
    )
  },

  // Xatoliklar uchun chiroyli xabar
  errorComponent: ({ error, reset }) => (
    <div className="error-banner">
      <h3>Xatolik: {error.message}</h3>
      <button onClick={() => reset()} className="btn-retry">
        Qayta urinish
      </button>
    </div>
  ),

  component: GitHubUserProfilePage,
})

function GitHubUserProfilePage() {
  const { username } = Route.useParams()

  // Komponent ichida tayyor kesh ma'lumotlarini o'qiymiz
  const { data: user } = useSuspenseQuery(githubUserQueryOptions(username))

  return (
    <div className="profile-card">
      <img src={user.avatar_url} alt={user.name} className="avatar" />
      <h2>{user.name || user.login}</h2>
      <p className="bio">{user.bio || 'Biografiya mavjud emas'}</p>
      <div className="stats">
        <span>Repolar: {user.public_repos}</span>
        <span>Kuzatuvchilar: {user.followers}</span>
      </div>
    </div>
  )
}

3. Tashqi API so‘rovlari va Kesh oqimi (Mermaid Diagram)

flowchart TD
    User["Foydalanuvchi /users/octocat sahifasiga kirdi"] --> Loader["Route loader() ishga tushadi"]

    Loader --> CacheCheck{"Query Keshida 'github-user/octocat' bormi?"}

    CacheCheck -- "HA (Keshda bor va yangi)" --> FastReturn["Keshdan 0 ms da olinadi (GitHub API'ga so'rov yo'q!)"]

    CacheCheck -- "YO'Q (Keshda yo'q)" --> CallAPI["GitHub API'ga tashqi fetch so'rovi ketadi"]
    
    CallAPI --> APIResponse{"API qanday javob berdi?"}
    APIResponse -- "200 OK" --> SaveCache["Ma'lumot keshga saqlanadi (15 daqiqa)"]
    APIResponse -- "404 Not Found" --> ErrorBoundary["errorComponent: Foydalanuvchi topilmadi"]
    APIResponse -- "429 Rate Limit" --> LimitUI["errorComponent: API limiti tugadi"]

    FastReturn & SaveCache --> Render["Profil sahifasi to'liq ma'lumot bilan ochiladi"]

4. To‘g‘ridan-to‘g‘ri Fetch va ensureQueryData taqqosi

Xususiyat Loader ichida oddiy fetch Loader ichida ensureQueryData
API Limitlarini tejash ❌ Har safar sahifaga kirganda yangi so‘rov ketadi ✅ staleTime davomida umuman so‘rov yuborilmaydi
Sahifalararo harakat tezligi Sekin (har safar tashqi server kutiladi) Zudlik bilan (Keshdan 0 ms kechikish)
Preloading imkoniyati Cheklangan kesh tufayli qayta-qayta yuklaydi Preload qilingan ma'lumot keshda barqaror saqlanadi
Avtomatik qayta urinish (Retry) Qo‘lda try/catch va sikllar yozish kerak retry: 2 orqali avtomatik eksponentsial urinish

Xulosa

  • Tashqi API'lar bilan ishlashda so‘rovlar soni limiti (Rate Limits) va tarmoq beqarorligini hisobga olish shart.
  • queryOptions fabrikasi va ensureQueryData usuli orqali tashqi ma'lumotlar loader bosqichidayoq keshga joylanadi.
  • Bu yondashuv uchinchi tomon API'lariga ortiqcha yuklama bermaydi, limitlarni tejaydi va sahifalar ochilishini chaqmoqdek tezlashtiradi.
  • Tashqi xatoliklar (404, 429) router'ning errorComponent komponenti orqali markazlashgan va tushunarli tarzda tutib olinadi.