NestJS / الأساسي: الوحدات وعقود الطلب / الدرس 2
المتحكمات والمسارات وعقود نتائج HTTP
حول إدخال النقل لاستدعاء مجال وأعد تمثيلاً مقصوداً دون تجاوز دورة رد الإطار.
في هذه الصفحة
أهداف الدرس
- اجمع بادئة المتحكم ومسار الطريقة بشكل صحيح.
- ميز القيم المعادة المعتادة عن معالجة رد المنصة.
المتحكم موائم لا حالة الاستخدام كلها
يربط المتحكم طلب النقل بقدرة تطبيق. تعرف المزخرفات الطرق والمسارات وتملك الخدمة المحقونة السلوك القابل لإعادة الاستخدام. تتجمع بادئة الفئة ومسار الطريقة مع البادئة العامة والإصدار؛ فراجعها معاً. يبقى المعامل الصحيح إدخالاً لا دليل صلاحية كائن. اجعل المتحكم ضيقاً لترى التحقق وتمرير الهوية والخدمة والنتيجة. لا يجعل نقل معاملة ضخمة لطريقة مزخرفة العزل صحيحاً لمجرد قدرة Nest على استدعائها. يحتاج العمل المتماسك خدمة بحدود واضحة يمكن أن يستعملها عامل أو موائم آخر أيضاً.
اقرأ عقد المسار من بياناته
يجمع الجزء courses و:id ليكون بحث GET ضمن بادئة التطبيق المضبوطة. يفترض الخدمة والاستيرادات. يصل id سلسلة ولا يحلل تعليق TypeScript القيمة وقت التشغيل. تمثل الخدمة سياسة قراءة عامة لا وصول قاعدة عشوائياً. تسمح القيمة المعادة لـNest بتسلسل النتيجة المختارة. لم يشغل المتحكم أو الحاوية أو الموائم؛ فالمطابقة عقد مستنتج لا مسار حي مختبر. إذا كانت القراءة خاصة فمرر الهوية صراحة ولا تنقل مثال العامة كما لو أنه سياسة تسمح بكل سجل.
@Controller("courses")
export class CoursesController {
constructor(private readonly catalog: CatalogService) {}
@Get(":id")
find(@Param("id") id: string) {
return this.catalog.publicCard(id);
}
}دون بادئة عامة إضافية يكون المسار GET /courses/:id. يبقى المعامل نصاً حتى تحقق وتحويل صريحين.
اختر مسؤول رد واحداً
يدير النمط القياسي الكائنات والوعود المعادة. قد ينقل حقن @Res الأصلي مسؤولية الإرسال إلى المنصة، فيجب إنهاء الرد ما لم يضبط المرور المناسب. يربك الجمع بين send أصلي وكائن معاد المسؤولية وقد يكرر العمل. تختلف الحالة الافتراضية حسب الطريقة ويعبر @HttpCode أو الاستثناء عن النتيجة المقصودة. لا تصمم جسماً مع 204. افصل عطل المصدر غير المتوقع عن الغياب بدلاً من تحويل كل فشل إلى كائن ناجح بحقل يبدو خطأ. يجب أن يفهم العميل هل تلقى تمثيلاً صالحاً أو رفضاً أو تعذراً في التنفيذ.
اربط نتيجة المجال قبل النقل
تحول الدالة السجل المرئي أو غيابه إلى خطة رد بحقوق ضيقة ورمز غياب موثق. لا تنشئ HttpException ولا تختبر تسلسله. قد يقصد المجال النتيجة العامة نفسها للمحجوب حتى لا يكشف وجوده؛ فاحفظ الاتساق. اختبر المعرف والعنوان لا الحالة وحدها، فقد يبدو الرد صحيحاً وهو لمستأجر آخر. لا يغير ربط النقل سياسة الإفصاح بصمت. تفيد الخطة في مراجعة القرار مستقلاً، ويبقى اختبار أن الاستثناء أو القيمة المعادة ينتجان HTTP المقصود حد دمج مختلفاً.
function resultPlan(record) {
return record ? {status:200,body:{id:record.id,title:record.title}}
: {status:404,body:{code:"COURSE_NOT_FOUND"}};
}
console.assert(resultPlan({id:"c1",title:"Routes"}).body.id === "c1");
console.assert(resultPlan(null).status === 404);يرتبط المرئي بالبطاقة المختارة والغياب بخطة 404 المعلنة دون إرسال HTTP.
تحقق من المسار والطريقة والأثر منفصلة
يختلف عدم مطابقة العنوان عن مطابقة مع غياب كائن. راجع الثابت قبل معامل واسع واحفظ عينات البادئة والإصدار. تحافظ GET على عقد القراءة الآمنة، وتحتاج الكتابة تحققاً وتفويضاً وتحملاً للإعادة. لا ينفذ المزخرف السياسات. اختبر المتحكم ببديل لتمرير الوسائط ثم التركيب للمطابقة والرد. يشغل المقرر موائم النتيجة فقط ولا يشغل التوجيه أو النقل. يساعد الفصل في عدم محاولة إصلاح البحث حين أن الطلب لم يصل إلى المتحكم أصلاً، أو اعتبار خطأ مصدر مجرد مسار غير موجود.
الأخطاء الشائعة وإصلاحها
يبقي التعليق العددي سلسلة وقت التشغيل
- لماذا يحدث؟
- اختلطت معلومات النوع وقت الترجمة بتحليل قيمة الطلب وقت التشغيل.
- كيف تصلحه؟
- استخدم pipe صريحة أو تحويلاً متحققاً منه في حد إدخال المجال.
- كيف تتجنب تكراره؟
- اختبر شكل القيم الفعلي الذي يصل إلى المعالج وقت التشغيل.
يعلق مسار رد أصلي
- لماذا يحدث؟
- تغيرت مسؤولية الرد إلى المعالج الأصلي، لكنه لم ينفذ إرسالاً نهائياً.
- كيف تصلحه؟
- اختر نمط العودة القياسي أو أنه الاستجابة الأصلية بقصد واضح.
- كيف تتجنب تكراره؟
- راجع كل فرع للاستجابة وافتراضات وضع المرور passthrough.
يعيد انقطاع المصدر بطاقة فارغة ناجحة
- لماذا يحدث؟
- دمج فشل المصدر مع الحالة المشروعة التي لا يوجد فيها كائن.
- كيف تصلحه؟
- احفظ فئات نتيجة المجال والخطأ المتميزة مع إفصاح آمن للمستدعي.
- كيف تتجنب تكراره؟
- اختبر المصدر الغائب والمصدر الذي يفشل كل حالة على حدة.
اختبر فهمك
1. ما جوانب Nest التي لا يثبتها موائم النتيجة المحلي؟
اعرض الحل المشروح
لا يثبت المثال تسجيل المزخرفات، أو مطابقة المسار، أو استخراج المعاملات، أو عمل مرشحات الاستثناء، أو إرسال حالة HTTP الفعلية. إنه يثبت قرار دالة JavaScript عادية في حالتي اختبار محددتين. احتفظ بالفصل بين هذه الادعاءات، واستخدم اختبار تطبيق مترجم للتحقق من حد المتحكم وموائم النقل الحقيقي عندما يكون ذلك الدمج مأذوناً به.
2. لماذا تتجنب إرجاع كيان التخزين كاملاً من المتحكم؟
اعرض الحل المشروح
قد تحمل حقول التخزين حالة داخلية لا يحتاجها المستدعي أو لا يجوز كشفها له. يجعل اختيار نموذج عام مراجع المفاتيح المسموحة مستقرة وقابلة للاختبار مستقلاً. طبق أهلية الوصول قبل اختيار الحقول، وراجع سلوك التسلسل إذا استعملت بيانات استبعاد مبنية على الفئة. آلية تنسيق الإخراج لا تعوض تفويض الوصول إلى الكائن نفسه.
أهم ما تعلمته
- تكيف المتحكمات المسارات وتملك الخدمات حالات الاستخدام.
- يحتاج الإدخال الفعلي ومسؤولية الرد قرارات صريحة.