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

GraphQL بنهج Schema-First و SDL والنماذج المشتركة

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

GraphQL بنهج Schema-First و SDL والنماذج المشتركة

ركزت دروس GraphQL السابقة على نهج code-first. يدعم NestJS أيضاً نهج schema-first حيث تكون لغة تعريف مخطط GraphQL هي العقد وتولد أنواع TypeScript حولها. يناسب ذلك الفرق التي تعتبر مراجعة المخطط طبقة حوكمة API.

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

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

ينشئ code-first ملفات SDL من أصناف TypeScript المزخرفة؛ بينما يبدأ schema-first من ملفات .graphql.
يفيد autoSchemaFile في code-first، بينما توجه typePaths تطبيق Nest إلى ملفات SDL في schema-first.
تستطيع DefinitionsFactory توليد تعريفات TypeScript من المخطط.
تقلل النماذج المشتركة التكرار، لكن أنواع GraphQL يجب ألا تسرب حقول التخزين الداخلي افتراضياً.
يشجع schema-first مراجعة API صريحة لأن فروق المخطط سهلة الفحص.

مثال عملي

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

GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  typePaths: ['./**/*.graphql'],
  definitions: {
    path: join(process.cwd(), 'src/graphql.ts'),
    outputAs: 'class',
  },
});

# users.graphql
type User {
  id: ID!
  email: String!
}

type Query {
  users: [User!]!
}

ملاحظة تصميمية: لا يوجد نهج أفضل دائماً بين code-first وschema-first. الأول منتج للفرق المعتمدة على TypeScript؛ والثاني قوي عندما يملك المخطط أكثر من فريق: الواجهة والخلفية والمنصة.

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

اختر نهج GraphQL واحداً لكل سياق محدد.
راجع SDL المولد في طلبات السحب عند استخدام code-first.
تجنب كشف كيانات ORM مباشرة كعقود GraphQL.
ولّد تعريفات TypeScript بثبات في مشاريع schema-first.

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

الخلاصة

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