NestJS — Node.js للمؤسسات

البادئة العامة والجسم الخام والتطبيقات الهجينة

18 دقيقة الدرس 56 من 80

البادئة العامة والجسم الخام والتطبيقات الهجينة

تحتاج واجهات API الإنتاجية غالباً إلى اختيارات HTTP على مستوى المنصة تؤثر في كل مسار: بادئة /api عامة، أو ترقيم إصدارات عبر URI أو الرؤوس، أو جسم طلب خام لتوقيعات الويب هوك، أو خيارات HTTPS، أو تطبيق هجين يجمع HTTP وخدمة مصغرة.

الفكرة الأساسية

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

تحافظ setGlobalPrefix() على تجميع مسارات API وتسمح بوجود المسارات الساكنة أو الواجهة بجانبها.
تدعم enableVersioning() استراتيجيات إصدار عبر URI أو الرأس أو نوع الوسائط أو استخراج مخصص.
يجب تفعيل الجسم الخام قبل تحليل الجسم عند التحقق من توقيعات Stripe أو GitHub أو مزودي الدفع.
تربط connectMicroservice() خادم خدمة مصغرة بسياق تطبيق Nest نفسه.
يمكن ضبط HTTPS وخوادم متعددة أثناء الإقلاع، لكن الوكيل العكسي غالباً أنظف في الإنتاج.

مثال عملي

يوضح المثال التالي الشكل العملي للفكرة داخل مشروع NestJS. ليست الغاية حفظ الكود، بل فهم مكانه في المعمارية:

const app = await NestFactory.create(AppModule, { rawBody: true });

app.setGlobalPrefix('api', { exclude: ['health'] });
app.enableVersioning({ type: VersioningType.URI });

app.connectMicroservice<MicroserviceOptions>({
  transport: Transport.TCP,
  options: { host: '0.0.0.0', port: 4001 },
});

await app.startAllMicroservices();
await app.listen(3000);

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

قائمة تطبيق إنتاجية

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

قاعدة عملية: إذا جعلت الميزة الحدود أوضح والاختبارات أسهل فهي اختيار جيد. إذا أخفت التبعيات أو صعّبت التتبع، فأعد التصميم.

الخلاصة

يغطي هذا الدرس جزءاً متقدماً من NestJS يجب فهمه عند بناء تطبيقات مؤسسية. ركّز على الحدود الواضحة، والسلوك القابل للاختبار، واختيار الأداة المناسبة للسياق بدلاً من استخدام كل ميزة في كل مكان.