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

عقود الأخطاء المتزامنة وغير المتزامنة

مرر كل فشل مرة واحدة وحوله لرد آمن ما دامت الاستجابة تسمح بذلك.

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

في هذه الصفحة

أهداف الدرس

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

صنف الفشل قبل تنسيقه

تحتاج مخالفة التحقق والكائن المحجوب والنسخة القديمة وانقطاع المصدر غير المتوقع نتائج تطبيق مختلفة. بعض الحالات نتائج مجال متوقعة وبعضها فشل يحتاج دليلاً داخلياً مضبوطاً. توفر وسائط أخطاء Express مسار نقل لا تصنيفاً عالمياً لقواعد العمل. استخدم رموزاً عامة ثابتة وحالات مناسبة دون كشف رسالة قاعدة البيانات أو تتبع المكدس. والطلب الذي لا يطابق مساراً حالة غير مطابقة عادية ما لم يحولها التطبيق صراحة؛ لا يستدعي معالج الأخطاء تلقائياً لأن الرد النهائي ينبغي أن يكون 404. يساعد هذا الفصل على تشخيص السبب بدلاً من خلط الغياب والاستثناء.

أعد الوعد الذي يملك العمل غير المتزامن

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

javascript مسار توضيحي لوعد وخطأ في Express 5

app.get("/courses/:id", async (req,res) => {
  const course = await catalog.findVisible(req.principal,req.params.id);
  if (!course) return res.status(404).json({code:"COURSE_NOT_FOUND"});
  return res.json({id:course.id,title:course.title});
});
app.use((err,req,res,next) => {
  if (res.headersSent) return next(err);
  const plan = publicFailure(err);
  return res.status(plan.status).json(plan.body);
});

يربط وعد async المعاد فشل البحث بمعالج الأخطاء. يبقى المعالج ذو الوسائط الأربع واعتماد publicFailure توضيحيين غير مشغلين.

تحتاج ردود النداء وحد الإرسال إلى مسؤولية واضحة

تحدث أخطاء مؤقت أو حدث لاحق خارج مكدس المعالج المتزامن الأصلي. حول العملية إلى وعد ينتظر حيث يناسب، أو التقط خطأ رد النداء ومرره بمساره الموثق. اجعل مسؤولية التمرير واحدة ولا تستمر في إرسال رد بعد next(error). إذا أرسلت الترويسات بالفعل فلن يتاح رد بديل نظيف؛ مرر الحالة لما تبقى من مسار الأخطاء وحرر الموارد وفق سياسة التدفق أو الاتصال. لا يستطيع منسق الفشل العام التراجع عن تغيير حفظته قاعدة البيانات أو سحب بايتات وصلت للعميل. لذا يجب أن تسبق الفحوص الآثار التي يفترض منعها.

اربط الفئات الآمنة المعروفة وحدها

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

javascript موائم محلي كامل للخطأ العام

function publicFailure(error) {
  if (error?.code === "INVALID_TITLE") return {status:400,body:{code:"INVALID_TITLE"}};
  return {status:500,body:{code:"INTERNAL_ERROR"}};
}
console.assert(publicFailure({code:"INVALID_TITLE"}).status === 400);
const plan = publicFailure({status:200,message:"private-source-detail"});
console.assert(plan.status === 500);
console.assert(JSON.stringify(plan.body) === '{"code":"INTERNAL_ERROR"}');

ترتبط الفئة المعروفة بحالة 400، ويصبح الاستثناء المجهول ذو الحالة المضللة خطأ 500 عاماً بلا رسالته.

اختبر الرفض قبل الأثر والفشل بعده

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

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

يتجاوز رفض منفصل مسار خطأ المسار

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

لا يستقبل وسيط الأخطاء الخطأ

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

يسرب استثناء المصدر تفاصيل خاصة

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

اختبر فهمك

1. لماذا قد يبقى خطأ مؤقت غير معالج داخل مسار async؟

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

ينفذ رد المؤقت لاحقاً وقد لا ينتمي للوعد المعاد. يعالج Express رفض ذلك الوعد ولا يستنتج ملكية ردود مستقلة. حول العمل المناسب لعملية منتظرة أو التقطه ومرره تحت مسؤول واحد؛ فلا تلتقط async كل عمل مستقبلي.

2. لماذا تختلف مهلة بعد الحفظ عن رفض تحقق قبل الكتابة؟