التعامل مع كائن الطلبية req في إطار العمل Express

يُعد الكائن request واختصارًا req جزءًا أساسيًا من الثنائي request وresponse، أي طلب وجواب، إذ يفحص الاستدعاءات من طرف العميل، ويرسل طلبات HTTP، ويتعامل مع البيانات الواردة بشكل سلسلة محرفية أو كائن JSON.

ستتعرف في هذا المقال بالتفصيل على كائن الطلبية req في إطار العمل Express.

ستحتاج في هذا المقال إلى:

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

إدارة البيانات الواردة من العميل

يستقبل إطار العمل Express بيانات من طرف العميل بواسطة الكائن req في ثلاث نسخ Instances هي: req.params وreq.query وreq.body.

يلتقط الكائن req.params البيانات بناءً على المعاملات المحددة في العنوان URL. استخدم الطلب GET مع المعامل userid:/ في ملف index.js كما يلي:

// GET https://example.com/user/1
app.get('/:userid', (req, res) => {
console.log(req.params.userid) // "1"
})

يوجه الكائن req.params إطار العمل Express إلى إظهار نتيجة معرف المستخدم user's id بواسطة المعامل userid:/ المأخوذة من العنوان، فمثلًا طلبية GET للعنوان https://example.com/user/1 تطابق القيمة 1 للمعامل userid وتطبعه في الطرفية Console.

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

أضف الطلب GET مع تحديد الوجهة search/، في ملف index.js كما يلي:

// GET https://example.com/search?keyword=great-white

app.get('/search', (req, res) => {
 console.log(req.query.keyword) // "great-white"
})

يطابق الكائن req.query البيانات التي أرسلها العميل في الرابط على شكل استعلام (بوضع كلمة مفتاحية وقيمة بعد الإشارة ?)، فنجد مثلًا في المثال السابق أن العنوان المرسل بطلبية GET يطابق أولًا المسار search/ ويزودنا بمعلومات (تدعى استعلامات) مرسلة في العنوان نصل إليها عن طريق الكائن query الذي يوفره Express وهي كلمة البحث keyword التي قيمتها great-white في حالة المثال السابق. أي تُظهِر نتيجة إضافة الوسيط keyword. إلى الكائن req.query الرسالة التالية: great-white في طرفية المتصفح.

يُتيح الكائن req.body الوصول إلى البيانات التي أرسلها العميل بشكل سلسة أو كائن JSON، ويُستخدم عادة للحصول على البيانات من طلبي POST و PUT في خادم Express.

استخدم طلب POST مع تحديد الوجهة login/، في ملف index.js كما يلي:

// POST https://example.com/login
//
//   {
//    "email": "user@example.com",
//    "password": "helloworld"
//   }
app.post('/login', (req, res) => {
 console.log(req.body.email) // "user@example.com"
 console.log(req.body.password) // "helloworld"
})

يخزن الكائن req.body معلومات البريد الإلكتروني وكلمة المرور التي يدخلها المستخدم، ويرسلها إلى خادم Express، فيطبع المثال التالي قيمة البريد email وكلمة المرور password التي أرسلها العميل في طلبيته إلى الرابط https://example.com/login (كما نفعل عندما نريد تسجيل الدخول إلى أي موقع).

بعد أن تعلمنا طرق تنفيذ الكائن req، سنتعرف على الأساليب الأخرى لاستخدامه في خادم Express.

فحص العنوان باستخدام خاصيات الكائن req

يمكن لخاصيات الكائن req أن تعرض الأجزاء الأساسية للعنوان URL وفقًا للبنية العامة، ومنها:

protocol: البرتوكول.
hostname: اسم المضيف.
path: مسار العنوان.
originalUrl: العنوان الأساسي.
subdomains: النطاق الفرعي.

أعِد الطلب GET مع تحديد الوجهة creatures/، في ملف index.js كما يلي:

// https://ocean.example.com/creatures?filter=sharks

app.get('/creatures', (req, res) => {
 console.log(req.protocol)   // "https"
 console.log(req.hostname)   // "example.com"
 console.log(req.path)     // "/creatures"
 console.log(req.originalUrl) // "/creatures?filter=sharks"
 console.log(req.subdomains)  // "['ocean']"
})

يمكننا الوصول إلى عدة أجزاء من العنوان URL باستخدام الخاصيات الجاهزة built-in properties مثل خاصية البروتوكول protocol وخاصية اسم المضيف hostname، وتؤدي طباعة الكائن req في الطرفية مع الخاصيات إلى الحصول على بنية العنوان URL.

تحليل الخاصيات الإضافية للكائن req

يحتوي الكائن res على عدة خاصيات توفر مرونة في التعامل مع طلبات HTTP.

استخدم خاصية method. في الكائن req، لمعرفة نوع طلبية HTTP المرسلة أي إن كانت GET أو POST أو PUT أو DELETE، فمثلًا يوضح المثال التالي طلبية DELETE نعرض فيها نوع الطلبية عبر الخاصية req.method والتي ستكون قيمتها بالفعل DELETE:

app.delete('/', (req, res) => {
 console.log(req.method) // "DELETE"
})

استعمل التابع ()header. الذي يوفره الكائن req للحصول على بيانات الترويسات المرسلة إلى خادمك، مثلًا نفذ طلب POST مع تحديد الوجهة login/، في ملف index.js كما يلي:

app.post('/login', (req, res) => {
 req.header('Content-Type') // "application/json"
 req.header('user-agent')  // "Mozilla/5.0 (Macintosh Intel Mac OS X 10_8_5) AppleWebKi..."
 req.header('Authorization') // "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
})

تعرض الدالة ()req.header نوع الترويسة مثل نوع المحتوى Content-Type والاستيثاق Authorization، ووسطاؤها غير حساسة لحالة الأحرف لذلك يمكنك استخدام req.header('Content-Type')‎ أو req.header('content-type')‎ على حد سواء.

إذا أضفت cookie-parser كملف اعتمادية dependency في خادم Express، حينها ستخزن الخاصية req.cookie القيم الموجودة في المحلل parser. أضف الخاصية req.cookie ثم طبق الخاصية sessionDate في ملف index.js كما يلي:

// Cookie sessionDate=2019-05-28T01:49:11.968Z
req.cookies.sessionDate // "2019-05-28T01:49:11.968Z"

لاحظ أنه عند استدعاء الكائن req سيستدعي النتيجة من تاريخ جلسة ملف تعريف الارتباط cookie.

ختاما

تهانينا! لقد تعلمت كيف يزودنا إطار Express بخاصيات مُعّدة مسبقًا لنتمكن من استخدام الكائن req كجزء من ثنائي request-response للتعامل مع طلبات HTTP والبيانات من طرف العميل. انتقل إلى موقع Express الرسمي للاطلاع على التوثيقات الرسمية للكائن req. للحصول على المساعدة والدعم يمكنك إضافة سؤالك في قسم الأسئلة والأجوبة في أكاديمية حسوب.

ترجمة -وبتصرف- للمقال How To Use the req Object in Express لصاحبه William Le.