كيفية التعامل مع معلمات الاستعلام في 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

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

التعامل المتقدم مع معلمات الاستعلام باستخدام الواجهة الوسيطة

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

مثال 4: الواجهة الوسيطة للتحقق من صحة معلمات الاستعلام

أنشئ ملفًا جديدًا يسمى 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() لتمرير التحكم إلى الواجهة الوسيطة التالية أو معالج الطريق إذا كانت التحقق ناجحًا.

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

قم بتحديث ملف 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.

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

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

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

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

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

الخاتمة

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

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