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

فرض کنید وارد یک فروشگاه اینترنتی می‌شوید. صفحه محصولات باز می‌شود اما هیچ اطلاعاتی داخل آن وجود ندارد. چند لحظه بعد، تصاویر، قیمت‌ها و مشخصات کالاها یکی‌یکی نمایش داده می‌شوند.

به نظر شما این اطلاعات از کجا آمده‌اند؟

آیا داخل فایل HTML نوشته شده‌اند؟مرورگر در پس‌زمینه یک درخواست (Request) به سرور ارسال کرده، سرور اطلاعات را به صورت JSON برگردانده و سپس جاوا اسکریپت آن‌ها را روی صفحه نمایش داده است.

تقریباً تمام وب‌سایت‌های مدرن، از شبکه‌های اجتماعی گرفته تا فروشگاه‌های اینترنتی، داشبوردهای مدیریتی و حتی ChatGPT، برای دریافت اطلاعات از سرور از همین مکانیزم استفاده می‌کنند.

در جاوا اسکریپت امروزی، استانداردترین ابزار انجام این کار Fetch API است.

در این مقاله یاد می‌گیریم چگونه بدون استفاده از کتابخانه‌هایی مانند Axios یا jQuery، اطلاعات را از سرور دریافت کنیم، پردازش کنیم و در صفحه نمایش دهیم.

Fetch API چیست؟

Fetch API یک رابط (API) داخلی مرورگر است که امکان ارسال درخواست‌های HTTP و دریافت پاسخ از سرور را فراهم می‌کند.

قبل از معرفی Fetch، برنامه‌نویسان معمولاً از XMLHttpRequest استفاده می‌کردند که کدنویسی پیچیده و خوانایی پایینی داشت.

اما Fetch با تکیه بر Promise و Async/Await کدنویسی را بسیار ساده‌تر کرده است.

به همین دلیل تقریباً تمام پروژه‌های مدرن جاوا اسکریپت از Fetch یا کتابخانه‌هایی استفاده می‌کنند که بر پایه همین مفهوم ساخته شده‌اند.

مهم‌ترین قابلیت‌های Fetch API

• ارسال درخواست GET، POST، PUT و DELETE
• دریافت اطلاعات از REST API
• ارسال داده به سرور
• ارسال Headerهای سفارشی
• پشتیبانی کامل از Promise
• استفاده آسان همراه با Async/Await
• مدیریت خطاها و پاسخ‌های سرور

اولین درخواست با Fetch API

برای شروع، بیایید ساده‌ترین درخواست ممکن را ارسال کنیم. در این مثال اطلاعات یک کاربر را از یک API آزمایشی دریافت می‌کنیم.

fetch("https://jsonplaceholder.typicode.com/users/1").then(response => response.json())
    .then(data => {
        console.log(data);
    });

اگر این کد را اجرا کنید، در Console مرورگر شیئی مشابه زیر مشاهده خواهید کرد:
{
    id: 1,
    name: "Leanne Graham",
    username: "Bret",
    email: "Sincere@april.biz"
}
}

در نگاه اول شاید کد بالا کمی پیچیده به نظر برسد، اما در واقع فقط سه مرحله انجام می‌شود.

مراحل اجرای اولین درخواست Fetch API

مرحله اول: ارسال درخواست

fetch("https://jsonplaceholder.typicode.com/users/1")

به محض اجرای این خط، مرورگر یک درخواست GET به آدرس موردنظر ارسال می‌کند.

در این لحظه برنامه منتظر دریافت پاسخ از سرور می‌ماند، اما اجرای سایر بخش‌های جاوا اسکریپت متوقف نمی‌شود. دلیل این رفتار را در مقاله Promise و Async/Await به طور کامل یاد گرفتیم.

مرحله دوم: دریافت پاسخ (Response)

.then(response => response.json())

بعد از اینکه سرور پاسخ را ارسال کرد، شیئی از نوع Response در اختیار ما قرار می‌گیرد.

نکته مهم اینجاست که اطلاعات داخل Response هنوز قابل استفاده نیستند.

در بیشتر APIها، داده‌ها با فرمت JSON ارسال می‌شوند و باید آن‌ها را به یک شیء جاوا اسکریپتی تبدیل کنیم.

برای این کار از متد json() استفاده می‌کنیم.

response.json()

این متد نیز یک Promise برمی‌گرداند؛ بنابراین دوباره از .then() استفاده می‌کنیم یا در ادامه مقاله خواهیم دید که Async/Await این کار را بسیار خواناتر می‌کند.

مرحله سوم: استفاده از داده‌ها

.then(data => {
console.log(data);
});

در این مرحله داده‌های واقعی در اختیار ما قرار گرفته‌اند.

از اینجا به بعد می‌توانیم آن‌ها را:

• در صفحه نمایش دهیم.
• داخل جدول قرار دهیم.
• در کارت محصولات استفاده کنیم.
• لیست کاربران را ایجاد کنیم.
• یا هر پردازش دیگری روی آن‌ها انجام دهیم.

در پروژه‌های واقعی معمولاً به جای console.log اطلاعات را داخل عناصر HTML نمایش می‌دهیم.

استفاده از Fetch API همراه با Async/Await

در مقاله قبل یاد گرفتیم که Async/Await باعث می‌شود کدهای مبتنی بر Promise بسیار خواناتر شوند. خوشبختانه Fetch API نیز کاملاً از این قابلیت پشتیبانی می‌کند و امروزه تقریباً در تمام پروژه‌های مدرن از این روش استفاده می‌شود.

بیایید همان مثال قبلی را این بار با Async/Await بازنویسی کنیم.

async function getUser() {

const response = await fetch("https://jsonplaceholder.typicode.com/users/1");

const data = await response.json();

console.log(data);

}

getUser();

اگر خروجی این کد را با مثال قبلی مقایسه کنید، هیچ تفاوتی در نتیجه وجود ندارد؛ تنها تفاوت در خوانایی کد است.

دیگر خبری از چندین .then() تو در تو نیست و مراحل اجرای برنامه دقیقاً مانند یک کد معمولی از بالا به پایین خوانده می‌شوند.

این کد چگونه اجرا می‌شود؟

بیایید خط به خط آن را بررسی کنیم.

ارسال درخواست

const response = await fetch(url);

با اجرای این دستور، مرورگر درخواست را به سرور ارسال می‌کند.

کلمه await باعث می‌شود اجرای این تابع تا زمان دریافت پاسخ متوقف شود، اما سایر قسمت‌های برنامه همچنان به کار خود ادامه می‌دهند.

در نتیجه صفحه مرورگر هنگ نمی‌کند و تجربه کاربری حفظ می‌شود.

تبدیل پاسخ به JSON

const data = await response.json();

پاسخ سرور هنوز یک شیء Response است.

برای اینکه بتوانیم به اطلاعات واقعی دسترسی داشته باشیم، باید آن را به یک شیء جاوا اسکریپتی تبدیل کنیم.

متد json() نیز یک Promise برمی‌گرداند؛ به همین دلیل دوباره از await استفاده کرده‌ایم.

استفاده از اطلاعات

console.log(data);

اکنون متغیر data شامل اطلاعات واقعی API است.

از این مرحله به بعد می‌توانید داده‌ها را در جدول، کارت محصولات، لیست کاربران یا هر بخش دیگری از رابط کاربری نمایش دهید.

مقایسه Fetch API با Promise و Async Await

ارسال پارامتر به Fetch API

تا اینجا فقط یک آدرس ثابت را فراخوانی کردیم، اما در پروژه‌های واقعی معمولاً لازم است اطلاعات خاصی را از سرور درخواست کنیم.

برای مثال:

• دریافت کاربر با شناسه ۵
• جستجوی یک محصول
• دریافت مقالات صفحه دوم
• فیلتر محصولات بر اساس دسته‌بندی

در این شرایط از Query String استفاده می‌کنیم.

مثال اول: دریافت یک کاربر

javascript id="v3d6kp"
const userId = 5;

fetch(`https://jsonplaceholder.typicode.com/users/${userId}`)
.then(response => response.json())
.then(data => {
console.log(data);
});

در این مثال با استفاده از Template Literal مقدار متغیر userId را داخل آدرس قرار داده‌ایم.

اگر مقدار متغیر را تغییر دهید، اطلاعات کاربر دیگری دریافت خواهید کرد.

مثال دوم: ارسال Query String

فرض کنید API امکان جستجوی محصولات را فراهم کرده است.

javascript id="k8p7vr"
const keyword = "laptop";

fetch(`https://example.com/api/products?search=${keyword}`)
.then(response => response.json())
.then(data => {
console.log(data);
});

در اینجا مقدار keywordبه انتهای آدرس اضافه می‌شود و سرور فقط محصولاتی را برمی‌گرداند که با عبارت جستجو شده مطابقت دارند.

اگر مقدار شامل فاصله یا کاراکتر فارسی باشد چه می‌شود؟

فرض کنید کاربر عبارت زیر را جستجو کند.

گوشی سامسونگ

اگر این مقدار را مستقیماً داخل URL قرار دهید، ممکن است درخواست به درستی ارسال نشود.

راه‌حل استفاده از encodeURIComponent() است.

javascript id="4w1rns"
const keyword = "گوشی سامسونگ";

fetch(
`https://example.com/api/products?search=${encodeURIComponent(keyword)}`
);

این تابع تمام کاراکترهای غیرمجاز URL را به فرمت استاندارد تبدیل می‌کند و باعث می‌شود درخواست بدون خطا به سرور ارسال شود.

بهترین روش ساخت URL

به جای نوشتن مستقیم آدرس داخل Fetch، بهتر است ابتدا آن را در یک متغیر قرار دهید.

javascript id="5u2w6g"
const apiUrl =
`https://jsonplaceholder.typicode.com/users/1`;

const response = await fetch(apiUrl);

این کار باعث می‌شود:

• خوانایی کد افزایش پیدا کند.
• ویرایش آدرس API راحت‌تر باشد.
• در پروژه‌های بزرگ مدیریت Endpointها ساده‌تر شود.

 اشتباه رایج

گاهی برنامه‌نویسان اطلاعات محرمانه مانند رمز عبور یا توکن را داخل Query String ارسال می‌کنند.

این کار از نظر امنیتی مناسب نیست، زیرا آدرس درخواست می‌تواند در تاریخچه مرورگر، لاگ سرور یا ابزارهای مانیتورینگ ذخیره شود.

در چنین شرایطی باید از درخواست POST استفاده کرد که در بخش بعدی مقاله به طور کامل با آن آشنا خواهیم شد.

ارسال داده به سرور با متد POST

تا اینجا تمام درخواست‌هایی که ارسال کردیم از نوع **GET** بودند؛ یعنی فقط اطلاعاتی را از سرور دریافت می‌کردیم.

اما در پروژه‌های واقعی بارها نیاز داریم اطلاعاتی را **به سرور ارسال کنیم**.

برای مثال:

• ثبت‌نام کاربر
• ورود به حساب کاربری
• ثبت سفارش
• ارسال فرم تماس با ما
• ثبت یک دیدگاه

در این شرایط از متد POST استفاده می‌کنیم.

ساختار درخواست POST

برخلاف GET، در درخواست POST باید علاوه بر آدرس API، تنظیمات درخواست را نیز مشخص کنیم.

javascript id="2l0r9k"
fetch("https://jsonplaceholder.typicode.com/posts", {

method: "POST",

headers: {
"Content-Type": "application/json"
},

body: JSON.stringify({
title: "آموزش Fetch API",
body: "این یک مقاله آزمایشی است.",
userId: 1
})
});

در نگاه اول ممکن است این کد کمی طولانی به نظر برسد، اما هر بخش وظیفه مشخصی دارد.

اجزای درخواست POST در Fetch API

تعیین نوع درخواست

method: "POST"

این گزینه به سرور اعلام می‌کند که قصد داریم اطلاعات جدیدی ارسال کنیم، نه اینکه فقط داده‌ای دریافت کنیم.
 تعیین Header

headers: {
"Content-Type": "application/json"
}

Headerها اطلاعاتی درباره درخواست در اختیار سرور قرار می‌دهند.

در این مثال مشخص کرده‌ایم که اطلاعات ارسالی با فرمت JSON هستند.
اگر این Header را ارسال نکنید، بسیاری از APIها قادر به پردازش اطلاعات نخواهند بود.
ارسال داده‌ها

body: JSON.stringify({

title: "آموزش Fetch API",

body: "این یک مقاله آزمایشی است.",

userId: 1

})

ویژگی body شامل اطلاعاتی است که قرار است به سرور ارسال شوند.

از آنجایی که Fetch انتظار یک رشته (String) را دارد، شیء جاوااسکریپتی را با استفاده از JSON.stringify() به متن JSON تبدیل می‌کنیم.
دریافت پاسخ سرور
در اکثر پروژه‌ها بعد از ثبت اطلاعات، سرور نتیجه عملیات را نیز برمی‌گرداند.

async function createPost() {

const response = await fetch(
"https://jsonplaceholder.typicode.com/posts",
{
method: "POST",

headers: {
"Content-Type": "application/json"
},

body: JSON.stringify({
title: "آموزش Fetch API",
body: "این یک مقاله آزمایشی است.",
userId: 1
})
}
);

const data = await response.json();

console.log(data);

}
createPost();

اگر درخواست با موفقیت انجام شود، اطلاعات رکورد ایجادشده توسط سرور در متغیر data قرار می‌گیرد.

const postData = {
title: "آموزش Fetch API",
body: "این یک مقاله آزمایشی است.",
userId: 1
};
body: JSON.stringify(postData);

مدیریت خطاها در Fetch API

یکی از مهم‌ترین بخش‌های کار با API، مدیریت خطاها است.

در پروژه‌های واقعی همیشه همه چیز طبق انتظار پیش نمی‌رود. ممکن است:

• اینترنت کاربر قطع شود.
• سرور در دسترس نباشد.
• آدرس API اشتباه باشد.
• کاربر مجوز دسترسی نداشته باشد.
• سرور با خطای 500 پاسخ دهد.

اگر این شرایط را مدیریت نکنید، برنامه با خطا مواجه می‌شود و تجربه کاربری بسیار ضعیفی ایجاد خواهد شد.

استفاده از try…catch

زمانی که از Async/Await استفاده می‌کنید، بهترین روش مدیریت خطا استفاده از بلوک `try…catch` است.

async function getUsers() {

try {

const response = await fetch(
"https://jsonplaceholder.typicode.com/users"
);

const data = await response.json();

console.log(data);

} catch (error) {

console.error(error);

}

}

getUsers();

اگر هنگام ارسال درخواست مشکلی مانند قطع اینترنت یا عدم برقراری ارتباط با سرور رخ دهد، برنامه وارد بخش `catch` می‌شود.

 آیا Fetch برای خطاهای 404 وارد catch می‌شود؟

این سؤال یکی از رایج‌ترین سؤالات برنامه‌نویسان تازه‌کار است.

پاسخ خیر است.

اگر سرور پاسخ 404 یا 500 برگرداند، Fetch همچنان Promise را Resolve می‌کند، زیرا از دید مرورگر ارتباط با سرور با موفقیت برقرار شده است.

بنابراین باید وضعیت پاسخ را خودمان بررسی کنیم.

بررسی وضعیت پاسخ

async function getUsers() {

try {

const response = await fetch(
"https://jsonplaceholder.typicode.com/users"
);

if (!response.ok) {

throw new Error("خطا در دریافت اطلاعات از سرور");

}

const data = await response.json();

console.log(data);

} catch (error) {

console.error(error.message);

}

}

ویژگی response.ok اگر کد وضعیت بین 200 تا 299 باشد مقدار true برمی‌گرداند.

در غیر این صورت مقدار آن false خواهد بود.

به همین دلیل تقریباً در تمام پروژه‌های حرفه‌ای بعد از Fetch ابتدا response.ok بررسی می‌شود.

مشاهده کد وضعیت (Status Code)

گاهی لازم است بدانیم سرور دقیقاً چه پاسخی داده است.

console.log(response.status);

خروجی ممکن است یکی از مقادیر زیر باشد.

پروژه عملی؛ نمایش لیست کاربران با Fetch API

تا اینجا با ارسال درخواست، دریافت پاسخ، ارسال اطلاعات و مدیریت خطا آشنا شدیم.

اکنون زمان آن رسیده است که همه این مفاهیم را در قالب یک پروژه کوچک اما کاربردی پیاده‌سازی کنیم.

در این مثال، اطلاعات کاربران را از یک API دریافت کرده و آن‌ها را داخل صفحه نمایش می‌دهیم.

ساختار HTML
ابتدا یک عنصر برای نمایش کاربران ایجاد می‌کنیم.

کد جاوا اسکریپت

async function loadUsers() {
  try {
    const response = await fetch("https://jsonplaceholder.typicode.com/users");

    if (!response.ok) {
      throw new Error("خطا در دریافت اطلاعات");
    }

    const users = await response.json();
    const container = document.getElementById("users");

    let html = "";

    users.forEach((user) => {
      html += `

`; }); container.innerHTML = html; } catch (error) { console.error(error); } } loadUsers();

با اجرای این کد، لیستی از کاربران به صورت خودکار داخل صفحه ایجاد می‌شود.

اجرای پروژه در مرورگر

این دقیقاً همان الگویی است که در بسیاری از پنل‌های مدیریت، فروشگاه‌های اینترنتی و داشبوردها مشاهده می‌کنید.

کمی ظاهر بهتر

برای اینکه خروجی زیباتر شود، می‌توانیم یک استایل ساده نیز اضافه کنیم.

 .user-card {
    background: #1f2937;
    border-radius: 12px;
    padding: 20px;
    margin-bottom: 15px;
    border: 1px solid #374151;
  }
  .user-card h3 {
    margin-bottom: 10px;
  }

 نتیجه نهایی
پس از اجرای پروژه، مرورگر مراحل زیر را انجام می‌دهد.

در ظاهر شاید این فرآیند ساده به نظر برسد، اما همین الگو پایه بسیاری از پروژه‌های واقعی است. کافی است به جای API آزمایشی، API پروژه لاراول، وردپرس یا Node.js خودتان را قرار دهید.

این پروژه را چگونه حرفه‌ای‌تر کنیم؟

در این مقاله برای سادگی فقط اطلاعات کاربران را دریافت و نمایش دادیم؛ اما در پروژه‌های واقعی معمولاً امکانات بیشتری نیز اضافه می‌شوند، مانند:

• نمایش Loading هنگام دریافت اطلاعات
• نمایش پیام مناسب در صورت بروز خطا
• صفحه‌بندی (Pagination) اطلاعات
• جستجو و فیلتر داده‌ها
• جدا کردن کدهای مربوط به ارتباط با API در فایل‌های مستقل

اگر این موارد را نیز به پروژه اضافه کنید، ساختار کد شما بسیار نزدیک‌تر به پروژه‌های واقعی خواهد بود.

 اشتباهات رایج هنگام کار با Fetch API

اگر تازه کار با Fetch API را شروع کرده‌اید، احتمالاً با برخی از خطاهای زیر روبه‌رو خواهید شد.

• فراموش کردن استفاده از await
• صدا نزدن متد response.json()
• بررسی نکردن response.ok
• ارسال Object بدون استفاده از JSON.stringify()
• فراموش کردن Header مربوط به Content-Type
• استفاده از innerHTML += در لیست‌های بسیار بزرگ که باعث کاهش کارایی می‌شود.

اگر این چند نکته را رعایت کنید، بخش بزرگی از خطاهای رایج Fetch API را تجربه نخواهید کرد.

پروژه عملی نمایش کاربران با Fetch API

 Best Practices در استفاده از Fetch API

نوشتن کدی که فقط کار کند کافی نیست؛ هدف این است که کد **خوانا، قابل نگهداری و توسعه‌پذیر** باشد. رعایت نکات زیر به شما کمک می‌کند کدهای حرفه‌ای‌تری بنویسید.

• تا حد امکان از Async/Await به جای زنجیره‌های طولانی .then() استفاده کنید.
• همیشه مقدار response.ok را قبل از پردازش داده‌ها بررسی کنید.
• در تمام درخواست‌ها از try...catch برای مدیریت خطاها استفاده کنید.
• آدرس APIها را در متغیر یا فایل تنظیمات قرار دهید و از تکرار آن‌ها در پروژه جلوگیری کنید.
• منطق ارتباط با API را از کدهای مربوط به رابط کاربری (UI) جدا نگه دارید.
• پیام‌های خطا را به زبان قابل فهم برای کاربر نمایش دهید.

اشتباهات رایج (Common Mistakes)

اگر تازه کار با Fetch API را شروع کرده‌اید، احتمالاً حداقل یکی از اشتباهات زیر را مرتکب خواهید شد. خوشبختانه با شناخت آن‌ها می‌توانید ساعت‌ها در زمان اشکال‌زدایی صرفه‌جویی کنید.

const response = fetch(url); console.log(response);

const response = await fetch(url);

const response = await fetch(url); console.log(response);

const response = await fetch(url); const data = await response.json();

if (!response.ok) { throw new Error("خطا در دریافت اطلاعات"); }

body: { name: "Vahid" }

body: JSON.stringify({ name: "Vahid" })

headers:{ "Content-Type":"application/json" }

در بسیاری از APIها اگر این Header ارسال نشود، اطلاعات پردازش نخواهند شد.

اگر از همین ابتدای یادگیری این نکات را رعایت کنید، هنگام ورود به فریم‌ورک‌هایی مانند Laravel، React یا Vue نیز ساختار کدهای شما استاندارد خواهد بود.

جمع‌بندی

در این مقاله با یکی از مهم‌ترین APIهای جاوااسکریپت آشنا شدیم.

یاد گرفتیم که چگونه اطلاعات را از سرور دریافت کنیم، داده‌های جدید ارسال کنیم، پاسخ‌ها را پردازش کنیم و خطاهای احتمالی را مدیریت کنیم.

تقریباً تمام برنامه‌های تحت وب مدرن، از فروشگاه‌های اینترنتی گرفته تا شبکه‌های اجتماعی و پنل‌های مدیریتی، برای ارتباط با سرور از مفاهیمی استفاده می‌کنند که در این مقاله یاد گرفتید.

اگر مفاهیم این آموزش را به‌خوبی درک کنید، در ادامه مسیر یادگیری React، Vue، Angular، Node.js و حتی ارتباط فرانت‌اند با APIهای Laravel، با چالش بسیار کمتری روبه‌رو خواهید شد.

سوالات متداول (FAQ)

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

بله. تمام مرورگرهای مدرن از Fetch API پشتیبانی می‌کنند. تنها در نسخه‌های بسیار قدیمی مرورگرها نیاز به Polyfill وجود دارد.

تفاوت Fetch API و Axios چیست؟

Fetch API به صورت پیش‌فرض در مرورگر وجود دارد و نیازی به نصب کتابخانه ندارد. اما Axios امکاناتی مانند Interceptor، Timeout،