كيفية التعامل مع معلمات الاستعلام في Node.js Express

مرحباً بكم، أيها المبرمجون الأعزاء! اليوم، سوف نغوص في عالم معلمات الاستعلام في Node.js Express. سواء كنت مبتدئًا أو مطورًا متمرسًا، فإن فهم كيفية التعامل مع معلمات الاستعلام بكفاءة أمر بالغ الأهمية لبناء واجهات برمجة التطبيقات القوية. لذا، استعدوا لتعزيز مهاراتكم في Express.js!

قبل أن نبدأ، تحية سريعة إلى Apidog - أداتك المفضلة لتوثيق واختبار واجهات برمجة التطبيقات. إنها مجانية، قوية، وتكمل تمامًا رحلتك في تطوير واجهات برمجة التطبيقات. لا تنسَ تنزيل Apidog مجانًا لتسهيل حياتك!

ما هي معلمات الاستعلام؟

أولًا، دعونا نوضح ما هي معلمات الاستعلام. عند إرسال طلب GET إلى خادم، يمكنك تضمين بيانات إضافية باستخدام معلمات الاستعلام. هذه المعلمات هي جزء من عنوان URL وغالبًا ما تستخدم لتصفية أو فرز أو تخصيص البيانات التي يتم إرجاعها من الخادم.

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

http://example.com/users?age=25&location=NY

في هذا العنوان، age=25 و location=NY هما معلمات استعلام.

إعداد بيئة Node.js الخاصة بك

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

بمجرد تثبيت Node.js، أنشئ دليل مشروع جديد وقم بتهيئته باستخدام npm:

mkdir express-query-params
cd express-query-params
npm init -y

بعد ذلك، قم بتثبيت Express:

npm install express

إنشاء خادم Express أساسي

الآن بعد أن تم إعداد بيئتنا، لنقم بإنشاء خادم Express أساسي. أنشئ ملفًا جديدًا يسمى server.js وأضف الكود التالي:

const express = require('express');
const app = express();
const port = 3000;

app.get('/', (req, res) => {
    res.send('مرحبًا بالعالم!');
});

app.listen(port, () => {
    console.log(`الخادم يعمل على http://localhost:${port}`);
});

شغل خادمك باستخدام الأمر التالي:

node server.js

يجب أن ترى الرسالة "الخادم يعمل على http://localhost:3000". افتح متصفحك وانتقل إلى http://localhost:3000 لرؤية "مرحبًا بالعالم!" معروضة على الشاشة.

التعامل مع طلبات GET باستخدام معلمات الاستعلام

الآن بعد أن أصبح لدينا خادم أساسي يعمل، دعونا نضيف بعض الوظائف للتعامل مع معلمات الاستعلام.

مثال 1: معلمات استعلام بسيطة

سنبدأ بمثال بسيط. دعونا نعدل خادمنا للتعامل مع طلب GET مع معلمات الاستعلام. قم بتحديث ملف server.js كما يلي:

app.get('/users', (req, res) => {
    const age = req.query.age;
    const location = req.query.location;

    res.send(`المستخدمون بعمر: ${age} والموقع: ${location}`);
});

في هذا الكود، نستخدم req.query للوصول إلى معلمات الاستعلام. يحتوي كائن req.query على جميع معلمات الاستعلام المرسلة في عنوان URL.

اختبار نقطة النهاية الخاصة بك

أعد تشغيل خادمك وانتقل إلى عنوان URL التالي في متصفحك:

http://localhost:3000/users?age=25&location=NY

يجب أن ترى الرسالة "المستخدمون بعمر: 25 والموقع: NY".

مثال 2: التعامل مع معلمات استعلام متعددة

دعونا نأخذ خطوة أخرى ونتعامل مع معلمات الاستعلام المتعددة بشكل أكثر فعالية. قم بتحديث ملف server.js الخاص بك للتعامل مع سيناريوهات أكثر تعقيدًا:

app.get('/search', (req, res) => {
    const { term, limit, page } = req.query;

    res.send(`البحث عن: ${term}, الحد: ${limit}, الصفحة: ${page}`);
});

في هذا المثال، نقوم بتفكيك كائن req.query لاستخراج المعلمات مباشرة. هذا يجعل الكود أنظف وأكثر قابلية للقراءة.

اختبار نقطة النهاية الخاصة بك

أعد تشغيل خادمك وانتقل إلى عنوان URL التالي في متصفحك:

http://localhost:3000/search?term=nodejs&limit=10&page=2

يجب أن ترى الرسالة "البحث عن: nodejs، الحد: 10، الصفحة: 2".

التحقق من صحة معلمات الاستعلام

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

مثال 3: التحقق الأساسي من الصحة

قم بتحديث ملف server.js الخاص بك ليشتمل على منطق التحقق من الصحة:

app.get('/products', (req, res) => {
    const { category, price } = req.query;

    if (!category || !price) {
        return res.status(400).send('فئة أو سعر مفقود');
    }

    res.send(`الفئة: ${category}, السعر: ${price}`);
});

في هذا المثال، نتحقق مما إذا كانت معلمات الاستعلام category و price موجودة. إذا كان أي منها مفقودًا، نرجع رمز حالة 400 مع رسالة خطأ.

اختبار نقطة النهاية الخاصة بك

أعد تشغيل خادمك وانتقل إلى عنوان URL التالي في متصفحك:

http://localhost:3000/products?category=electronics&price=100

يجب أن ترى الرسالة "الفئة: electronics، السعر: 100".

حاول الوصول إلى عنوان URL بدون واحدة من معلمات الاستعلام:

http://localhost:3000/products?category=electronics

يجب أن ترى رسالة الخطأ "فئة أو سعر مفقود".

التعامل المتقدم مع معلمات الاستعلام باستخدام middleware

تعد وظائف middleware في Express وسيلة قوية لإضافة مزيد من الوظائف إلى المسارات الخاصة بك. دعونا نرى كيف يمكننا استخدام middleware للتعامل مع معلمات الاستعلام بشكل أكثر كفاءة.

مثال 4: Middleware للتحقق من صحة معلمات الاستعلام

قم بإنشاء ملف جديد يسمى middleware.js وأضف الكود التالي:

const validateQueryParams = (req, res, next) => {
    const { category, price } = req.query;

    if (!category || !price) {
        return res.status(400).send('فئة أو سعر مفقود');
    }

    next();
};

module.exports = validateQueryParams;

في هذه الوظيفة الوسيطة، نقوم بالتحقق من صحة معلمات الاستعلام ونستدعي next() لتمرير السيطرة إلى الوظيفة الوسيطة التالية أو معالج المسار إذا كانت التحقق من الصحة ناجحة.

استخدام middleware في المسارات الخاصة بك

قم بتحديث ملف server.js الخاص بك لاستخدام الوظيفة الوسيطة:

const validateQueryParams = require('./middleware');

app.get('/products', validateQueryParams, (req, res) => {
    const { category, price } = req.query;

    res.send(`الفئة: ${category}, السعر: ${price}`);
});

الآن، سيتم تنفيذ وظيفة validateQueryParams الوسيطة قبل معالج المسار، مما يضمن تحقق معلمات الاستعلام.

استخدام Apidog لوثائق واجهة برمجة التطبيقات والاختبار

كما وعدنا، دعونا نتحدث عن Apidog. إنها أداة ممتازة لتوثيق واختبار واجهات برمجة التطبيقات الخاصة بك. مع Apidog، يمكنك إنشاء وثائق واجهة برمجة التطبيقات التفاعلية، واختبار نقاط النهاية الخاصة بك، وضمان أن كل شيء يعمل كما هو متوقع.

إنشاء وثائق واجهة برمجة التطبيقات

لإنشاء وثائق واجهة برمجة التطبيقات لتطبيق Express الخاص بك، يمكنك استخدام Apidog. داخل المشروع، يمكنك إنشاء واجهة برمجة تطبيقات جديدة. الوثائق هي المخطط العام لواجهة برمجة التطبيقات REST، حيث تصف مواردها وعملياتها ومعلماتها. لإنشاء واجهة برمجة تطبيقات جديدة، اضغط على زر "+" في صفحة المشروع.

اختبار واجهة برمجة التطبيقات الخاصة بك باستخدام Apidog

بمجرد إعداد الوثائق الخاصة بك، يمكنك اختبار نقاط النهاية لواجهة برمجة التطبيقات مباشرة من واجهة Apidog. هذا يسهل التحقق من أن معلمات الاستعلام والاستجابات تعمل بشكل صحيح.

املأ طرق HTTP، والنماذج الطلب/الاستجابة، ومعلمات الاستعلام، والعناوين، إلخ.

بعد تطوير جميع واجهات برمجة التطبيقات، يمكنك النقر على زر "إرسال" لاختبار واجهات برمجة التطبيقات الخاصة بك.

أفضل الممارسات للعمل مع معلمات الاستعلام

الآن بعد أن غطينا الأساسيات، دعونا نناقش بعض أفضل الممارسات للعمل مع معلمات الاستعلام في Node.js Express.

تحقق من معلماتك: تحقق دائمًا من صحة معلمات الاستعلام لضمان أمان واجهة برمجة التطبيقات الخاصة بك وموثوقيتها. استخدم middleware للحفاظ على كودك نظيفًا وسهل الصيانة.

استخدام القيم الافتراضية: قدم قيمًا افتراضية لمعلمات الاستعلام الاختيارية لجعل واجهة برمجة التطبيقات الخاصة بك أكثر سهولة في الاستخدام. يمكن أن يساعد ذلك في تجنب الأخطاء وتحسين تجربة المستخدم.

توثيق واجهة برمجة التطبيقات الخاصة بك: استخدم أدوات مثل Apidog لتوثيق نقاط النهاية ومعلمات الاستعلام الخاصة بواجهة برمجة التطبيقات الخاصة بك. هذا يسهل على المطورين الآخرين فهم واستخدام واجهة برمجة التطبيقات الخاصة بك.

التعامل مع الأخطاء بشكل لطيف: أعد رسائل خطأ ذات معنى عندما تكون معلمات الاستعلام مفقوده أو غير صحيحة. يساعد هذا المستخدمين على فهم ما حدث بشكل خاطئ وكيفية إصلاحه.

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

الخاتمة

التعامل مع معلمات الاستعلام في Node.js Express هو مهارة أساسية لأي مطور واجهات برمجة التطبيقات. من خلال اتباع الأمثلة وأفضل الممارسات في هذا الدليل، ستكون مجهزًا جيدًا لبناء واجهات برمجة تطبيقات قوية وسهلة الاستخدام.

وتذكر، Apidog موجودة لجعل رحلة تطوير واجهة برمجة التطبيقات الخاصة بك أكثر سلاسة. قم بتنزيل Apidog مجانًا وابدأ في توثيق واختبار واجهات برمجة التطبيقات الخاصة بك مثل المحترف!