NestJS — Node.js للمؤسسات
أنواع GraphQL المتقدمة: Scalars و Directives و Interfaces و Unions
أنواع GraphQL المتقدمة: Scalars و Directives و Interfaces و Unions
تحتاج مخططات GraphQL الحقيقية إلى أكثر من أنواع الكائنات. تمثل scalars المخصصة قيماً مثل DateTime وMoney، وتضيف directives سلوكاً على مستوى المخطط، وتصف interfaces حقولاً مشتركة، وتعيد unions واحداً من عدة أشكال كائنات.
الفكرة الأساسية
تدور هذه الميزة حول التحكم في كيفية تنظيم التطبيق وسلوكه وقت التشغيل. النقاط التالية هي ما يجب أن يعرفه المطور قبل استخدامها في مشروع حقيقي:
- يجب على scalars المخصصة تحليل إدخال العميل وتسلسل مخرجات الخادم والتحقق من حدود القيمة بعناية.
- تستطيع directives تعليم حقول المخطط لسلوكيات مثل تلميحات المصادقة أو التنسيق أو بيانات federation.
- تصلح interfaces عندما تشترك عدة أنواع كائنات في حقول ويستطيع العملاء استعلام الشكل المشترك.
- تفيد unions لنتائج البحث أو الاستجابات متعددة الأشكال عندما لا تشترك العناصر في حقول كافية.
- يجب أن يكون منطق ResolveType حتمياً حتى يحصل العملاء على __typename الصحيح.
مثال عملي
يوضح المثال التالي الشكل العملي للفكرة داخل مشروع NestJS. ليست الغاية حفظ الكود، بل فهم مكانه في المعمارية:
@Scalar('DateTime', () => Date)
export class DateTimeScalar implements CustomScalar<string, Date> {
parseValue(value: string): Date {
return new Date(value);
}
serialize(value: Date): string {
return value.toISOString();
}
parseLiteral(ast: ValueNode): Date | null {
return ast.kind === Kind.STRING ? new Date(ast.value) : null;
}
}
export const SearchResultUnion = createUnionType({
name: 'SearchResult',
types: () => [User, Article] as const,
resolveType(value) {
return 'email' in value ? User : Article;
},
});
ملاحظة تصميمية: أنواع GraphQL المتقدمة جزء من تصميم API وليست زينة. تساعد العملاء على فهم شكل البيانات ومعناها بدقة قبل وقت التشغيل.
قائمة تطبيق إنتاجية
- تحقق من حدود scalar بصرامة.
- وثق سلوك directives لفرق الواجهة.
- فضّل interfaces عندما تشترك الأنواع في عقد مشترك.
- استخدم unions عندما تكون النتيجة واحدة من عدة أشكال غير مترابطة.
قاعدة عملية: إذا جعلت الميزة الحدود أوضح والاختبارات أسهل فهي اختيار جيد. إذا أخفت التبعيات أو صعّبت التتبع، فأعد التصميم.
الخلاصة
يغطي هذا الدرس جزءاً متقدماً من NestJS يجب فهمه عند بناء تطبيقات مؤسسية. ركّز على الحدود الواضحة، والسلوك القابل للاختبار، واختيار الأداة المناسبة للسياق بدلاً من استخدام كل ميزة في كل مكان.