آموزش جامع Fetch API در جاوا اسکریپت: کاربردی و گام‌به‌گام

فهرست مطالب

• Fetch API چیست و چگونه کار می‌کند؟
• مقایسه Fetch API با XMLHttpRequest و Axios
• ارسال درخواست GET (دریافت اطلاعات)
• مدیریت خطاهای شبکه و status HTTP (نکته حیاتی)
• ارسال داده به سرور با متد POST
• متدهای PUT ،PATCH و DELETE
• لغو درخواست‌ها و تعیین Timeout با AbortController
• ارسال فایل و داده‌های Form-Data
• عیب‌یابی سریع و رفع مشکلات رایج
• پرسش‌های متداول

خلاصه سریع نکات کلیدی

• تابع fetch() بر پایه Promise کار می‌کند و کدنویسی ناهمگام را بسیار ساده می‌سازد.
• پاسخ‌های ۴۰۴ یا ۵۰۰ باعث reject شدن Promise نمی‌شوند؛ باید شرط response.ok را دستی بررسی کنید.
• برای لغو درخواست یا تنظیم محدودیت زمانی (Timeout) از API بومی AbortController استفاده می‌شود.
• هنگام ارسال داده‌های فرم با FormData، نباید هدر Content-Type را دستی مقداردهی کنید.

ویژگی	توضیحات و عملکرد
پشتیبانی بومی (Native)	بله، بدون نیاز به نصب هیچ package یا کتابخانه اضافی در مرورگر و Node.js 18 به بعد در دسترس است.
پایه مدرن بر اساس Promise	بر خلاف XMLHttpRequest که بر پایه Callback است، Fetch کاملاً استاندارد async/await را پشتیبانی می‌کند.
پارس خودکار JSON	خیر، برخلاف کتابخانه Axios، باید پاسخ را دستی با متد response.json() تبدیل کنید.
رفتار در خطاهای ۴۰۴ و ۵۰۰	درخواست رد (Reject) نمی‌شود و باید خصوصیت response.ok چک شود.

fetch('https://jsonplaceholder.typicode.com/posts/1')
  .then(response => {
    return response.json();
  })
  .then(data => {
    console.log('داده‌های دریافتی:', data);
  })
  .catch(error => {
    console.error('خطای شبکه:', error);
  });

async function getPostData() {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/posts/1');
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error('خطا در دریافت اطلاعات:', error);
  }
}

getPostData();

نکته بسیار مهم: تابع fetch() تنها زمانی Promise را Reject می‌کند (به catch می‌برد) که یک خطای واقعی در سطح شبکه مثل قطع بودن اینترنت یا عدم دسترسی به دامنه رخ دهد. اگر سرور پاسخی با کد وضعیت ۴۰۴ برگرداند، از نظر Fetch درخواست با موفقیت انجام شده است!

async function fetchUser(userId) {
  try {
    const response = await fetch(`https://jsonplaceholder.typicode.com/users/${userId}`);

    // بررسی کد وضعیت HTTP
    if (!response.ok) {
      throw new Error(`خطای HTTP! کد وضعیت: ${response.status}`);
    }

    const userData = await response.json();
    return userData;
  } catch (error) {
    console.error('عملیات ناموفق بود:', error.message);
  }
}

async function createNewPost() {
  const newPost = {
    title: 'آموزش Fetch API',
    body: 'این یک پست نمونه است.',
    userId: 1
  };

  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/posts', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_TOKEN_HERE'
      },
      body: JSON.stringify(newPost) // تبدیل شیء به رشته JSON
    });

    if (!response.ok) {
      throw new Error('خطا در ثبت اطلاعات');
    }

    const result = await response.json();
    console.log('پست با موفقیت ایجاد شد:', result);
  } catch (error) {
    console.error(error);
  }
}

async function deletePost(postId) {
  try {
    const response = await fetch(`https://jsonplaceholder.typicode.com/posts/${postId}`, {
      method: 'DELETE'
    });

    if (response.ok) {
      console.log(`پست شماره ${postId} با موفقیت حذف شد.`);
    }
  } catch (error) {
    console.error('خطا در حذف پست:', error);
  }
}

async function fetchWithTimeout(url, timeoutMs = 5000) {
  const controller = new AbortController();
  const id = setTimeout(() => controller.abort(), timeoutMs);

  try {
    const response = await fetch(url, { signal: controller.signal });
    clearTimeout(id); // پاک‌سازی تایمر در صورت موفقیت
    const data = await response.json();
    return data;
  } catch (error) {
    if (error.name === 'AbortError') {
      console.error('درخواست به دلیل پایان مهلت زمانی (Timeout) لغو شد.');
    } else {
      console.error('خطای شبکه:', error);
    }
  }
}

// اگر پاسخ سرور بیشتر از ۳ ثانیه طول بکشد، لغو می‌شود
fetchWithTimeout('https://jsonplaceholder.typicode.com/photos', 3000);

اشتباه رایج: هنگام ارسال FormData، هرگز هدر Content-Type را به صورت دستی مقداردهی نکنید! مرورگر به‌صورت خودکار هدر را همراه با مرزهای (boundary) لازم برای فایل تنظیم می‌کند.

async function uploadUserAvatar(fileInput) {
  const formData = new FormData();
  formData.append('avatar', fileInput.files[0]);
  formData.append('username', 'ali_dev');

  try {
    const response = await fetch('/api/upload', {
      method: 'POST',
      body: formData // هدر Content-Type اتوماتیک تنظیم می‌شود
    });

    const result = await response.json();
    console.log('نتیجه آپلود:', result);
  } catch (error) {
    console.error('خطا در آپلود فایل:', error);
  }
}

آیا برای استفاده از Fetch API نیاز به نصب فایل یا کتابخانه داریم؟

خیر، Fetch API به‌صورت داخلی و بومی در تمام مرورگرهای مدرن و نسخه‌های جدید Node.js پیاده‌سازی شده است و نیاز به هیچ ابزار خارجی ندارد.

تفاوت اصلی بین response.text() و response.json() چیست؟

متد response.json() خروجی دریافتی را به‌صورت اتوماتیک پارس کرده و به شیء جاوا اسکریپت تبدیل می‌کند، در حالی که response.text() خروجی خام سرور را به صورت یک رشته (String) ساده تحویل می‌دهد.

چرا کدهای درون catch هنگام دریافت خطاهای ۴۰۴ اجرا نمی‌شوند؟

چون کدهای HTTP از سمت سرور برگردانده شده‌اند و ارتباط شبکه قطع نشده است. برای تشخیص این خطاها باید ویژگی response.ok یا response.status چک شود.

آیا Fetch API از تمام مرورگرها پشتیبانی می‌کند؟

بله، تمامی مرورگرهای مدرن شامل Chrome، Firefox، Edge و Safari کاملاً از Fetch API پشتیبانی می‌کنند. تنها مرورگرهای بسیار قدیمی مثل Internet Explorer از آن پشتیبانی نمی‌کنند که نیازمند polyfill هستند.