type graphql - type graphql

قم بإنشاء مخطط GraphQL ومحلوله مع TypeScript ، باستخدام الفصول والديكور!

https://typegraphql.com

مقدمة

يجعل TypegraphQl تطوير واجهات برمجة تطبيقات GraphQL عملية ممتعة ، أي من خلال تحديد المخطط باستخدام فصول فقط وقليل من السحر.

لذلك ، لإنشاء أنواع مثل نوع الكائن أو نوع الإدخال ، نستخدم نوعًا من فئة DTO. على سبيل المثال ، لإعلان نوع Recipe ، نقوم ببساطة بإنشاء فصل وتوضيحه مع ديكورات:

@ ObjectType ( )
class Recipe {
  @ Field ( type => ID )
  id : string ;

  @ Field ( )
  title : string ;

  @ Field ( type => [ Rate ] )
  ratings : Rate [ ] ;

  @ Field ( { nullable : true } )
  averageRating ?: number ;
}

ونحصل على الجزء المقابل من المخطط في SDL:

 type Recipe {
  id : ID !
  title : String !
  ratings : [ Rate ! ] !
  averageRating : Float
}

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

@ Resolver ( Recipe )
class RecipeResolver {
  // dependency injection
  constructor ( private recipeService : RecipeService ) { }

  @ Query ( returns => [ Recipe ] )
  recipes ( ) {
    return this . recipeService . findAll ( ) ;
  }

  @ Mutation ( )
  @ Authorized ( Roles . Admin ) // auth guard
  removeRecipe ( @ Arg ( "id" ) id : string ) : boolean {
    return this . recipeService . removeById ( id ) ;
  }

  @ FieldResolver ( )
  averageRating ( @ Root ( ) recipe : Recipe ) {
    return recipe . ratings . reduce ( ( a , b ) => a + b , 0 ) / recipe . ratings . length ;
  }
}

وبهذه الطريقة البسيطة ، نحصل على هذا الجزء من المخطط في SDL:

 type Query {
  recipes : [ Recipe ! ] !
}

type Mutation {
  removeRecipe ( id : String ! ): Boolean !
}

تحفيز

نعلم جميعًا أن GraphQL رائع ويحل العديد من المشكلات التي نواجهها مع واجهات برمجة تطبيقات REST ، مثل الإفراط في الإحساس وفنتره. لكن تطوير واجهة برمجة تطبيقات GraphQL في Node.js مع TypeScript يكون في بعض الأحيان ألمًا. لماذا؟ دعونا نلقي نظرة على الخطوات التي عادة ما نتخذها.

أولاً ، نقوم بإنشاء جميع أنواع GraphQL في schema.graphql باستخدام SDL. ثم نقوم بإنشاء نماذج البيانات الخاصة بنا باستخدام فئات ORM ، والتي تمثل كيانات DB الخاصة بنا. ثم نبدأ في كتابة محلول لاستعلاماتنا وطفراتنا وحقولنا ، لكن هذا يجبرنا على إنشاء واجهات TS أولاً لجميع الوسائط والمدخلات وحتى أنواع الكائنات.

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

 export const getRecipesResolver : GraphQLFieldResolver < void , Context , GetRecipesArgs > = async (
  _ ,
  args ,
  ctx ,
) => {
  // common tasks repeatable for almost every resolver
  const repository = TypeORM . getRepository ( Recipe ) ;
  const auth = Container . get ( AuthService ) ;
  await joi . validate ( getRecipesSchema , args ) ;
  if ( ! auth . check ( ctx . user ) ) {
    throw new NotAuthorizedError ( ) ;
  }

  // our business logic, e.g.:
  return repository . find ( { skip : args . offset , take : args . limit } ) ;
} ;

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

أدوات مثل GraphQL Code Generator أو GraphQlgen فقط تحل الجزء الأول-فهي تنشئ الواجهات المقابلة (و Resolvers Heachetons) لمخطط GraphQL الخاص بنا ، لكنهم لا يقومون بإصلاح المخطط <-> النماذج المتكررة وتجربة المطورين (F2 Rename لن يعمل ، عليك أن تتذكر مهمة مراقبة الكود في الخلفية ، وما إلى ذلك) ، بالإضافة إلى مهام شائعة ، مخططات ، إلخ.

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

الوثائق

تتوفر توثيق ودليل التثبيت والوصف التفصيلي لواجهة برمجة التطبيقات وجميع ميزاته على الموقع الإلكتروني.

ابدء

يمكن العثور على دليل بدء التشغيل الكامل مع تجول بسيط (البرنامج التعليمي) في بدء مستندات البدء.

فيديو تعليمي

إذا كنت تفضل دروس الفيديو ، فيمكنك مشاهدة سلسلة فيديو Ben Awad's Typegraphql على YouTube.

أمثلة

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

قد يعطيك مجلد الاختبارات أيضًا بعض النصائح حول كيفية إنجاز أشياء مختلفة.

معلومات الاتصال الأمنية

للإبلاغ عن ثغرة أمنية ، يرجى استخدام جهة اتصال Tidelift Security. سوف Tidelift تنسيق الإصلاح والكشف.

المستقبل

الإصدار الذي تم إصداره حاليًا هو إصدار مستقر 1.0.0. يتم اختباره جيدًا (تغطية 97 ٪ ، حوالي 500 حالة اختبار) ولديها معظم الميزات المخطط لها بالفعل. الكثير من الشركات والمطورين المستقلين يستخدمونها في الإنتاج بنجاح.

ومع ذلك ، هناك أيضًا خطط لمزيد من الميزات مثل Better Typeorm و Prisma و Dataloader Integration و Decorators المخصصة ودعم التعليقات التوضيحية للبيانات الوصفية - تتوفر القائمة الكاملة للأفكار على Github Repo. يمكنك أيضًا تتبع تقدم التطوير في مجلس المشروع.

إذا كان لديك أي طلبات ميزة مثيرة للاهتمام ، فلا تتردد في فتح مشكلة على Github حتى نتمكن من مناقشة ذلك!

يدعم

Typegraphql هو مشروع مفتوح المصدر المرخص له معهد ماساتشوستس للتكنولوجيا. هذا الإطار هو نتيجة لكمية هائلة من العمل - الليالي بلا نوم ، أمسيات مزدحمة وعطلات نهاية الأسبوع.

ليس لديها شركة كبيرة تقع وراءها - لا يمكن تطويرها المستمر إلا بفضل دعم المجتمع.