API & REST Tutorial فصل ۴ — مصرف API و کیفیت درس آموزشی

مصرف API از فرانت: fetch، retry و حالت‌های UI

سمت مصرف‌کننده، کیفیت API شما با کیفیت مصرف‌کننده‌اش سنجیده می‌شود: مدیریت خطا، وضعیت‌های بارگذاری، retry با بک‌آفس و لغو درخواست‌های قدیمی. درس‌های fetch دوره JS را با الگوهای واقعیProduction کامل می‌کنیم.

مراحل قدم‌به‌قدم

  1. ۱

    الگوی پایه fetch

    تابع apiFetch با timeout (AbortController)، چک res.ok و پارس JSON امن؛ خطاهای شبکه و HTTP را دو مسیر جدا کنید تا پیام درست به کاربر برسد. تایم‌اوت پیش‌فرض (مثلاً ۱۰ ثانیه) از تعلیق بی‌پایان UI جلوگیری می‌کند.

  2. ۲

    retry با بک‌آفس

    خطای شبکه و 5xx موقتی‌اند؛ دوباره تلاش کنید با فاصله فزاینده (۱ ثانیه، ۲، ۴...) و jitter؛ 4xx دوباره تلاش نکنید (همان درخواست همان جواب می‌دهد). حداکثر ۳ تلاش؛ بعد از آن پیام و دکمه دستی.

  3. ۳

    لغو و مسابقه درخواست‌ها

    در جستجوی زنده، پاسخ‌های قدیمی بعد از جدید می‌رسند و UI را خراب می‌کنند. با AbortController درخواست قبلی را abort کنید و id ثانیه‌ای هم نگه دارید.

  4. ۴

    حالت‌های UI سه‌گانه

    loading، empty، error — هر سه طراحی‌شده و متن فارسی مشخص. اسکلتون (shimmer) حین بارگذاری؛ حالت خالی با لینک اقدام؛ خطا با دکمه «تلاش دوباره». UI که فقط حالت موفق دارد، نیمه‌کاره است.

نکات مهم

  • ◆ timeout با AbortController همیشه ست کنید؛ شبکه هرگز پاسخ تضمینی ندارد.
  • ◆ retry فقط برای 5xx/شبکه؛ 4xx یعنی منطق کلاینت غلط است.
  • ◆ درخواست قبلی جستجو را abort کنید وگرنه پاسخ کهنه رندر می‌شود.

کد یا مسیر نمونه

async function apiFetch(url, { tries = 3, timeoutMs = 10000, ...opts } = {}) {
  for (let attempt = 1; attempt <= tries; attempt++) {
    const ac = new AbortController();
    const timer = setTimeout(() => ac.abort(), timeoutMs);
    try {
      const res = await fetch(url, { ...opts, signal: ac.signal });
      clearTimeout(timer);
      if (res.ok) return res.json();
      if (res.status >= 500 && attempt < tries) {
        await new Promise((r) => setTimeout(r, 2 ** attempt * 500 + Math.random() * 300));
        continue;      // retry برای خطای سرور
      }
      const body = await res.json().catch(() => null);
      throw new Error(body?.error?.message ?? `خطای HTTP ${res.status}`);
    } catch (err) {
      clearTimeout(timer);
      if (attempt === tries) throw err;
    }
  }
}

// مصرف در جستجوی زنده:
let controller = null;
searchInput.addEventListener("input", async (e) => {
  controller?.abort();
  controller = new AbortController();
  showSkeleton();
  try {
    const data = await apiFetch(`/api/v1/search?q=${encodeURIComponent(e.target.value)}`, { signal: controller.signal });
    render(data.data);
  } catch (err) {
    if (err.name !== "AbortError") showError("جستجو ناموفق بود");
  }
});

اجرای زنده کد JavaScript

editor.html
در حال آماده‌سازی زمین بازی…

کد را ویرایش کنید و «اجرای کد» را بزنید — خروجی واقعی مرورگر همین‌جا رندر می‌شود؛ مثل آزمایشگاه w3schools.

پرسش و پاسخ این درس (۰)

هنوز دیدگاهی ثبت نشده؛ اولین نفر باشید!

دیدگاه خود را بنویسید

کپچا

دیدگاه شما پس از تأیید مدیر نمایش داده می‌شود.