تطوير مخططات Protobuf بالطريقة الصحيحة باستخدام ScalaPB وfs2grpc
عندما تُعرَّف واجهات برمجة التطبيقات بلغات وصف الواجهات، يمكن أن تتطور المخططات بشكل أمتن وأكثر أمانًا مقارنةً بالرسائل المبنية على JSON. ويعتمد كون إضافة حقول الرسائل أو حذفها آمنًا تمامًا على عدة عوامل. دعونا نستعرض أنماط التواصل المختلفة ونفكّر في أيّها نختار.
اكتسب النموذج القائم على المخططات شعبية واسعة عبر كثير من نماذج التواصل. فعندما تُعرَّف واجهات برمجة التطبيقات بـ لغات وصف الواجهات، يمكن أن تتطور المخططات بشكل أمتن وأكثر أمانًا مقارنةً بالرسائل المبنية على JSON. وبحسب عدد من العوامل، قد تكون إضافة حقول الرسائل أو حذفها آمنة تمامًا، وقد تكسر التوافق الثنائي بمجرد النشر. وقد تتطلب خدمات gRPC، وتخزين الأحداث (event sourcing)، وتواصل الممثلين (actors) في Akka Cluster سياسة مختلفة لتطور المخطط لكلٍّ منها – وقد يتغير الاختيار أيضًا بحسب بروتوكول النقل المحدد. دعونا نستعرض أنماط التواصل المختلفة ونفكّر متى نختار التوافق الخلفي (backward) أو الأمامي (forward) أو الكامل (full).
التقنية
يركّز هذا المقال على Google Protocol Buffers، المعروفة اختصارًا بـ Protobuf – وهو البروتوكول الأساسي الافتراضي لخدمات gRPC وخيار قوي للتواصل القائم على الرسائل. ويتخذ أسلوب التواصل في gRPC نهجه الخاص في السماح بتغييرات المخطط والحقول المطلوبة والقيم الافتراضية. وإذا كنت تبني أنظمة خلفية بـ Scala، فإن ScalaPB يتيح لك توليد case classes من عقد .proto أثناء تصريف المشروع. ويمكن جعل هذه الأنواع المولَّدة أمتن بعد بإضافة تعليقات توضيحية (annotations) إضافية، وسنلقي نظرة عليها أدناه.
أسلوب التواصل
gRPC
يواصل هذا الشكل من التواصل المتزامن بين الخدمات اكتساب الشعبية. فعقود REST الكلاسيكية يصعب تطويرها – وهذا قبل أن نذكر الأداء الأفضل ودعم البث (streaming). ومشكلة أخرى هي التعبير عن حالات استخدام الخدمة عبر أفعال HTTP مثل POST/PUT/DELETE وغيرها مع عناوين URL للموارد، وهي كثيرًا ما تلائم حالات الاستخدام الفعلية بشكل سيئ. ويحلّ gRPC هذه المشكلات. في عالم gRPC نتحدث عادةً عن العملاء والخوادم. وفي العادة تمتلك خدمة الخادم عقدها على شكل ملفات protobuf، يمكن منها توليد case classes عبر ScalaPB**.** بعد ذلك يستطيع fs2grpc إنتاج طبقة عميل رقيقة مبنية على Cats Effect، ويمكن لـ CI تغليف كل هذا الكود في حزمة .jar ذات إصدار ينشرها الخادم. ثم تعتمد خدمات العملاء على هذه الحزم المولَّدة.
الرسائل
يجلب التواصل غير المتزامن القائم على الرسائل فوائد كثيرة، مثل فك الارتباط (decoupling) وضمانات التسليم وتخزين الأحداث (event sourcing) وتخزين الأوامر (command sourcing) وغيرها. يمكنك بناءه على Kafka أو Pulsar أو غيرهما من حلول البنية التحتية. ومع Kafka، كثيرًا ما يُستكمل هذا النمط بسجل مخططات (Schema Registry) خارجي يساعد على إدارة توافق المخططات بين المنتِجين والمستهلكين. دعونا نركّز على نمطي التكامل التاليين:
- منتِج واحد – عدة مستهلكين
تنشر خدمة أحداثها، ويمكن للمستهلكين الانضمام أو المغادرة لقراءتها ومعالجتها. وعادةً تكون تغييرات المخطط بقيادة المنتِج. - مستهلك واحد – عدة منتِجين
تقرأ خدمة أوامر من موضوع (topic) يمكن لخدمات العملاء المحتملين النشر فيه. هنا المستهلك هو من يحدّث المخطط، مما يجعله يشبه خادم gRPC. - التواصل بين ممثلين من النوع نفسه
هذا السيناريو خاص بالنماذج التي يتراسل فيها ممثلون من النوع نفسه، مثلًا داخل Akka Cluster. لن نتعمق فيه. يكفي القول إنه يتطلب توافقًا كاملًا، بحيث يستطيع الممثلون أثناء التحديث المتدرج (rolling update) تبادل الرسائل بالنسختين الجديدة والقديمة.
ورقة مرجعية لأنماط التوافق
لنترجم الآن استخدامات Protobuf المذكورة أعلاه إلى قوائم بالعمليات المسموحة، مثل إضافة الحقول أو حذفها وتغيير اختيارية الحقل وغيرها. في البداية، تذكير موجز بأنماط التوافق:
- backward (خلفي) – النمط الأكثر شهرة. يجب أن يكون مستهلكو البيانات قادرين على استهلاك الإصدارات الأقدم من كائنات البيانات.
- forward (أمامي) – ينطبق عندما يملك المستهلك إصدارًا أقدم من المخطط لكنه يحتاج إلى فهم بيانات سُلسلت بإصدار أحدث.
- full (كامل) – القيد الأشد صرامة، ويتطلب التوافق الخلفي والأمامي معًا.
gRPC
بالنسبة إلى الطلبات، يُوصى بالحفاظ على التوافق الخلفي. يحدّث الخادم مخططه أولًا دون أن يضطر إلى القلق بشأن الطلبات الواردة من عملاء ما زالوا على مخططات أقدم، ثم يحدّث العملاء مخططاتهم خطوة بخطوة. أما بالنسبة إلى الاستجابات، فالنمط المطلوب هو الأمامي، لكي يظل بإمكان العملاء التعامل مع الرسائل الجديدة القادمة من الخادم. لاحظ أن غلاف no_box مشروح بالتفصيل لاحقًا، في قسم الاختيارية.
| النمط | التواصل | السيناريو | الطريقة |
| BACKWARD | طلبات gRPC | إضافة حقل اختياري إلى الطلب | أضفه في proto |
| BACKWARD | طلبات gRPC | جعل حقل مطلوب في الطلب اختياريًا | أزل no_box (خاص بـ ScalaPB) |
| BACKWARD | طلبات gRPC | جعل حقل اختياري في الطلب مطلوبًا | كاسر للتوافق |
| BACKWARD | طلبات gRPC | حذف حقل اختياري من الطلب | أزله من proto |
| BACKWARD | طلبات gRPC | حذف حقل مطلوب من الطلب | أزله من proto |
| BACKWARD | طلبات gRPC | إضافة حقل مطلوب إلى الطلب | كاسر للتوافق |
| BACKWARD | طلبات gRPC | إضافة حقل إلى oneof في الطلب | أضفه في proto |
| BACKWARD | طلبات gRPC | نقل حقل إلى oneof جديد في الطلب | انقله في proto |
| BACKWARD | طلبات gRPC | حذف حقل من oneof في الطلب | كاسر للتوافق** |
| FORWARD | استجابات gRPC | إضافة حقل اختياري إلى الاستجابة | أضفه في proto |
| FORWARD | استجابات gRPC | إضافة حقل مطلوب إلى الاستجابة | أضفه في proto |
| FORWARD | استجابات gRPC | حذف حقل اختياري من الاستجابة | أزله من proto |
| FORWARD | استجابات gRPC | جعل حقل مطلوب في الاستجابة اختياريًا | كاسر للتوافق |
| FORWARD | استجابات gRPC | حذف حقل مطلوب من الاستجابة | كاسر للتوافق* |
| FORWARD | استجابات gRPC | إضافة حقل إلى oneof في الاستجابة | كاسر للتوافق** |
| FORWARD | استجابات gRPC | نقل حقل إلى oneof جديد في الاستجابة | للحقل الاختياري فقط، انقله في proto |
| FORWARD | استجابات gRPC | حذف حقل من oneof في الاستجابة | أزله من proto |
ضع في اعتبارك أن حذف الحقول في Protobuf لا بأس به ما دام رقم الفهرس لا يُعاد استخدامه أبدًا. تتيح لك الكلمة المفتاحية reserved أن تنص صراحةً على أنه لا يجوز استخدام فهرس مرة أخرى.
- ممكن في ظل قيود معينة – انظر قسم الاختيارية أدناه.
** ملاحظة خاصة بشأن oneof: إذا أُزيل متغيّر في oneof من الطلبات، يفك الخادم ترميز تلك القيمة على أنهاUNKNOWN، ولا يمكن من الناحية النظرية تمييزها عن قيمة غير معيّنة.
ولهذا أصنّفه على أنه غير متوافق خلفيًا. وبالطريقة نفسها، تُعدّ إضافة حقل إلى oneof تغييرًا غير متوافق أماميًا. وإذا كنت متأكدًا من أن جميع عملائك يستخدمون ScalaPB وأنك تتعامل مع قيم UNKNOWN بشكل صحيح، فيمكنك إجراء مثل هذه التغييرات – لكن بحذر شديد.
الرسائل: الأحداث
هنا يمتلك الناشر العقد ويقرأ المستهلكون الأحداث التي ينشرها. وكثيرًا ما يُنفَّذ هذا الأسلوب عبر حزمة .jar تحتوي على ملف .proto إضافةً إلى أصناف ScalaPB المولَّدة وخدمات fs2grpc، يحتفظ بها الخادم وينشرها. وعادةً يكون الناشر أول من يكيّف كوده مع العقد الجديد، ويأتي المستهلكون بعده. ومع ذلك، دعونا نستعرض كل حالة فرعية:
- إذا احتاج المنتِج إلى تحديث الأحداث دون كسر المستهلكين، الذين يمكنهم مواصلة استخدام المخطط القديم إلى أن يحدّثوا، فإن التوافق الأمامي يكفي.
- أو قد تفضّل تحديث المستهلكين أولًا. وإذا اخترت هذا الترتيب، فإن التوافق الخلفي هو ما يجب أن تحافظ عليه. وهذا النهج موصوف في وثائق Avro وSchema Registry – ألقِ نظرة للتعمق أكثر.
- التوافق الكامل هو الخيار الأشد صرامة. ويُنصح به عندما نحتاج إلى ضمان أن المستهلكين، حتى بعد تكيّفهم مع أحدث مخطط، ما زال بإمكانهم تحليل الأحداث الأقدم ومعالجة الحقول التي تكون قيمها موجودة أو مفقودة معالجةً خاصة. اختره عندما تتوقع إعادة تشغيل الأحداث التاريخية، بحيث يتعامل المستهلكون مع كل إصدار أقدم بشكل صحيح – كما في تخزين الأحداث (event sourcing) مثلًا.
| النمط | التواصل | السيناريو | الطريقة |
| FORWARD/FULL | الرسائل: الأحداث | إضافة حقل اختياري | أضفه في proto |
| FORWARD | الرسائل: الأحداث | إضافة حقل مطلوب | أضفه في proto |
| FULL | الرسائل: الأحداث | إضافة حقل مطلوب | كاسر للتوافق |
| FORWARD/FULL | الرسائل: الأحداث | حذف حقل اختياري | أزله من proto |
| FORWARD ONLY | الرسائل: الأحداث | جعل حقل اختياري مطلوبًا | أضف no_box |
| FULL | الرسائل: الأحداث | جعل حقل اختياري مطلوبًا | كاسر للتوافق |
| FORWARD/FULL | الرسائل: الأحداث | جعل حقل مطلوب اختياريًا | كاسر للتوافق* |
| FORWARD/FULL | الرسائل: الأحداث | حذف حقل مطلوب | كاسر للتوافق |
| FORWARD/FULL | الرسائل: الأحداث | إضافة حقل إلى oneof | كاسر للتوافق |
| FORWARD/FULL | الرسائل: الأحداث | نقل حقل إلى oneof جديد | انقله في proto (للاختياري فقط) |
| FORWARD ONLY | الرسائل: الأحداث | حذف حقل من oneof | أزله من proto |
| FULL | الرسائل: الأحداث | حذف حقل من oneof | كاسر للتوافق |
الرسائل: الأوامر
يشبه هذا النمط إلى حد بعيد التعامل مع طلبات GRPC. فالعقد يمتلكه معالج الأوامر، لذا يجب أن يبقى متوافقًا خلفيًا.
| النمط | التواصل | السيناريو | الطريقة |
| BACKWARD | الرسائل: الأوامر | إضافة حقل اختياري | أضفه في proto |
| BACKWARD | الرسائل: الأوامر | إضافة حقل مطلوب | كاسر للتوافق |
| BACKWARD | الرسائل: الأوامر | حذف حقل مطلوب | أزله من proto |
| BACKWARD | الرسائل: الأوامر | حذف حقل اختياري | أزله من proto |
| BACKWARD | الرسائل: الأوامر | جعل حقل مطلوب اختياريًا | أزل no_box |
| BACKWARD | الرسائل: الأوامر | جعل حقل اختياري مطلوبًا | كاسر للتوافق |
| BACKWARD | الرسائل: الأوامر | إضافة حقل إلى oneof | أضفه في proto |
| BACKWARD | الرسائل: الأوامر | حذف حقل من oneof | كاسر للتوافق |
| BACKWARD | الرسائل: الأوامر | نقل حقل إلى oneof جديد | انقله في proto |
الاختيارية وno_box
بدءًا من الإصدار 3، لم يعد بروتوكول Protobuf يسمح بالحقول المطلوبة (required)، وأصبحت الاختيارية (optional) هي الافتراضية. والمنطق في ذلك أن السماح للناس بإضافة الحقول المطلوبة أو حذفها أدى إلى مشكلات كثيرة جدًا من كسر غير متوقع لتوافق النقل (انظر التعليق الأصلي على GitHub).
ومع ذلك، وكما توضح الجداول أعلاه، فإن الحقول المطلوبة منطقية في سيناريوهات معينة. فمع التوافق BACKWARD مثلًا، من المقبول تمامًا أن تبدأ بحقول مطلوبة في المخطط الأولي ثم تزيلها لاحقًا. وينطبق هذا على طلبات gRPC وعلى الأوامر غير المتزامنة. ولمنع ScalaPB من تغليف الأنواع غير البدائية في Option، أضف التعليق التوضيحي no_box، مثلًا:
google.protobuf.Timestamp createdAt = 1 [(scalapb.field).no_box = true];
حذف الحقول المطلوبة يكسر التوافق FORWARD، لكن في حالات معينة يمكن تنفيذ هذه العملية على مراحل:
- اجعل الحقل المطلوب اختياريًا بإزالة غلاف
no_box - حدّث كل المستهلكين بحيث يتعاملون مع حالة None
- ابدأ بإنتاج حالة
None
انتبه! هذه عملية محفوفة بالمخاطر. فهي لا تتوافق تمامًا مع قواعد التوافق في ورقتنا المرجعية، لذا ما زلت أصنّفها على أنها «كاسرة للتوافق».
القيم الافتراضية
لا يغلّف ScalaPB أنواع protobuf البدائية مثل string وdouble وغيرهما في Option. وبدلًا من ذلك تُعيَّن قيم افتراضية، مثل السلسلة الفارغة «». وقد يكون هذا خطيرًا جدًا، لأن هذه القيم الافتراضية غير صالحة في الواقع في معظم الحالات – لذا إذا تركتَ حقلًا عند بناء case class فستقع في مشكلة. ولتحسين أمان الأنواع، يمكنك اتباع أحد نهجين:
-
ضع
no_default_values_in_constructorفي ملف .proto الخاص بك، وهذا يعطّل القيم الافتراضية فقط. العيب: يصبح الحقل مطلوبًا بصرامة، ولا توجد طريقة بسيطة لتحويله إلى حقل اختياري لاحقًا.option (scalapb.options) = { no_default_values_in_constructor: true }; -
الاعتماد على أنواع الأغلفة (wrapper types)
يمكن أن تضيف بعض الضوضاء إلى الكود، لأن الوصول إلى القيمة الفعلية يتطلب استدعاءات.valueإضافية، لكنها معno_boxتمنحك تحكمًا أفضل في كيفية تطور الاختيارية.
إضافة: buf
إن صيانة ملفات protobuf وتوزيع العقد وفرض قواعد التوافق والحفاظ على مجموعة متسقة من قواعد تصميم واجهات برمجة التطبيقات، كل ذلك يتطلب استثمارًا كبيرًا. يُعدّ buf مجموعة أدوات مثيرة للاهتمام صُممت لأتمتة هذه العمليات. فهو يأتي بمصرّف Protobuf جديد عالي الأداء، ومدقّق شيفرة (linter) يفرض خيارات وبنية سليمة لتصميم واجهات برمجة التطبيقات، وكاشف للتغييرات الكاسرة يفرض التوافق على مستوى الكود المصدري أو النقل، ومولِّد يشغّل إضافات protoc الخاصة بك وفق قالب قابل للضبط. ويتضمن أيضًا The Buf Schema Registry (BSR) – منصة SaaS مستضافة تعمل كمصدر الحقيقة لدى مؤسستك لواجهات Protobuf البرمجية. فكّر في إدخال أجزاء من buf إلى مسار مشروعك لتحصل على المزيد من العمل مع Protobuf.
الخلاصة
تعتمد متطلبات التوافق التي تحتاجها مخططاتك على عوامل كثيرة. ويمكن لامتدادات ScalaPB مثل الحقول المطلوبة أو تعطيل القيم الافتراضية أن ترفع أمان الأنواع على جانب التطبيق دون التضحية بتوافق نقل Protobuf، شريطة أن تتناسب قواعد التطور جيدًا مع حالة الاستخدام. آمل أن يساعدك هذا الدليل على ضبط تلك القواعد لتطبيقك الخاص – أو حتى على أتمتة كيفية فرضها بالكامل.