Express.js / الأساسي: مسؤولية الطلب والاستجابة / الدرس 1

التطبيق وHTTP ودورة حياة الطلب

حدد موضع Express داخل دورة HTTP في Node.js، وافصل بناء التطبيق عن امتلاك خادم يستمع للاتصالات.

وقت القراءة التقريبي: 4 دقيقةتاريخ مراجعة المحتوى 2026-10-28

في هذه الصفحة

أهداف الدرس

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

حتى الإطار الصغير يحتاج عقود تطبيق

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

ابن التطبيق دون فتح اتصال يستمع

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

javascript مصنع تطبيق توضيحي

function createApp(express, catalog) {
  const app = express();
  app.get("/courses/:id", async (req, res) => {
    const course = await catalog.findPublic(req.params.id);
    if (!course) return res.status(404).json({code:"COURSE_NOT_FOUND"});
    return res.json({id:course.id, title:course.title});
  });
  return app;
}

يسجل الجزء مسار GET ويعيد التطبيق دون استدعاء listen. يبقى البحث في المجال اعتماداً محقوناً لم ينفذ في المثال.

لكل معالج مسؤولية إنهاء المسار أو تمرير التحكم

يستقبل الوسيط المعتاد req وres وnext. يستطيع فحص الطلب، أو إرفاق معلومات خاصة به، أو إنهاء الرد، أو تمرير التحكم. استدعاء next يتابع سلسلة المعالجات المناسبة ولا يعني أن الرد أرسل. وإرسال الرد لا يوقف تنفيذ JavaScript داخل الدالة؛ لذا استعمل return صراحة عندما يجب ألا تنفذ الأسطر اللاحقة. إذا لم ينه الوسيط الرد ولم يستدع next ولم يترك مساراً غير متزامن سيكمل العمل، ظل الطلب معلقاً. فسر ذلك كمسؤولية مفقودة عن دورة الطلب، لا كمشكلة تعالجها زيادة المهلة.

اجعل إسقاط البيانات العامة قابلاً لاختبار مستقل

تختار الدالة المحلية حقول البطاقة العامة وحدها من سجل مصدر اصطناعي. لا تعتمد نتيجتها الحتمية على Express أو HTTP. يسهل فصل هذا الإسقاط ملاحظة غياب الخاصية الداخلية والتحقق من شكل الرد المقصود. لكنه لا ينفذ نظام تفويض كاملاً؛ فما زال على المستدعي تقديم سجل مسموح وفق سياسة المجال. لا تسلسل كيان قاعدة البيانات كله لمجرد قدرة res.json على ذلك. سهولة الأداة لا تقرر هل ملاحظات التسجيل أو حقول المراجعة الداخلية مناسبة للاستجابة العامة.

javascript نموذج محلي كامل لإسقاط الحقول العامة

function courseCard(record) {
  return {id:record.id, title:record.title};
}
const record = {id:"c1",title:"HTTP foundations",internalNote:"lab-only"};
const card = courseCard(record);
console.assert(JSON.stringify(card) === '{"id":"c1","title":"HTTP foundations"}');
console.assert(!Object.hasOwn(card,"internalNote"));

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

سجل الإصدار الفعلي ومسؤولية التشغيل

يتطلب Express 5 إصدار Node.js 18 أو أحدث، لكن الحد الأدنى لا يحدد أي فرع سيظل مدعوماً عند موعد نشر لاحق. اختر مشغلاً مدعوماً وسجل نسخته مستقلاً، وثبت الإطار وراجع ملاحظات انتقاله. تحتاج أمثلة CommonJS وESM إعداد وحدات متوافقاً؛ فلا تمزج require وimport عشوائياً. يجب أن يمتلك طرف واضح التحقق من الإعداد والاستماع والمهام الخلفية والإيقاف. يستخدم المقرر Node.js 22.23.3 للنماذج المحلية المعزولة فقط، ولا يدعي اختبار تثبيت Express أو نشر إنتاجي.

الأخطاء الشائعة وإصلاحها

يبقى الطلب معلقاً دون نهاية

لماذا يحدث؟: لم ينه الوسيط المختار الاستجابة ولم يمرر التحكم إلى ما يكملها.
كيف تصلحه؟: حدد لكل فرع رداً أو استدعاء next أو إكمالاً غير متزامن يملك مسؤوليته.
كيف تتجنب تكراره؟: راجع فروع الإكمال بعينات مسموحة وأخرى مرفوضة.

تحجز الاختبارات منفذاً دون توقع

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

تظهر حقول المصدر الخاصة في JSON

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

اختبر فهمك

1. هل يفتح createApp منفذاً أو يثبت نجاح الوصول إلى catalog؟

اعرض الحل المشروح

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

2. لماذا يفيد return res.status(404).json(...) داخل فرع if؟