Axios: ما هو، طلبات HTTP وأساسيات العمل مع API

ما هو Axios؟

Axios هي مكتبة جافا سكريبت مصممة لتنفيذ طلبات HTTP من المتصفح وبيئة Node.js. وهي مبنية فوق XMLHttpRequest في المتصفح ووحدة http في Node.js، مما يوفر واجهة برمجة موحدة لكلا المنصتين.

الميزة الرئيسية لـ Axios مقارنة بـ fetch الأصلي هي المعالجة التلقائية لـ JSON، ودعم المعترضات، ومعالجة الأخطاء بشكل أكثر ملاءمة. على عكس fetch، لا يتطلب Axios استدعاءين .then للحصول على نص استجابة JSON ويطرح استثناء تلقائياً عند أخطاء HTTP (4xx, 5xx).

تدعم المكتبة جميع طرق HTTP الرئيسية: GET، POST، PUT، DELETE، PATCH و HEAD. يمكن استخدامها في المشاريع البسيطة وفي تطبيقات المؤسسات الكبيرة التي تتعامل مع مئات الآلاف من الطلبات يومياً.

الخصائص الرئيسية لـ Axios

• Promise API — جميع العمليات تُرجع Promise، مما يبسط الكود غير المتزامن
• دعم TypeScript — كتابة كاملة لجميع الطرق والتكوينات
• المعترضات — وسيط (middleware) لمعالجة الطلبات والاستجابات
• التحويل — تحويل تلقائي للبيانات عند الإدخال والإخراج

هندسة Axios ومبدأ العمل

هندسة Axios تعتمد على مفهوم المحولات (adapters). تقوم المكتبة بتجريد طبقة النقل: تستخدم XMLHttpRequest في المتصفح ووحدة http أو https في Node.js. مما يوفر واجهة واحدة بغض النظر عن بيئة التشغيل.

يمر كل طلب عبر سلسلة من المعترضات التي يمكنها تعديل تكوين الطلب أو الاستجابة. بعد المعترضات، يتم تمرير الطلب إلى المحول الذي ينفذ استدعاء HTTP الفعلي. ثم تمر الاستجابة عبر معترضات الاستجابة قبل الوصول إلى كود التطبيق.

دورة حياة طلب Axios

1. إنشاء التكوين — الطريقة، URL، الرؤوس، نص الطلب
2. معترض الطلب — تعديل التكوين، إضافة الرموز
3. استدعاء HTTP — التنفيذ عبر محول المتصفح أو Node.js
4. معترض الاستجابة — تحويل الاستجابة، معالجة الأخطاء
5. إرجاع النتيجة — يتم حل Promise مع البيانات أو رفضها

الميزات الرئيسية لـ Axios

Axios تتضمن العديد من الميزات المدمجة التي تجعلها خياراً مناسباً للعمل مع HTTP في تطبيقات الجوال والويب. دعنا نستعرض أهمها.

التحويل التلقائي للبيانات

عند إرسال طلب، يقوم Axios تلقائياً بتحويل كائن JavaScript إلى سلسلة JSON باستخدام JSON.stringify. وعند استلام الاستجابة، تقوم المكتبة بتحليل JSON مرة أخرى إلى كائن. وهذا يوفر على المطور عناء التسلسل وإلغاء التسلسل اليدوي للبيانات.

حماية CSRF

في بيئة المتصفح، يضيف Axios تلقائياً رؤوس XSRF-TOKEN من ملفات تعريف الارتباط، مما يحمي التطبيق من تزوير الطلبات عبر المواقع. للقيام بذلك، يكفي تكوين الخادم لإرسال الرمز المميز في ملف تعريف ارتباط باسم XSRF-TOKEN.

المهلات وإلغاء الطلبات

تدعم المكتبة تعيين مهلة عبر معلمة timeout وإلغاء الطلب عبر AbortController. وهذا مهم بشكل خاص في تطبيقات الجوال ذات الاتصالات غير المستقرة، حيث تستهلك الطلبات المعلقة البطارية والبيانات.

تثبيت وتكوين Axios

تثبيت Axios يتم عبر أي مدير حزم. المكتبة متاحة في سجل npm ويمكن استخدامها في مشاريع Node.js والمتصفح. بالنسبة لـ TypeScript، الأنواع مضمنة في الحزمة الرئيسية — لا حاجة لتبعيات إضافية.

بعد التثبيت، يمكنك إنشاء مثيل بتكوين أساسي: URL أساسي، مهلة افتراضية، رؤوس مشتركة. وهذا يسمح بعدم تكرار نفس المعلمات في كل طلب وإدارة إعدادات عميل HTTP مركزياً.

# التثبيت عبر npm
npm install axios

# التثبيت عبر yarn
yarn add axios

# التثبيت عبر pnpm
pnpm add axios

إنشاء مثيل مع تكوين

يوصى بإنشاء مثيل منفصل Axios لكل خدمة API. وهذا يسمح بتعيين 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 الذي يتحول تلقائياً إلى سلسلة استعلام. تحتوي الاستجابة على البيانات في حقل 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 تتطلب استدعاءين .then() للحصول على JSON: response.json() ثم تُرجع Promise بالبيانات. Axios يفعل ذلك تلقائياً. Fetch لا تدعم تقدم رفع الملفات بدون إضافات إضافية. Axios يوفر onUploadProgress و onDownloadProgress مدمجين.

في Node.js، Fetch متاح منذ الإصدار 18 كميزة تجريبية، بينما يعمل Axios بشكل مستقر منذ Node.js 10. للمشاريع التي تدعم إصدارات Node.js القديمة، يكون الاختيار واضحاً لصالح Axios. لمشاريع المتصفح الحديثة دون معالجة طلبات معقدة، قد يكون fetch كافياً.