NestJS / الأساسي: الوحدات وعقود الطلب / الدرس 6

دورة الطلب والحراس والمعترضات ومرشحات الاستثناء

أسند كل شأن مشترك لمرحلته الصحيحة وافهم أي فشل يتجاوز العمل اللاحق.

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

في هذه الصفحة

أهداف الدرس

تتبع الوسيط والحارس والمعترض وpipe والمعالج.
ميز نتيجة المجال المتوقعة عن ترجمة الاستثناء الآمنة.

الدورة عقد مرتب

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

وثق أين يثبت كل شرط سابق

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

json سجل اصطناعي لمراحل الطلب

{"inbound":["middleware","guards","interceptors-before","pipes","handler"],"outbound":"interceptors-unwind","uncaughtFailure":"applicable-exception-filter","objectPolicy":"shared-domain-service"}

يشرح السجل النموذج المختار ولا يرصد كل تفاصيل النطاق أو يشغل طلب Nest.

ترجم الفشل دون إخفاء عدم اليقين

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

اختبر توقف الشرط السابق بمنطق محلي

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

javascript نموذج محلي كامل لتدفق ممنوع

const trace=[];
for (const stage of ["middleware","guard","pipe","handler"]) {
  trace.push(stage); if (stage === "guard") break;
}
console.assert(JSON.stringify(trace) === '["middleware","guard"]');
console.assert(!trace.includes("handler"));

يتوقف عند الحارس الاصطناعي ولا ينشئ حراس Nest أو يختبر ترتيب المزخرف.

نسق التسجيل والاختبار

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

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

يثق الحارس في DTO محولة مسبقاً

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

يعيد المرشح تفاصيل مصدر خاصة

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

تفوت اختبارات المتحكم حارساً مربوطاً خطأ

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

اختبر فهمك

1. لماذا لا يستطيع الحارس الاعتماد على خرج pipe الخاصة بمعامل الطلب؟

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

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

2. هل يستطيع مرشح الاستثناء ضمان أن الكتابة الفاشلة لم تحفظ؟