مكتبة CORS لجافا سكريبت (Node.js): دليل شامل

1. ما هي CORS ولماذا تحتاجها؟

CORS (Cross-Origin Resource Sharing) هي آلية أمان مدمجة في المتصفحات تتحكم في الوصول إلى الموارد (مثل APIs، الخطوط، البرامج النصية) من صفحات ويب محملة من نطاق (origin) مختلف. بشكل افتراضي، تمنع المتصفحات طلبات HTTP التي تبدأها البرامج النصية (مثل fetch أو XMLHttpRequest) إذا كانت موجهة إلى نطاق يختلف عن النطاق الذي حمل الصفحة. هذا يمنع هجمات مثل CSRF (Cross-Site Request Forgery) وتسرب البيانات.

مكتبة cors الخاصة بـ Node.js و Express هي middleware (برمجية وسيطة) تتيح للمطورين ضبط وإدارة سياسات CORS بسهولة على جانب الخادم. بدلاً من كتابة الرؤوس يدويًا (Access-Control-Allow-Origin، Access-Control-Allow-Methods، إلخ) ومعالجة الطلبات التمهيدية (preflight requests بطريقة OPTIONS)، تقوم هذه المكتبة بأتمتة العملية بأكملها. تتكامل مع سلسلة معالجة الطلبات في Express وتضيف الرؤوس اللازمة إلى الاستجابات.

لماذا تحتاجها؟ إذا كنت تطور API باستخدام Node.js سيتم استخدامه من قبل تطبيق واجهة أمامية (React، Vue، Angular)، تطبيق جوال، أو خدمة طرف ثالث تعمل من نطاق مختلف (مثل api.mysite.com لـ app.mysite.com)، فأنت ملزم بإعداد CORS. بدون ذلك، سيقوم المتصفح ببساطة بحظر الطلبات، وسيرى المستخدم خطأ في وحدة التحكم. مكتبة cors تجعل هذا الإعداد مرنًا وآمنًا وبسيطًا.

2. التثبيت

يتم التثبيت عبر مدير الحزم npm (Node Package Manager). تأكد من تثبيت Node.js و npm على جهازك.

npm install cors

بعد التثبيت، ستتم إضافة الحزمة إلى مجلد node_modules، وسيظهر سجل بها في ملف package.json.

إذا كنت تستخدم yarn:

yarn add cors

3. بداية سريعة — مثال عملي بسيط

أسهل طريقة لاستخدام CORS هي تفعيله لجميع الطلبات. هذا مناسب للتطوير أو APIs العامة حيث يُسمح بالوصول من أي نطاق.

const express = require('express');
const cors = require('cors');

const app = express();

// تفعيل CORS لجميع المسارات
app.use(cors());

app.get('/api/data', (req, res) => {
    res.json({ message: 'هذه الاستجابة مسموحة لجميع المصادر!' });
});

app.listen(3000, () => {
    console.log('الخادم يعمل على المنفذ 3000');
});

في هذا المثال، أي طلب من أي نطاق (مثل http://localhost:8080 أو https://example.com) إلى /api/data سيتم معالجته بنجاح. لن يقوم المتصفح بحظر الاستجابة.

4. الطرق/الدوال/الفئات الأساسية

توفر مكتبة cors دالة رئيسية واحدة — cors(options) — والتي تعيد دالة middleware. ومع ذلك، يتم تمرير الإعدادات عبر كائن options، مما يوفر مرونة هائلة. دعنا نستعرض 8 خيارات وطرق رئيسية.