في منشور سابق
، تحدثنا عن كيفية وسبب قيامنا في Ancronis بتقديم تعليقات توضيحية للخدمات الميكروية ، ووعدنا بمشاركة ممارستنا المتمثلة في استخدام تنسيق API واحد لكامل Acronis Cyber Platform. سنخبر اليوم عن تجربتنا في فحوصات التعليقات التوضيحية الثابتة - ويعرف أيضًا باسم الخطوة الأولى على طريق إدخال التعليقات التوضيحية في الشركة.
لذلك ، لنفترض أن لديك بالفعل تعليقات توضيحية لكل أو معظم واجهات برمجة التطبيقات. سؤال معقول طرحه زملاؤنا أيضًا: "ما الذي يمكن فعله بهذه الأشياء السحرية؟"
في الواقع ، هناك نوعان من الشيكات التي يمكن القيام بها مباشرة عن طريق الشرح. تذهب الاختبارات الثابتة مباشرةً إلى نص التعليقات التوضيحية لـ Swagger أو RAML. لا يحتاجون إلى أي شيء آخر ، ويمكن اعتبارهم بحق أول ميزة لاستخدام عقود الخدمات المصغرة الرسمية.
لا يمكن بدء عمليات الفحص الديناميكية إلا إذا كان لديك خدمة عمل. إنها أكثر تعقيدًا إلى حد ما ، لأنها تسمح لك بالغطس بشكل أعمق والتحقق من مدى صلاحية التعليق التوضيحي على الإطلاق ، واختبار استقرار الخدمة ، وكذلك القيام بالكثير. ولكن هذا هو موضوع المنشور التالي ، واليوم سنركز على الإحصائيات.
يعيش دليل API!
لكي لا تخلط بينك وبين الآخرين ، تجدر الإشارة على الفور إلى أن اختبارات التعليقات التوضيحية الثابتة يتم إنشاؤها للتحكم في توافق تعليقات تعليقات واجهة برمجة التطبيقات (ونأمل أن تكون واجهات برمجة التطبيقات نفسها) مع متطلبات الشركة. يمكن أن يكون إما مجرد الممارسات التي تتبعها الشركة ، أو واجهة برمجة تطبيقات توجيهية كاملة ، والتي تضفي الطابع الرسمي على القواعد لإعداد API لخدماتك.
عندما نتحدث عن عالم الملونة من الخدمات المجهرية ، هذا أمر مهم للغاية ، لأن كل فريق يمكن أن يكون له إطاره الخاص ، أو لغته البرمجية الخاصة ، أو مجموعة فريدة من نوعها ، أو بعض المكتبات الخاصة. تحت تأثير الممارسات الخاصة بـ microservice ، يتغير عرض واجهة برمجة التطبيقات (API) للمراقب الخارجي. هذا يخلق مجموعة متنوعة لا لزوم لها. للتفاعل الفعال لعناصر النظام الإيكولوجي (أو النظام الأساسي) ، من الضروري "محاذاة" واجهة برمجة التطبيقات قدر الإمكان.
فيما يلي مثال: يتم إرجاع رمز 404 إلى واجهة برمجة التطبيقات لمكون واحد فقط في حالة عدم وجود المورد. ويربط الفريق الآخر هذا الخطأ بمنطق التطبيق وسيعود واجهة برمجة التطبيقات إلى 404 عندما يريد المستخدم شراء منتج انتهى في المستودع. وصف
أتيغايف هذه المشاكل بوضوح شديد
هنا . هذا التناقض في فهم الكود 404 سيؤدي إلى إبطاء عملية التطوير ويؤدي إلى أخطاء ، مما يعني دعوات غير ضرورية للدعم أو ساعات إضافية من التصحيح ، ولكن على أي حال ، يتم قياس المشكلات من الناحية النقدية.
وتستكمل تفاصيل بناء الجملة والتسمية التي اعتمدتها الشركة بجوانب مختلفة خاصة بـ REST نفسها. يجب على المطور الإجابة عن أسئلة مثل:
- هل ستكون وظيفة البريد العاطفية أم لا؟
- ما هي رموز الخطأ التي نستخدمها وماذا تعني؟
- هل يمكنني إضافة منطق العمل إلى رموز الخطأ؟
الآن تخيل أن كل فريق يجب أن يتغلب بشكل فردي على هذه الإجابات.
يمكن أن يكون تنسيق استعلام البحث مختلفًا تمامًا. على سبيل المثال ، هناك حوالي 12 طريقة لإنشاء نموذج يتم فيه فقط سرد هؤلاء المستخدمين الذين لديهم MacBookPro وهجمات الفيروسات المتكررة. عند العمل في مشروع كبير يتكون من العشرات من الخدمات المصغرة ، من الضروري أن يكون بناء جملة استعلام البحث شائعًا في جميع إصدارات الشركة ومنتجاتها. وإذا اعتاد شخص ما على الإشارة إلى أحد المنتجات / الخدمات الخاصة بتطويرك ، فإنه يتوقع أن يجد نفس هيكل الطلب والاستجابة في آخر. خلاف ذلك ، لن يتم تجنب الدهشة (والحزن).
لدى العديد من الشركات ، وخاصة الشركات العملاقة ، مثل
Microsoft و
PayPal و
Google ، إرشاداتها الخاصة ، وهي مدروسة جيدًا. لكن استخدام إرشادات الأشخاص الآخرين غير ممكن دائمًا ، لأنه يرتبط إلى حد كبير بخصائص الشركة. بالإضافة إلى ذلك ، لدى تفكير الجميع بنية مختلفة ، وقد تختلف القواعد ببساطة لأنها أكثر ملاءمة للناس للعمل بهذه الطريقة وليس على خلاف ذلك.
لم يتحقق الفهم بأن أكرونيس يحتاج إلى دليل API الخاص به على الفور ، ولكن مع تزايد عدد المطورين ، والخدمات المصغرة والعملاء والتكامل الخارجيين في الواقع. في مرحلة ما ، كان على فريق المهندسين المعماريين وضع قواعد موحدة للإعلان عن واجهة برمجة التطبيقات ، مع مراعاة كل من خبرة عمالقة تكنولوجيا المعلومات المذكورة أعلاه والممارسات الفعلية القائمة بالفعل في فرق التطوير.
تتمثل إحدى مشكلات هذا التطبيق المتأخر لواجهة برمجة تطبيقات Guideline في واجهات برمجة التطبيقات المنشورة الحالية التي لا تفي بالمتطلبات ، مما يؤدي بدوره إلى تكاليف إضافية لإعادة تصميم الواجهات والحفاظ على التوافق مع الإصدارات السابقة. لذلك ، إذا كان نموذج عملك يتضمن تكامل ونشر API في المستقبل ، فأنت بحاجة إلى التفكير في قواعد موحدة في أقرب وقت ممكن.
بالطبع ، لم يجعل اعتماد واجهات برمجة التطبيقات الإرشادية تلقائيًا جميع واجهات برمجة التطبيقات. كان لابد من تحليل كل واجهة برمجة التطبيقات ، وكان على كل devlid أن يفهم المتطلبات الجديدة. لذلك ، قمنا بأتمتة عمليات التحقق من RAML مقابل واجهة برمجة التطبيقات التوجيهية التي طورناها.
تحليل ثابت
أولاً ، عليك أن تقرر ما الذي سنحلله بشكل ثابت. لا يمكن إضفاء الطابع الرسمي على جميع نقاط واجهة برمجة التطبيقات التوجيهية ، لذلك تحتاج أولاً إلى إبراز مجموعة من القواعد التي يمكن فهمها بسهولة من التعليق التوضيحي لواجهة برمجة التطبيقات.
في الإصدار الأول ، حددنا القواعد التالية:
- تحقق من أوصاف API. كما قلنا في مقالتنا السابقة ، يمكنك إنشاء وثائق جميلة بناءً على شرح API. هذا يعني أن كل مورد ومعلمة استعلام واستجابة يجب أن يكون لها وصف يعطي كل المعلومات الضرورية لأي مستخدم لواجهة برمجة التطبيقات. قد يبدو ذلك تافهًا ، ولكن كم هو سهل أن نوضح للمطورين أن تعليقاتهم التوضيحية ليست غنية بالأوصاف!
- التحقق من وجود وصحة الأمثلة. تسمح لك لغات شرح API أيضًا بوصف الأمثلة. على سبيل المثال ، ردًا على ذلك ، يمكننا إضافة مثال على استجابة حقيقية للخدمة ، شيء من الحياة الحقيقية. استخدام الأمثلة يوضح كيفية استخدام نقطة النهاية وعملها ، ونتحقق من الأمثلة من خلال التحليل الثابت للتعليقات التوضيحية.
- التحقق من صحة رموز استجابة HTTP. يحدد معيار HTTP عددًا كبيرًا من الرموز ، لكن يمكن تفسيرها بطرق مختلفة. المبدأ التوجيهي لدينا إضفاء الطابع الرسمي على استخدام الرموز. نحن أيضًا نحد من إمكانية تطبيق الرموز المختلفة وفقًا لطريقة HTTP. على سبيل المثال ، يتم إرجاع رمز 201 ، وفقًا لمواصفات HTTP ، عند إنشاء مورد. لذلك ، سيكون GET Return 201 عبارة عن دعوة للاستيقاظ (إما أن يتم استخدام الكود بشكل غير صحيح أو يقوم GET بإنشاء المورد). لذلك ، تحظر واجهة برمجة التطبيقات التوجيهية لدينا مثل هذا الاستخدام. علاوة على ذلك ، فإن المهندسين المعماريين لديهم مجموعات ثابتة من الرموز لكل طريقة ، ونحن الآن نتحقق منها في الوضع الثابت على مستوى التعليقات التوضيحية.
- التحقق من طرق HTTP. يعلم الجميع أن بروتوكول HTTP يحتوي على مجموعة من الطرق القياسية (GET ، POST ، PUT ، وما إلى ذلك) ، كما يتيح أيضًا استخدام الأساليب المخصصة. تصف API Guideline الخاصة بنا الأساليب المسموح بها ، ولكن غير المرغوب فيها (OPTIONS) ، وكذلك ممنوع تمامًا (لا يمكن استخدامها إلا بمباركة المهندسين المعماريين). ممنوع تشمل طريقة HEAD القياسية ، وكذلك أي أساليب مخصصة. كل هذا يسهل التحقق منه في شروح العقود.
- التحقق من حقوق الوصول. نأمل أن لا تحتاج الحاجة إلى دعم التفويض في عام 2019 إلى تفسيرات إضافية. يجب أن تتضمن الوثائق الجيدة معلومات حول الأدوار التي يدعمها API وأساليب API المتاحة لكل دور. بالإضافة إلى توثيق المعلومات حول نموذج الدور ، المسجلة على مستوى التعليقات التوضيحية ، يتيح لك القيام بأشياء أكثر إثارة للاهتمام في الديناميات ، ومع ذلك ، سنتحدث عن هذا في المقالة التالية.
- التحقق من التسمية. يخفف الصداع من استخدام طرق مختلفة لتسمية الكيانات. بشكل عام ، يوجد "معسكران" - مؤيدو CamelCase و snake_case.Camelcase - عندما تبدأ كل كلمة بحرف كبير ، و snake_case - عندما تكون الكلمات مفصولة بشرطة سفلية وكل شيء مكتوبًا بأحرف صغيرة. في لغات مختلفة ، من المعتاد إعطاء الأسماء بطرق مختلفة. على سبيل المثال ، يتم قبول snake_case في Python ، وتم اعتماد CamelCase في Go أو Java. لقد جعلنا اختيارنا عالميًا لجميع المشاريع وتم إصلاحه في دليل API. لذلك ، من خلال الشروح ، نتحقق من أسماء الموارد والمعلمات بشكل ثابت ؛
- التحقق من صحة الرؤوس المخصصة. هذا مثال آخر لفحص التسمية ، لكنه مرتبط بشكل خاص بالرؤوس. عندنا في Acronis ، من المعتاد استخدام تنسيق النموذج X-Custom-Header-Name (على الرغم من إهمال هذا التنسيق). ونتحكم في التزامها على مستوى التعليقات التوضيحية.
- تحقق من دعم HTTPS. يجب أن تدعم أي خدمة حديثة HTTPS ، ويعتقد البعض أن العمل مع HTTP هذه الأيام يعد أخبارًا سيئة بشكل عام. لذلك ، يجب توضيح تعليق RAML أو Swagger. أن microservice يدعم HTTPS دون HTTP.
- تحقق من بنية URI. في أوقات ما قبل التاريخ ، أي قبل إصدار واجهة توجيهية API ، بدا طلب URI مختلفًا في الخدمات المختلفة: في مكان ما / api / 2 ، في مكان ما / api / service_name / v2 ، وهكذا. الآن في المبدأ التوجيهي لدينا يتم تحديد بنية URI قياسية لجميع واجهات برمجة التطبيقات الخاصة بنا. يصف الدليل كيف ينبغي أن يبدو حتى لا يخلق البلبلة.
- التحقق من توافق الإصدارات الجديدة. هناك عامل آخر يجب على أي مؤلف API أن يضعه في الاعتبار وهو التوافق مع الإصدارات السابقة. من المهم التحقق مما إذا كان الرمز المبني على أساس واجهة برمجة التطبيقات القديمة يمكن أن يعمل مع الإصدار الجديد. بناءً على هذا التغيير ، يمكن تقسيمها إلى فئتين: كسر التوافق مع الإصدارات السابقة ومتوافق. يعلم الجميع أن كسر التغييرات أمر غير مقبول ، وإذا كنت ترغب في "تحسين" شيء ما بشكل كبير ، يجب على المطور إصدار نسخة جديدة من واجهة برمجة التطبيقات ، ولكن يمكن أن يكون الجميع على خطأ ، لذلك فإن هدفنا الآخر في مرحلة الاختبارات الثابتة هو تخطي التغييرات المتوافقة فقط وأقسم التغييرات غير المتوافقة. من المفترض أن يتم حفظ التعليق التوضيحي ، مثل الرمز ، في المستودع ، وبالتالي ، فإنه يحتوي على سجل التغييرات بالكامل. لذلك ، يمكننا التحقق من HTTP REST من أجل التوافق مع الإصدارات السابقة. على سبيل المثال ، لا تتعارض إضافة التوافق (الطريقة ، المعلمة ، رمز الاستجابة) ، وقد تتسبب الإزالة في فقد التوافق. ويمكن بالفعل التحقق من ذلك على مستوى التعليقات التوضيحية.
عندما لا توجد أوصاف
عندما يكون هناك أوصاف
النتائج
يلزم إجراء تحليل ثابت للتعليقات التوضيحية من أجل التحقق (لا ، ليس من جودة الخدمة) ، ولكن جودة واجهة برمجة التطبيقات. تتيح لك هذه المرحلة محاذاة واجهات البرنامج مع بعضها البعض بحيث يعمل الناس في بيئة واضحة ومفهومة حيث كل شيء يمكن التنبؤ به إلى حد ما.
بالطبع ، من الضروري فقط التعامل مع مثل هذه الشكليات في الشركات الكبيرة بما يكفي ، عندما يكون فحص جميع المراسلات "يدويًا" طويلًا للغاية ومكلفة وغير موثوق بها. بدء التشغيل الصغير لا يحتاج إليه. على الأقل في الوقت الحاضر. ولكن إذا كانت هناك خطط في المستقبل لتصبح يونيكورن ، مثل Akronis ، فإن الشيكات الثابتة و API الإرشادية سوف تساعدك.