تُستخدم واجهات برمجة التطبيقات APIs على نطاق واسع في شتى المجالات، إذ تتيح للبرمجيات إمكانية التواصل والتكامل مع أنظمة وبرمجيات أخرى، سواء كانت داخلية ضمن نفس النظام أو خارجية. وتكمن إحدى أبرز فوائدها في تسهيل إعادة استخدام المكونات البرمجية، وتوفّر معظم الخدمات الإلكترونية عبر الإنترنت واجهات برمجة تطبيقات تمكّن المطورين من دمج ميزات متنوعة، مثل تسجيل الدخول واستخدام حسابات التواصل الاجتماعي، والدفع بواسطة بطاقات الائتمان، وتتبع سلوك المستخدمين بكل سهولة. ويُعد معيار نقل الحالة التمثيلية Representational State Transfer أو  REST اختصارًا المعيار الأكثر شيوعًا في تصميم هذه الواجهات.

سنشرح في هذا المقال طريقة إنشاء REST API خاصة ببيئة Node.js فلغة جافا سكريبت JavaScript من أكثر لغات البرمجة شيوعًا بين المطورين المحترفين. لذلك سنركز في هذا المقال على إنشاء REST API بسيطة وآمنة، ويمكن بالطبع استخدام أي من المنصات واللغات البرمجية الأخرى لتحقيقها، مثل إطار عمل ASP.NET Core، أو إطار لارافيل Laravel للغة PHP، أو إطار Bottle للغة Python لإنشاء واجهة REST API.

متطلبات العمل

يحتاج فهم وتطبيق هذا المقال لامتلاك الأمور التالية:

• خبرة مسبقة في التعامل مع إطار Node.js
• معرفة بإطار Express.js لأنه معيار أساسي في بناء الواجهة الخلفية للواجهة البرمجية REST API
• معرفة بمكتبة Mongoose لربط الواجهة الخلفية بقاعدة بيانات MongoDB

ملاحظة: لن نتناول في هذا المقال شرح أكواد الواجهة الأمامية، وسنركز على الواجهة الخلفية فقط. ولكن بما أننا سنستخدم لغة JavaScript في تطوير الواجهة الخلفية، فإن هذا يتيح لنا إمكانية مشاركة بعض الأجزاء البرمجية مثل نماذج الكائنات Object Models بين الواجهة الأمامية والخلفية، مما يسهم في توحيد الكود وتقليل التكرار داخل المشروع.

هيكلية REST API

تستخدم واجهات REST APIs من أجل الوصول للبيانات والتحكم بها، وذلك باستخدام مجموعة من العمليات عديمة الحالة stateless بمعنى أن الخادم ينفذ العملية المطلوبة منه ثم ينسى كل شيء عنها بعد الانتهاء منها. وهذه العمليات جزء لا يتجزأ من بروتوكول HTTP المستخدم في نقل البيانات على الويب، وهي تستخدم في تنفيذ الوظائف الأساسية كإنشاء البيانات وقراءتها وتحديثها وحذفها أو ما يعرف باسم عمليات CRUD، على الرغم من عدم تطابقها بدقة تامة معها. وهذه العمليات هي كالتالي:

• POST لإنشاء مورد جديد أو توفير البيانات بشكل عام
• GET للحصول على قائمة موارد أو مورد محدد
• PUT لإنشاء أو استبدال مورد
• PATCH لتحديث أو تعديل مورد
• DELETE لحذف المورد

ملاحظة: ما نعنيه بالمورد resource هنا البيانات التي نتعامل معها عبر واجهة برمجة التطبيقات API ويمكننا الوصول إليها عبر عنوان URL لنقطة الوصول endpoint.

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

والآن، دعونا نبدأ بشرح خطوات بناء REST API آمنة باستخدام Node.js خطوة بخطوة.

بناء REST API آمنة لإدارة المستخدمين باستخدام Node.js

سنبني في هذا المقال REST API آمنة تتميز بكونها شائعة وعملية لإدارة المستخدمين users. سيملك المورد الذي سننشئه هيكلا بسيطا كالآتي:

• id: معرف مستخدم مميز UUID منشأ تلقائيًا
• :firstName: الاسم الأول للمستخدم
• lastName: الاسم الأخير للمستخدم
• email: البريد الإلكتروني للمستخدم
• password: كلمة المرور
• permissionLevel: أذونات المستخدم كأن يكون مستخدم عادي أو مشرف أو لديه أذونات خاصة

ثم سننشئ عمليات لهذا المورد كالآتي:

• POST عند نقطة الوصول ‎/users لإنشاء مستخدم جديد
• GET عند نقطة الوصول ‎/users للحصول على قائمة بكافة المستخدمين
• GET عند نقطة الوصول ‎/users/:userId للحصول على بيانات مستخدم معين
• PATCH عند نقطة الوصول ‎/users/:userId لتحديث بيانات مستخدم معين
• DELETE عند نقطة الوصول ‎/users/:userId لحذف مستخدم معين

سنستخدم رموز JSON Web Tokens -أو JWTs اختصارًا- كوسلية للتحقق من هوية المستخدمين. عند تسجيل الدخول، سيُطلب من المستخدم إدخال بريده الإلكتروني وكلمة مروره، وسيتم إرسال هذه البيانات إلى مورد خاص بالمصادقة يحمل الاسم auth، بعد التحقق من صحة البيانات، يصدر هذا المورد رمز JWT ويُستخدم لاحقًا للوصول إلى بعض العمليات المحمية داخل الواجهة البرمجية. لمعرفة المزيد عن هذا النوع من الرموز، يمكن الرجوع إلى مقال الاستيثاق عبر مفتاح المستخدم المشفر token authentication في تطبيق Node.js و React

إعداد بيئة العمل

بداية، علينا التأكد من تثبيت آخر إصدار من Node.js على جهازنا، يستخدم في هذا المقال الإصدار 14.9.0 لكن يمكنك استخدام إصدار أحدث إذا كان متوفرًا. بعد ذلك يجب التأكد من أن MongoDB مثبت أيضَا على جهازنا، لن نخوض في تفاصيل استخدام Mongoose أو هيكلية MongoDB، لكننا سنعتمد على تشغيل الأساسيات فقط.

لتبسيط العمل، يمكن تشغيل خادم MongoDB في الوضع التفاعلي، أي باستخدام سطر الأوامر مباشرة بدلًا من تشغيله كخدمة تعمل في الخلفية بكتابة الأمر التالي:

mongo

سنحتاج لاحقًا في هذا المقال إلى التفاعل المباشر مع MongoDB من خلال هذا الوضع -دون استخدام كود Node.js- لفهم كيفية التعامل مع البيانات.

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

لا يحتوي هذا المقال على جميع الأكواد اللازمة لاكتمال عمل المشروع، ويمكنك الحصول على الكود كاملًا من هذا المستودع ومتابعة النقاط المهمة أثناء القراءة، كما يمكن نسخ ملفات ومقاطع محددة من المستودع. بعد ذلك سننتقل إلى ملف rest-api-tutorial/ الناتج في الطرفية، نلاحظ أن المشروع يحتوي على ثلاثة مجلدات لوحدات Modules تنظم مختلف أجزاء التطبيق وهي كالتالي:

• common لمعالجة جميع الخدمات المشتركة والمعلومات المتبادلة بين المستخدمين
• users يتضمن كل ما يتعلق بإدارة المستخدمين
• auth لمعالجة رموز JWT وعمليات تسجيل الدخول

بعد ذلك، سنشغل الأمر npm install أو الأمر yarn لتنصيب التبعيات المطلوبة. بمجرد اكتمال عملية التنصيب، سنكون قد أعددنا كل الأمور والتبعيات اللازمة لتشغيل الواجهة الخلفية للواجهة البرمجية REST API باستخدام Node.js.

إنشاء وحدة المستخدم User Module

سنستخدم مكتبة Mongoose مع MongoDB ، وهي مكتبة تساعدنا في التعامل مع بيانات MongoDB بطريقة مبسطة، وذلك من خلال إنشاء مخطط schema يحدد شكل بيانات المستخدم، ثم استخدامه لبناء نموذج model يسمح لنا بإضافة المستخدمين وتعديلهم وحذفهم من قاعدة البيانات.

أولًا، نحتاج لإنشاء مخطط المستخدم User Schema في الملف /users/models/users.model.js كما يلي:

const userSchema = new Schema({
firstName: String,
lastName: String,
email: String,
password: String,
permissionLevel: Number
});

بعد تعريف المخطط يمكننا ربط المخطط بنموذج المستخدم بسهولة كما يلي:

const userModel = mongoose.model('Users', userSchema);

يمكننا بعدها استخدام هذا النموذج لإضافة كل عمليات CRUD التي نحتاجها في نقاط وصول Express.js الخاصة بنا.

لنبدأ بإنشاء مستخدم جديد باستخدام العملية create user عن طريق تعريف وجهة Route‏ في الملف users/routes.config.js:

app.post('/users', [
   UsersController.insert
]);

نقوم بإدراج هذا الجزء من الكود داخل تطبيقنا باستخدام Express.js من خلال الملف الرئيسي index.js، أما كائن UsersController، فنستورده من ملف المتحكم controller المسؤول عن معالجة المستخدمين.

وسنشفر كلمة المرور بالشكل المناسب في الملف /users/controllers/user.controller.js لضمان حفظها بأمان في قاعدة البيانات:

exports.insert = (req, res) => {
   let salt = crypto.randomBytes(16).toString('base64');
   let hash = crypto.createHmac('sha512',salt)
                                    .update(req.body.password)
                                    .digest("base64");
   req.body.password = salt + "$" + hash;
   req.body.permissionLevel = 1;
   UserModel.createUser(req.body)
       .then((result) => {
           res.status(201).send({id: result._id});
       });
};

عند الوصول لهذه النقطة يمكننا اختبار نموذجنا Mongoose عن طريق تشغيل خادم Node.js API باستخدام الأمر npm start وإرسال طلب POST يحتوي على بعض بيانات JSON إلى نقطة الوصول users/:

 {
   "firstName" : "ِِAbd",
   "lastName" : "Hamza",
   "email" : "ِِabd.hamza@example.com",
   "password" : "s3cr3tp4sswo4rd"
}

هنالك العديد من الأدوات التي يمكننا استخدامها لاختبار واجهتنا البرمجية، سنعتمد على الأداة Insomnia، و يمكن أيضًا استخدام Postman أو أي بدائل مفتوحة المصدر مثل أداة cURL أو Bruno كما يمكننا الاكتفاء بكتابة أكواد جافاسكريبت مباشرة، ككتابة الكود التالي في التبويب Console ضمن أدوات المطور Developer Tools للمتصفح:

fetch('http://localhost:3600/users', {
        method: 'POST',
        headers: {
            "Content-type": "application/json"
        },
        body: JSON.stringify({
            "firstName": "Abd",
            "lastName": "Hamza",
            "email": "abd.hamza@example.com",
            "password": "s3cr3tp4sswo4rd"
        })
    })
    .then(function(response) {
        return response.json();
    })
    .then(function(data) {
        console.log('Request succeeded with JSON response', data);
    })
    .catch(function(error) {
        console.log('Request failed', error);
    });

ستحتوي نتيجة طلب POST الناجحة على المعرف id للمستخدم الذي أنشأناه حديثًا:

{ "id": "5b02c5c84817bf28049e58a3" }

سنحتاج أيضا لإضافة التابع createUser إلى النموذج في الملف  users/models/users.model.js:

exports.createUser = (userData) => {
    const user = new User(userData);
    return user.save();
};

الآن علينا التأكد فيما إذا كان المستخدم موجودًا في قاعدة البيانات، لذلك سنضيف ميزة الحصول على اسم المستخدم من خلال المعرّف  id إلى نقطة الوصول users/:userId.

سننشئ أولًا وجهة Route للتطبيق في الملف /users/routes/config.js:

app.get('/users/:userId', [
    UsersController.getById
]);

ثم سننشئ وحدة تحكم في الملف /users/controllers/users.controller.js:

exports.getById = (req, res) => {
   UserModel.findById(req.params.userId).then((result) => {
       res.status(200).send(result);
   });
};

وأخيرا نضيف التابع findById إلى النموذج في الملف /users/models/users.model.js:

exports.findById = (id) => {
    return User.findById(id).then((result) => {
        result = result.toJSON();
        delete result._id;
        delete result.__v;
        return result;
    });
};

يجب أن نحصل على استجابة كما يلي:

{
   "firstName": "Abd",
   "lastName": "Hamza",
   "email": "abd.hamza@example.com",
   "password": "Y+XZEaR7J8xAQCc37nf1rw==$p8b5ykUx6xpC6k8MryDaRmXDxncLumU9mEVabyLdpotO66Qjh0igVOVerdqAh+CUQ4n/E0z48mp8SDTpX2ivuQ==",
   "permissionLevel": 1,
   "id": "5b02c5c84817bf28049e58a3"
}

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

يمكننا الآن إضافة الوظيفة اللازمة لتحديث بيانات المستخدم مثل الاسم أو البريد الإلكتروني أو كلمة المرور بنفس الطريقة التي استخدمناها سابقًا. سنستخدم هنا عملية PATCH لأنها تسمح لنا بإرسال الحقول المرغوب بتعديلها فقط، ولذلك ستكون ال وجهة Route هو العملية PATCH لنقطة الوصول
/users/:userid وسنرسل أي حقول نريد تعديلها في جسم الطلب.

سنحتاج أيضًا لإضافة بعض التحققات الإضافية لأن التعديل يجب أن يقتصر على المستخدم المسؤول admin، ولا يجب أن يتمكن أحد غير المسؤول من التعديل على الحقل permisionLevel. ولكننا سنتخطى هذا الأمر حاليًا ونعود له عندما نضيف وحدة المصادقة auth. يجب أن يبدو المتحكم controller الخاص بنا الآن كما يلي:

exports.patchById = (req, res) => {
   if (req.body.password){
       let salt = crypto.randomBytes(16).toString('base64');
       let hash = crypto.createHmac('sha512', salt).update(req.body.password).digest("base64");
       req.body.password = salt + "$" + hash;
   }
   UserModel.patchUser(req.params.userId, req.body).then((result) => {
           res.status(204).send({});
   });
};

ترسل هذه الخطوة استجابة برمز الحالة HTTP 204 الذي يشير لنجاح تنفيذ الطلب، ولكن دون إرجاع أي بيانات أو محتوى في جسم الاستجابة.

سنحتاج أيضا لإضافة التابع patchUser للنموذج model لتحديث بيانات المستخدم:

exports.patchUser = (id, userData) => {
    return User.findOneAndUpdate({
        _id: id
    }, userData);
};

يحقق المتحكم controller التالي عملية GET لعرض قائمة المستخدمين عند نقطة الوصول/users/ مع تطبيق آلية التصفية باستخدام الصفحات والحد الأقصى للعناصر المعروضة:

exports.list = (req, res) => {
   let limit = req.query.limit && req.query.limit <= 100 ? parseInt(req.query.limit) : 10;
   let page = 0;
   if (req.query) {
       if (req.query.page) {
           req.query.page = parseInt(req.query.page);
           page = Number.isInteger(req.query.page) ? req.query.page : 0;
       }
   }
   UserModel.list(limit, page).then((result) => {
       res.status(200).send(result);
   })
};

سيكون تابع النموذج المقابل كالآتي:

exports.list = (perPage, page) => {
    return new Promise((resolve, reject) => {
        User.find()
            .limit(perPage)
            .skip(perPage * page)
            .exec(function (err, users) {
                if (err) {
                    reject(err);
                } else {
                    resolve(users);
                }
            })
    });
};

وستكون للاستجابة الناتجة البنية التالية:

[
   {
       "firstName": "Maher",
       "lastName": "Saleh",
       "email": "maher.saleh@example.com",
       "password": "z4tS/DtiH+0Gb4J6QN1K3w==$al6sGxKBKqxRQkDmhnhQpEB6+DQgDRH2qr47BZcqLm4/fphZ7+a9U+HhxsNaSnGB2l05Oem/BLIOkbtOuw1tXA==",
       "permissionLevel": 1,
       "id": "5b02c5c84817bf28049e58a3"
   },
   {
       "firstName": "Abd",
       "lastName": "Hamza",
       "email": "abd.hamza@example.com",
       "password": "wTsqO1kHuVisfDIcgl5YmQ==$cw7RntNrNBNw3MO2qLbx959xDvvrDu4xjpYfYgYMxRVDcxUUEgulTlNSBJjiDtJ1C85YimkMlYruU59rx2zbCw==",
       "permissionLevel": 1,
       "id": "5b02d038b653603d1ca69729"
   }
]

وأخيرا سنضيف عملية DELETE لحذف المستخدم بناء على المعرف الخاص به عند نقطة الوصول /users/:userId.

سننشئ المتحكم controller المسؤول عن الحذف كالآتي:

exports.removeById = (req, res) => {
   UserModel.removeById(req.params.userId)
       .then((result)=>{
           res.status(204).send({});
       });
};

كما في السابق، سيرسل المتحكم استجابة بالحالة HTTP 204 الذي يشير لنجاح الطلب. ويكون تابع النموذج model method المقابل كالآتي:

exports.removeById = (userId) => {
    return new Promise((resolve, reject) => {
        User.deleteMany({_id: userId}, (err) => {
            if (err) {
                reject(err);
            } else {
                resolve(err);
            }
        });
    });
};

أصبحنا الآن نملك جميع العمليات اللازمة للتحكم ببيانات المستخدم.

إنشاء وحدة المصادقة Auth

قبل أن نتمكن من تأمين وحدة المستخدمين users عن طريق إضافة الأذونات والبرامج الوسيطة للتحقق، نحتاج أولًا إلى طريقة تمكننا من توليد رمز مميز JWT صالح للمستخدم الحالي. سيُستخدم هذا الرمز لإثبات هوية المستخدم في الطلبات المستقبلية دون الحاجة لإجراء التحقق في كل مرة. يملك هذا الرمز عادة وقت انتهاء صلاحية ويُنشَأ رمز جديد كل عدة دقائق للحفاظ على تواصل آمن، ولكن في هذا المقال سنتخطى إعادة إنشاء الرمز كل مرة ونكتفي برمز واحد كل تسجيل دخول لتبسيط العمل.

سننشئ بداية نقطة وصول تستقبل طلبات POST إلى المورد  auth/. يجب أن يحتوي جسم الطلب على البريد الإلكتروني وكلمة المرور الخاصة بالمستخدم على النحو التالي:

{
   "email" : "abd.hamza@example.com",
   "password" : "s3cr3tp4sswo4rd2"
}

قبل أن نسمح للطلب بالوصول للمتحكم والتفاعل معه يجب التحقق من أن المستخدم موجود وكلمة مروره صحيحة عن طريق كود يكتب في الملف
/authorization/middlewares/verify.user.middleware.js:

exports.isPasswordAndUserMatch = (req, res, next) => {
   UserModel.findByEmail(req.body.email)
       .then((user)=>{
           if(!user[0]){
               res.status(404).send({});
           }else{
               let passwordFields = user[0].password.split('$');
               let salt = passwordFields[0];
               let hash = crypto.createHmac('sha512', salt)
                                .update(req.body.password)
                                .digest("base64");
               if (hash === passwordFields[1]) {
                   req.body = {
                       userId: user[0]._id,
                       email: user[0].email,
                       permissionLevel: user[0].permissionLevel,
                       provider: 'email',
                       name: user[0].firstName + ' ' + user[0].lastName,
                   };
                   return next();
               } else {
                   return res.status(400).send({errors: ['Invalid email or password']});
               }
           }
       });
};

بعد القيام بذلك، يمكننا الانتقال إلى المتحكم controller وتوليد رمز JWT:

exports.login = (req, res) => {
   try {
       let refreshId = req.body.userId + jwtSecret;
       let salt = crypto.randomBytes(16).toString('base64');
       let hash = crypto.createHmac('sha512', salt).update(refreshId).digest("base64");
       req.body.refreshKey = salt;
       let token = jwt.sign(req.body, jwtSecret);
       let b = Buffer.from(hash);
       let refresh_token = b.toString('base64');
       res.status(201).send({accessToken: token, refreshToken: refresh_token});
   } catch (err) {
       res.status(500).send({errors: err});
   }
};

رغم أننا في هذا المقال لن نعيد إنشاء الرمز المميز JWT بشكل متكرر، إلا أن المتحكم Controller مُصمم ليكون قادرًا على توليد هذه الرموز عند الحاجة. يُعد JWT جزءًا أساسيًا من عملية التحقق من هوية المستخدم، لذلك تم تضمين وظيفة توليد الرمز في المتحكم لتسهيل استخدامها مستقبلًا، سواء في هذا المشروع أو في مشاريع قادمة.

كل ما نحتاجه هو إنشاء وجهة واستدعاء البرمجية الوسيطة Middleware المناسبة في الملف /authorization/routes.config.js على النحو التالي:

  app.post('/auth', [
        VerifyUserMiddleware.hasAuthValidFields,
        VerifyUserMiddleware.isPasswordAndUserMatch,
        AuthorizationController.login
    ]);

ستحتوي الاستجابة الناتجة على رمز JWT المولد في الحقل accessToken:

{
   "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI1YjAyYzVjODQ4MTdiZjI4MDQ5ZTU4YTMiLCJlbWFpbCI6Im1hcmNvcy5oZW5yaXF1ZUB0b3B0YWwuY29tIiwicGVybWlzc2lvbkxldmVsIjoxLCJwcm92aWRlciI6ImVtYWlsIiwibmFtZSI6Ik1hcmNvIFNpbHZhIiwicmVmcmVzaF9rZXkiOiJiclhZUHFsbUlBcE1PakZIRG1FeENRPT0iLCJpYXQiOjE1MjY5MjMzMDl9.mmNg-i44VQlUEWP3YIAYXVO-74803v1mu-y9QPUQ5VY",
   "refreshToken": "U3BDQXBWS3kyaHNDaGJNanlJTlFkSXhLMmFHMzA2NzRsUy9Sd2J0YVNDTmUva0pIQ0NwbTJqOU5YZHgxeE12NXVlOUhnMzBWMGNyWmdOTUhSaTdyOGc9PQ=="
}

بعد إنشاء الرمز، يمكننا استخدامه داخل ترويسة Authorization باستخدام صيغة Bearer ACCESS_TOKEN

إنشاء برمجيات وسيطة لعمليات التحقق Validations والأذونات Permissions

أول ما يجب علينا فعله هو تحديد من يستطيع استخدام المورد users. وفيما يلي السيناريوهات التي علينا التعامل معها:

• التسجيل أو إنشاء مستخدم جديد: متاح للجميع، ولا يتطلب استخدام رموز JWT
• تحديث بيانات مستخدم: مسموح فقط للمستخدم الذي قام بتسجيل الدخول أو للمسؤولين
• حذف حساب مستخدم: مخصص للمسؤولين فقط

بعد تحديد السيناريوهات المحتملة لكيفية تصميم مستويات مختلفة من الوصول بناءً على الأدوار ومتطلبات الأمان في التطبيق، سنحتاج أولًا إلى برمجية وسيطة Middleware تتحقق فيما إذا كان المستخدم يملك رمز JWT صالح. قد تكون عبارة عن برمجية وسيطة بسيطة ضمن الملف 
/common/middlewares/auth.validation.middleware.js كما يلي:

exports.validJWTNeeded = (req, res, next) => {
    if (req.headers['authorization']) {
        try {
            let authorization = req.headers['authorization'].split(' ');
            if (authorization[0] !== 'Bearer') {
                return res.status(401).send();
            } else {
                req.jwt = jwt.verify(authorization[1], secret);
                return next();
            }
        } catch (err) {
            return res.status(403).send();
        }
    } else {
        return res.status(401).send();
    }
}; 

سنستخدم رموز الحالة الخاصة ببروتوكول HTTP للتعامل مع الأخطاء التي قد تحدث أثناء معالجة الطلبات، وذلك على النحو التالي:

• رمز 401 Unauthorized: يُستخدم عندما يكون الطلب غير مصحوب برمز JWT صالح، أو عندما لا يتم إرسال أي رمز على الإطلاق
• رمز 403 Forbidden: يُستخدم عندما يكون الرمز المرسل صالحًا، لكن المستخدم لا يملك الصلاحيات الكافية لتنفيذ هذا الطلب

يمكننا استخدام العملية المنطقية AND أو ما يُعرف بـ قناع البِت Bitmasking، حيث نعتبر كل بت في عدد مكوّن من 32 بت كإذن منفصل. وكل إذن يُمثَّل كقوة للعدد 2. على سبيل المثال، يمكن للمسؤول أن يمتلك جميع الأذونات عن طريق تعيين الرقم 2147483647، مما يعني أن جميع الأذونات مفعّلة. من جهة أخرى، يمكننا تعيين قيمة 7 للأذونات، مما يعني تفعيل الأذونات الموجودة في البتات التي تحمل القيم 1 و 2 و 4، أو ما يعادل القوى 0 و 1 و 2 للعدد 2.

وفيما يلي مثال على كيفية استخدام ذلك في برمجية وسيطة Middleware:

exports.minimumPermissionLevelRequired = (required_permission_level) => {
   return (req, res, next) => {
       let user_permission_level = parseInt(req.jwt.permission_level);
       let user_id = req.jwt.user_id;
       if (user_permission_level & required_permission_level) {
           return next();
       } else {
           return res.status(403).send();
       }
   };
};

تتحقق هذه البرمجية الوسيطة مما إذا كان مستوى أذونات المستخدم يتطابق مع المستوى المطلوب باستخدام العملية AND. إذا كانت النتيجة أكبر من الصفر -أي أن المستخدم يملك الإذن المطلوب- يُسمَح للعملية بالاستمرار عبر الدالة next أما إذا كانت النتيجة صفرًا، فهذا يعني أن المستخدم ليس لديه الأذونات الكافية، وبالتالي ترجع الرمز HTTP 403.

الآن، نحتاج إلى إضافة البرمجية الوسيطة الخاصة بالاستيثاق في وجهة وحدة المستخدم الموجودة في الملف
/users/routes.config.js، بحيث نضيف التحقق من صلاحيات المستخدم قبل السماح له بالوصول إلى العمليات المختلفة:

app.post('/users', [
   UsersController.insert
]);
app.get('/users', [
   ValidationMiddleware.validJWTNeeded,
   PermissionMiddleware.minimumPermissionLevelRequired(PAID),
   UsersController.list
]);
app.get('/users/:userId', [
   ValidationMiddleware.validJWTNeeded,
   PermissionMiddleware.minimumPermissionLevelRequired(FREE),
   PermissionMiddleware.onlySameUserOrAdminCanDoThisAction,
   UsersController.getById
]);
app.patch('/users/:userId', [
   ValidationMiddleware.validJWTNeeded,
   PermissionMiddleware.minimumPermissionLevelRequired(FREE),
   PermissionMiddleware.onlySameUserOrAdminCanDoThisAction,
   UsersController.patchById
]);
app.delete('/users/:userId', [
   ValidationMiddleware.validJWTNeeded,
   PermissionMiddleware.minimumPermissionLevelRequired(ADMIN),
   UsersController.removeById
]);

هكذا نكون أكملنا التطوير الأساسي لواجهة REST API باستخدام Node.js وكل ما يتبقى هو اختبارها للتأكد من خلوها من الأخطاء.

تشغيل واختبار الواجهة البرمجية باستخدام Insomnia

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

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

بعد نجاح الطلب، سنحفظ المعرّف الذي أنشأته لنا الواجهة البرمجية لهذا المستخدم، لاستخدامه لاحقًا في عمليات لاحقة مثل التحديث أو الحذف.

يمكننا الآن توليد رمز JWT باستخدام نقطة الوصول /auth/:

يجب أن نحصل بنتيجة الطلب على رمز وصول Token كما يلي:

الآن، سننسخ هذا الرمز ونضيف قبله كلمة Bearer، مع التأكد من ترك فراغ بين الكلمتين. وسنضيف هذا الرمز لكافة ترويسات الطلب Request Headers ضمن الحقل Authorization.

تعرض الصورة التالية استجابة الواجهة البرمجية API عند طلب بيانات مستخدم معين من نقطة الوصول /users/:userId بعد إضافة البرمجية الوسيطة للتحقق من الصلاحيات Permissions Middleware، مع وجود رمز مصادقة صالح Valid Token.

كما ذكرنا سابقًا نعرض هنا كلمة المرور لتبسيط الشرح، ولكن لا ننسى أنه لا يجب نهائيًا عرض كلمة المرور في الاستجابات، سواءً كانت مشفرة أم لم تكن.

لنحاول الآن الحصول على قائمة بجميع المستخدمين بإرسال الطلب GET على النحو التالي:

سنتفاجأ بالحصول على استجابة برمز الخطأ 403:

السبب وراء عدم القدرة على الوصول إلى هذه النقطة هو أن مستوى الصلاحيات الحالي للمستخدم هو permissionLevel=1 وهذا لا يمنحه الإذن الكافي للوصول إلى البيانات المطلوبة، لذلك يجب تحديث الصلاحيات permissionLevel لهذا المستخدم من القيمة 1 للقيمة 7، أو ربما للقيمة 5 فهي كافية للوصول إلى نقطة الوصول الحالية.

يمكننا القيام بهذا التحديث عبر واجهة MongoDB التفاعلية يدويًا، مع تعديل المعرف ليتناسب مع المستخدم الحالي لدينا كما يلي:

db.users.update({"_id" : ObjectId("5b02c5c84817bf28049e58a3")},{$set:{"permissionLevel":5}})

سنحتاج بعد ذلك لتوليد رمز JWT جديد. وبعدها سنحصل على استجابة صحيحة للطلب GET:

سنختبر الآن وظيفة تحديث بيانات المستخدم عبر إرسال طلب POST مع بعض الحقول إلى نقطة الوصول /users/:userId:

نتوقع الحصول على استجابة بالرمز 204 للتأكد بأن العملية نجحت، ولكن يمكننا التأكد عبر طلب معلومات المستخدم مجددًا.

وأخيرا سنحتاج لاختبار حذف المستخدم، للقيام بهذا يجب علينا إنشاء مستخدم جديد، مع عدم نسيان الاحتفاظ برمز المعرف الخاص بالمستخدم والتأكد من امتلاكنا لرمز JWT مناسب لمستخدم مسؤول. يجب علينا تعيين الرقم 2053 إلى userPermission الخاص بالمستخدم الجديد والذي يساوي الرقم 2048، أي ADMIN، بالإضافة إلى الرقم 5 الذي عيناه سابقًا ليتمكن من تنفيذ عملية حذف المستخدم بعد الانتهاء من ذلك وتوليد رمز JWT جديد، يجب علينا تحديث ترويسة طلب Authorization الذي أضفناه سابقًا:

بعد إرسال طلب DELETE لنقطة الوصول /users/:userId يفترض أن نحصل على استجابة برمز الحالة 204 لتأكيد نجاح العملية. ويمكننا التأكد مجددا عبر إرسال طلب /users/ لجميع المستخدمين الموجودين من خادم Node API الخاص بنا.

الخاتمة

تعلمنا في هذا المقال أهم الخطوات اللازمة لإنشاء واجهة برمجة تطبيقات REST API بسيطة وآمنة باستخدام Node.js باستخدام مجموعة من الأدوات والتقنيات، ويجب الانتباه إلى أننا تخطينا هنا اتباع أفضل الممارسات للسهولة ويجب الانتباه للأمور التالية عند تطوير واجهة برمجية فعلية:

• إضافة تحققات صحيحة وشاملة، كالتأكد من كون البريد الإلكتروني فريد لكل مستخدم
• إضافة اختبار الوحدة unit testing وتقارير للأخطاء
• منع المستخدمين من تغيير مستوى الصلاحيات الخاص بهم
• منع المسؤولين من حذف أنفسهم
• منع الكشف عن المعلومات الحساسة، ككلمات المرور المشفرة على سبيل المثال
• نقل رمز JWT من ملف common/config/env.config.js إلى نظام مخصص لتوزيع الرموز السرية خارج الكود البرمجي، بحيث لا يعتمد على البيئة المحلية

ترجمة -وبتصرف- لمقال Creating a Secure REST API in Node.js لصاحبه Marcos Henrique da Silva.

اقرأ أيضًا

• اللاتزامن والانتظار async/await في جافاسكربت
• تعرف على وحدات Node.js الأساسية
• مدخل إلى الواجهات البرمجية API
• شرح فلسفة RESTful - تعلم كيف تبني واجهات REST البرمجية
• مدخل إلى Node.js وExpress

GraphQL لغة استعلام مفتوحة المصدر لواجهات برمجة التطبيقات API وبيئة تشغيل لتنفيذ الاستعلامات، وأُنشِئَت في الأساس لمعالجة مشكلات REST التقليدية وقد عرضنا بعضًا منها، وسنطّلع في هذا المقال على آلية تفاعل مكونات GraphQL مع بعضها، عبر بناء خادم GraphQL API في بيئة Node.js، وسيُستخدم خادم Express API بدلًا من Apollo GraphQL رغم أنه الأشهر بين تطبيقات GraphQL.

ستتعلم خلال متابعتك لخطوات العمل إنشاء مخطط GraphQL متوافق مع نظام الأنواع بما فيه من عمليات، مثل الاستعلامات والطفرات ومحللات الاستجابة، وستتآلف مع بيئة التطوير المتكاملة GraphiQL، إذ سنستعملها لاستعراض المخطط وتصحيح أخطائه، ولطلب استعلامات العميل من واجهة GraphQL.

متطلبات العمل

جهّز المتطلبات التالية لتتابع معنا سير العمل:

• بيئة Node.js جاهزة على خادمك المحلي، ويمكنك الاسترشاد بأحد المقالين تثبيت Node.js على نظام أبونتو 18.04 أو كيفية تثبيت Node.js على Debian 8 لإعدادها.
• فهم أساسيات GraphQL.
• الإلمام ببروتوكول HTTP، ننصحك بقراءة مدخل إلى HTTP.
• معرفة أساسية بكل من HTML و JavaScript، تفيدك هذه المقالات أساسيات إنشاء موقع ويب باستخدام تعليمات HTML، وأساسيات لغة جافاسكربت.

إعداد خادم Express HTTP

يبدأ إعداد خادم Express بتثبيت الحزمتين express و cors، باستخدام الأمر npm install ضمن مشروع جديد وفق التالي:

npm install express cors

Express هو إطار لتطبيقات الويب المبنية على Node.js، وهو مصمم خصيصًا لبناء واجهات برمجة التطبيقات، وسيكون إطار العمل الخاص بخادمنا، أما الحزمة CORS وهي اختصار لمصطلح البرمجيات الوسيطة لمشاركة الموارد ذات الأصل المختلط Cross-Origin Resource Sharing، إذ إن الغاية منها هي السماح لمتصفحك بالوصول إلى موارد الخادم.

ثبّت أيضًا الاعتمادية Nodemon مع الراية D بصفتها اعتمادية تطوير، لتستخدمها في مرحلة التطوير فقط:

npm install -D nodemon

Nodemon هي أداة مساعدة في تطوير تطبيقات Node، تعيد تشغيل التطبيق في كل مرة يطرأ فيها تغيير على ملفات المشروع الموجودة في مجلد الجذر لتأخذ التعديلات مفعولها.

سينشأ بتثبيت هذه الحزم المجلد node_modules والملف package.json مع اعتماديتي إنتاج واعتمادية تطوير.

إذا فتحت الملف package.json بمحرر نصوص مثل نانو nano ستجده يحتوي المعلومات التالية:

{
  "dependencies": {
    "cors": "^2.8.5",
    "express": "^4.17.3"
  },
  "devDependencies": {
    "nodemon": "^2.0.15"
  }
}

عدّل عليه ليصبح وفق التالي:

{
  "main": "server.js",
  "scripts": {
    "dev": "nodemon server.js"
  },
  "dependencies": {
    "cors": "^2.8.5",
    "express": "^4.17.3"
  },
  "devDependencies": {
    "nodemon": "^2.0.15"
  },
  "type": "module"
}

لنشرح التعديلات السابقة، إذ وضعنا ملف الخادم "server.js" -الذي سننشئه بعد قليل- في الحقل main، وبهذا تتأكد من تشغيل npm start للخادم؛ أما الملف النصي المسمى "dev"، فيُسهل التطوير إذ يتضمن أمر تشغيل nodemon server.js.

أضفنا في السطر الأخير القيمة module لحقل النوع type لنُفعّل إمكانية استخدام تعليمة الاستيراد import عوضًا عن require -تعليمة CommonJS الافتراضية- وفي هذا أيضًا تسهيلٌ للعمل.

احفظ التغييرات، وأغلق الملف، لننتقل لإنشاء ملف الخادم.

سنبني الآن خادم Express بسيط عبر إنشاء ملف نصي باسم "server.js"، يتضمن التعليمات المبينة أدناه، يعمل هذا الخادم على المنفذ 4000، وتظهر في صفحته الأولى عبارة الترحيب !Hello, GraphQL:

import express from 'express'
import cors from 'cors'

const app = express()
const port = 4000

app.use(cors())
app.use(express.json())
app.use(express.urlencoded({ extended: true }))

app.get('/', (request, response) => {
  response.send('Hello, GraphQL!')
})

app.listen(port, () => {
  console.log(`Running a server at http://localhost:${port}`)
})

لاحظ أن الملف يبدأ بتعليمة استيراد الدالة express، ثم بعض الإعدادات الخاصة بكل من CORS و JSON، وبعدها استعملنا ('/')app.get لتحديد ما ينبغي إرساله إلى الجذر / ضمن طلبات GET، وفي نهاية الملف استخدمنا ()app.listen لتحديد منفذ خادم API.

احفظ الآن التغيرات، وأغلق الملف، ثم نفذ الأمر التالي لتشغيل خادم Node:

npm run dev

تأكد -قبل الانتقال للخطوات التالية- من سلامة تشغيل الخادم بظهور صفحة الترحيب !Hello, GraphQL عند فتح الرابط "http://localhost:4000" من المتصفح أو تشغيل الأمر:

curl http://localhost:4000

إعداد البرمجية الوسيطة لخادم GraphQL HTTP

يوجد ثلاث خطوات أساسية لتحقيق التكامل بين مخطط GraphQL مع خادم إكسبريس، وتتلخص في إعداد الاتصال مع مخزن البيانات، وتعريف المخطط، وتعريف محللات الاستجابة.

ستحتاج في البداية لتنفيذ الأمر التالي:

npm install graphql@14 express-graphql @graphql-tools/schema

الذي يثبت الحزم الضرورية للعمل مع GraphQL، وهي:

• graphql: الحزمة المرجعية التي تستخدمها لغة جافا سكربت لجعل التعامل مع GraphQL متاحًا في اللغة.
• express-graphql: البرمجية الوسيطة لخادم HTTP للتعامل مع GraphQL.
• graphql-tools/schema@: مجموعة أدوات تُسرّع تطوير GraphQL.

ضِف تعليمات استيراد هذه الحزم إلى الملف "server.js"، لتصبح بدايته على النحو التالي:

import express from 'express'
import cors from 'cors'
import { graphqlHTTP } from 'express-graphql'
import { makeExecutableSchema } from '@graphql-tools/schema'

...

لننجز الآن إعدادات الاتصال مع مخزن البيانات قبل إنشاء مخطط GraphQL القابل للتنفيذ.

أنشئ الكائن data بإضافة التعليمات الخاصة به إلى الملف "server.js" مباشرةً بعد تعليمات الاستيراد كما هو مبين أدناه، إذ يمثل هذا الكائن مخزنًا للبيانات في الذاكرة in-memory store، ويحتوي مجموعة بيانات بسيطة لنستعلم عنها من خادم GraphQL. نخفف بهذه الطريقة عبء إنشاء قاعدة بيانات حقيقية والاتصال معها كوننا نجهز بيئة تعليمة بسيطة.

import express from 'express'
import cors from 'cors'
import { graphqlHTTP } from 'express-graphql'
import { makeExecutableSchema } from '@graphql-tools/schema'

const data = {
  warriors: [
    { id: '001', name: 'Jaime' },
    { id: '002', name: 'Jorah' },
  ],
}

…

تمثّل هيكلة البيانات جدولًا بسيطًا يدعى warriors، الذي يحتوي سطرين 'Jaime' و 'Jorah' لبيانات اثنين من محاربي لعبة افتراضية سنستخدمها في مثالنا.

ملاحظة: لا يغطي هذا المقال حالة اتصال خادم GraphQL بقاعدة بيانات حقيقية، وعادةً ما يستخدم خادم GraphQL دوال الاختزال reducers للوصول إلى قواعد البيانات والتعديل عليها، ويعتمد تقنياتٍ مثل Prisma، وهي أداة ربط العلاقات بالكائنات ORM، أما إعدادات الاتصال مع قاعدة البيانات فيحملها المعامل context أحد معاملات محللات الاستجابة غير المتزامنة. سيمثل المتغير data إعدادات اتصالنا مع مخزن البيانات حتى نهاية هذا المقال.

الآن، بعد تثبيت الحزم المطلوبة، وتجهيز بعض البيانات للاستعلام، يمكننا إنشاء المخطط الذي يُعرّف واجهة API، ويصف ماهية البيانات الممكن الاستعلام عنها.

مخطط GraphQL

سننشئ مخططًا أوليًّا لواجهة API يتضمن الحد الأدنى من التعليمات البرمجية التي تسمح لنا بالاتصال مع نقطة الوصول GraphQL Endpoint. سنفترض في هذا المثال أننا نستعلم عن بيانات لعبة مغامرات فيها أدوار لشخصيات مختلفة، مثل المحاربين والسحرة والمعالجين وغيرهم، لذا سنحرص عند إنشاء المخطط أن يكون مرنًا وقابلًا لإعادة الاستخدام، لتستطيع تكراره مع أي نوع من شخصيات اللعبة وتوسعته ليشمل متغيرات أخرى تخصهم مثل الأسلحة والتعويذات.

تستند مخططات GraphQL إلى نظام الأنواع، ويمكنك دائمًا إنشاء أنواعك الخاصة إذا لم تلبِ الأنواع الافتراضية المُضمّنة في النظام حاجتك، وهذا ما سنفعله هنا إذ سننشئ نوعًا type يدعى المحارب warrior له حقلين id و name.

type Warrior {
  id: ID!
  name: String!
}

الحقل id نوعه ID رقم تعريفي، والحقل name نوعه سلسلة نصية String، وكلاهما من الأنواع الأولية المُضمّنة في نظام الأنواع، والأنواع الأولية تستخدم لإنشاء أنواع أعقد مثل الكائنات، أما إشارة التعجب ! الواردة في التعليمات أعلاه فتشير لكون الحقل بجانبها لا يقبل قيمة فارغة "Null"، فلا يجب أن يكون فارغًا بأية حال.

الآن بعد إنشاء نوع المحارب، سننشئ نوع الاستعلام Query، وهو نقطة الدخول entry point إلى استعلام GraphQL. ألقِ نظرةً على التعليمات المبينة أدناه، إذ يُعرّف هذا النوع المحاربين warriors على أنهم مصفوفة من البيانات التابعة لنوع المحارب Warrior.

type Query {
  warriors: [Warrior]
}

أصبح مخططنا جاهزًا للاستخدام مع البرمجية الوسيطة GraphQL HTTP، لذا سنمرره للدالة makeExecutableSchema، إحدى أدوات graphql-tools، بصفته typeDefs ليصبح قابلًا للتنفيذ. للدالة makeExecutableSchema معاملان أحدهما للمخطط والآخر لمحللات الاستجابة، وينبغي تعريفها قبل تنفيذ الدالة:

• typeDefs: لغة مخطط GraphQL، وهي سلسلة نصية.
• resolvers: محللات الاستجابة، وهي الدوال التي تُستدعى لتنفيذ حقل معين وإرجاع قيمة.

اكتب تعليمات تعريف typeDefs ضمن الملف "server.js" تمامًا بعد تعليمات استيراد الاعتماديات، وأسند له قيمة نصية هي مخطط GraphQL، وفق التالي:

...

const data = {
  warriors: [
    { id: '001', name: 'Jaime' },
    { id: '002', name: 'Jorah' },
  ],
}

const typeDefs = `
type Warrior {
  id: ID!
  name: String!
}

type Query {
  warriors: [Warrior]
}
`

...

إذًا، فقد جهزّنا إلى الآن البيانات التي سنستعلم عنها data، وعرّفنا المخطط ضمن typeDefs، وسنعرّف في الخطوة التالية محللات الاستجابة، التي ستحدد طريقة استجابة خادمنا للطلبات الواردة.

محللات الاستجابة

محللات الاستجابة Resolvers هي مجموعة من الدوال البرمجية التي توّلد استجابة خادم GraphQL، ولكل محلل استجابة أربعة معاملات:

• obj: الكائن الأب، غير ضروري في حالتنا لأن الكائن المستخدم لدينا وحيد وهو الأب أو الجذر.
• args: تمرر هنا أي متغيرات وسيطة يحتاجها GraphQL.
• context: حقل مشترك بين جميع محللات الاستجابة، ويُخصص غالبًا لمعلومات الاتصال مع قاعدة البيانات.
• info: معلومات إضافية.

سننشئ الآن محلل استجابة لاستعلام الجذر Query، يُرجع لطالب الاستعلام معلوماتٍ عن المحاربين warriors، وسنمرّر له مخزن البيانات في الذاكرة الذي عرّفناه سابقًا.

ضِف ما يلي إلى الملف "server.js":

...

const typeDefs = `
type Warrior {
  id: ID!
  name: String!
}

type Query {
  warriors: [Warrior]
}
`

const resolvers = {
  Query: {
    warriors: (obj, args, context, info) => context.warriors,
  },
}

...

أنشأنا بهذه التعليمات دالة محلل استجابة تدعى warriors، ترتبط بالاستعلام Query وهو نقطة دخولنا إلى خادم GraphQL، ومهمة هذه الدالة هي إرجاع بيانات المحاربين من جدول المحاربين warriors الموجود في قاعدة البيانات التي يشير إليها المعامل context، وهي في حالتنا مخزن البيانات البسيط data.

إذًا، فلكل دالة محلل استجابة أربعة معاملات: obj و args و info، إضافةً إلى context، الذي كان أكثرها ارتباطًا بمخططنا، وهذا المعامل مشترك بين جميع محللات الاستجابة، ويشير غالبًا إلى إعدادات الاتصال بين خادم GraphQL وقاعدة البيانات.

الآن، بعد أن عرّفنا typeDefs و resolvers معاملات الدالة makeExecutableSchema، يمكننا تحويل المخطط إلى مخطط قابل للتنفيذ بكتابة الأوامر التالية في الملف "server.js":

...

const resolvers = {
  Query: {
    warriors: (obj, args, context, info) => context.warriors,
  },
}

const executableSchema = makeExecutableSchema({
  typeDefs,
  resolvers,
})

...

تنشئ الدالة makeExecutableSchema مخططًا كاملًا يمكنك تمريره إلى نقطة وصل GraphQL.

لنستبدل نقطة الوصل الحالية أي عبارة الترحيب !Hello, GraphQL بنقطة الوصول graphql/ عبر كتابة التعليمات التالية:

...

const executableSchema = makeExecutableSchema({
  typeDefs,
  resolvers,
})

app.use(
  '/graphql',
  graphqlHTTP({
    schema: executableSchema,
    context: data,
    graphiql: true,
  })
)

...

يتطلب استخدام البرمجية الوسيطة graphqlHTTP مخططًا أنشأناه وسياقًا يمثّل معلومات الاتصال مع مخزن البيانات، وينص الاتفاق على استخدام خادم GraphQL نقطة الوصول graphql/.

إليك المحتوى النهائي للملف "server.js" بعد جميع التعديلات:

import express from 'express'
import cors from 'cors'
import { graphqlHTTP } from 'express-graphql'
import { makeExecutableSchema } from '@graphql-tools/schema'

const app = express()
const port = 4000

// مخزن البيانات في الذاكرة
const data = {
  warriors: [
    { id: '001', name: 'Jaime' },
    { id: '002', name: 'Jorah' },
  ],
}

// المخطط
const typeDefs = `
type Warrior {
  id: ID!
  name: String!
}

type Query {
  warriors: [Warrior]
}
`

// محلل الاستجابة للمحاربين
const resolvers = {
  Query: {
    warriors: (obj, args, context) => context.warriors,
  },
}

const executableSchema = makeExecutableSchema({
  typeDefs,
  resolvers,
})

app.use(cors())
app.use(express.json())
app.use(express.urlencoded({ extended: true }))

// نقطة الدخول
app.use(
  '/graphql',
  graphqlHTTP({
    schema: executableSchema,
    context: data,
    graphiql: true,
  })
)

app.listen(port, () => {
  console.log(`Running a server at http://localhost:${port}`)
})

احفظ التغييرات على الملف وأغلقه.

تكتمل بذلك واجهة برمجة التطبيقات، يمكنك الآن فتح الرابط "http://localhost:4000/graphql"، واستعراض مخطط GraphQL وتصحيح أخطائه باستخدام بيئة التطوير المتكاملة GraphiQL IDE، وهو موضوع القسم التالي من المقال.

استخدام GraphiQL IDE

الخطوة الأولى لاستخدام بيئة التطوير GraphiQL IDE هي تفعيلها بإسناد القيمة true للخيار graphiql في كتلة التعليمات الخاصة بالبرمجية الوسيطة ضمن ملف الخادم، ولو رجعت للتعليمات السابقة ستجدها مُفعلة.

تعمل GraphiQL ضمن المتصفح، وتفيدك في كتابة استعلامات GraphQL، والتحقق من صحتها، واختبارها لضمان خرج صحيح من الخادم.

تنقسم شاشة GraphiQL إلى قسمين، القسم الأيسر لكتابة التعليمات والأيمن لعرض النتائج. سنجري الآن استعلامًا عن المحاربين warriors، لذلك اطلب المُعرّف id والاسم name لكل محارب بكتابة التعليمات التالية في القسم الأيسر من الشاشة:

{
  warriors {
    id
    name
  }
}

اضغط بعدها على الزر التشغيل أعلى يسار الشاشة، وستظهر نتيجة استعلامك في القسم الأيمن بصيغة JSON، وفق التالي:

Output{
  "data": {
    "warriors": [
      { "id": "001", "name": "Jaime" },
      { "id": "002", "name": "Jorah" }
    ]
  }
}

حاول تعديل الاستعلام، استعلم مثلًا عن الاسم name فقط:

{
  warriors {
    name
  }
}

ولاحظ تغير النتيجة تبعًا لاستعلامك، فهي تشمل الآن أسماء المحاربين دون أرقامهم:

Output{
  "data": {
    "warriors": [{ "name": "Jaime" }, { "name": "Jorah" }]
  }
}

تعكس هذه التجربة واحدةً من أقوى خصائص GraphQL، وهي أنها موجهة بطلبات العميل [Client-driven]()، إذ تسمح له بالاستعلام عن الحقول التي يحتاجها فقط، وتعرضها هي بالذات دون زيادة أو نقصان.

تفيدك GraphiQL أيضًا باستعراض تفاصيل المخطط، فكل ما تحتاجه هو الضغط على زر التوثيق Docs في يمين الشاشة، وسيظهر لك شريط جانبي خاص بالتوثيقات.

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

إرسال طلب استعلام لواجهة GraphQL API من طرف العميل

يمكنك إرسال طلبات الاستعلام إلى واجهة GraphQL عبر بروتوكول HTTP بالطريقة نفسها المتبعة مع واجهات REST، وتستطيع أيضًا استعمال واجهات APIs المُضمّنة في المتصفحات مع GraphQL، ومن أمثلتها fetch الخاصة بجلب البيانات.

افتح الملف "index.html"، وأنشئ بداخله هيكل HTML مع الوسم <pre> كما يلي:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    <title>GraphQL Client</title>
  </head>

  <pre><!-- البيانات ستعرض هنا --></pre>

  <body>
    <script>
      // Add query here
    </script>
  </body>
</html>

ثم أنشئ دالة غير متزامنة تحت الوسم script، ترسل طلب POST لواجهة GraphQL API:

...
<body>
    <script>
      async function queryGraphQLServer() {
        const response = await fetch('http://localhost:4000/graphql', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            query: '{ warriors { name } }',
          }),
        })
        const data = await response.json()

        // إضافة البيانات إلى الوسم
        const pre = document.querySelector('pre')
        pre.textContent = JSON.stringify(data, null, 2) // JSON بصيغة

      }

      queryGraphQLServer()
    </script>
  </body>
...

أسند القيمة application/json للحقل Content-Type في ترويسة المقطع script، واكتب الاستعلام الذي تطلبه بصيغة سلسلة نصية ضمن المتن، فيكون تسلسل الإجراءات كما يلي: يستدعي script الدالة غير المتزامنة، فترسل طلبًا للخادم، وعند ورود الاستجابة توضع تحت الوسم pre.

إليك المحتوى النهائي للملف "index.html":

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    <title>GraphQL</title>
  </head>

  <pre></pre>

  <body>
    <script>
      async function queryGraphQLServer() {
        const response = await fetch('http://localhost:4000/graphql', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            query: '{ warriors { name } }',
          }),
        })
        const data = await response.json()

        const pre = document.querySelector('pre')
        pre.textContent = JSON.stringify(data, null, 2) // Pretty-print the JSON
      }

      queryGraphQLServer()
    </script>
  </body>
</html>

احفظ التغييرات، وأغلق الملف "index.html"، ثم استعرضه بواسطة المتصفح، وافتح نافذة الشبكة Network ضمن أدوات المطور لترى الطلب المرسل عبر الشبكة من المتصفح إلى نقطة وصول GraphQL ذات العنوان "http://localhost:4000/graphql"، وافحص بعدها استجابة الخادم؛ فإذا تضمنت البيانات التي استعلمت عنها مع رمز الاستجابة 200، فاستعلامك صحيح وقد نجحت بإنشاء خادم GraphQL API.

الخاتمة

تناول هذا المقال إعداد خادم GraphQL API في بيئة Node.js باستخدام إطار العمل Express بطريقة مبسطة تعينك على فهم أساسيات GraphQL، وأبرزها أن الخادم يتكون من نقطة وصول وحيدة graphql/ تستقبل جميع طلبات الاستعلام، وواجهة برمجة التطبيقات تحتوي دومًا مخطط ومحلل استجابة. يتضمن المخطط نوعين، نوعًا أساسيًا للاستعلام Query، ونوعًا مخصصًا تُعرّفه حسب حالتك، وفي مثالنا كان نوع المحارب Warrior، ومهمة محلل الاستجابة جلب البيانات المناسبة لهذه الأنواع من مخزن البيانات.

نأمل أننا ساعدناك في خطوتك الأولى مع GraphQL، وننصحك بتوسيع بحثك عنها لتتعرف على خياراتها المتقدمة ومكملاتها، مثل أدوات المصادقة والأمان والتخبئة caching، لتزيد فعاليتها في تطبيقاتك.

ترجمة -وبتصرف- للمقال How To Set Up a GraphQL API Server in Node.js لصاحبته Tania Rascia.

اقرأ أيضًا

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

نماذج اللغة الكبيرة (أو Large Language Models) هي نوع من نماذج الذكاء الاصطناعي التي تُدرّب على كمية كبيرة من النصوص لتستطيع بذلك توليد نصوص مشابهة لها، وهنا يأتي ChatGPT وهو نموذج لغة كبير دُرّب على محتوى كبير جدًا من الانترنت، بحيث أصبح لديه اطلاع على الكثير من المعلومات واللغات وأساليب الكتابة، وطوّر باستخدام بعض التقنيات أهمها تقنية التعلم الموجه من قبل البشر RLHF (أو Reinforcement learning from human feedback) ليتّبع في توليده للنصوص اسلوب الحوار بين المستخدم والنموذج، مما يبسط طريقة التعامل معه وتوجيهه لتوليد النصوص التي نحتاحها، وفي هذا المقال سنتعامل مع ذلك النموذج لتوليد نصائح وحكم مفيدة للمستخدم بحسب ما يطلب أو يشعر، وذلك عبر واجهة سطر الأوامر نطورها ضمن بيئة نود (Node.js) حيث يُدخل المستخدم موضوع النصيحة أو الهدف منها ويولد ChatGPT ذلك، وستحتاج لاتباع المقال معرفة بلغة جافاسكربت وبيئة نود ومدير الحزم npm.

إنشاء برنامج سطر أوامر باستخدام npm

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

npm init -y

سينشئ عن تنفيذ ذلك الأمر ملف تعريف الحزمة package.json ضمن المجلد، وباستخدام الخيار y- ستُملئ القيم الافتراضية ضمنه دون الحاجة لإدخالها يدويًا، والآن نُنشئ ملف البرنامج الرئيسي index.js والذي سيحتوي شيفرة البرنامج، ولتعريفه كبرنامج سطر أوامر يمكن بداخل ملف تعريف الحزمة package.json وضمن المفتاح bin تعريف كائن مفاتيحه هي أسماء برامج سطر الأوامر التي توفرها هذه الحزمة، وقيمها هي مسار الملفات التي ستُنفذ باستخدام نود عند تنفيذ البرنامج، لتطبيقنا سنعرف برنامج بالاسم ألهمني ومسار ملف البرنامج له هو الملف الرئيسي index.js كالتالي:

"bin": {
  "ألهمني": "index.js"
}

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

#!/usr/bin/env node

console.log('مرحبًا')

وبذلك يمكن لأي مستخدم بعد تثبيت هذا المشروع كحزمة على جهازه تنفيذ الأمر باستخدام اسم البرنامج المُعرف ضمن الكائن bin ليُنفذ البرنامج index.js في بيئة نود ويظهر له النتيجة، ولاختباره أثناء التطوير يمكن الاستفادة من أمر الربط link من مدير الحزم npm والذي يربط الحزمة ضمن البيئة العامة للجهاز لنتمكن من استخدامها من أي مكان، لذا ننفذ الأمر التالي ضمن مجلد المشروع:

npm link .

تدل النقطة على المشروع الذي نرغب بربطه وتعني المشروع في المسار الحالي، وبعد تنفيذ هذا الأمر أصبح الوصول لبرنامج سطر الأوامر ممكنًا من أي مكان لنختبر ذلك بتنفيذ الأمر التالي ضمن أي طرفية terminal لنلاحظ خرج البرنامج كالتالي:

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

دورة تطوير التطبيقات باستخدام لغة JavaScript

تعلم البرمجة بلغة جافا سكريبت انطلاقًا من أبسط المفاهيم وحتى بناء تطبيقات حقيقية.

اشترك الآن

استقبال الدخل من المستخدم

نحتاج أن يدخل المستخدم موضوع النصيحة أو الحكمة التي يرغب بها، ويمكن استقبال ذلك عبر معاملات سطر الأوامر التي يمررها المستخدم عند تنفيذ البرنامج، ويمكن الوصول إليها في نود عبر المتغير العام process.argv وهو مصفوفة من القيم أول قيمة منه هي مسار البرنامج التنفيذي لبيئة نود التي ستُنفذ البرنامج، والقيمة الثانية هي مسار ملف البرنامج الحالي الذي سيُنفذ، والقيم الباقية هي ما تُهمنا وهي جميع المعاملات المُمررة للبرنامج من قبل المستخدم عند تنفيذه، حيث سنجمعها معًا لنكون منها الجملة التي أدخلها المستخدم لتحضيرها قبل إرسالها، لذا نعدل ملف البرنامج index.js ليصبح كالتالي:

#!/usr/bin/env node

const args = process.argv.slice(2)
const input = args.join(' ')

حيث باستخدام التابع slice على مصفوفة المعاملات المُمررة للبرنامج يمكننا تجاهل أول عنصرين منها واستخراج المعاملات المُمررة فقط، وباستخدام التابع join نجمع تلك الكلمات ونفصل بينها بفراغات لتكون قيمة الثابت input هي جملة الدخل من المستخدم، وفي الفقرة التالية سنُرسل تلك الجملة إلى نموذج ChatGPT لتوليد النصيحة المطلوبة.

إرسال الدخل إلى ChatGPT وتوليد النصيحة

لنتمكن من التعامل مع نموذج ChatGPT عبر الواجهة البرمجية API له يجب إنشاء حساب جديد ضمن المنصة المالكة له OpenAI وإعداد الحساب كحساب مدفوع وإدخال وسيلة الدفع، بعد ذلك يمكن توليد مفتاح للتعامل مع الواجهة البرمجية نتأكد من نسخه والاحتفاظ به، وننفذ الأمر التالي مع تبديل قيمة المفتاح لتخزينه ضمن متغيرات البيئة لجلبه ضمن البرنامج لاحقًا:

set OPENAI_API_KEY=<قيمة المفتاح>

وضمن نظام ماك أو لينكس يمكن تنفيذ الأمر التالي:

export OPENAI_API_KEY=<قيمة المفتاح>

وبذلك عند تنفيذ البرنامج من نفس هذه الطرفية سيتمكن البرنامج من الوصول لقيمة ذلك المفتاح دون الحاجة لكتابته ضمن الشيفرة المصدرية، والآن لنرسل دخل المستخدم ونطلب من نموذج ChatGPT الرد المناسب ويمكن ذلك بحسب التوثيق الرسمي لواجهة النموذج البرمجية بإرسال طلب HTTP من نوع POST إلى مسار الواجهة البرمجية https://api.openai.com/v1/chat/completions ونضع مفتاح الواجهة ضمن الترويسة Authorization وقيمتها الكلمة Bearer ثم مسافة ثم قيمة المفتاح، وضمن جسم الطلب نحدد كقيمة للمفتاح model اسم النموذج الذي نرغب بالتعامل معه وهو gpt-3.5-turbo وهو الاسم التقني لنموذج ChatGPT بالإصدار الثالث، ونضيف كقيمة للمفتاح messages مصفوفة من الكائنات المُعبرة عن الرسائل المُرسلة للنموذج نرسل ضمنها رسالة المستخدم وهو الدخل المُمرر للبرنامج، ويمكننا توجيه النموذج لشكل الخرج الذي نريده عبر تشكيل رسالة المستخدم لتصبح بالشكل التالي:

const message = `ألهمني بعبارة مختصرة عن الموضوع التالي:  ${input}`

وبذلك نرشد النموذج داخل البرنامج لطبيعة الرد الذي نريده منه دون أن يحتاج المستخدم سوى لإدخال الموضوع الذي يريده للبرنامج، وباستخدام fetch يمكننا إرسال طلب HTTP للواجهة البرمجية للنموذج كالتالي:

fetch('https://api.openai.com/v1/chat/completions', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${proccess.env.OPENAI_API_KEY}`,
    },
    body: JSON.stringify({
        "model": "gpt-3.5-turbo",
        "messages": [{ "role": "user", "content": message }]
    }),
})

حيث يعيد التابع fetch وعدًا (أو Promise) يمكننا استخدام التابع then للحصول على الرد، ونحول الرد القادم إلى صيغة json ثم نستخرج منها محتوى جواب النموذج على الرسالة المرسلة من قبل المستخدم وهي ضمن القيمة json.choices[0].message.content من رد json المرسل ونعرضها له على الشاشة كالتالي:

fetch(...)
  .then(r => r.json())
  .then(json => json.choices[0].message.content)
  .then(gpt_response => console.log(gpt_response))

وبذلك يصبح البرنامج جاهزًا لنختبره في الفقرة التالية لتوليد بعض النصائح المفيدة.

اختبار البرنامج

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

النجاح هو النتيجة الإيجابية للجهود المستمرة والتفاني في العمل لتحقيق الأهداف.

لنرى ما سينصح به شخص يشعر بالتعب بتنفيذ الأمر ألهمني أشعر بالتعب:

استرح قليلاً، واشرب ماء بكميات كافية، ومارس التمارين الرياضية بانتظام.

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

لا تستسلم للتعب، النجاح يتطلب الجهد والإصرار.

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

دورة الذكاء الاصطناعي

احترف برمجة الذكاء الاصطناعي AI وتحليل البيانات وتعلم كافة المعلومات التي تحتاجها لبناء نماذج ذكاء اصطناعي متخصصة.

اشترك الآن

اقرأ أيضًا

• برمجة تطبيق 'لخصلي' لتلخيص المقالات باستخدام ChatGPT ولارافل
• تطوير تطبيق 'وصفة' لاقتراح الوجبات باستخدام ChatGPT و DALL-E في PHP
• تطوير تطبيق 'اختبرني' باستخدام ChatGPT ولغة جافاسكربت مع Node.js

تتميز نماذج اللغة الكبيرة أو Large Language Models بقدرتها على فهم اللغة الطبيعية وتوليد النصوص الصحيحة إملائيًا والصحيحة بمعناها أيضًا، مما يسمح بالتعامل مع نماذج الذكاء الاصناعي تلك بسهولة وبساطة من خلال اللغة الطبيعية، ومن تلك النماذج نموذج ChatGPT الشهير من شركة OpenAI والذي سنستفيد من مزاياه تلك والمعلومات الكامنة ضمنه والتي اكتسبها أثناء مرحلة تدريبه على البيانات النصية المتوفرة على الإنترنت في هذا المقال لتوليد أسئلة للمستخدم عن موضوع معين يطلبه المستخدم، ثم عرض الأجوبة التي يُدخلها المستخدم على النموذج لتحديد مستوى فهمه لذلك الموضوع وحتى تصحيح أجوبته إن كانت خاطئة، سنلاحظ أيضًا الطيف الواسع من الاحتمالات الممكنة عند التعامل مع ذلك النموذج، من توليد المحتوى إلى طلب البيانات بشكل وتنسيق محدد يسهل تكامله مع التطبيق.

تجهيز المشروع وإعداد الصفحات

نبدأ بإنشاء مجلد جديد للمشروع وننفذ الأمر التالي بداخله والذي سيُعرّف المشروع كحزمة وتوليد ملف توصيف المشروع package.json والذي يمكن تعريف بعض الأوامر الخاصة بالمشروع ضمنه وتحديد الاعتماديات التي يريدها:

npm init -y

نثبت الاعتماديات التي نحتاجها لبناء المشروع وهي مكتبة express لإنشاء خادم الويب للتطبيق والمكتبة ejs لبناء قوالب HTML لصفحات المشروع، ومكتبة openai للتعامل مع الواجهة البرمجية API لنموذج ChatGPT ومكتبة dotenv والتي سنحتاجها لتحميل متغيرات البيئة من ملف env. للمشروع، وذلك بتنفيذ الأمر التالي:

npm install express ejs openai dotenv

لنبدأ ببناء خادم الويب وتجهيز الصفحات الأساسية للتطبيق وهي ثلاثة صفحات صفحة يدخل فيها المستخدم موضوع الاختبار، وصفحة لعرض الاختبار وإدخال الأجوبة، وصفحة عرض النتيجة، ونولد أولًا تطبيق جديد باستدعاء تابع مكتبة Express ونضبط إعداداته لاستخدام محرك القوالب ejs كمحرك توليد ملفات العرض وتخديم الملفات الثابتة العامة من المجلد public ضمن المشروع، واستقبال الدخل المرسل من نموذج HTML والتعامل معه، وذلك ضمن الملف bin/www ونضيف له ترويسة تحديد بيئة التشغيل لذلك الملف كالتالي:

#!/usr/bin/env node
const path = require("path");
const express = require("express");

// إنشاء تطبيق جديد
const app = express();
// ضبط محرك توليد ملفات العرض
app.set('view engine', 'ejs');
//إعداد تخديم الملفات العامة
app.use(express.static(path.join(__dirname, '../public')));
// ضبط استقبال المدخلات
app.use(express.urlencoded({ extended: true }))

نُعرّف ضمن متغير التطبيق app ثلاث مسارات وهي المسار الرئيسي / بالطريقة GET لعرض الصفحة الرئيسية، والمسار test/ لعرض الاختبار، والمسار result/ لعرض نتيجة الاختبار، وضمن كل منها نٌصيّر ونعيد صفحة القالب المقابلة لذلك المسار باستخدام التابع render من كائن الطلب req المُمرر لتابع معالجة الطلب لكل مسار، ليكون تعريف المسارات كالتالي مع تمرير بعض البيانات الوهمية لاختبار الصفحات والتي سنستبدلها لاحقًا:

// الصفحة الرئيسية
app.get('/', (req, res) => {
    res.render('index');
})

// صفحة الاختبار
app.post('/test', async (req, res) => {
    res.render('test', { 
        questions: [
            'السؤال الأول',
            'السؤال الثاني',
        ]
    });
})

// صفحة عرض النتيجة
app.post('/result', async (req, res) => {
    res.render('result', {
        results: [
            {
                question: 'السؤال الأول',
                answer: 'جواب السؤال الأول',
                correct: true,
                note: null,
            },
            {
                question: 'السؤال الثاني',
                answer: 'جواب السؤال الثاني',
                correct: false,
                note: 'ملاحظة حول الإجابة الخاطئة',
            }
        ],
    })
})

ملفات قوالب صفحات العرض مكانها الافتراضي ضمن المجلد views، وبما أننا نستخدم محرك ejs يجب أن تنتهي جميع تلك الملفات باللاحقة ejs.، ونربط ضمنها ملف التنسيقات style.css والذي يمكننا إنشاءه في المسار public\style.css، والصفحات هي الصفحة الرئيسية views\index.ejs وتحوي حقل لإدخال موضوع الاختبار:

<html lang="ar">
  <head>
    <link rel="stylesheet" href="style.css" />
    <title>اختبرني</title>
  </head>
  <body>
    <h1>?</h1>
    <form action="test" method="post">
      <input type="text" name="subject" placeholder="أدخل موضوع الاختبار"/>
      <button type="submit">اختبرني</button>
    </form>
  </body>
</html>

والصفحة الثانية لعرض الأسئلة المقترحة، حيث نمرر لقالب العرض القيمة questions والتي تحوي الأسئلة كمصفوفة سلاسل نصية، نمر عليها ضمن القالب ونعرض لكل منها نص السؤال ثم حقل مخفي يحوي نص السؤال لإرساله مع حقل الجواب المُدخل من المستخدم، والبيانات ضمن النموذج المُرسل ستحوي على القيمة answers وهي مصفوفة من الكائنات الذي يُمثل كل منها السؤال question مع الجواب answer المُدخل من قبل المستخدم لتكون من الشكل التالي:

{
  "answers": [
    { "question": "...", "answer": ""},
    …
  ]
}

نستعمل صيغة الأقواس المربعة ‎[question][index]answers و ‎[answer][index]answers كأسماء لتلك الحقول ليتولى express ترجمتها إلى الكائن answers وقيمته مصفوفة من كائنات يحوي كل منها الحقل question لنص السؤال والحقل answer للجواب المقابل لذلك السؤال، ليكون ملف قالب صفحة الأسئلة كالتالي:

<html lang="ar">
  <head>
    <link rel="stylesheet" href="style.css" />
    <title>اختبرني | الاختبار</title>
  </head>
  <body>
    <form action="result" method="post">
      <% questions.forEach((question, index) => { %>
      <p dir="auto"><%- question %></p>
      <input type="hidden" name="answers[<%= index %>][question]" value="<%- question %>"
      />
      <input type="text" name="answers[<%= index %>][answer]" />
      <% }) %>
      <button type="submit">عرض النتيجة</button>
    </form>
  </body>
</html>

والصفحة الأخيرة لعرض النتيجة، حيث سنمرر لقالب العرض القيمة results وهي مصفوفة من كائنات نتائج الأسئلة، يحوي كل منها على الحقل question لنص السؤال والحقل answer للجواب المدخل من قبل المستخدم سنضعه كقيمة لحقل input مع الخاصية readonly لمنع تعديله، والحقل المنطقي correct يعبر عما إذا كان الجواب صحيحًا أم لا، وأخيرًا الحقل note والذي سنعرضه في حال كان الجواب خاطئًا ويحوي على ملاحظة من قبل ChatGPT عن الإجابة الصحيحة، وأخيرًا رابط للصفحة الرئيسية لطلب اختبار جديد كالتالي:

<html lang="ar">
  <head>
    <link rel="stylesheet" href="style.css" />
    <title>اختبرني | النتيجة</title>
  </head>
  <body>
    <% results.forEach((result, index) => { %>
    <div class="result">
      <p dir="auto"><%- result.question %></p>
      <input type="text" value="<%= result.answer %>" readonly class="<% if(result.correct){ %> correct <% } else { %> wrong <% } %>"/>
      <% if(!result.correct) { %>
        <div class="wrong"><%= result.note %></div>
      <% } %>
    </div>
    <% }) %>

    <a href="/">اختبار جديد</a>
  </body>
</html>

وقبل أن نعاين الصفحات يجب أن نضيف تعليمة تشغيل خادم الويب بنهاية الملف bin/www على منفذ محدد نستخرجه من متغيرات البيئة كالتالي:

// رقم المنفذ من متغيرات البيئة
const port = process.env.PORT;

// تشغيل خادم الويب
app.listen(port, () => console.log(`Listening on http://localhost:${port}`))

ولتحميل متغيرات البيئة من ملف env. نضعه ضمن مجلد المشروع مباشرةً نستخدم المكتبة dotenv بإضافة التعليمة التالية في بداية نفس الملف لتحميل القيم من env. وتعيينها كمتغيرات بيئة مباشرةً كالتالي:

#!/usr/bin/env node
// تحميل متغيرات البيئة
require('dotenv').config()
...

وننشئ الملف env. ونعرف ضمنه القيمة PORT بأي رقم منفذ نريده وليكن 3000:

PORT=3000

ونُعرّف ضمن ملف تعريف الحزمة package.json النص البرمجي start لتشغيل الخادم ضمن القيمة scripts كالتالي:

"scripts": {
  "start": "node bin/www"
},

لتنسيق جميع الصفحات يمكن التعديل على الملف public/style.css ولن نعرض محتواه اختصارًا، وبعد التعديل عليه لتنسيق الصفحات يمكن معاينتها بتشغيل الخادم بتنفيذ التعليمة التالية بطرفية ضمن مجلد المشروع:

npm start

نزور الصفحة الرئيسية على الرابط المعروض بعد تشغيل الخادم:

ندخل أي قيمة ضمن الصفحة السابقة لنعاين صفحة عرض الأسئلة لنشاهد التالي:

ونضغط عرض النتيجة لنعاين صفحة عرض النتيجة النهائية كالتالي:

بعد أن جهزنا ملفات المشروع بالكامل والصفحات المطلوبة أصبح جاهزًا الآن لربطه مع ChatGPT لتوليد المحتوى المطلوب وعرضه وهو ما سنبدأ به في الفقرات التالية.

تحضير الربط مع ChatGPT

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

...
OPENAI_API_KEY=<قيمة المفتاح>

وضمن الملف نستخدم المكتبة openai التي ثبتناها في بداية المقال ونُنشئ كائن جديد من الصنف الذي توفره OpenAIApi ونمرر له الإعدادات المناسبة مع قيمة المفتاح السابق من متغيرات البيئة في بداية الملف كالتالي:

...
const { OpenAIApi, Configuration } = require("openai");

const openai = new OpenAIApi(
    new Configuration({ apiKey: process.env.OPENAI_API_KEY })
)

يمكننا الآن استخدام الثابت openai للتعامل مع الواجهات البرمجية التي توفرها OpenAI وتحديدًا نموذج ChatGPT وهو ما سنبدأ بالتعامل معه في الفقرة التالية.

اقتباس

ChatGPT المُطلق للعموم والمجاني محصور بواجهة الويب التي توفرها الشركة وهو مجاني أصلًا كي يُدربه المستخدمون، ولا يملك واجهة برمجية سوى المدفوعة حاليًا.

توليد أسئلة الاختبار

كل ما علينا الآن هو تعديل توابع معالجة الطلبات المرسلة والطلب من نموذج ChatGPT توليد بعض الأسئلة عن الموضوع الذي أرسله المستخدم من الصفحة الرئيسية إلى المسار test/ باستخراج قيمة موضوع الاختبار ضمن تابع معالجة الطلب كالتالي:

app.post('/test', async (req, res) => {
    // استخراج موضوع الاختبار
    const { subject } = req.body
    ...
})

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

اقتباس

أكتب أربعة أسئلة يمكن الاجابة عليها بجواب قصير لاختبار مستوايي في <الموضوع>، الأسئلة كل سؤال بسطر:

نلاحظ كيف حددنا شكل الخرج الذي نريده وهو أن يكتب كل سؤال ضمن سطر لنتمكن من استخراجه، ويمكننا تحديد شكل الخرج بطريقة متقدمة سنتعرف عليها لاحقًا أما حاليًا يمكننا فصل الجواب الناتج من النموذج إلى الأسطر المكونة له واعتبار كل سطر هو سؤال، ونبني التعليمة السابقة وندرج ضمنها قيمة الموضوع المرسل ونستخدم الثابت openai لإرسال رسالة إلى النموذج gpt-3.5-turbo وهو النسخة المتاحة دون اشتراك شهري وقت كتابة هذا المقال، حيث تحوي الرسالة على التعليمة السابقة، ثم نستخرج من الجواب قيمة الرسالة المُرسلة من النموذج ليصبح تابع معالجة طلب توليد أسئلة عن موضوع معين كالتالي:

app.post('/test', async (req, res) => {
    // استخراج موضوع الاختبار
    const { subject } = req.body

    // بناء التعليمة
    const prompt = `أكتب أربعة أسئلة يمكن الاجابة عليها بجواب قصير لاختبار مستوايي في ${subject}، الأسئلة كل سؤال بسطر:`;

    // إرسال طلب إلى النموذج
    const response = await openai.createChatCompletion({
        model: 'gpt-3.5-turbo',
        messages: [
            { role: 'user', content: prompt }
        ]
    })

    // استخراج الجواب
    const message = response.data.choices[0].message.content

    // استخراج الأسئلة المولدة من الجواب
    const questions = message.split('\n')

    // تمرير الأسئلة المقترحة لصفحة الاختبار
    res.render('test', { questions });
})

وفي الفقرة التالية سنستقبل الأجوبة من المستخدم ونُقيمها باستخدام ChatGPT مجددًا ونعرض النتيجة للمستخدم.

إرسال الإجابات للتقييم

بعد إدخال الإجابات في صفحة الاختبار وإرسالها إلى مسار عرض النتيجة result/ يمكننا ضمن ذلك المسار استقبال الإجابات من الكائن answers من جسم الطلب:

app.post('/result', async (req, res) => {
    // استخراج الإجابات
    const { answers } = req.body
    ...
})

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

اقتباس

السؤال: … الجواب: …

السؤال: … الجواب: …

قيم الإجابات السابقة مع الشرح بصيغة JSON التالية:

[{correct: false, note:"تعليل أو ملاحظة حول الإجابة...."}، ...]

نبني تلك التعليمة من الأجوبة المرسلة كالتالي:

const { answers } = req.body

// الأسئلة مع الأجوبة
const questionsAndAnswers = answers
        .map(({ question, answer }) => `السؤال: ${question}\nالجواب: ${answer}`)
        .join('\n\n')

// بناء التعليمة
const prompt = `${questionsAndAnswers}\n\nقيم الإجابات السابقة مع الشرح بصيغة JSON التالية:
    [{correct: false, note:"تعليل أو ملاحظة حول الإجابة...."}، ...]`;

ثم نرسلها إلى ChatGPT كما فعلنا سابقًا والفرق هذه المرة في معالجة الجواب حيث سنترجمه من صيغة JSON إلى مصفوفة في جافاسكريبت باستخدام التابع JSON.parse

// إرسال التعليمة
const response = await openai.createChatCompletion({
        model: 'gpt-3.5-turbo',
        messages: [
            { role: 'user', content: prompt }
        ]
    })

// استخراج الجواب
const message = response.data.choices[0].message?.content

// معالجة الجواب
const results = JSON.parse(message)

والآن نعرضها ضمن قالب العرض result.ejs باستخدام التابع renderمع تمرير نص السؤال والجواب المدخل من المستخدم وتقييم الجواب والملاحظة حوله كالتالي:

// عرض النتيجة
res.render('result', {
    results: results.map((result, index) => ({
        question: answers[index].question,
        answer: answers[index].answer,
        note: result.note,
        correct: result.correct,
    })),
})

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

اختبار التطبيق

لنحاول الإجابة على بعض الأسئلة المتعلقة بالبرمجة في نود لاختبار المستوى:

نلاحظ اقتراح أسئلة متنوعة عن ذلك الموضوع، لنحاول الإجابة عليها باللغة العربية وترك الجواب الأخير خاطئًا:

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

خاتمة

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

اقرأ أيضًا

• برمجة تطبيق 'لخصلي' لتلخيص المقالات باستخدام ChatGPT ولارافل
• تطوير تطبيق 'وصفة' لاقتراح الوجبات باستخدام ChatGPT و DALL-E في PHP

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

توفر نود دعمًا للتواصل عن طريق طلبات HTTP مع واجهات API عبر الويب، فتتيح الوحدة البرمجية ‎http‎ والوحدة ‎https‎، حيث تحتوي كل منهما على التوابع اللازمة لإنشاء خادم HTTP لمعالجة الطلبات الواردة إلى الخادم، وتوابع لإنشاء طلبات HTTP وإرسالها إلى الخوادم الأخرى، حيث تسمح هاتين الميزتين بتطوير تطبيقات ويب حديثة تعتمد على الواجهات البرمجية API للتواصل بينها، ولا حاجة لتثبيت أي وحدة برمجية خارجية حيث تأتي تلك الوحدات جاهزة مع نود افتراضيًا.

سنتعلم في هذا المقال كيف يمكننا الاستفادة من الوحدة ‎https‎ لإرسال طلبات HTTP بمثال عن التعامل مع خادم JSON Placeholder وهو واجهة برمجية API وهمية تستخدم في عمليات التدريب والاختبار، حيث سنتعلم طريقة إرسال طلب HTTP لطلب البيانات من نوع ‎GET‎، ثم سنتعرف على طرق تخصيص الطلب المرسل كإضافة الترويسات، وسنتعرف أيضًا على الطلبات بمختلف أنواعها مثل ‎POST‎ و ‎PUT‎ و ‎DELETE‎ والتي تستخدم لتعديل البيانات على الخوادم الأخرى.

المستلزمات

• نسخة نود مثبتة على جهازك، حيث استخدمنا في هذا المقال الإصدار رقم 10.19.0.
• تعتمد توابع إرسال طلبات HTTP على واجهة مجرى البيانات stream في نود وهي بدورها نسخة من كائن مرسل الأحداث event emitter، لذا يمكن التعامل مع البيانات الواردة منها بنفس طريقة تعاملنا مع الأحداث المرسلة، وللتعرف على مرسل الأحداث وطريقة التعامل معه يمكنك مراجعة المقال التاسع من هذه السلسلة.

إرسال طلب من نوع ‎GET‎

إن أردنا طلب بيانات من خادم ويب ما عبر واجهته البرمجية API نرسل إليه عادة طلب HTTP من نوع ‎GET‎، ففي هذه الفقرة سنتعلم طريقة إرسال تلك الطلبات في نود وتحديدًا لجلب مصفوفة بيانات بصيغة JSON تحتوي على بيانات حسابات شخصية لمستخدمين وهميين من واجهة برمجية API متاحة للعموم، حيث تحوي الوحدة البرمجية ‎https‎ على تابعين يمكن استخدامهما لإرسال طلبات من نوع ‎GET‎ هما التابع ‎get()‎، والتابع ‎request()‎ الذي يمكن استخدامه لإرسال طلبات من أنواع متعددة أخرى كما سنتعلم لاحقًا، ولنبدأ أولًا بالتعرف على التابع ‎get()‎.

إرسال الطلبات باستخدام التابع ‎get()‎

صيغة استخدام التابع ‎get()‎ تكون كالتالي:

https.get(URL_String, Callback_Function) {
    Action
}

حيث نمرر له سلسلة نصية كمعامل أول تحوي المسار الذي سنرسل الطلب إليه، والمعامل الثاني يكون دالة رد النداء callback function لمعالجة نتيجة الطلب.

سنبدأ بإنشاء مجلد جديد للمشروع سيحوي الأمثلة التي سنكتبها ضمن هذا الفصل كالتالي:

$ mkdir requests

وندخل إلى المجلد:

$ cd requests

ننشئ ملف جافاسكربت جديد ونفتحه باستخدام أي محرر نصوص حيث سنستخدم في أمثلتنا محرر نانو ‎nano‎ كالتالي:

$ nano getRequestWithGet.js

ونبدأ باستيراد الوحدة ‎https‎ كالتالي:

const https = require('https');

ملاحظة: يوجد في نود وحدتين برمجيتين هما ‎http‎ و ‎https‎ تحويان على نفس التوابع التي تعمل بنفس الطريقة، والفرق بينها أن التوابع ضمن ‎https‎ ترسل الطلبات عبر طبقة أمان النقل Transport Layer Security أو TLS/SSL، وسنرسل الطلبات في أمثلتنا عبر HTTPS لذا سنستخدم تلك التوابع من الوحدة ‎https‎، بينما لو كنا سنرسل الطلبات عبر HTTP فيجب استخدام توابع الوحدة ‎http‎ بدلًا منها.

نبدأ بكتابة شيفرة إرسال طلب ‎GET‎ إلى الواجهة البرمجية API لجلب بيانات المستخدمين، حيث سنرسل طلبًا إلى واجهة JSON Placeholder وهي واجهة برمجية متاحة للاستخدام العام لأغراض الاختبار، ولا تتأثر البيانات على ذلك الخادم بالطلبات المرسلة فمهمته فقط محاكاة عمل خادم حقيقي، حيث سيرجع لنا دومًا بيانات وهمية طالما أن الطلب المرسل إليه سليم، لنبدأ بكتابة الشيفرة التالية:

const https = require('https');

let request = https.get('https://jsonplaceholder.typicode.com/users?_limit=2', (res) => { });

كما ذكرنا سابقًا يقبل التابع ‎get()‎ معاملين وهما المسار الوجهة للطلب URL كسلسلة نصية للواجهة البرمجية، ودالة رد نداء لمعالجة نتيجة طلب HTTP الواردة، حيث يمكن استخراج البيانات من الرد ضمن دالة رد النداء.

يحمل طلب HTTP على رمز الحالة status code وهو عدد يشير إلى نجاح الطلب من عدمه، فمثلًا إذا كانت قيمة الرمز بين 200 و 299 فالطلب ناجح، أما إذا كان بين 400 و 599 فهناك خطأ ما، وفي مثالنا الرد من الواجهة البرمجية يجب أن يحتوي على رمز الحالة 200 إن نجح وهو أول ما سنتحقق منه ضمن تابع رد النداء لمعالجة الطلب كالتالي:

const https = require('https');

let request = https.get('https://jsonplaceholder.typicode.com/users?_limit=2', (res) => {
  if (res.statusCode !== 200) {
    console.error(`Did not get an OK from the server. Code: ${res.statusCode}`);
    res.resume();
    return;
  }
});

يحوي كائن الرد res المُمرر لدالة رد النداء على الخاصية ‎statusCode‎ والتي تمثِّل قيمة رمز الحالة، وإذا لم تكن قيمته تساوي 200 سنطبع رسالة خطأ إلى الطرفية ونخرج مباشرةً.

نلاحظ استدعاء التابع ‎res.resume()‎ من كائن الرد وهي طريقة لتحسين أداء البرنامج فعند إرسال طلبات HTTP في نود يتم عادة معالجة البيانات المرسلة ضمن الطلب كاملةً، أما عند استدعائنا للتابع ‎res.resume()‎ فإننا نخبر نود بتجاهل البيانات ضمن مجرى كائن الرد، وهي طريقة أسرع من لو تُركت تلك البيانات لالتقاطها في مرحلة كنس المهملات garbage collection التي تتم دوريًا لتفريغ الذاكرة المستخدمة من قبل التطبيق.

والآن بعد أن تحققنا من رمز الحالة للرد سنبدأ بقراءة البيانات الواردة حيث تتوفر البيانات ضمن كائن مجرى الرد على دفعات، ويمكننا قراءتها بالاستماع إلى الحدث ‎data‎ من كائن الرد ثم تجميعها معًا ثم تحليلها بصيغة JSON لنتمكن من استخدامها ضمن التطبيق، لذلك سنضيف الشيفرة التالية ضمن تابع رد النداء:

const https = require('https');

let request = https.get('https://jsonplaceholder.typicode.com/users?_limit=2', (res) => {
  if (res.statusCode !== 200) {
    console.error(`Did not get an OK from the server. Code: ${res.statusCode}`);
    res.resume();
    return;
  }

  let data = '';

  res.on('data', (chunk) => {
    data += chunk;
  });

  res.on('close', () => {
    console.log('Retrieved all data');
    console.log(JSON.parse(data));
  });
});

عرفنا متغيرًا جديدًا بالاسم ‎data‎ والذي يحتوي على سلسلة نصية فارغة، حيث يمكننا تجميع البيانات الواردة إما على شكل مصفوفة من الأعداد تمثل البيانات للبايتات المكونة لها، أو على شكل سلسلة نصية وهو ما سنستخدمه في مثالنا لسهولة تحويل السلسلة النصية الناتجة عن عملية التجميع إلى كائن جافاسكربت.

نضيف بعد ذلك تابع الاستماع للبيانات الواردة على دفعات من الحدث ‎data‎ ونجمع البيانات كلها ضمن المتغير السابق ‎data‎، ويمكننا التأكد من انتهاء دفعات البيانات الواردة عند إطلاق حدث الإغلاق ‎close‎ من كائن الرد، وبعدها يمكننا تحويل السلسلة النصية بصيغة JSON ضمن المتغير ‎data‎ وطباعة القيمة النهائية إلى الطرفية، وبذلك نكون قد أكملنا كتابة عملية إرسال طلب إلى واجهة برمجية ستُرسل بدورها مصفوفة من بيانات حسابات شخصية لثلاثة مستخدمين بصيغة JSON ونقرأ الرد الوارد.

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

...
  res.on('data', (chunk) => {
    data += chunk;
  });

  res.on('close', () => {
    console.log('Retrieved all data');
    console.log(JSON.parse(data));
  });

});

request.on('error', (err) => {
  console.error(`‎Encountered an error trying to make a request: ${err.message}‎`);
});

عند حدوث خطأ في عملية الإرسال سنتلقى الحدث ‎error‎ من كائن الطلب، وإذا لم نستمع لهذا الحدث فسيرمى الخطأ الناتج ما يؤدي لإيقاف عمل البرنامج، لذلك نضيف دالة استماع للحدث ‎error‎ على كائن الطلب باستخدام التابع ‎on()‎ والذي سيطبع رسالة الخطأ الوارد إلى الطرفية، وبذلك نكون قد انتهينا من كتابة البرنامج.

والآن نحفظ الملف ونخرج منه وننفذه باستخدام الأمر ‎node‎ كالتالي:

$ node getRequestWithGet.js

نحصل على الخرج التالي الذي يمثل الرد الوارد على الطلب المُرسل:

Retrieved all data
[
  {
    id: 1,
    name: 'Leanne Graham',
    username: 'Bret',
    email: 'Sincere@april.biz',
    address: {
      street: 'Kulas Light',
      suite: 'Apt. 556',
      city: 'Gwenborough',
      zipcode: '92998-3874',
      geo: [Object]
    },
    phone: '1-770-736-8031 x56442',
    website: 'hildegard.org',
    company: {
      name: 'Romaguera-Crona',
      catchPhrase: 'Multi-layered client-server neural-net',
      bs: 'harness real-time e-markets'
    }
  },
  {
    id: 2,
    name: 'Ervin Howell',
    username: 'Antonette',
    email: 'Shanna@melissa.tv',
    address: {
      street: 'Victor Plains',
      suite: 'Suite 879',
      city: 'Wisokyburgh',
      zipcode: '90566-7771',
      geo: [Object]
    },
    phone: '010-692-6593 x09125',
    website: 'anastasia.net',
    company: {
      name: 'Deckow-Crist',
      catchPhrase: 'Proactive didactic contingency',
      bs: 'synergize scalable supply-chains'
    }
  }
]

بذلك نكون قد أرسلنا طلبًا من نوع ‎GET‎ بنجاح باستخدام مكتبات نود فقط، حيث أن التابع الذي استخدمناه ‎get()‎ يوجد في نود بسبب كثرة الحاجة لإرسال الطلبات من نوع ‎GET‎، بينما الطريقة الأساسية لإرسال الطلبات هي باستخدام التابع ‎request()‎ والذي يمكنه إرسال أي نوع من الطلبات، وهو ما سنتعرف عليه في القسم التالي حيث سنستخدمه لإرسال طلب من نوع ‎GET‎.

إرسال الطلبات باستخدام التابع ‎request()‎

يمكن استخدام التابع ‎request()‎ بعدة صيغ والصيغة التي سنستخدمها في أمثلتنا هي كالتالي:

https.request(URL_String, Options_Object, Callback_Function) {
    Action
}

حيث نمرر له سلسلة نصية كمعامل أول تحتوي على مسار الواجهة البرمجية API الذي سنرسل الطلب إليه، والمعامل الثاني هو كائن جافاسكربت يحتوي على عدة خيارات للطلب المرسل، والمعامل الأخير المُمرر هو دالة رد النداء callback لمعالجة نتيجة الطلب.

نبدأ بإنشاء ملف جافاسكربت جديد بالاسم ‎getRequestWithRequest.js‎:

$ nano getRequestWithRequest.js

سنكتب برنامجًا مشابهًا لما كتبناه في القسم السابق ضمن الملف ‎getRequestWithGet.js‎، حيث نبدأ باستيراد الوحدة ‎https‎ كالتالي:

const https = require('https');

ثم نعرف كائن جافاسكربت يحتوي على الخاصية ‎method‎ كالتالي:

const https = require('https');

const options = {
  method: 'GET'
};

تعبر الخاصية ‎method‎ ضمن كائن خيارات التابع ‎request()‎ عن نوع الطلب الذي نريد إرساله، والآن نُرسل الطلب كما فعلنا سابقًا لكن مع بعض الاختلافات كالتالي:

...

let request = https.request('https://jsonplaceholder.typicode.com/users?_limit=2', options, (res) => {
  if (res.statusCode !== 200) {
    console.error(`Did not get an OK from the server. Code: ${res.statusCode}`);
    res.resume();
    return;
  }

  let data = '';

  res.on('data', (chunk) => {
    data += chunk;
  });

  res.on('close', () => {
    console.log('Retrieved all data');
    console.log(JSON.parse(data));
  });
});

request.end();

request.on('error', (err) => {
  console.error(`Encountered an error trying to make a request: ${err.message}`);
});

مررنا مسار الوجهة للطلب كمعامل أول للتابع ‎request()‎ ثم كائن خيارات HTTP كمعامل ثاني، وبعدها دالة رد النداء لمعالجة الرد، حيث حددنا نوع الطلب المرسل كطلب ‎GET‎ ضمن كائن الخيارات ‎options‎ الذي عرفناه سابقًا، وبقي دالة رد النداء لمعالجة الطلب كما هو في المثال السابق، وأضفنا استدعاءً للتابع ‎end()‎ من كائن الطلب ‎request‎، حيث يجب استدعاء هذا التابع عند إرسال الطلبات باستخدام ‎request()‎ لإتمام الطلب وإرساله، وفي حال لم نستدعيه فلن يُرسل الطلب ويبقى نود ينتظر منا إضافة بيانات جديدة إلى الطلب.

والآن نحفظ الملف ونخرج منه ثم ننفذ البرنامج:

$ node getRequestWithRequest.js

ليظهر الخرج التالي كما المثال السابق تمامًا:

Retrieved all data
[
  {
    id: 1,
    name: 'Leanne Graham',
    username: 'Bret',
    email: 'Sincere@april.biz',
    address: {
      street: 'Kulas Light',
      suite: 'Apt. 556',
      city: 'Gwenborough',
      zipcode: '92998-3874',
      geo: [Object]
    },
    phone: '1-770-736-8031 x56442',
    website: 'hildegard.org',
    company: {
      name: 'Romaguera-Crona',
      catchPhrase: 'Multi-layered client-server neural-net',
      bs: 'harness real-time e-markets'
    }
  },
  {
    id: 2,
    name: 'Ervin Howell',
    username: 'Antonette',
    email: 'Shanna@melissa.tv',
    address: {
      street: 'Victor Plains',
      suite: 'Suite 879',
      city: 'Wisokyburgh',
      zipcode: '90566-7771',
      geo: [Object]
    },
    phone: '010-692-6593 x09125',
    website: 'anastasia.net',
    company: {
      name: 'Deckow-Crist',
      catchPhrase: 'Proactive didactic contingency',
      bs: 'synergize scalable supply-chains'
    }
  }
]

وبذلك نكون قد تعرفنا على طريقة استخدام التابع ‎request()‎ لإرسال الطلبات من نوع ‎GET‎ وهو تابع أقوى من التابع السابق ‎get()‎ حيث يسمح بتخصيصات عدة على الطلب المرسل كتحديد نوعه وخيارات أخرى سنتعرف عليها في الفقرة التالية.

تخصيص خيارات HTTP للتابع ‎request()‎

يمكن استخدام التابع ‎request()‎ لإرسال طلبات HTTP دون تمرير عنوان مسار الوجهة للطلب كمعامل أول بل بتمريره ضمن كائن الخيارات ‎options‎ لتصبح صيغة استدعاء التابع كالتالي:

https.request(Options_Object, Callback_Function) {
    Action
}

في هذه الفقرة سنستخدم هذه الصيغة للتركيز على إعداد وتخصيص خيارات التابع ‎request()‎، لذا نعود إلى ملف المثال السابق ‎getRequestWithRequest.js‎ ونعدله بأن نزيل المسار URL المُمرر للتابع ‎request()‎ لتصبح المعاملات المُمررة له هي كائن الخيارات ‎options‎ ودالة رد النداء فقط كالتالي:

const https = require('https');

const options = {
  method: 'GET',
};

let request = https.request(options, (res) => {
...

لنضيف الخيارات الجديدة إلى الكائن ‎options‎ كالتالي:

const https = require('https');

const options = {
  host: 'jsonplaceholder.typicode.com',
  path: '/users?_limit=2',
  method: 'GET'
};

let request = https.request(options, (res) => {
...

نلاحظ أنه وبدلًا من تمرير المسار كاملًا فإننا نمرره على قسمين ضمن الخاصيتين ‎host‎ و ‎path‎ حيث تُعبّر الخاصية ‎host‎ عن عنوان النطاق أو عنوان IP للخادم الوجهة، أما الخاصية ‎path‎ فهي كل ما يلي بعد ذلك ضمن المسار بما فيها معاملات الاستعلام query parameters التي تأتي بعد إشارة الاستفهام.

ويمكن أن تحتوي الخيارات على بيانات مفيدة أخرى للطلب المرسل مثل الترويسات المرسلة وهي بيانات وصفية عن الطلب نفسه، فمثلًا عادة تتطلب الواجهة البرمجية API تحديد صيغة البيانات المرسلة من عدة صيغ مدعومة مثل JSON أو CSV أو XML، ولتحديد الصيغة التي يطلبها المستخدم يمكن للواجهة البرمجية معاينة قيمة الترويسة ‎Accept‎ ضمن الطلب الوارد إليها وتحدد على أساسه الصيغة المناسبة لإرسالها.

تُعبّر الترويسة ‎Accept‎ عن نوع البيانات التي يمكن للمستخدم التعامل معها، وبما أننا نتعامل مع واجهة برمجية تدعم صيغة JSON فقط، فيمكننا إضافة الترويسة ‎Accept‎ وإضافة قيمة لها توضح أننا نريد البيانات بصيغة JSON كالتالي:

const https = require('https');

const options = {
  host: 'jsonplaceholder.typicode.com',
  path: '/users?_limit=2',
  method: 'GET',
  headers: {
    'Accept': 'application/json'
  }
};

وبذلك نكون قد تعرفنا على أكثر أربعة خيارات استخدامًا ضمن طلبات HTTP وهي عنوان المضيف ‎host‎ و المسار ‎path‎ ونوع الطلب ‎method‎ والترويسات ‎headers‎، ويوجد العديد من الخيارات الأخرى المدعومة يمكنك الرجوع إلى التوثيق الرسمي لها ضمن نود للتعرف عليها.

والآن نحفظ الملف ونخرج منه ثم ننفذ البرنامج لنختبر طريقة إرسال الطلبات بتمرير كائن الخيارات فقط:

$ node getRequestWithRequest.js

ليظهر لنا بيانات الرد مطابقة للأمثلة السابقة:

Retrieved all data
[
  {
    id: 1,
    name: 'Leanne Graham',
    username: 'Bret',
    email: 'Sincere@april.biz',
    address: {
      street: 'Kulas Light',
      suite: 'Apt. 556',
      city: 'Gwenborough',
      zipcode: '92998-3874',
      geo: [Object]
    },
    phone: '1-770-736-8031 x56442',
    website: 'hildegard.org',
    company: {
      name: 'Romaguera-Crona',
      catchPhrase: 'Multi-layered client-server neural-net',
      bs: 'harness real-time e-markets'
    }
  },
  {
    id: 2,
    name: 'Ervin Howell',
    username: 'Antonette',
    email: 'Shanna@melissa.tv',
    address: {
      street: 'Victor Plains',
      suite: 'Suite 879',
      city: 'Wisokyburgh',
      zipcode: '90566-7771',
      geo: [Object]
    },
    phone: '010-692-6593 x09125',
    website: 'anastasia.net',
    company: {
      name: 'Deckow-Crist',
      catchPhrase: 'Proactive didactic contingency',
      bs: 'synergize scalable supply-chains'
    }
  }
]

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

أرسلنا ضمن كل الأمثلة السابقة طلبات فقط من نوع ‎GET‎ لجلب البيانات، وفي الفقرة التالية سنتعلم طريقة إرسال الطلبات من نوع ‎POST‎ والتي تستخدم لرفع البيانات إلى الخادم.

إرسال طلب من نوع ‎POST‎

نستخدم الطلبات من نوع ‎POST‎ لرفع البيانات إلى الخادم أو لطلب إنشاء بيانات جديدة من قبل الخادم، وفي هذه الفقرة سنتعرف على طريقة إرسال مثل هذه الطلبات في نود عبر إرسال طلب إنشاء مستخدم جديد إلى المسار ‎users‎ على الواجهة البرمجية API.

يمكننا إعادة استخدام بعض الشيفرات من مثال إرسال طلب من نوع ‎GET‎ السابق لإرسال طلبات من نوع ‎POST‎ مع إجراء بعض التعديلات عليها:

• تعديل نوع الطلب ضمن كائن الخيارات ‎options‎ ليصبح ‎POST‎.
• تعيين ترويسة نوع المحتوى المُرسل وهو في حالتنا بصيغة JSON.
• التأكد من رمز الحالة للرد لتأكيد نجاح إنشاء مستخدم جديد.
• رفع بيانات المستخدم الجديد.

نبدأ بإنشاء ملف جافاسكربت جديد بالاسم ‎postRequest.js‎ ونفتحه ضمن محرر النصوص:

$ nano postRequest.js

ونبدأ كما سابقًا باستيراد الوحدة ‎https‎ وتعريف كائن الخيارات ‎options‎ كالتالي:

const https = require('https');

const options = {
  host: 'jsonplaceholder.typicode.com',
  path: '/users',
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json; charset=UTF-8'
  }
};

ونعدل خيار مسار الطلب ‎path‎ ليتوافق مع مسار إرسال الطلبات من نوع ‎POST‎ على الخادم، ونعدل خيار نوع الطلب المرسل ‎method‎ إلى القيمة ‎POST‎، وأخيرًا نضيف الترويسة ‎Content-Type‎ ضمن الخيارات والتي تدل الخادم على نوع البيانات التي أرسلناها مع الطلب وهي في حالتنا بصيغة JSON وبترميز من نوع UTF-8، ثم نُرسل الطلب باستدعاء التابع ‎request()‎ كما فعلنا تمامًا عند إرسال طلب من نوع ‎GET‎ سابقًا ولكن هذه المرة سنتحقق من رمز الحالة للرد بقيمة تختلف عن 200 كالتالي:

...
const request = https.request(options, (res) => {
  if (res.statusCode !== 201) {
    console.error(`‎Did not get a Created from the server. Code: ${res.statusCode}‎`);
    res.resume();
    return;
  }

  let data = '';

  res.on('data', (chunk) => {
    data += chunk;
  });

  res.on('close', () => {
    console.log('Added new user');
    console.log(JSON.parse(data));
  });
});

تحققنا من صحة العملية بالتحقق من قيمة رمز الحالة بأن يساوي 201، وهو الرمز الذي يدل على إنشاء مورد جديد على الخادم بنجاح، ويُعبّر الطلب المرسل عن إنشاء مستخدم جديد لهذا سنحتاج لرفع بيانات هذا المستخدم وإرفاقها ضمن الطلب، لذا سننشئ تلك البيانات كالتالي:

...

const requestData = {
  name: 'New User',
  username: 'hsoub',
  email: 'user@hsoub.com',
  address: {
    street: 'North Pole',
    city: 'Murmansk',
    zipcode: '12345-6789',
  },
  phone: '555-1212',
  website: 'hsoub.com',
  company: {
    name: 'Hsoub',
    catchPhrase: 'Welcome to hsoub academy',
    bs: 'cloud scale security'
  }
};

request.write(JSON.stringify(requestData));

عرفنا بيانات المستخدم الجديد ضمن المتغير ‎requestData‎ على شكل كائن جافاسكربت يحتوي على بيانات المستخدم، ونلاحظ أننا لم نرفق قيمة المعرف ‎id‎ للمستخدم حيث أن هذه القيمة يولدها الخادم تلقائيًا للبيانات الجديدة، ثم استدعينا التابع ‎request.write()‎ والذي يقبل سلسلة نصية أو كائن مخزن مؤقت buffer ليتم إرسالها ضمن الطلب، وبما أن البيانات لدينا ضمن المتغير ‎requestData‎ هي كائن جافاسكربت فيجب تحويله إلى سلسلة نصية باستخدام ‎JSON.stringify‎.

ولإنهاء عملية الإرسال ننهي الطلب عبر استدعاء request.end()‎ ونتحقق من حدوث أي أخطاء في عملية الإرسال كالتالي:

...

request.end();

request.on('error', (err) => {
  console.error(`‎Encountered an error trying to make a request: ${err.message}‎`);
});

من الضروري استدعاء التابع ‎end()‎ لإنهاء الطلب وللإشارة إلى نود بأن كل البيانات التي نريد إرسالها ضمن الطلب قد أرفقت وأصبح بالإمكان إرساله.

والآن نحفظ الملف ونخرج منه ثم ننفذ البرنامج ونتأكد من عملية إنشاء المستخدم الجديد:

$ node postRequest.js

سنحصل على الخرج التالي:

Added new user
{
  name: 'New User',
  username: 'hsoub',
  email: 'user@hsoub.com',
  address: { street: 'North Pole', city: 'Murmansk', zipcode: '12345-6789' },
  phone: '555-1212',
  website: 'hsoub.com',
  company: {
    name: 'Hsoub',
    catchPhrase: 'Welcome to the hsoub academy',
    bs: 'cloud scale security'
  },
  id: 11
}

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

إرسال طلب من نوع ‎PUT‎

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

نختبر ذلك بإنشاء طلب من نوع ‎PUT‎ لتعديل اسم المستخدم لأول مستخدم، وبما أن طريقة إرسال الطلب مشابهة لطريقة إرسال الطلب من نوع ‎POST‎ يمكننا الاستفادة من المثال السابق ونسخ الملف ‎postRequest.js‎ إلى ملف جديد بالاسم ‎putRequest.js‎ كالتالي:

$ cp postRequest.js putRequest.js

نفتح الملف ‎putRequest.js‎ ضمن محرر النصوص:

$ nano putRequest.js

ونعدل نوع الطلب إلى ‎PUT‎ ومساره إلى ‎https://jsonplaceholder.typicode.com/users/1‎ والبيانات المرسلة كالتالي:

const https = require('https');

const options = {
  host: 'jsonplaceholder.typicode.com',
  path: '/users/1',
  method: 'PUT',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json; charset=UTF-8'
  }
};

const request = https.request(options, (res) => {
  if (res.statusCode !== 200) {
    console.error(`‎Did not get an OK from the server. Code: ${res.statusCode}‎`);
    res.resume();
    return;
  }

  let data = '';

  res.on('data', (chunk) => {
    data += chunk;
  });

  res.on('close', () => {
    console.log('Updated data');
    console.log(JSON.parse(data));
  });
});

const requestData = {
  username: 'hsoub'
};

request.write(JSON.stringify(requestData));

request.end();

request.on('error', (err) => {
  console.error(`‎Encountered an error trying to make a request: ${err.message}‎`);
});

نلاحظ تعديل قيم المسار ‎path‎ ونوع الطلب ‎method‎ ضمن كائن الخصائص ‎options‎ حيث يحوي المسار على معرّف المستخدم الذي نود تعديل بياناته، ثم نتحقق من من رمز الحالة للطلب بأن يكون بالقيمة 200 ما يدل على نجاح الطلب، ونلاحظ أن البيانات التي أرسلناها تحوي فقط على الخصائص التي نريد تحديثها من بيانات المستخدم.

والآن نحفظ الملف ونخرج منه ثم ننفذ البرنامج:

$ node putRequest.js

ليظهر الخرج التالي:

Updated data
{ username: 'hsoub', id: 1 }

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

إرسال طلب من نوع ‎DELETE‎

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

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

$ cp getRequestWithRequest.js deleteRequest.js

ونفتح الملف الجديد ضمن محرر النصوص:

$ nano deleteRequest.js

ونعدل الشيفرة لإرسال طلب حذف لأول مستخدم كالتالي:

const https = require('https');

const options = {
  host: 'jsonplaceholder.typicode.com',
  path: '/users/1',
  method: 'DELETE',
  headers: {
    'Accept': 'application/json',
  }
};

const request = https.request(options, (res) => {
  if (res.statusCode !== 200) {
    console.error(`‎Did not get an OK from the server. Code: ${res.statusCode}‎`);
    res.resume();
    return;
  }

  let data = '';

  res.on('data', (chunk) => {
    data += chunk;
  });

  res.on('close', () => {
    console.log('Deleted user');
    console.log(JSON.parse(data));
  });
});

request.end();

request.on('error', (err) => {
  console.error(`‎Encountered an error trying to make a request: ${err.message}‎`);
});

عدلنا قيمة المسار ‎path‎ ضمن كائن خيارات الطلب ليحوي معرّف المستخدم الذي نريد حذفه، وعدلنا نوع الطلب إلى ‎DELETE‎، والآن نحفظ الملف ونخرج منه ثم ننفذ البرنامج كالتالي:

$ node deleteRequest.js

لنحصل على الخرج:

Deleted user
{}

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

خاتمة

تعرفنا في هذا الفصل على طريقة إرسال الطلبات في نود بأنواعها مختلفة مثل ‎GET‎ و ‎POST‎ و ‎PUT‎ و ‎DELETE‎ دون استخدام أي مكتبات خارجية وفقط باستخدام الوحدة البرمجية ‎https‎ التي يوفرها نود، وتعرفنا على طريقة خاصة لإرسال الطلبات من نوع ‎GET‎ باستخدام التابع ‎get()‎ وكيف أن باقي الطلبات يمكن إرسالها باستخدام التابع ‎request()‎، وتعاملنا ضمن الأمثلة مع واجهة برمجية API عامة ويمكن بنفس الطريقة إرسال الطلبات إلى مختلف أنواع الواجهات البرمجية.

ترجمة -وبتصرف- للمقال How To Create an HTTP Client with Core HTTP in Node.js.

اقرأ أيضًا

• المقال السابق: التعامل مع الملفات باستخدام الوحدة fs في Node.js
• مدخل إلى خادم الويب
• مدخل إلى HTTP: شرح التخاطب بين العميل والخادم
• رموز الإجابة في HTTP

كثيرًا ما نحتاج للتعامل مع نظام الملفات، فمثلًا لتخزين بعض الملفات بعد تنزيلها، أو لترتيب بعض البيانات ضمن مجلدات أو لقراءة الملفات للتعامل مع محتوياتها ضمن بعض التطبيقات، وحتى تطبيقات النظم الخلفية أو أدوات واجهة سطر الأوامر CLI قد تحتاج أحيانًا لحفظ بعض البيانات إلى ملفات، والتطبيقات التي تتعامل مع البيانات تحتاج أحيانًا لتصديرها بمختلف الصيغ مثل JSON أو CSV أو ملفات برنامج إكسل، فكل تلك المتطلبات تحتاج للتعامل مع نظام الملفات ضمن نظام التشغيل التي تعمل عليه.

توفر نود طريقة برمجية للتعامل مع الملفات باستخدام الوحدة البرمجية ‎fs‎، وهي اختصار لجملة "نظام الملفات" أو "file system" حيث تحتوي على العديد من التوابع التي نحتاجها لقراءة الملفات أو الكتابة إليها أو حذفها، وهذه المزايا تجعل من لغة جافاسكربت لغة مفيدة لاستخدامها ضمن تطبيقات النظم الخلفية و أدوات سطر الأوامر.

سنتعرف في هذا المقال على الوحدة البرمجية ‎fs‎ وسنستخدمها لقراءة الملفات وإنشاء ملفات جديدة والكتابة إليها وحذف الملفات وحتى نقل الملفات من مجلد إلى آخر، حيث توفر الوحدة البرمجية ‎fs‎ توابع للتعامل مع الملفات بالطريقتين المتزامنة synchronously واللامتزامنة asynchronously وباستخدام مجاري البيانات streams، حيث سنستخدم في هذا المقال الطريقة اللامتزامنة باستخدام الوعود Promises وهي الطريقة الأكثر استخدامًا.

المستلزمات

• نسخة نود مثبتة على الجهاز، والتي ستوفر الوحدة البرمجية ‎fs‎ التي سنتعامل معها، حيث استخدمنا في هذا المقال الإصدار رقم 10.22.0.
• سنستخدم ضمن الأمثلة الوعود في جافاسكربت مع صيغة اللاتزامن والانتظار ‎async/await‎ للتعامل مع الملفات، وللتعرف أكثر على هذه الصيغة يمكنك مراجعة مقال طرق كتابة شيفرات غير متزامنة التنفيذ في Node.js من هذه السلسة.

قراءة الملفات باستخدام ‎readFile()‎

سنطور في هذه الفقرة برنامجًا في نود لقراءة الملفات، وسنستعين بالتابع ‎readFile()‎ الذي توفره الوحدة البرمجية ‎fs‎ في نود لقراءة محتوى ملف معين وتخزينه ضمن متغير ثم طباعته إلى الطرفية.

سنبدأ بإعداد المجلد الذي سيحوي على ملفات الأمثلة المستخدمة في هذا المقال ونُنشئ لذلك مجلدًا جديدًا بالاسم ‎node-files‎ كالتالي:

$ mkdir node-files

وندخل لذلك المجلد باستخدام الأمر ‎cd‎:

$ cd node-files

ننشئ داخل المجلد ملفين الأول هو الملف الذي سنحاول قراءته باستخدام البرنامج، والثاني هو ملف جافاسكربت للبرنامج الذي سنطوره، ونبدأ بإنشاء ملف جديد يحوي المحتوى النصي ‎greetings.txt‎، وهنا سنُنشئ الملف عن طريق سطر الأوامر كالتالي:

$ echo "hello, hola, bonjour, hallo" > greetings.txt

في الأمر السابق سيطبع الأمر ‎echo‎ النص المُمرر له إلى الطرفية، واستخدمنا المعامل ‎>‎ لإعادة توجيه خرج الأمر ‎echo‎ إلى الملف النصي الجديد ‎greetings.txt‎.

والآن ننشئ ملف جافاسكربت جديد للبرنامج بالاسم ‎readFile.js‎ ونفتحه باستخدام أي محرر نصوص، حيث سنستخدم ضمن أمثلتنا محرر النصوص ‎nano‎ كالتالي:

$ nano readFile.js

يتكون البرنامج الذي سنكتبه من ثلاث أقسام رئيسية، حيث نبدأ أولًا باستيراد الوحدة البرمجية التي تحوي توابع التعامل مع الملفات كالتالي:

const fs = require('fs').promises;

تحوي الوحدة ‎fs‎ كافة التوابع المستخدمة في التعامل مع نظام الملفات، ونلاحظ كيف استوردنا منها الجزء ‎.promises‎ حيث كانت طريقة كتابة الشيفرة اللامتزامنة سابقًا ضمن الوحدة ‎fs‎ عبر استخدام دوال رد النداء callbacks، ولاحقًا وبعد أن انتشر استخدام الوعود كطريقة بديلة أضاف فريق التطوير في نود دعمًا لها ضمن الوحدة ‎fs‎، حيث وبدءًا من الإصدار رقم 10 من نود أضيفت الخاصية ‎promises‎ ضمن كائن الوحدة البرمجية ‎fs‎ والتي تحوي التوابع التي تدعم طريقة الوعود، بينما بقي عمل الوحدة البرمجية ‎fs‎ الأساسية كما هي سابقًا باستخدام توابع رد النداء لدعم البرامج التي تستخدم الطريقة القديمة، وفي أمثلتنا سنستخدم نسخة التوابع التي تعتمد على الوعود.

في القسم الثاني من البرنامج سنضيف دالة لامتزامنة لقراءة محتوى الملف، حيث يمكن تعريف الدوال اللامتزامنة في جافاسكربت بإضافة الكلمة ‎async‎ في بدايتها، وبذلك نستطيع ضمن التابع انتظار نتيجة كائنات الوعود باستخدام الكلمة ‎await‎ مباشرةً بدلًا من ربط العمليات المتتالية باستخدام التابع ‎.then()‎.

والآن نعرف الدالة ‎readFile()‎ التي تقبل سلسلة نصية ‎filePath‎ تمثِّل مسار الملف الذي نود قراءته، حيث سنستعين بتوابع الوحدة ‎fs‎ لقراءة محتوى الملف المطلوب وتخزينه ضمن متغير باستخدام صيفة ‎async/await‎ كالتالي:

const fs = require('fs').promises;

async function readFile(filePath) {
  try {
    const data = await fs.readFile(filePath);
    console.log(data.toString());
  } catch (error) {
    console.error(`‎Got an error trying to read the file: ${error.message}‎`);
  }
}

يمكن التقاط الأخطاء التي قد يرميها استدعاء التابع ‎fs.readFile()‎ باستخدام ‎try...catch‎، حيث نستدعي التابع ‎fs.readFile()‎ ضمن جسم ‎try‎ ثم نخزن النتيجة ضمن المتغير ‎data‎، ويقبل ذلك التابع معاملًا وحيدًا إجباريًا وهو مسار الملف الذي نود قراءته، ويعيد كائن مخزن مؤقت ‎buffer‎ كنتيجة لعملية القراءة حيث يمكن لهذا الكائن أن يحوي أي نوع من الملفات، ولكي نطبع ذلك المحتوى إلى الطرفية يجب تحويله إلى سلسلة نصية باستخدام التابع ‎toString()‎ من كائن المخزن المؤقت.

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

أما القسم الثالث والأخير من البرنامج هو استدعاء دالة قراءة الملف مع تمرير اسم الملف ‎greetings.txt‎ ليصبح البرنامج كالتالي:

const fs = require('fs').promises;

async function readFile(filePath) {
  try {
    const data = await fs.readFile(filePath);
    console.log(data.toString());
  } catch (error) {
    console.error(`Got an error trying to read the file: ${error.message}`);
  }
}

readFile('greetings.txt');

نحفظ الملف ونخرج منه وفي حال كنت تستخدم أيضًا محرر النصوص nano يمكنك الخروج بالضغط على الاختصار ‎CTRL+X‎، وعند تنفيذ البرنامج سيقرأ المحتوى النصي للملف ‎greetings.txt‎ ويطبع محتواه إلى الطرفية، والآن ننفذ البرنامج عبر الأمر ‎node‎ لنرى النتيجة:

$ node readFile.js

بعد تنفيذ الأمر سيظهر الخرج التالي:

hello, hola, bonjour, hallo

وبذلك نكون قد استخدمنا التابع ‎readFile()‎ من الوحدة ‎fs‎ لقراءة محتوى الملف باستخدام صيغة ‎async/await‎.

ملاحظة: إذا كنت تستخدم إصدارًا قديمًا من نود وحاولت استخدام الوحدة ‎fs‎ بالطريقة السابقة سيظهر لك رسالة التحذير التالية:

(node:13085) ExperimentalWarning: The fs.promises API is experimental

حيث أن الخاصية ‎promises‎ من الوحدة ‎fs‎ تم اعتمادها رسميًا منذ الإصدار 10 من نود، وقبل ذلك كانت في المرحلة التجريبية وهذا سبب رسالة التحذير السابقة، ولاحقًا وتحديدًا ضمن إصدار نود رقم 12.6 أصبحت التوابع ضمن تلك الخاصية مستقرة وأزيلت رسالة التحذير تلك.

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

كتابة الملفات باستخدام ‎writeFile()‎

سنتعلم في هذه الفقرة طريقة كتابة الملفات باستخدام التابع ‎writeFile()‎ من الوحدة البرمجية ‎fs‎، وذلك بكتابة ملف بصيغة CSV يحـوي على بيانات لفاتورة شراء، حيث سنبدأ بإنشاء ملف جديد وإضافة ترويسات عناوين الأعمدة له، ثم سنتعلم طريقة إضافة بيانات جديدة إلى نهاية الملف.

نبدأ أولًا بإنشاء ملف جافاسكربت جديد للبرنامج ونفتحه باستخدام محرر النصوص كالتالي:

$ nano writeFile.js

ونستورد الوحدة ‎fs‎ كالتالي:

const fs = require('fs').promises;

وسنستخدم في هذا المثال أيضًا صيغة ‎async/await‎ لتعريف دالتين، الأولى لإنشاء ملف CSV جديد والثانية لكتابة بيانات جديدة إليه.

نفتح الملف ضمن محرر النصوص ونضيف الدالة التالي:

const fs = require('fs').promises;

async function openFile() {
  try {
    const csvHeaders = 'name,quantity,price'
    await fs.writeFile('groceries.csv', csvHeaders);
  } catch (error) {
    console.error(`Got an error trying to write to a file: ${error.message}`);
  }
}

نُعرّف المتغير ‎csvHeaders‎ والذي يحتوي على عناوين رؤوس الأعمدة لملف CSV، ثم نستدعي التابع ‎writeFile()‎ من وحدة ‎fs‎ لإنشاء ملف جديد وكتابة البيانات إليه، حيث أن المعامل الأول المُمرر له هو مسار الملف الجديد، وإذا مررنا اسم الملف فقط فسيُنشَأ الملف الجديد ضمن المسار الحالي لتنفيذ البرنامج، وأما المعامل الثاني المُمرر هو البيانات التي نريد كتابتها ضمن الملف، وفي حالتنا هي عناوين الأعمدة الموجودة ضمن المتغير ‎csvHeaders‎.

والآن نضيف الدالة الثانية ومهمتها إضافة بيانات جديدة ضمن ملف الفاتورة كالتالي:

const fs = require('fs').promises;

async function openFile() {
  try {
    const csvHeaders = 'name,quantity,price'
    await fs.writeFile('groceries.csv', csvHeaders);
  } catch (error) {
    console.error(`Got an error trying to write to a file: ${error.message}`);
  }
}

async function addGroceryItem(name, quantity, price) {
  try {
    const csvLine = `\n${name},${quantity},${price}`
    await fs.writeFile('groceries.csv', csvLine, { flag: 'a' });
  } catch (error) {
    console.error(`Got an error trying to write to a file: ${error.message}`);
  }
}

عرفنا الدالة اللامتزامنة ‎addGroceryItem()‎ التي تقبل ثلاثة مُعاملات، وهي اسم المنتج والكمية والسعر للقطعة الواحدة منه، ويتم إنشاء السطر الجديد الذي نود كتابته إلى الملف باستخدام قالب نص template literal وتخزينه ضمن المتغير ‎csvLine‎، ثم نستدعي التابع ‎writeFile()‎ كما فعلنا سابقًا ضمن التابع الأول ‎openFile()‎، ولكن هذه المرة سنمرر كائن جافاسكربت كمعامل ثالث يحتوي على المفتاح ‎flag‎ بالقيمة ‎a‎، وتعبر تلك القيمة عن الرايات المستخدمة للتعامل مع نظام الملفات، والراية ‎a‎ هنا تخبر نود بأننا نريد إضافة ذلك المحتوى إلى الملف، وليس إعادة كتابة محتوى الملف كاملًا، وفي حال لم نمرر أي راية عند كتابة الملف كما فعلنا ضمن الدالة الأولى فإن القيمة الافتراضية هي الراية ‎w‎ والتي تعني إنشاء ملف جديد في حال لم يكن الملف موجودًا، وإذا كان موجودًا سيتم تبديله وإعادة كتابة محتواه كاملًا، ويمكنك الرجوع إلى التوثيق الرسمي لتلك الرايات من نود للتعرف عليها أكثر.

والآن لننهي كتابة البرنامج باستدعاء الدوال التي عرّفناها كالتالي:

...
async function addGroceryItem(name, quantity, price) {
  try {
    const csvLine = `\n${name},${quantity},${price}`
    await fs.writeFile('groceries.csv', csvLine, { flag: 'a' });
  } catch (error) {
    console.error(`Got an error trying to write to a file: ${error.message}`);
  }
}

(async function () {
  await openFile();
  await addGroceryItem('eggs', 12, 1.50);
  await addGroceryItem('nutella', 1, 4);
})();

وبما أن الدوال التي سنستدعيها لامتزامنة، فيمكننا تغليفها بدالة لامتزامنة واستدعاءها مباشرة كي نستطيع استخدام ‎await‎ لانتظار إكمال تنفيذها، وذلك لأنه لا يمكن ضمن إصدار نود الذي نستخدمه حاليًا استخدام await مباشرة ضمن النطاق العام global scope، بل حصرًا ضمن دوال لامتزامنة تُستخدم ضمن تعريفها الكلمة async، ولا حاجة لتسمية تلك الدالة ويمكننا تعريفها كدالة مجهولة لأن الغرض منها فقط التغليف والتنفيذ المباشر ولن نشير إليها من أي مكان آخر.

وبما أن كلا الدالتين ‎openFile()‎ و ‎addGroceryItem()‎ لا متزامنين فبدون انتظار نتيجة استدعاء الدالة الأولى ثم استدعاء الثانية لا يمكن ضمان ترتيب التنفيذ وبالتالي ترتيب المحتوى ضمن الملف الذي نريد إنشاءه، لذلك عرفنا دالة التغليف تلك الغير متزامنة بين قوسين وأضفنا قوسي الاستدعاء في النهاية قبل الفاصلة المنقوطة كي لاستدعائها مباشرةً، وتُدعى تلك الصيغة بصيغة التنفيذ المباشر لدالة Immediately-Invoked Function Expression أو IIFE، وباستخدام تلك الصيغة في مثالنا نضمن احتواء ملف CSV الجديد على الترويسات بدايةً ثم أول سطر للمنتج ‎eggs‎ وبعده المنتج الثاني ‎nutella‎.

والآن نحفظ الملف ونخرج منه ثم ننفذ البرنامج باستخدام الأمر ‎node‎:

$ node writeFile.js

لن نلاحظ أي خرج من التنفيذ ولكن سنلاحظ إنشاء ملف جديد ضمن المجلد الحالي ويمكن معاينة محتوى الملف ‎groceries.csv‎ باستخدام الأمر ‎cat‎ كالتالي:

$ cat groceries.csv

ليظهر الخرج التالي:

name,quantity,price
eggs,12,1.5
nutella,1,4

أنشأت الدالة ‎openFile()‎ ملف CSV وأضافت الترويسات له، ثم أضافت استدعاءات الدالة ‎addGroceryItem()‎ التي تليها سطرين من البيانات إلى ذلك الملف، وبذلك نكون قد تعلمنا طريقة استخدام التابع ‎writeFile()‎ لإنشاء الملفات الجديدة والتعديل على محتواها.

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

حذف الملفات باستخدام ‎unlink()‎

سنتعلم في هذه الفقرة طريقة حذف الملفات باستخدام التابع ‎unlink()‎ من الوحدة البرمجية ‎fs‎، حيث سنكتب برنامجًا لحذف الملف ‎groceries.csv‎ الذي أنشأناه في الفقرة السابقة.

نبدأ بإنشاء ملف جافاسكربت جديد بالاسم deleteFile.js نُعرف ضمنه الدالة اللامتزامنة ‎deleteFile()‎ التي تقبل مسار الملف المراد حذفه، وبدورها ستمرر ذلك المعامل إلى التابع ‎unlink()‎ والذي سيحذف ذلك الملف من نظام الملفات كالتالي:

const fs = require('fs').promises;

async function deleteFile(filePath) {
  try {
    await fs.unlink(filePath);
    console.log(`Deleted ${filePath}`);
  } catch (error) {
    console.error(`Got an error trying to delete the file: ${error.message}`);
  }
}

deleteFile('groceries.csv');

تحذير: لن تُنقل الملفات المحذوفة باستخدام التابع ‎unlink()‎ إلى سلة المحذوفات بل ستُحذف نهائيًا من نظام الملفات، لذا تلك العملية لا يمكن الرجوع عنها ويجب الحذر والتأكد من الملفات التي نحاول حذفها قبل تنفيذ البرنامج.

والآن نخرج من الملف وننفذه كالتالي:

$ node deleteFile.js

ليظهر الخرج التالي:

Deleted groceries.csv

نستعرض الملفات الموجودة حاليًا بعد التنفيذ للتأكد من نجاح عملية الحذف باستخدام الأمر ‎ls‎ كالتالي:

$ ls

ليظهر لنا الملفات التالية:

deleteFile.js   greetings.txt   readFile.js     writeFile.js

نلاحظ حذف الملف بنجاح باستخدام التابع ‎unlink()‎، وبذلك نكون قد تعلمنا طريقة قراءة وكتابة وحذف الملفات، وسنتعلم في الفقرة التالية كيف يمكن نقل الملفات من مجلد لآخر، لنكون بذلك قد تعلمنا كافة العمليات التي تسمح بإدارة الملفات عن طريق نود.

نقل الملفات باستخدام ‎rename()‎

تُستخدم المجلدات لتنظيم وترتيب الملفات معًا، لذا من المفيد تعلم طريقة نقل تلك الملفات برمجيًا، حيث يتم ذلك في نود باستخدام التابع ‎rename()‎ من الوحدة ‎fs‎، وسنتعلم طريقة استخدامه بنقل الملف السابق ‎greetings.txt‎ إلى مجلد جديد مع إعادة تسميته.

نبدأ بإنشاء ذلك مجلد جديد بالاسم ‎test-data‎ ضمن المجلد الحالي كالتالي:

$ mkdir test-data

ونُنشئ نسخة عن الملف ‎greetings.txt‎ بتنفيذ أمر النسخ ‎cp‎ كالتالي:

$ cp greetings.txt greetings-2.txt

ثم نُنشئ ملف جافاسكربت للبرنامج كالتالي:

$ nano moveFile.js

ونُعرف ضمنه الدالة ‎moveFile()‎ لنقل الملف، والتي ستستدعي بدورها التابع ‎rename()‎ الذي يقبل مسار الملف المراد نقله كمعامل أول، ثم المسار الجديد الوجهة كمعامل ثانِ، ففي حالتنا نريد استخدام الدالة ‎moveFile()‎ لنقل الملف الجديد ‎greetings-2.txt‎ إلى المجلد الذي أنشأناه ‎test-data‎ مع إعادة تسمية ذلك الملف إلى ‎salutations.txt‎، ولذلك نضيف الشيفرة التالية:

const fs = require('fs').promises;

async function moveFile(source, destination) {
  try {
    await fs.rename(source, destination);
    console.log(`Moved file from ${source} to ${destination}`);
  } catch (error) {
    console.error(`Got an error trying to move the file: ${error.message}`);
  }
}

moveFile('greetings-2.txt', 'test-data/salutations.txt');