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

تطوير مخططات Protobuf بالطريقة الصحيحة باستخدام ScalaPB وfs2grpc

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

9 دقائق قراءة
ScalaProtobufgRPC

اكتسب النموذج القائم على المخططات شعبية واسعة عبر كثير من نماذج التواصل. فعندما تُعرَّف واجهات برمجة التطبيقات بـ لغات وصف الواجهات، يمكن أن تتطور المخططات بشكل أمتن وأكثر أمانًا مقارنةً بالرسائل المبنية على 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، يحتفظ بها الخادم وينشرها. وعادةً يكون الناشر أول من يكيّف كوده مع العقد الجديد، ويأتي المستهلكون بعده. ومع ذلك، دعونا نستعرض كل حالة فرعية:

  1. إذا احتاج المنتِج إلى تحديث الأحداث دون كسر المستهلكين، الذين يمكنهم مواصلة استخدام المخطط القديم إلى أن يحدّثوا، فإن التوافق الأمامي يكفي.
  2. أو قد تفضّل تحديث المستهلكين أولًا. وإذا اخترت هذا الترتيب، فإن التوافق الخلفي هو ما يجب أن تحافظ عليه. وهذا النهج موصوف في وثائق Avro وSchema Registry – ألقِ نظرة للتعمق أكثر.
  3. التوافق الكامل هو الخيار الأشد صرامة. ويُنصح به عندما نحتاج إلى ضمان أن المستهلكين، حتى بعد تكيّفهم مع أحدث مخطط، ما زال بإمكانهم تحليل الأحداث الأقدم ومعالجة الحقول التي تكون قيمها موجودة أو مفقودة معالجةً خاصة. اختره عندما تتوقع إعادة تشغيل الأحداث التاريخية، بحيث يتعامل المستهلكون مع كل إصدار أقدم بشكل صحيح – كما في تخزين الأحداث (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، شريطة أن تتناسب قواعد التطور جيدًا مع حالة الاستخدام. آمل أن يساعدك هذا الدليل على ضبط تلك القواعد لتطبيقك الخاص – أو حتى على أتمتة كيفية فرضها بالكامل.