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

عمارة التطبيق وحدود الموائم

حدد موضع وحدات Nest وخدمات التطبيق فوق موائم النقل المختار، واجعل بدء العملية مسؤولية صريحة.

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

في هذه الصفحة

أهداف الدرس

افصل رسم الوحدات وحاوية الاعتمادات وموائم HTTP.
اشرح دليل نموذج مجال محلي دون إقلاع Nest.

لا توفر بنية الإطار ضمانات المجال وحدها

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

اقرأ التركيب دون تشغيل خدمة

يسجل جزء الوحدة متحكماً وخدمة ويفترض تعريفهما مسبقاً. لا يتضمن الاستيراد أو إعداد الترجمة أو الإقلاع. تنتمي NestFactory.create وlisten لاحقاً لنقطة دخول صريحة؛ فلا يفتح استيراد وحدة مجال منفذاً أو يشغل ترحيلاً. لا تبني الحاوية رسماً صحيحاً إلا بتسجيل الاعتمادات المطلوبة وإتاحتها. يدرس المقرر الأجزاء دون تثبيت Nest أو إنشاء سياق تطبيق، ويشغل نماذج JavaScript كاملة مستقلة. يحفظ ذلك الفرق بين صحة فكرة تركيب على الورق وبين إثبات أن الحاوية الفعلية استطاعت حلها في مشروع معين.

typescript وحدة catalog توضيحية

@Module({
  controllers: [CoursesController],
  providers: [CatalogService],
})
export class CatalogModule {}

تصف البيانات التركيب فقط. يفترض المثال الفئات والمزخرفات ومشغل Nest ولم ينفذها.

اختر منصة HTTP بقصد

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

افصل إسقاط البيانات العامة عن الإطار

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

javascript إسقاط بطاقة محلي كامل

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

ينجح التأكيدان للعينة ويفحصان شكل الإخراج فقط دون تفويض أو مشغل Nest.

سجل الإصدار وافتراضات التنفيذ

يختار المقرر توثيق Nest 12 المراجع في 2026-10-28 ويبقي الأمثلة ضمن مفاهيم الوحدات والطلبات المستقرة. يميز دليل الانتقال متطلبات تشغيل التطبيق عن متطلبات CLI والتوليد الأعلى ويوثق حزم الأساس بصيغة ESM. لا تفترض أن مشغلاً ينفذ دالة محلية يستطيع توليد كل مشروع Nest أو اختباره. ثبت الحزم ونمط الوحدة والمترجم وأداة الاختبار قبل الدمج. تبقى أجزاء الإطار runnable:false، ولا يعني نجاح النموذج اختبار الإقلاع أو الخطافات أو حل الاعتمادات. يحدد هذا القيد ما يحتاج تحققاً مستقلاً قبل ممارسة حقيقية.

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

يفتح استيراد الوحدة مستمعاً

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

يكسر تبديل الموائم سلوك الرد

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

تظهر حقول خاصة في نتيجة عامة

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

اختبر فهمك

1. هل تثبت بيانات @Module أن الحاوية تستطيع بناء CatalogService؟

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

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

2. لماذا تفصل دالة اختيار الحقول العامة عن متحكم HTTP؟