فهل هو RAML أو OAS (Swagger)؟

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

تم إعداد المشاركة آنا ميليكوفا и فلاديمير لاباتين

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

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

مخطط خدمات أمازون الصغيرة من سقسقة ويرنر فوجيليس، المدير التنفيذي للتكنولوجيا في أمازون
ما هي المعضلة؟ في الواقع، هناك طريقتان للتفاعل مع الخدمات الصغيرة - HTTP Rest وgRPC من Google. نظرًا لعدم رغبتنا في التورط في مجموعة تقنيات Google، اخترنا HTTP Rest. غالبًا ما يتم وصف التعليقات التوضيحية لعقد HTTP REST بأحد التنسيقين: RAML وOAS، المعروف سابقًا باسم Swagger، لذلك يواجه كل فريق تطوير الحاجة إلى اختيار أحد المعايير. ولكن كما تبين، فإن اتخاذ هذا الاختيار يمكن أن يكون صعبًا للغاية.

لماذا هناك حاجة إلى التعليقات التوضيحية؟

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

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

مثال على وصف العقد المنظم

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

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

لتمكين أدوات إضافية، يتمتع كل من RAML وOAS بالقدرة على إضافة بيانات تعريف غير منصوص عليها في المعيار (على سبيل المثال، هذه هي الطريقة التي يتم بها ذلك في منظمة الدول الأمريكية).

وبشكل عام، فإن نطاق الإبداع في استخدام عقود الخدمات المصغرة كبير... على الأقل من الناحية النظرية.

مقارنة القنفذ مع الثعبان

في الوقت الحالي، مجال التطوير ذو الأولوية في Acronis هو تطوير Acronis Cyber ​​Platform. Acronis Cyber ​​Platform عبارة عن نقاط جديدة لتكامل خدمات الطرف الثالث مع Acronis Cyber ​​Cloud وجزء الوكيل. على الرغم من أننا كنا سعداء بواجهات برمجة التطبيقات الداخلية الخاصة بنا الموضحة في RAML، إلا أن الحاجة إلى نشر واجهة برمجة التطبيقات أثارت مرة أخرى مسألة الاختيار: ما هو معيار التعليقات التوضيحية الأفضل لاستخدامه في عملنا؟

في البداية، بدا أن هناك حلين - التطورات الأكثر شيوعًا كانت RAML وSwagger (أو OAS). ولكن في الواقع اتضح أنه لا يوجد بديلان على الأقل، بل 2 أو أكثر.

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

لكن مطور RAML، Mulesoft، انضم إلى اتحاد Open API، الذي يقوم بالتطوير اختيال. ولذلك، علقت شركة RAML تطويرها. ولتخيل شكل الحدث، تخيل أن المشرفين على مكونات Linux الرئيسية غادروا للعمل لدى Microsoft. يخلق هذا الموقف المتطلبات الأساسية لاستخدام Swagger، الذي يتطور ديناميكيًا وفي الإصدار الثالث الأحدث - يلحق عمليا بـ RAML من حيث المرونة والوظائف.

إن لم يكن لواحد ولكن ...

وكما تبين، لم يتم تحديث جميع الأدوات المساعدة مفتوحة المصدر إلى OAS 3.0. بالنسبة للخدمات الصغيرة في Go، سيكون الأمر الأكثر أهمية هو الافتقار إلى التكيف تبختر للحصول على أحدث إصدار من المعيار. ومع ذلك، فإن الفرق بين Swagger 2 وSwagger 3 هو تسربت. على سبيل المثال، في الإصدار الثالث المطورين:

• تحسين وصف مخططات المصادقة
• مكتمل دعم مخطط JSON
• ترقية القدرة على إضافة أمثلة

الوضع مضحك: عند اختيار معيار، تحتاج إلى النظر في بدائل منفصلة RAML، Swagger 2 و Swagger 3. ومع ذلك، فإن Swagger 2 هو الوحيد الذي يتمتع بدعم جيد لأدوات OpenSource. RAML مرنة جدًا... ومعقدة، كما أن Swagger 3 لا تحظى بدعم جيد من قبل المجتمع، لذا سيتعين عليك استخدام أدوات خاصة أو حلول تجارية، والتي تميل إلى أن تكون باهظة الثمن.

علاوة على ذلك، إذا كان هناك العديد من الميزات الرائعة في Swagger، مثل البوابة الجاهزة Editor.swagger.io، حيث يمكنك تحميل تعليق توضيحي والحصول على تصوره مع وصف تفصيلي وروابط واتصالات، ثم بالنسبة لـ RAML الأكثر أساسية والأقل ودية لا توجد مثل هذه الفرصة. نعم، يمكنك البحث عن شيء ما بين المشاريع على GitHub، والعثور على نظير هناك ونشره بنفسك. ومع ذلك، في أي حال، سيتعين على شخص ما صيانة البوابة، وهي ليست مناسبة للاستخدام الأساسي أو احتياجات الاختبار. بالإضافة إلى ذلك، يعد Swagger أكثر "غير مبدئي"، أو أكثر ليبرالية - يمكن إنشاؤه من التعليقات في الكود، والذي يتعارض بالطبع مع المبدأ الأول لواجهة برمجة التطبيقات (API) ولا يدعمه أي من أدوات RAML المساعدة.

في وقت ما، بدأنا العمل مع RAML كلغة أكثر مرونة، ونتيجة لذلك كان علينا القيام بالكثير من الأشياء بأنفسنا. على سبيل المثال، يستخدم أحد المشاريع الأداة المساعدة ramlfications في اختبارات الوحدة، والذي يدعم فقط RAML 0.8. لذلك كان علينا إضافة عكازات حتى تتمكن الأداة المساعدة من "أكل" الإصدار 1.0 من RAML.

هل تحتاج إلى الاختيار؟

بعد أن عملنا على استكمال النظام البيئي لحلول RAML، توصلنا إلى استنتاج مفاده أننا بحاجة إلى تحويل RAML إلى Swagger 2 وتنفيذ جميع عمليات الأتمتة والتحقق والاختبار والتحسين اللاحق فيه. تعد هذه طريقة جيدة للاستفادة من مرونة RAML ودعم أدوات المجتمع من Swagger.

لحل هذه المشكلة، هناك أداتان مفتوحتان المصدر يجب أن توفرا تحويل العقود:

1. oas-raml-converter هي أداة مساعدة غير مدعومة حاليًا. أثناء العمل معه، اكتشفنا أنه يحتوي على عدد من المشكلات المتعلقة بسجلات RAML المعقدة التي "تنتشر" على عدد كبير من الملفات. هذا البرنامج مكتوب بلغة JavaScript ويقوم باجتياز عودي لشجرة بناء الجملة. نظرًا للكتابة الديناميكية، يصبح من الصعب فهم هذا الرمز، لذلك قررنا عدم إضاعة الوقت في كتابة التصحيحات لأداة مساعدة على وشك الموت.
2. محلل webapi - أداة من نفس الشركة تدعي أنها جاهزة لتحويل أي شيء وكل شيء وفي أي اتجاه. حتى الآن، تم الإعلان عن دعم RAML 0.8 وRAML 1.0 وSwagger 2.0. ومع ذلك، في وقت بحثنا، كانت المنفعة لا تزال قائمة الى ابعد حد رطبة وغير صالحة للاستعمال. يقوم المطورون بإنشاء نوع من IRمما يسمح لهم بإضافة معايير جديدة بسرعة في المستقبل. لكن حتى الآن لا يعمل الأمر.

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

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

اختتام

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

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

ولكن من الجدير أن ندرك أن جميع النظم البيئية الموجودة اليوم غير كاملة. لذلك، إذا كان هناك معجبين في الشركة يحبون العمل في RAML لأنه “يتيح لك التعبير عن الأفكار بمرونة أكبر”، أو على العكس يفضلون Swagger لأنه “أكثر وضوحًا”، فمن الأفضل تركهم للعمل. لقد اعتادوا عليها ويريدونها، لأن أدوات أي من التنسيقات تتطلب التعديل مع الملف.

أما بالنسبة لتجربتنا، فسنتحدث في المنشورات التالية عن عمليات التحقق الثابتة والديناميكية التي نجريها استنادًا إلى بنية RAML-Swagger الخاصة بنا، بالإضافة إلى الوثائق التي ننشئها من العقود، وكيف يعمل كل ذلك.

يمكن للمستخدمين المسجلين فقط المشاركة في الاستطلاع. تسجيل الدخول، من فضلك.

ما هي اللغة التي تستخدمها لتعليق عقود الخدمات الصغيرة؟

• الرمل 0.8

• الرمل 1.0

• التباهي 2

• OAS3 (ويعرف أيضًا باسم)

• مخطط

• آخر

• عدم استخدام

صوت 100 مستخدمًا. امتنع 24 مستخدما عن التصويت.

المصدر: www.habr.com