تقدير المشروع
← كل المقالات

ما تحتاج إلى معرفته عن GraphQL في 2024

بعد سنوات من العمل مع GraphQL، يرغب الكاتب في نقل رؤاه وخبرته مع هذه التقنية.

14 دقائق قراءة
العمارة البرمجيةتطوير البرمجياتAPIGraphQL

أصبحت GraphQL مع السنوات أمرًا كبيرًا. فقد تحمّس كثير من المطورين لهذه التقنية، وأنا منهم.

وبعد أن عملت بهذه التقنية عدة سنوات، أود أن أنقل رؤاي وخبرتي مع GraphQL.

لنبدأ بتعريف أساسي: ما هي GraphQL؟

GraphQL هي لغة استعلام تتيح لك تحديد البيانات التي تحصل عليها ردًّا على طلب. وتوفر أيضًا بيئة تشغيل تحل تلك الاستعلامات مقابل بياناتك الحالية. يمكنك تخيّل تلك البيانات عقدًا في رسم بياني (graph). فقد تكون الكائنات مرتبطة بكائنات أخرى، لكنك قد لا تهتم إلا بمجموعة فرعية صغيرة من تلك العقد.

سهل بما يكفي؟ رائع، لنتعمق أكثر.

الحرية

تتيح GraphQL لعملاء الخدمة أن يختاروا بحرية ما يعود إليهم من الخادم. ففي كل طلب – سواء كان استعلامًا (query) أو تعديلًا (mutation) أو اشتراكًا (subscription) – أنت تقرر أي معلومات تجلبها وأي حقول لا تحتاجها. وهذه هي أنواع الطلبات الثلاثة الوحيدة. عمليات Query مخصصة لقراءة البيانات، وعمليات Mutation لتغييرها، وعمليات Subscription تقدم تحديثات فورية كلما ظهرت بيانات جديدة.

بصفتك عميلًا، يمكنك طلب كل البيانات التي تحتاجها في استعلام واحد. وإذا كانت أجزاء معينة فقط من البيانات تهمك، فيمكنك طلب تلك الأجزاء فقط. ويمكن لأجزاء مختلفة من نظامك/واجهتك أن تختار بيانات مختلفة.

وهذا يعني أن مزوّد الـ API لا يحتاج إلى توقع كل حالة حدّية لطريقة استخدام البيانات. وهذا يعمل جيدًا حين يكون لـ API العامة لديك عملاء كثيرون، إذ يمكنهم استهلاك بياناتك بطرق متعددة.

لهذه الفكرة أثر كبير في عملية التطوير لدينا. إذ يمكن للفرق، أو لأجزاء من الفرق مثل الواجهة الخلفية والأمامية، أن تتواصل بصورة أكثر لاتزامنية. والسبب أن هناك عقدًا بين المزوّد والمستهلك – هو المخطط (schema)، وسنتناوله لاحقًا.

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

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

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

يمكن لحرية الاختيار هذه أن تقلّص حمولتك بصورة كبيرة. فمثلًا، في Migrating to GraphQL: A Practical Assessment – حيث نقل المؤلفون API الخاصة بـ GitHub من REST إلى GraphQL – انخفضت الحمولة من 93.5 حقلًا (القيم الوسيطة) إلى 5.5 فقط بعد الانتقال إلى GraphQL. ونتيجة لذلك، انخفض حجم الاستجابة من 9.8 MB (القيم الوسيطة) إلى 86 KB فقط بعد التحول إلى GraphQL. وهذا خبر ممتاز لتطبيقات الجوال التي تتشارك API مع تطبيقات الويب.

هذا بالضبط هو سبب إنشاء GraphQL في الأصل. وهذا أول مقال لـ Facebook عنها.

المخطط (Schema)

لقد ذكرت المخطط. إنه، بشكل ما، المكان الذي يتفق فيه المطورون على شكل الاستعلامات/الاشتراكات والتعديلات. وهو بالنسبة لي من أعظم ميزات GraphQL. وإنشاؤه أمر لا مفر منه. وحتى لو لم يكن كذلك، فلا ينبغي لك تخطيه، لأنه يمنحك التحكم في عملية التطوير ويرسي عقدًا بين مزوّد الـ API وعملائه – سواء كان زميلًا في الواجهة الأمامية أو فريقًا في قارة أخرى أو حتى شركة خارجية.

مخطط GraphQL قوي الأنواع (strongly typed)، لذا تستطيع الأدوات مساعدتنا في التحقق مما إذا كان الطلب يطابق المخطط. كما يتحقق خادم GraphQL من الطلبات. ويعتمد المزوّدون على المخطط لبناء نقاط دخول صحيحة إلى الخدمة.

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

هناك عدة طرق لتزويد العملاء بالمخطط. يمكنك مشاركة ملف معهم، أو يمكن للعميل جلب المخطط باستعلام استكشافي (introspection query). ومن الممارسات الجيدة تعطيل استعلامات introspection على خدمة الإنتاج لديك.

يشرح هذا المقال لماذا وكيف يتم ذلك.

كثيرًا ما يخفف المخطط عنا عبئًا حين نتساءل What endpoint should I query for this use case? لم يعد هذا شأني – فـ GraphQL تعطيني مخططًا، وإن كانت المعلومة فيه فيمكنني جلبها.

توليد الشيفرة

بما أن GraphQL تمنحنا مخططًا نعمل به، تستطيع الأدوات توليد بنى لاستخدامها في الشيفرة، في الواجهة الخلفية والأمامية على السواء. وهذه القدرة البسيطة توفر عليك الإنشاء/التحرير المملّ للفئات في كل مرة يتغير فيها المخطط. ففي Java مثلًا، يمكنك استخدام graphql-java-codegen. ويمكن أن يكون هذا مفيدًا خصوصًا في المشاريع الأكبر التي لا نعرف فيها كل تغيير في المخطط. نكتفي بسحب أحدث نسخة من المخطط وإعادة بناء الشيفرة، فيصبح كل شيء محدّثًا. كما يحمينا من أخطاء تافهة مثل الأخطاء المطبعية في أسماء الحقول. من المرجح أن يوفر لك توليد الشيفرة بعض الوقت.

التطور

تُوصف GraphQL بأنها version free (بلا إصدارات)، أي أنك إن فعلت الأمور بشكل صحيح فلا حاجة إلى إصدار نسخ من مخططك.

التطبيقات التي أصدرتها Facebook على مدى ثلاث سنوات لا تزال مدعومة على إصدار واحد بعينه من GraphQL API لدينا.
GraphQL – a data query language

كيف يمكن أن ينجح ذلك أصلًا؟

إضافة حقل جديد لا تخرق أي عقد – فالعميل لا يحتاج حتى إلى معرفة وجود هذه الحقول أو الاستعلامات الجديدة، أليس كذلك؟

حسنًا، لكن ماذا عن إزالة الميزات؟ هنا يأتي دور التوجيه @Deprecated لينقذ الموقف.

أولًا، لنشرح ما هو التوجيه (directive).

ببساطة قدر الإمكان، هو معلومة إضافية يمكنك تضمينها في المخطط. ويمكنك أيضًا بناء منطق حول التوجيهات، مما يجعلها قوية جدًا.

والآن، لنعد إلى @Deprecated.

استخدام التوجيه @Deprecated

يشير إلى العملاء بأنه لم يعد ينبغي استخدام هذا الجزء من المخطط. لكن الحقل يبقى في مخططنا حتى بعد وسمه بـ @Deprecated، وعلى مدى السنوات قد نتراكم لدينا الكثير منها. ولهذا ينبغي أن نراقب كيفية استخدام مخططنا. وحين تتأكد أن أحدًا لم يعد يستخدم الحقل، يمكنك إزالته.

تستحق قابلية الرصد (observability) مقالة مدونة خاصة بها، لكن قد ترغب في الاطلاع على Apollo Studio الذي يتيح لك عرض إحصاءات عن مخططك وطلباتك ومعدل الإخفاق والكثير غير ذلك، مما يساعدك على الحكم على إمكانية إزالة حقل.

إن تطوير مخطط GraphQL عملية تدريجية لا تغيير جذري دفعة واحدة.

وبطبيعة الحال، إن كنت في فريق صغير أو تتواصل جيدًا مع عملائك، يمكنك حذف حقل حين يكون الطرفان جاهزين، دون الإبقاء على حقول @Deprecated طويلة العمر. وكما هو الحال دائمًا، كل شيء يعتمد على الظروف.

الاستعلامات غير الفعالة

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

فما المشكلة إذن؟ البيانات موجودة في المخطط، فلماذا لا أسحبها فحسب؟

من منظور GraphQL، كل حقل هو دالة. وغالبًا ما تكون دالة الحل (resolver) هذه بسيطة جدًا – مجرد getter على الكائن. وكثيرًا ما تخفي أدوات الواجهة الخلفية ذلك عنا، لأننا لا نتعامل إلا مع كائنات. غير أن بعض الحقول مختلفة: فهي تتطلب حساب شيء ما أو إرسال طلب إضافي إلى خدمة أخرى لمجرد أن تلك البيانات موجودة في مكان آخر. ومن الصعب معرفة أي الحقول مكلفة.

على سبيل المثال:

مثال على عقدة User

هل نستطيع بسهولة معرفة أي من هذه الحقول يحتاج إلى طلبات إضافية؟ ربما accountNumber، أليس كذلك؟ لكن ربما يحتاج name وlastName إلى بعض التعمية لأسباب أمنية. أو ربما لن تكون هناك أي طلبات أو حسابات إضافية على الإطلاق. لا يمكننا أبدًا التيقن مما يحدث بعد أن نقوم باستدعائنا. هذا المثال بسيط جدًا، بأربعة حقول فقط. فماذا لو كان لدينا 20 حقلًا بأنواع متداخلة مخصصة؟ سيصبح الأمر أصعب بكثير.

فماذا يترتب على ذلك؟

مشكلة N+1

مثال على مشكلة N+1 محتملة

قد نضيف حقلًا جديدًا إلى User يحمل جميع بطاقات الائتمان لمستخدم معين. وفي كل مرة نجلب فيها User، قد نجلب بطاقاته أيضًا. هنا سيرغب الخادم في جلب كل عنصر من تلك المجموعة على حدة، مما قد يؤدي إلى مشكلة N+1.

يمكن معالجة مشكلات كهذه بواسطة data loaders. وهي آلية جلب إضافية تتيح لخادمك تجميع العقد في دفعات وطلبها جميعًا دفعة واحدة.

جحيم التبعيات

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

رأيت مطورين يميلون إلى «الأنواع الإلهية» (godly types) في المخططات. ففي سياق التطوير، مثلًا، قد يتحول نوع User لدينا إلى وحش كهذا:

مثال على عقدة ضخمة

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

على الأرجح لا توجد واجهة تحتاج كل تلك المعلومات. فماذا يمكننا أن نغير؟ يمكننا تغيير بنية البيانات الكامنة (قاعدة البيانات أو الخدمات) أو المخطط في الأعلى.

وحيثما أمكن، ابتعد عن تغيير مخطط قاعدة البيانات. فالاقتران الوثيق بين الـ API وقاعدة البيانات أمر ينبغي تجنبه. أحد الخيارات نقل البيانات من خدمة إلى أخرى. قد ينجح ذلك، لكن تذكّر أن للخدمات مسؤوليات تتجاوز جمع البيانات – فهي تتولى قابلية التوسع ومنطق الأعمال والسياقات المحدودة (bounded contexts) وما إلى ذلك.

خيار آخر هو بناء نموذج قراءة لهذا النوع تحديدًا. وقد ينجح ذلك جيدًا، رغم أنك قد تواجه مشكلات الاتساق النهائي (eventual consistency) عند القراءة.

والملاذ الأخير هو تغيير مخطط GraphQL.

بناء مخططك على الواجهة ليس فكرة جيدة. بدلًا من ذلك، يمكننا استعارة مفاهيم من التصميم الموجّه بالمجال (domain-driven design)، ولا سيما اللغة الشاملة (ubiquitous language). وهي بحكم تعريفها مجموعة مصطلحات يتشاركها فريقا الأعمال والتطوير، ويفترض أن يفهمها كلاهما بالطريقة نفسها.

لنحاول إذن تقسيم User إلى عدة مفاهيم منفصلة.

(إن كنت تعمل في المجال المصرفي، فربما ستجد تسمياتي سخيفة – أعتذر عن ذلك :) )

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

علاوة على ذلك، قد يأتي كل نوع من المعلومات من مكان مختلف. فمثلًا، SecurityInformation تحتوي على معلومات عما إذا كان العملاء قد تعرضوا للاختراق. وهذا النوع من البيانات لا ينتمي إلى مجال debt، أليس كذلك؟

عند هذه النقطة، كثير من هذه الأنواع غير مترابطة. وإذا أُجري التقسيم جيدًا، فهذا أمر حسن. فكل استعلام سيجلب الآن المعلومات من مكان واحد (خدمة/نموذج قراءة) بأسرع ما يمكن.

هل يمكن تحقيق ذلك في الإنتاج؟ على الأرجح لا – فمن المرجح أن تظل هناك روابط بين الأنواع، كما في MortgageInfromation. لكن هدفك ينبغي أن يكون تقليل عددها.

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

ماذا يمكنني أن أرى؟

في كل مرة نعالج فيها طلبًا من مستخدم، علينا التحقق من هويته ومما إذا كانت لديه الصلاحيات الصحيحة لجلب بيانات معينة. لننظر الآن إلى النوع Account لدينا.

لنفترض أن الحقل loans لا يمكن جلبه إلا لعدد قليل من أنواع المستخدمين. ماذا ينبغي أن يحدث حين لا يملك مستخدم يجلب الكائن بأكمله صلاحية الوصول إلى ذلك الحقل؟ هل نُطلق استثناءً؟ يبدو ذلك صحيحًا، إذ حدث خطأ ما في جانب الخادم. وهناك نهج آخر أيضًا: إرجاع كائن جزئي. فتكون كل الحقول متاحة، لكن ما القيمة التي سيحملها الحقل loans؟ يمكننا إرجاع null، لكن علامة «!» في المخطط تقول إن الحقل لن يكون null أبدًا. فربما ينبغي أن نرجع قائمة فارغة؟

إنه قرار صغير لكنه مهم، لأنه قد يُدخل عدم اتساق في تطبيقنا. فقد يحصل بعض العملاء الآن على قائمة قروض فارغة رغم وجود قروض. وقد يتخذ مستخدمك قرارًا تجاريًا بناءً على تلك البيانات. هذا ليس جيدًا، أليس كذلك؟

ربما إن كانت لدي صلاحية الوصول إلى النوع Account فينبغي أن أستطيع جلب كل حقل؟ عندها تقع الصلاحيات على النوع الجذري للاستعلام. وهو نهج مثير للاهتمام يجعل مشكلة التفويض أبسط.

وبطبيعة الحال، هناك ثمن: فقد يجعل ذلك تصميم الـ API يبدو مقيّدًا. ومع تغيّر المجال، قد ننتهي إلى الموقف نفسه. ويمكن لتوجيه مخصص (custom directive) أن يساعد مستهلكي الـ API لديك. ناقشنا التوجيه @Deprecated، لكن يمكنك أيضًا كتابة توجيهك المخصص. يمكنك مثلًا إنشاء توجيه يسمى @hasRole يأخذ الدور المطلوب ثم يتحقق وقت التشغيل مما إذا كان المستخدم يملكه.

مثال على توجيه مخصص

الأمان

هل GraphQL آمنة؟ كالعادة، ينبغي أن تكون الإجابة «يعتمد على الظروف». لكنني أراهن أنك سئمت سماع ذلك. لذا دعني أعيد صياغة السؤال: «هل سيكون تطبيقي آمنًا إذا أضفت GraphQL ببساطة إلى المنظومة؟» في هذه الحالة، الإجابة لا. وكما يحدث كثيرًا، حين نمنح المستخدمين حرية كبيرة، قد يستخدمونها لإيذائك. ومن الأخطاء الشائعة ترك استعلام introspection مفعّلًا في الإنتاج، مما يتيح لمستخدمي منتجنا جلب استعلامات وبيانات لا ينبغي أن يروها أبدًا. وفي مثل هذا السيناريو، تكشف التوجيهات المخصصة مثل @hasRole الكثير للمهاجمين المحتملين.

هذا موضوع مهم يستحق التعمق فيه، ويستحق مقالًا خاصًا به. لا تتجاهله، لأنه قد يلحق بإنتاجك ضررًا كبيرًا.

ومع ذلك، إن أردت التعرف على ثغرات GraphQL في بيئة آمنة، فأوصي بشدة بمشروع Damn Vulnerable GraphQL Application. إنه تطبيق hack me مليء بالثغرات لاستغلالها. استمتع :)

تنفيذات GraphQL

ضع في اعتبارك أن ليس كل تنفيذ لخادم GraphQL يدعم بالضرورة كل ميزة.

لماذا؟ كُتبت مواصفة GraphQL عام 2015، وجاء أحدث تحديث رسمي لها عام 2021. وصناعتنا في تطور مستمر، لذا كان لا بد من اتخاذ قرارات معينة.

خذ مثلًا مسألة أي حالة استجابة HTTP تُرجع. قد تفترض 200، وبالفعل 200 OK هي «الممارسة الشائعة»، لكن مواصفة GraphQL لا تحدد في أي موضع أي رمز ينبغي للخادم إرجاعه. وبالتالي تستخدم بعض الأدوات رموزًا مختلفة للأخطاء.

يتبع Graphlq-helix أو Netlix-dgs نهجًا مختلفًا في هذا.

يرى بعض المطورين أن ذلك يمثل مشكلة، ولهذا كتبوا RFC (لا يزال مسودة) يصف كيف ينبغي تقديم GraphQL واستهلاكها عبر HTTP.

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

الخلاصة

GraphQL تقنية رائعة تستحق الاستكشاف. أقترح أن تجرّبها، أو أن تطّلع ببساطة على الدروس المجانية من Apollo. فقد تمنحك منظورًا جديدًا للـ API ولعملية التطوير.

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