Axios: چیست، درخواست‌های HTTP و مبانی کار با API

Axios چیست؟

Axios یک کتابخانه JavaScript برای اجرای درخواست‌های HTTP از مرورگر و محیط Node.js است. این کتابخانه بر روی XMLHttpRequest در مرورگر و ماژول http در Node.js ساخته شده و یک API واحد برای هر دو پلتفرم ارائه می‌دهد.

مزیت اصلی Axios نسبت به fetch بومی، پردازش خودکار JSON، پشتیبانی از میان‌افزارها و کار راحت‌تر با خطاهاست. برخلاف fetch، Axios برای دریافت بدنه JSON پاسخ به دو فراخوانی .then نیاز ندارد و به طور خودکار در خطاهای HTTP (4xx، 5xx) استثنا پرتاب می‌کند.

این کتابخانه از تمام روش‌های اصلی HTTP پشتیبانی می‌کند: GET، POST، PUT، DELETE، PATCH و HEAD. می‌تواند هم در پروژه‌های ساده و هم در برنامه‌های سازمانی بزرگ با صدها هزار درخواست روزانه استفاده شود.

ویژگی‌های کلیدی Axios

• Promise API — همه عملیات‌ها Promise برمی‌گردانند که کد ناهمگام را ساده می‌کند
• پشتیبانی TypeScript — تایپ‌گذاری کامل برای همه روش‌ها و پیکربندی‌ها
• میان‌افزارها — middleware برای پردازش درخواست‌ها و پاسخ‌ها
• تبدیل — تبدیل خودکار داده‌ها در ورودی و خروجی

معماری Axios و اصل کار

معماری Axios بر اساس مفهوم آداپتورها (adapters) است. کتابخانه لایه انتقال را انتزاع می‌کند: در مرورگر از XMLHttpRequest استفاده می‌شود، در Node.js — از ماژول http یا https. این امکان یک رابط واحد را بدون توجه به محیط اجرا فراهم می‌کند.

هر درخواست از زنجیره‌ای از میان‌افزارها (interceptors) عبور می‌کند که می‌توانند پیکربندی درخواست یا پاسخ را تغییر دهند. پس از میان‌افزارها، درخواست به آداپتور ارسال می‌شود که فراخوانی واقعی HTTP را انجام می‌دهد. سپس پاسخ قبل از رسیدن به کد برنامه از میان‌افزارهای پاسخ عبور می‌کند.

چرخه عمر درخواست Axios

1. ایجاد پیکربندی — روش، URL، هدرها، بدنه درخواست
2. میان‌افزار درخواست — تغییر پیکربندی، افزودن توکن‌ها
3. فراخوانی HTTP — اجرا از طریق آداپتور مرورگر یا Node.js
4. میان‌افزار پاسخ — تبدیل پاسخ، مدیریت خطاها
5. بازگشت نتیجه — Promise با داده‌ها حل یا رد می‌شود

قابلیت‌های اصلی Axios

Axios شامل بسیاری از قابلیت‌های داخلی است که آن را به انتخابی راحت برای کار با HTTP در برنامه‌های موبایل و وب تبدیل می‌کند. بیایید مهم‌ترین آنها را بررسی کنیم.

تبدیل خودکار داده‌ها

هنگام ارسال درخواست، Axios به طور خودکار شیء JavaScript را با استفاده از JSON.stringify به رشته JSON تبدیل می‌کند. هنگام دریافت پاسخ، کتابخانه JSON را دوباره به شیء تجزیه می‌کند. این کار برنامه‌نویس را از سریال‌سازی و دسریال‌سازی دستی داده‌ها بی‌نیاز می‌کند.

محافظت در برابر CSRF

در محیط مرورگر، Axios به طور خودکار هدرهای XSRF-TOKEN را از cookie اضافه می‌کند و از برنامه در برابر جعل درخواست بین‌سایتی محافظت می‌کند. برای این کار کافی است سرور را برای ارسال توکن در cookie با نام XSRF-TOKEN پیکربندی کنید.

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

کتابخانه از تنظیم تایم‌اوت از طریق پارامتر timeout و لغو درخواست از طریق AbortController پشتیبانی می‌کند. این به ویژه در برنامه‌های موبایل با اتصال ناپایدار مهم است، جایی که درخواست‌های معلق باتری و ترافیک مصرف می‌کنند.

نصب و پیکربندی Axios

نصب Axios از طریق هر مدیر بسته انجام می‌شود. کتابخانه در مخزن npm در دسترس است و می‌تواند هم در Node.js و هم در پروژه‌های مرورگری متصل شود. برای TypeScript، تایپ‌ها در بسته اصلی گنجانده شده‌اند و وابستگی‌های اضافی لازم نیست.

پس از نصب می‌توان یک نمونه با پیکربندی پایه ایجاد کرد: URL پایه، تایم‌اوت پیش‌فرض، هدرهای مشترک. این کار از تکرار پارامترهای یکسان در هر درخواست جلوگیری می‌کند و امکان مدیریت متمرکز تنظیمات کلاینت HTTP را فراهم می‌کند.

# نصب از طریق npm
npm install axios

# نصب از طریق yarn
yarn add axios

# نصب از طریق pnpm
pnpm add axios

ایجاد نمونه با پیکربندی

توصیه می‌شود برای هر سرویس API یک نمونه جداگانه Axios ایجاد کنید. این امکان تنظیم URL پایه، هدرهای استاندارد و تایم‌اوت را فراهم می‌کند که بدون تکرار در هر فراخوانی برای همه درخواست‌های این نمونه اعمال می‌شوند.

import axios from 'axios';

const api = axios.create({
  baseURL: 'https://api.example.com/v1',
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  }
});

نمونه کد با Axios

نمونه درخواست‌ها الگوهای اصلی استفاده از Axios را نشان می‌دهند. همه نمونه‌ها از نحو async/await استفاده می‌کنند که کد ناهمگام را در مقایسه با زنجیره‌های .then() خواناتر می‌کند.

درخواست GET با پارامترها

برای دریافت داده از سرور از روش axios.get استفاده می‌شود. پارامترهای درخواست از طریق شیء params ارسال می‌شوند که به طور خودکار به query-string تبدیل می‌شود. پاسخ شامل داده‌ها در فیلد data، وضعیت در status و هدرها در headers است.

interface User {
  id: number;
  name: string;
  email: string;
}

async function getUsers() {
  try {
    const response = await api.get<User[]>('/users', {
      params: { page: 1, limit: 10 }
    });
    return response.data;
  } catch (error) {
    console.error('خطای بارگیری کاربران', error);
    throw error;
  }
}

درخواست POST با بدنه

برای ارسال داده به سرور از axios.post استفاده می‌شود. آرگومان دوم یک شیء با داده‌هایی است که Axios به طور خودکار به JSON سریال‌سازی می‌کند. نوع محتوای Content-Type به طور پیش‌فرض روی application/json تنظیم می‌شود.

interface CreateUserDto {
  name: string;
  email: string;
  role: string;
}

async function createUser(data: CreateUserDto) {
  const response = await api.post<User>('/users', data);
  return response.data;
}

میان‌افزارها (Interceptors)

میان‌افزارها توابع middleware هستند که برای هر درخواست یا پاسخ اجرا می‌شوند. آنها امکان افزودن توکن‌های احراز هویت، ثبت درخواست‌ها و مدیریت متمرکز خطاها را فراهم می‌کنند. میان‌افزار درخواست هدر Authorization را با توکن گرفته شده از ذخیره‌گاه اضافه می‌کند.

// میان‌افزار درخواست — توکن احراز هویت اضافه می‌کند
api.interceptors.request.use(
  (config) => {
    const token = getToken();
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

// میان‌افزار پاسخ — خطاهای 401 را مدیریت می‌کند
api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      redirectToLogin();
    }
    return Promise.reject(error);
  }
);

مدیریت خطا در Axios

مدیریت خطا در Axios بر اساس مکانیزم استثناها است. برخلاف fetch، Axios به طور خودکار خطاهای HTTP (4xx، 5xx) را گرفته و به بلوک catch منتقل می‌کند. شیء خطا شامل اطلاعاتی درباره پاسخ سرور، درخواست و زمینه اجرا است.

تشخیص سه نوع خطا مهم است: خطای پاسخ سرور (response)، خطای درخواست (request) و خطای پیکربندی (config). اولی هنگام اجرای موفق فراخوانی HTTP با کد خطا رخ می‌دهد، دومی — در صورت عدم پاسخ از سرور، سومی — در صورت پیکربندی نادرست درخواست.

import axios, { AxiosError } from 'axios';

async function safeRequest() {
  try {
    return await api.get('/data');
  } catch (error) {
    if (error instanceof AxiosError) {
      if (error.response) {
        console.warn('خطای پاسخ', error.response.status);
      } else if (error.request) {
        console.warn('پاسخی از سرور وجود ندارد');
      } else {
        console.warn('خطای پیکربندی');
      }
    }
  }
}

مقایسه Axios با Fetch API

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

Fetch خطاهای HTTP (4xx، 5xx) را استثنا در نظر نمی‌گیرد — باید response.ok را بررسی کرد. Fetch برای دریافت JSON به دو فراخوانی .then() نیاز دارد: response.json() سپس Promise با داده‌ها برمی‌گرداند. Axios این کار را خودکار انجام می‌دهد. Fetch بدون polyfill اضافی از پیشرفت آپلود فایل پشتیبانی نمی‌کند. Axios دارای onUploadProgress و onDownloadProgress داخلی است.

در Node.js Fetch از نسخه ۱۸ به عنوان یک ویژگی آزمایشی در دسترس است، در حالی که Axios از Node.js 10 به طور پایدار کار می‌کند. برای پروژه‌هایی که از نسخه‌های قدیمی Node.js پشتیبانی می‌کنند، انتخاب به نفع Axios واضح است. برای پروژه‌های مدرن مرورگری بدون پردازش پیچیده درخواست، fetch ممکن است کافی باشد.