الدليل الشامل لـ Node Fetch API: إجراء طلبات HTTP في Node.js

طلبات HTTP هي جزء أساسي من تطوير الويب الحديث. مع إدخال واجهة برمجة التطبيقات Fetch إلى Node.js، أصبح لدى المطورين الآن طريقة قوية ومتسقة لإجراء طلبات الشبكة عبر كل من متصفح الخادم. في هذا الدليل الشامل، سنستكشف كيفية استخدام Fetch في Node بشكل فعال في مشاريعك.

ما هي واجهة برمجة التطبيقات Node Fetch ولماذا يجب عليك استخدامها؟

واجهة برمجة التطبيقات Node Fetch هي آلية حديثة تعتمد على الوعد لإجراء طلبات HTTP في تطبيقات Node.js. كانت في الأصل ميزة خاصة بالمتصفح، وأصبحت واجهة برمجة التطبيقات Fetch ميزة تجريبية في Node.js v18 وحققت الاستقرار في Node.js v21.

الفوائد الرئيسية لاستخدام Node Fetch:

وظائف مدمجة: لا حاجة لتثبيت حزم طرف ثالث
معتمدة على الوعود: صياغة حديثة ونظيفة مع دعم للأسلوب async/await
معرفة متعددة الأنظمة الأساسية: نفس واجهة البرمجة مثل Fetch في جانب المتصفح
أداء محسن: مبنية على عميل HTTP عالي الأداء Undici

اختبار طلبات واجهة برمجة تطبيقات Node Fetch الخاصة بك باستخدام أدوات حديثة

أثناء تعلم كيفية استخدام Node Fetch، من الضروري أن يكون لديك أدوات موثوقة لاختبار نقاط نهاية واجهة برمجة التطبيقات الخاصة بك. Apidog تبرز كأفضل بديل لـ Postman لاختبار وتوثيق طلبات واجهة برمجة التطبيقات Node Fetch الخاصة بك.

كنظام تطوير واجهة برمجة التطبيقات الشامل، يجمع Apidog بين وثائق واجهة برمجة التطبيقات والاختبار والخوادم الوهمية في واجهة واحدة بديهية.

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

زر

إعداد بيئتك لواجهات برمجة التطبيقات Node Fetch

متطلبات مسبقة لاستخدام Node Fetch

قبل الغوص في أمثلة Node Fetch، تأكد من أن لديك:

Node.js v18 أو أعلى (يفضل v21+ لدعم Fetch المستقر)
تحقق من إصدار Node.js لديك:

node -v

التوافق مع إصدار Node Fetch

Node.js v21+: Fetch مستقر وجاهز للاستخدام في الإنتاج
Node.js v18-v20: Fetch متاحة ولكن تجريبية (استخدم -experimental-fetch)
إصدارات Node.js الأقدم: قم بتثبيت حزمة node-fetch أو قم بترقية Node.js

إذا كنت تستخدم v18-v20، قم بتشغيل تطبيقاتك باستخدام:

node --experimental-fetch app.js

إجراء أول طلب Node Fetch لك

دعونا نبدأ بطلب GET أساسي باستخدام Node Fetch:

// طلب GET أساسي باستخدام Node Fetch
fetch('<https://api.example.com/data>')
  .then(response => {
    if (!response.ok) {
      throw new Error(`خطأ HTTP! الحالة: ${response.status}`);
    }
    return response.json(); // تحليل استجابة JSON
  })
  .then(data => {
    console.log('البيانات المستلمة:', data);
  })
  .catch(error => {
    console.error('خطأ Fetch:', error);
  });

استخدام Node Fetch مع Async/Await

للحصول على شيفرة أنظف، يمكنك استخدام async/await مع Node Fetch:

async function fetchData() {
  try {
    const response = await fetch('<https://api.example.com/data>');

    if (!response.ok) {
      throw new Error(`خطأ HTTP! الحالة: ${response.status}`);
    }

    const data = await response.json();
    console.log('البيانات المستلمة:', data);
    return data;
  } catch (error) {
    console.error('خطأ Fetch:', error);
  }
}

// استدعاء الدالة
fetchData();

طرق طلب Node Fetch المتقدمة

إجراء طلبات POST باستخدام Node Fetch

async function postData(url, data) {
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(data),
    });

    if (!response.ok) {
      throw new Error(`خطأ HTTP! الحالة: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error('خطأ Fetch POST:', error);
  }
}

// مثال على الاستخدام
const newUser = {
  name: 'جون دو',
  email: 'john@example.com',
};

postData('<https://api.example.com/users>', newUser)
  .then(data => console.log('تم إنشاء المستخدم:', data));

طلبات PUT باستخدام Node Fetch

async function updateData(url, data) {
  try {
    const response = await fetch(url, {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(data),
    });

    if (!response.ok) {
      throw new Error(`خطأ HTTP! الحالة: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error('خطأ Fetch PUT:', error);
  }
}

// مثال على الاستخدام
const updatedUser = {
  id: 1,
  name: 'جين سميث',
  email: 'jane@example.com',
};

updateData('<https://api.example.com/users/1>', updatedUser)
  .then(data => console.log('تم تحديث المستخدم:', data));

طلبات DELETE باستخدام Node Fetch

async function deleteResource(url) {
  try {
    const response = await fetch(url, {
      method: 'DELETE',
    });

    if (!response.ok) {
      throw new Error(`خطأ HTTP! الحالة: ${response.status}`);
    }

    // بعض واجهات برمجة التطبيقات لا تعيد محتوى عند حذف
    if (response.status === 204) {
      return { success: true };
    }

    return await response.json();
  } catch (error) {
    console.error('خطأ Fetch DELETE:', error);
  }
}

// مثال على الاستخدام
deleteResource('<https://api.example.com/users/1>')
  .then(result => console.log('نتيجة الحذف:', result));

التعامل مع أنواع الاستجابة المختلفة باستخدام Node Fetch

يمكن لـ Node Fetch العمل مع تنسيقات استجابة متنوعة:

التعامل مع استجابة JSON

fetch('<https://api.example.com/data>')
  .then(response => response.json())
  .then(data => console.log(data));

التعامل مع استجابة نصية

fetch('<https://example.com/plain-text>')
  .then(response => response.text())
  .then(text => console.log(text));

التعامل مع بيانات ثنائية

fetch('<https://example.com/image.png>')
  .then(response => response.arrayBuffer())
  .then(buffer => {
    // التعامل مع البيانات الثنائية
    const bytes = new Uint8Array(buffer);
    console.log('طول البيانات الثنائية:', bytes.length);
  });

تخصيص طلبات Node Fetch مع الرؤوس والخيارات

تعيين رؤوس مخصصة

fetch('<https://api.example.com/protected-data>', {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'تطبيقي على Node.js'
  }
})
.then(response => response.json())
.then(data => console.log(data));

تكوين خيارات الطلب

fetch('<https://api.example.com/data>', {
  method: 'GET',
  headers: { 'Content-Type': 'application/json' },
  cache: 'no-cache',
  redirect: 'follow',      // متابعة، خطأ، أو يدوي
  referrerPolicy: 'no-referrer'
})
.then(response => response.json())
.then(data => console.log(data));

التعامل مع الأخطاء باستخدام Node Fetch

التعامل الشامل مع الأخطاء

جانب مهم لفهمه حول Node Fetch هو أنها لا ترفض على رموز حالة الأخطاء HTTP. يتم رفض الوعد فقط في حال حدوث أخطاء في الشبكة أو إذا منع شيء ما الطلب من الاكتمال.

إليك نهج شامل للتعامل مع الأخطاء:

async function fetchWithErrorHandling(url) {
  try {
    const response = await fetch(url);

    // تحقق من الأخطاء HTTP
    if (!response.ok) {
      // محاولة الحصول على تفاصيل الخطأ من الاستجابة
      let errorDetails;
      try {
        errorDetails = await response.json();
      } catch (e) {
        errorDetails = await response.text();
      }

      throw new Error(
        `خطأ HTTP! الحالة: ${response.status}, التفاصيل: ${
          typeof errorDetails === 'object'
            ? JSON.stringify(errorDetails)
            : errorDetails
        }`
      );
    }

    return await response.json();
  } catch (error) {
    // أخطاء الشبكة، وأخطاء التحليل، وأخطائنا HTTP المخصصة
    console.error('فشل Fetch:', error.message);
    throw error; // إعادة طرح للسماح للشفرة المستدعية بالتعامل
  }
}

تنفيذ مهلة الطلب مع Node Fetch

لا تحتوي Node Fetch على دعم مدمج للمهلة، ولكن يمكنك تنفيذها باستخدام AbortController:

async function fetchWithTimeout(url, options = {}, timeoutMs = 5000) {
  const controller = new AbortController();
  const { signal } = controller;

  // إعداد المهلة
  const timeout = setTimeout(() => {
    controller.abort();
  }, timeoutMs);

  try {
    const response = await fetch(url, { ...options, signal });
    clearTimeout(timeout); // مسح المهلة إذا اكتمال Fetch

    if (!response.ok) {
      throw new Error(`خطأ HTTP! الحالة: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    clearTimeout(timeout);
    if (error.name === 'AbortError') {
      throw new Error(`انتهت مهلة الطلب بعد ${timeoutMs}ms`);
    }
    throw error;
  }
}

// مثال على الاستخدام
fetchWithTimeout('<https://api.example.com/data>', {}, 3000)
  .then(data => console.log(data))
  .catch(error => console.error('خطأ:', error.message));

التعامل مع المصادقة باستخدام Node Fetch

المصادقة الأساسية

const username = 'مستخدم';
const password = 'كلمة السر';
const credentials = Buffer.from(`${username}:${password}`).toString('base64');

fetch('<https://api.example.com/protected>', {
  headers: {
    'Authorization': `Basic ${credentials}`
  }
})
.then(response => response.json())
.then(data => console.log(data));

المصادقة باستخدام توكن Bearer

const token = 'your_jwt_or_oauth_token';

fetch('<https://api.example.com/protected>', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})
.then(response => response.json())
.then(data => console.log(data));

أفضل الممارسات لاستخدام Node Fetch في الإنتاج

تحقق دائمًا من حالة الاستجابة: لا تفترض أن الاستجابات ناجحة
تعامل مع أنواع المحتوى المختلفة بشكل مناسب: استخدم الطريقة الصحيحة لنوع الاستجابة الخاص بك (json()، text()، إلخ)
نفذ معالجة الأخطاء المناسبة: أنشئ دوال مساعدة تتعامل مع الأخطاء بشكل متسق
تعيين مهلات الطلب: منع الطلبات المعلقة باستخدام AbortController
إنشاء أغطية Fetch قابلة لإعادة الاستخدام: بناء طبقة خدمة بأنماط طلبات شائعة
فكر في منطق إعادة المحاولة للطلبات الفاشلة: تنفيذ التراجع الأسي لواجهات برمجة التطبيقات غير المستقرة
استخدم متغيرات البيئة لعناوين URLs الأساسية: احتفظ بعناوين URLs الخاصة بالبيئة بعيدًا عن الشيفرة

استكشاف المشكلات الشائعة في Node Fetch

خطأ "Fetch غير معرّف"

إذا واجهت ReferenceError: fetch is not defined، تحقق من:

أنك تستخدم Node.js v18+
بالنسبة لـ Node.js v18-v20، استخدم علامة -experimental-fetch
للإصدارات الأقدم، قم بتثبيت حزمة node-fetch

مشاكل شهادة HTTPS

ت inherited Node Fetch معالجة شهادة HTTPS الخاصة بـ Node. للشهادات المخصصة:

const https = require('https');
const fs = require('fs');

const httpsAgent = new https.Agent({
  ca: fs.readFileSync('./custom-certificate.pem')
});

fetch('<https://api.example.com/data>', {
  agent: httpsAgent
})
.then(response => response.json())
.then(data => console.log(data));

خاتمة: احتضان واجهة برمجة التطبيقات Node Fetch في مشاريعك

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

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

الآن بعد أن لديك فهم شامل لـ Node Fetch، أنت جاهز لتنفيذه في مشاريعك الخاصة والاستفادة من هذه الواجهة القوية لجميع احتياجات طلبات HTTP الخاصة بك.

زر