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

بيانات الانعكاس والمزخرفات قوية النوع

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

بيانات الانعكاس والمزخرفات قوية النوع

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

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

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

تعمل SetMetadata()، لكن Reflector.createDecorator() يمنح نوعاً أقوى ويقلل أخطاء مفاتيح النصوص.
تصلح getAllAndOverride() عندما يجب أن تستبدل بيانات الدالة بيانات المتحكم.
تصلح getAllAndMerge() عندما يجب دمج بيانات الصنف والدالة.
البيانات الوصفية مكانها قرارات التنظيم، لا إخفاء قواعد العمل التي يجب أن تبقى في الخدمات.
تحافظ المزخرفات المركبة عبر applyDecorators() على وضوح المتحكم عندما يحتاج المسار حراساً وأدواراً وبيانات OpenAPI ومعترضات معاً.

مثال عملي

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

export const Roles = Reflector.createDecorator<string[]>();

export function AdminEndpoint(summary: string) {
  return applyDecorators(
    Roles(['admin']),
    UseGuards(JwtAuthGuard, RolesGuard),
    ApiBearerAuth(),
    ApiOperation({ summary }),
  );
}

@AdminEndpoint('List billing reports')
@Get('reports')
findReports() {
  return this.reportsService.findAll();
}

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

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

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

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

الخلاصة

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