في العالم الديناميكي للخدمات الميكروية ، يمكن تغيير أي شيء - يمكن إعادة كتابة أي مكون بلغة أخرى باستخدام أطر عمل وهندسة مختلفة. يجب أن تظل العقود فقط بدون تغيير ، بحيث يكون من الممكن التفاعل مع الخدمة الصغيرة من الخارج بشكل مستمر ، بغض النظر عن التحولات الداخلية. واليوم سوف نتحدث عن مشكلتنا المتمثلة في اختيار شكل لوصف العقود وتبادل القطع الأثرية التي تم العثور عليها.
أعد هذا
المقال آنا ميليكوفا وفلاديمير لاباتينMikroservisy. عند تطوير Acronis Cyber Cloud ، أدركنا أننا لا نستطيع الابتعاد عنها. وتصميم خدمة microservice أمر مستحيل دون إضفاء الطابع الرسمي على العقد ، والذي هو واجهة microservice.
ولكن عندما يحتوي منتج ما على أكثر من مكون واحد ، ويصبح تطوير العقد نشاطًا منتظمًا ، فإنك تبدأ بشكل غير إرادي بالتفكير في تحسين العملية. يصبح من الواضح أن الواجهة (العقد) والتنفيذ (microservice) يجب أن تتوافق مع بعضها البعض ، وأن المكونات المختلفة يجب أن تفعل نفس الأشياء ، وأنه بدون اعتماد مركزي لكل هذه القرارات ، سيضطر كل فريق لقضاء بعض الوقت في الحصول عليها مرارا وتكرارا .
تصميم أمازون مايكروسيرفيس من سقسقة فيرنر فوجيليس ، أمازون CTOما هي المعضلة؟ في الواقع ، هناك طريقتان تتفاعلان بهما الخدمات المصغرة - HTTP Rest و gRPC من Google. لعدم الرغبة في المشاركة في رصة تكنولوجيا Google ، اخترنا HTTP Rest. غالبًا ما يتم شرح التعليقات التوضيحية لعقود HTTP REST بأحد التنسيقين التاليين: RAML و OAS ، المعروفة سابقًا باسم Swagger ، وبالتالي ، يواجه كل فريق تطوير الحاجة إلى اختيار أحد المعايير. ولكن ، كما اتضح ، يمكن أن يكون اختيار هذا صعبًا للغاية.
لماذا الشروح؟
هناك حاجة إلى تعليق توضيحي حتى يتمكن المستخدم الخارجي من معرفة ما يمكن القيام به بسهولة من خلال خدمتك من خلال واجهة HTTP الخاصة به. وهذا ، على المستوى الأساسي ، يجب أن يحتوي التعليق التوضيحي على الأقل على قائمة بالموارد المتاحة ، وطرق HTTP الخاصة به ، ونصوص الطلب ، وتعداد المعلمات ، ومؤشر للرؤوس الضرورية والمدعومة ، بالإضافة إلى رموز الإرجاع وتنسيقات الاستجابة. أحد العناصر المهمة للغاية في التعليق التوضيحي للعقد هو الوصف اللفظي ("ماذا يحدث إذا أضفت معلمة الاستعلام هذه إلى الطلب؟" ، "وفي هذه الحالة سيعود كود 400؟")
ومع ذلك ، عندما يتعلق الأمر بتطوير عدد كبير من الخدمات المصغرة ، أريد أن أحصل على فائدة إضافية من التعليقات التوضيحية المكتوبة. على سبيل المثال ، بناءً على RAML / Swagger ، يمكنك إنشاء كود العميل والخادم في عدد كبير من لغات البرمجة. يمكنك أيضًا تلقي الوثائق تلقائيًا عن الخدمة الميكروية وتحميلها على بوابة مطور البرامج :).
مثال على وصف منظم للعقدأقل شيوعًا هو ممارسة اختبار الخدمات المصغرة على أساس أوصاف العقد. إذا كتبت تعليقًا توضيحيًا ومكونًا ، فيمكنك إنشاء اختبار تجريبي يتحقق من مدى كفاية الخدمة مع أنواع مختلفة من بيانات الإدخال. هل تقوم الخدمة بإرجاع رمز استجابة غير موصوف في التعليق التوضيحي؟ هل ستكون قادرة على معالجة البيانات غير الصحيحة عن علم بشكل صحيح؟
علاوة على ذلك ، فإن التنفيذ عالي الجودة ليس فقط للعقود ذاتها ، ولكن أيضًا لأدوات تصور التعليقات التوضيحية ، يجعل من السهل التعامل مع الخدمة المصغرة. وهذا هو ، إذا وصف المهندس المعماري العقد نوعيا ، فإن المصممين والمطورين على أساسه سينفذون الخدمة في منتجات أخرى دون تكاليف إضافية.
لتشغيل الأدوات الإضافية ، يكون لدى كل من RAML و OAS القدرة على إضافة بيانات التعريف التي لا يتم توفيرها بواسطة المعيار (
على سبيل المثال ، يتم ذلك في OAS ).
بشكل عام ، مجال الإبداع في تطبيق عقود الخدمات الصغيرة ضخم ... على الأقل من الناحية النظرية
مقارنة بين القنفذ والثعبان
حاليًا ، مجال تطوير أولوية Acronis هو تطوير منصة Acronis Cyber Platform. Acronis Cyber Platform - هذه نقاط جديدة لتكامل خدمات الجهات الخارجية مع Acronis Cyber Cloud وجزء الوكيل. على الرغم من أن واجهات برمجة التطبيقات الداخلية الموصوفة في RAML كانت جيدة معنا ، فإن الحاجة إلى نشر واجهة برمجة التطبيقات مرة أخرى أثارت مسألة الاختيار: ما معيار التعليقات التوضيحية الأفضل في عملنا؟
في البداية ، بدا أن هناك حلين - هذه هي التطورات الأكثر شيوعًا في RAML و Swagger (أو OAS). ولكن في الواقع اتضح أن البدائل ليست على الأقل 2 ، ولكن 3 أو أكثر.
من ناحية ، هناك RAML - لغة قوية وفعالة. ينفذ هذا التسلسل الهرمي والميراث بشكل جيد ، لذلك هذا التنسيق أكثر ملاءمة للشركات الكبيرة التي تحتاج إلى العديد من الأوصاف - أي ، ليس منتج واحد ، ولكن العديد من الخدمات المجهرية التي لها أجزاء مشتركة من العقود - مخططات المصادقة ، ونفس أنواع البيانات ، وهيئات الخطأ.
لكن مطور RAML ، Mulesoft ، انضم إلى كونسورتيوم API المفتوح الذي يعمل على تطوير
Swagger . لذلك ، علقت RAML تطورها. لتخيل تنسيق الحدث ، تخيل أن محافظي مكونات Linux الرئيسية ذهبوا للعمل في Microsoft. يخلق هذا الموقف المتطلبات المسبقة لاستخدام Swagger ، الذي يتطور بشكل ديناميكي وفي أحدث إصدار - الإصدار الثالث - من الناحية العملية يتماشى مع RAML من حيث المرونة والأداء الوظيفي.
إن لم يكن لأحد ولكن ...
كما اتضح ، لم يتم تحديث جميع الأدوات المساعدة مفتوحة المصدر إلى الإصدار OAS 3.0. بالنسبة إلى خدمات micros on on Go ، سيكون الأكثر أهمية هو عدم وجود مداومة اختيارية على أحدث إصدار من المعيار. ومع ذلك ، فإن الفرق بين Swagger 2 و Swagger 3
كبير . على سبيل المثال ، في الإصدار الثالث ، المطورين:
- وصف محسّن لخطط المصادقة
- دعم مكتمل لخطة JSON
- ضخ القدرة على إضافة أمثلة
الموقف مضحك: عند اختيار معيار ، عليك أن تنظر إلى RAML و Swagger 2 و Swagger 3 كبديلين منفصلين. ومع ذلك ، فإن Swagger 2 فقط لديه دعم جيد لمجموعة أدوات OpenSource. RAML مرنة للغاية ... ومعقدة ، وسواغر 3 مدعوم بشكل سيئ من قبل المجتمع ، لذلك يجب عليك استخدام أدوات الملكية أو الحلول التجارية ، والتي عادة ما تكون باهظة الثمن.
في الوقت نفسه ، إذا كان هناك العديد من الميزات
الرائعة في Swagger ، مثل
محرر البوابة
الجاهزة .swagger.io ، والذي يمكنك من خلاله تنزيل التعليق التوضيحي والحصول على صورته مع وصف مفصل وروابط وروابط ، عندئذٍ لا توجد مثل هذه الإمكانية للحصول على RAML أكثر جوهرية وأقل ودية. نعم ، يمكنك البحث عن شيء من بين المشاريع على جيثب ، والعثور على التناظرية هناك ونشره بنفسك. ومع ذلك ، في أي حال ، سيتعين على شخص ما دعم البوابة ، والتي ليست ملائمة للاستخدام الأساسي أو احتياجات الاختبار. بالإضافة إلى ذلك ، يكون swagger "غير مبدئي" أكثر أو جيدًا أو ليبراليًا - يمكن إنشاؤه من التعليقات في التعليمات البرمجية ، والتي ، بالطبع ، تتعارض مع مبدأ API أولاً ولا تدعمها أي من أدوات RAML المساعدة ،
في وقت واحد ، بدأنا العمل مع RAML كلغة أكثر مرونة ، ونتيجة لذلك ، كان علينا أن نفعل الكثير بأيدينا. على سبيل المثال ، يستخدم أحد المشروعات الأداة المساعدة
ramlfications في اختبارات الوحدة ، والتي تدعم RAML 0.8 فقط. لذلك اضطررت إلى إضافة عكازات حتى تتمكن الأداة من "أكل" RAML الإصدار 1.0.
هل أحتاج للاختيار؟
بعد الانخراط في إضافة نظام إيكولوجي لحلول RAML ، توصلنا إلى استنتاج أننا بحاجة إلى تحويل RAML إلى Swagger 2 وننفذ بالفعل جميع عمليات التشغيل الآلي والتحقق والاختبار والتحسين اللاحق فيه. هذه طريقة جيدة لزيادة مرونة RAML ودعم أداة المجتمع من Swagger.
لحل هذه المشكلة ، هناك نوعان من أدوات OpenSource التي يجب أن تضمن تحويل العقود:
- oas-raml-Converter الآن أداة غير مدعومة. في عملية العمل معها ، وجدنا أن لديها عددًا من المشكلات المتعلقة بذاكرة الوصول العشوائي المعقدة "المنتشرة" على عدد كبير من الملفات. هذا البرنامج مكتوب بلغة جافا سكريبت ويقوم بإجراء تكراري متكرر لشجرة بناء الجملة. بسبب الكتابة الديناميكية ، يصبح من الصعب فهم هذا الرمز ، لذلك قررنا عدم إضاعة الوقت في كتابة تصحيحات عن أداة مساعدة للموت.
- webapi-parser هي أداة من نفس الشركة ، تدعي أنها مستعدة لتحويل كل شيء وكل شيء ، وفي أي اتجاه. حتى الآن ، تم الإعلان عن دعم RAML 0.8 و RAML 1.0 و Swagger 2.0. ومع ذلك ، في وقت دراستنا ، وكانت الأداة المساعدة الخام للغاية وغير صالحة للاستعمال. ينشئ المطورون نوعًا من الأشعة تحت الحمراء ، مما سيتيح لهم إضافة معايير جديدة بسرعة في المستقبل. لكن في الوقت الحالي ، كل هذا لا ينجح.
وهذه ليست كل الصعوبات التي واجهناها. إحدى الخطوات في خط أنابيبنا هي التحقق من صحة RAML من المستودع فيما يتعلق بالمواصفات. حاولنا العديد من المرافق. والمثير للدهشة أنهم جميعًا لعنوا تعليقاتنا في أماكن مختلفة وبكلمات سيئة مختلفة تمامًا. وليس الحال دائما :).
في النهاية ، استقرنا على المشروع الذي عفا عليه الزمن الآن ، والذي يحتوي أيضًا على عدد من المشكلات (أحيانًا ينفجر اللون الأزرق ، ويواجه مشاكل عند العمل باستخدام تعبيرات منتظمة). وبالتالي ، لم نجد طريقة لحل مهام التحقق والتحويل استنادًا إلى أدوات مجانية ، وقررنا استخدام أداة تجارية. في المستقبل ، عندما تصبح أدوات OpenSource أكثر تطوراً ، فقد يصبح حل هذه المشكلة أسهل. في هذه الأثناء ، بدا لنا الوقت واليد العاملة في "التشطيب" أكثر أهمية من تكلفة الخدمة التجارية.
استنتاج
بعد كل هذا ، أردنا أن نشارك تجربتنا ونلاحظ أنه قبل اختيار أداة لوصف العقود ، تحتاج إلى تحديد ما تريد منه بوضوح والميزانية التي أنت مستعد للاستثمار. إذا نسيت OpenSource ، فهناك الآن عدد كبير من الخدمات والمنتجات التي ستساعدك على التحقق والتحويل والتحقق من الصحة. لكنها باهظة الثمن ، وأحيانا باهظة الثمن. بالنسبة لشركة كبيرة ، تكون هذه التكاليف مقبولة ، لكن بالنسبة للشركات الناشئة ، يمكن أن تصبح عبئًا كبيرًا.
حدد مجموعة من الأدوات التي ستستخدمها لاحقًا. على سبيل المثال ، إذا كنت بحاجة فقط إلى عرض العقد ، فسيكون من الأسهل استخدام Swagger 2 ، الذي يحتوي على واجهة برمجة تطبيقات جميلة ، لأنه في RAML يجب عليك رفع الخدمة والحفاظ عليها بنفسك.
كلما زادت المهام التي لديك ، زادت الحاجة إلى الأدوات ، وستكون مختلفة لأنظمة مختلفة ، ومن الأفضل أن تتعرف على الفور على الإصدارات المتاحة لاتخاذ خيار يقلل تكاليفك إلى الحد الأدنى في المستقبل.
ولكن تجدر الإشارة إلى أن جميع النظم الإيكولوجية الموجودة اليوم غير كاملة. لذلك ، إذا كان لدى الشركة معجبين يرغبون في العمل في RAML ، لأنه "يسمح لك بالتعبير عن أفكارك بطريقة أكثر مرونة" ، أو على العكس من ذلك ، تفضل Swagger ، لأنه "أكثر قابلية للفهم" ، فمن الأفضل تركهم للعمل في ما يشتركون فيه. لقد اعتادوا على ذلك ويريدون ذلك ، لأن مجموعة الأدوات بأي شكل من الأشكال تحتاج إلى الانتهاء من ملف.
بالنسبة لتجربتنا ، سنتحدث في المنشورات التالية عن نوع عمليات الفحص الثابتة والديناميكية التي نقوم بها استنادًا إلى بنية RAML-Swagger ، وكذلك الوثائق التي ننتجها من العقود ، وكيف تعمل جميعها.