يتطلب الانتقال إلى بنية الخدمة الصغيرة مراجعة منهج التطوير والاختبار والصيانة والتصميم - بمعنى آخر ، إلى جميع جوانب دورة حياة مكونات البرنامج. في هذا المنشور ، سنتحدث عن الممارسات التي توصل إليها فريق مهندسي Acronis في الانتقال إلى أفضل واجهات برمجة التطبيقات للمكونات. ستشمل القصة كلاً من بيان المشكلة وتحليل حلولها. ربما يبدو هذا المنشور "نقيبًا" بالنسبة للبعض ، فلن يكون من الواضح لشخص ما سبب افتقاره إلى الحل الفائق X ، لكننا نأمل أن يكون هذا الأمر مفيدًا ومفيدًا لك. نحن ندعو بناة خدمات microservice لقراءة تعليقاتك وتركها تحت القط.
إذا كنت مشتركًا في مدونتنا ، فقد قرأت بالفعل عن عقود خدمات microservice. تحدثنا عنهم في مشاركات حول اختيار
Swagger أو RAML ، بالإضافة إلى
اختبارات ثابتة يمكن إجراؤها على أساس التعليقات التوضيحية التي تم إنشاؤها مسبقًا. سبب نشر اليوم هو
تقرير في مؤتمر HighLoad . كنا بحاجة إلى التحدث عمومًا عن المسار الذي سلكناه لإضفاء الطابع الرسمي على العلاقة بين الخدمات الصغيرة. واليوم أود أن أشارك هابر في استنتاجنا ، وكذلك للتحقق مما إذا كان المهندسون المعماريون الآخرون يتفقون معنا.
Microservices هي "الطوب" الذي يقوم المطورون من خلاله بإنشاء تطبيقات حديثة. تتفاعل كل هذه الخدمة مع العالم الخارجي من خلال واجهة برمجة التطبيقات. عادة ، يتم تطوير الخدمات المصغرة بواسطة فرق منفصلة ، متفرقة في بعض الأحيان جغرافياً ، لذلك من أجل العمل الفعال ، من الضروري الحفاظ على اتساق وسلامة واجهاتها العامة. في الشركات الكبيرة التي لديها مئات الخدمات ، من الضروري أن يكون هناك تعليق توضيحي لكل مكون: إضفاء الطابع الرسمي على بيانات المدخلات ووصف نتائج عملها بالتفصيل. إذا كنت تعمل مع HTTP REST ، فهناك نسقان توضيحيان شائعان لهذا: RAML و Open API Specification (aka Swagger). لكن الأسئلة التي نركز عليها اليوم ليست مرتبطة بأي بروتوكول معين. لذلك ، سيكون ما يلي ذا صلة حتى بالنسبة لـ gRPC.
قبل التاريخ
كان أكرونيس موجودًا منذ أكثر من 15 عامًا. خلال هذا الوقت ، تطورت المنتجات وقواعد الكود بشكل ملحوظ. من تطبيق سطح المكتب المعقد ، توصلنا إلى نموذج مؤسسي يحتوي على وحدات تحكم إدارة مركزية ، وتعيين الحقوق وسجلات التدقيق. كانت الخطوة التالية هي تحويل تطبيق المؤسسة إلى منصة مفتوحة ، حيث تم استخدام الخبرة المتراكمة للتكامل مع الخدمات الخارجية.
إذا كانت مهمة API قبل ذلك ، أصبحت الآن مكونًا مهمًا للمنتج. والعمليات التي توفرها واجهة برمجة التطبيقات هذه قد نضجت.
القضايا الرئيسية
المشاكل المحيطة ببناء API تبدو مألوفة للجميع. سنصفها في شكل متضخم: كآلام تعذب مبرمجًا افتراضيًا فازيا ومديره الأقل افتراضية كوليا. جميع الأسماء وهمية ، وأي مباريات ليست عرضية :)
1. الوصف قديماسمح للمبرمج Vasya بتطوير المكون A ، والذي يستخدم API للمكون B. يحتوي الأخير على تعليق توضيحي ، لكنه غير صالح. يتعين على Vasya الزحف إلى رمز شخص آخر ، والبحث عن الأشخاص ، وطرح الأسئلة. تنتهي المواعيد النهائية ، ويتعين على مديره كوليا التعامل مع عمليات نقل المواعيد النهائية.
2. API ليست متسقةأنهى المبرمج Vasya المهمة وانتقل إلى المهمة التالية المتعلقة بتشغيل المكون B. لكن كلا من المطورين B والمطورين C لديهم شعور مختلف بالجمال ، لذلك يتم تنفيذ نفس الأشياء بشكل مختلف في API. ذهب Vasya مرة أخرى للتعامل مع رمز ، وكوليا يعاني مرة أخرى من الفشل في الوفاء بالمواعيد النهائية.
3. API غير موثقةيقرر مدير Kolya نشر واجهة برمجة التطبيقات للمكون "أ" حتى يتمكن الدمجون من تكامل رائع. يواجه الدمجون مشكلات ، خدمة الدعم مثقلة ، كل شيء على النار مع المدير كوليا ، وفاسيا تشعر أن دوره سيأتي قريباً.
4. API غير متوافق مع الإصدار القديم.يتم تنفيذ عمليات الدمج ، يتم إطفاء جميع الحرائق. لكن Vasya يقرر فجأة أن واجهة برمجة التطبيقات لمكونه أبعد ما تكون عن الكمال ومغمورة في المراجعة. بالطبع ، في هذه الحالة ، يتم انتهاك التوافق مع الإصدارات السابقة وتنهار جميع عمليات الدمج. هذا الموقف يؤدي إلى تكاليف من جانب الدمجين وخسارة المال من قبل شركة التطوير.
طرق العلاج
تنشأ كل هذه المشكلات عندما لا يكون لدى المبرمجين أي فكرة عن واجهة برمجة تطبيقات REST جيدة أو تكون طريقة العرض هذه مجزأة. في الواقع ، ليس كل المطورين لديهم خبرة مع REST. وبالتالي ، فإن الطرق الرئيسية "للعلاج" تهدف إلى التعليم. عندما تبدأ رؤية واجهة برمجة التطبيقات الصحيحة ، المنسقة مع رؤية المطورين والمهندسين المعماريين والأفلام الوثائقية الأخرى ، في رأس كل مطور ، تصبح واجهة برمجة التطبيقات مثالية. تتطلب عملية تشكيل هذه الرؤية بذل جهود وأدوات متخصصة ، والتي سنتحدث عنها الآن.
الألم 1. الشرح لا يتوافق مع التنفيذ
قد يختلف التعليق التوضيحي عن الحالة الحالية للخدمة ليس فقط لأنه يمثل واجهة برمجة التطبيقات لـ "الماضي المظلم" ، والذي لا يمكن الوصول إليه. قد يكون أيضًا واجهة برمجة تطبيقات مستقبلية مشرقة لم تصل بعد.
سبب هذه الظروف هو عدم فهم سبب الحاجة إلى التعليقات التوضيحية. دون الخوف من جانب المهندسين المعماريين ، يميل المطورون إلى اعتبار التعليقات التوضيحية أداة مساعدة داخلية ولا تعني أن شخصًا ما في الخارج سيستخدمها.
يمكنك علاج هذا الألم عن طريق:
- مراجعة معمارية. شيء مفيد للغاية للشركات من جميع الأحجام ، حيث يوجد على الأقل مبرمج واحد "يعرف كيفية القيام بذلك بشكل صحيح". عند تغيير الخدمة ، يجب على المهندس المعماري أو الشخص المسؤول مراقبة حالة التعليقات التوضيحية وتذكير المبرمجين بأنه من الضروري تحديث الخدمة ليس فقط ، ولكن أيضًا وصفها. الآثار الجانبية - عنق الزجاجة في وجه المهندس المعماري
- توليد الشفرة من التعليقات التوضيحية. هذا هو ما يسمى النهج API الأولى. فهذا يعني أنك تقوم في البداية بعمل تعليق توضيحي ، ثم إنشاء الكود الأساسي (هناك أدوات كافية لذلك ، على سبيل المثال [go-swagger] (https://github.com/go-swagger/go-swagger)) ، ثم ملء خدمة الأعمال - المنطق. هذا الترتيب يتجنب التناقضات. يعمل بشكل جيد عندما يتم تحديد مجال المهام التي تحلها الخدمة بوضوح.
- اختبار التعليقات التوضيحية مقابل التنفيذ . للقيام بذلك ، نولد من الشرح (RAML / swagger) العميل الذي يقصف الخدمة بالطلبات. إذا كانت الإجابات تتوافق مع التعليق التوضيحي ، ولم تسقط الخدمة نفسها ، فكل شيء على ما يرام.
اختبار الشرح مقابل التنفيذدعونا نتناول الاختبار. مثل إنشاء الاستعلام التلقائي بالكامل مهمة معقدة. وجود بيانات من تعليقات توضيحية لواجهة برمجة التطبيقات ، يمكنك إنشاء طلبات منفصلة. ومع ذلك ، تتضمن أي واجهة برمجة تطبيقات التبعيات ، على سبيل المثال ، قبل الاتصال بـ GET / clients / {cliend_id} ، يلزمك إنشاء هذا الكائن أولاً ثم الحصول على معرفه. في بعض الأحيان تكون التبعيات أقل وضوحًا - يتطلب إنشاء كائن X تمرير معرف الكائن المرتبط Y ، وهذا ليس مجموعة فرعية. لا يسمح RAML أو Swagger بوصف التبعيات الصريحة. لذلك ، هناك عدة طرق ممكنة هنا:
- توقع تعليقات رسمية من المطورين في التعليقات التوضيحية التي تشير إلى التبعيات.
- اطلب وصفًا للتسلسل المتوقع من المطورين (هناك عدة طرق لوصف الطلبات التي تستخدم YAML ، أو DSL المتخصصة ، أو من خلال واجهة المستخدم الرسومية الجميلة ، كما فعلت الأبيج المهجورة الآن.
- خذ بيانات حقيقية (على سبيل المثال ، باستخدام OpenResty لتسجيل جميع طلبات الخادم والردود)
- استخرج التبعيات من التعليقات التوضيحية باستخدام الذكاء الاصطناعي ( تقريبًا )
في أي حال ، مهمة الاختبار تستغرق وقتًا طويلاً للغاية.
شخصيا ، وصلنا إلى نقطة إعداد تسلسل الاختبار يدويا. في أي حال ، يحتاج المطورون إلى كتابة الاختبارات ، حتى نتمكن من تزويدهم بأداة مريحة قد تجد بعض الأخطاء الإضافية.
تستخدم فائدتنا أداة yaml التالية لوصف تسلسل الطلبات:
تعلن الأقواس المجوفة عن المتغيرات التي يتم استبدالها أثناء الاختبار. يتم تمرير متغير العنوان كمعلمة CLI ، ويقوم عشوائي بإنشاء سلسلة عشوائية. الأكثر أهمية هنا هو حقل الاستجابة إلى var: إنه يحتوي على متغير سيتم فيه كتابة json مع استجابة الخادم. وبالتالي ، في السطر الأخير ، يمكنك الحصول على معرف الكائن الذي تم إنشاؤه باستخدام task.id.
الألم 2. API غير ثابت
ما هو الاتساق؟ لن نقدم أي تعريف رسمي ، ولكن التبسيط ، هذا هو الاتساق الداخلي. على سبيل المثال ، في المشروع الأولي ، احتاج Vasya إلى تجميع البيانات على التقارير حول HighLoad ، ويوفر API تصفية البيانات حسب السنة. بعد اكتمال المشروع تقريبًا ، جاء مدير Kolya إلى Vasya وطلبًا بإضافة إحصائيات عن المتحدثين إلى التحليل ، ولعمل طريقة جديدة "GET speakers" أيضًا مع التصفية حسب السنة. نتيجة لذلك ، يكمل Vasya الرمز في غضون ساعتين ، لكن خلال عملية الاختبار ، تبين أن الطريقة لا تعمل. والسبب هو أن "السنة" في إحدى الحالات هي رقم ، وفي حالة أخرى ، سلسلة. لكن هذا ، بالطبع ، ليس واضحًا للوهلة الأولى ويتطلب عناية مستمرة عند العمل مع API. API الثبات هو عندما لا تكون مثل هذه الرعاية المفرطة مطلوبة.
هناك العديد من الأمثلة على عدم الاتساق:
- استخدام صيغ مختلفة من نفس البيانات. على سبيل المثال ، تنسيق الوقت ، نوع المعرف (الرقم أو السلسلة UUID) ،
- تطبيق بناء جملة مختلف للترشيح أو ترقيم الصفحات ،
- خطط ترخيص مختلفة للخدمات. لا تكتفي أدمغة المبرمجين بالاختلافات فحسب ، بل تنعكس أيضًا على الاختبارات التي ستحتاج إلى دعم مخططات مختلفة.
العلاج :
- مراجعة معمارية. إذا كان هناك مهندس طاغية ، فسوف يضمن (في غياب الفصام) الاتساق. الآثار الجانبية: عامل الحافلة والطغيان :)
- إنشاء API التوجيهي. هذا معيار واحد يحتاج إلى تطوير (أو جاهز) ، ولكن الشيء الأكثر أهمية هو تنفيذه. وهذا يتطلب دعاية ، وعصا ، والجزرة.
- تنفيذ عمليات الفحص الثابتة للتأكد من توافقها مع إرشادات شرح التعليقات التوضيحية API (اقرأ عنها هنا ).
مثال - عناصر الاختبار الثابتةتقوم كل شركة باختيار خيار التوجيه الذي تستخدمه. وربما ، لا يوجد نهج عالمي ، ما ينبغي أن يكون وما لا ينبغي. بعد كل شيء ، كلما زاد عدد الأحكام الواردة في المعيار ، زادت صرامة تحكمك وتقييدك حرية الإبداع. والأهم من ذلك ، قلة من الناس قرأوا في النهاية وثيقة "100 صفحة فقط".
في شركتنا ، قمنا بإدراج النقاط التالية في المبدأ التوجيهي:
يمكن العثور على أمثلة جيدة أخرى للإرشادات في
Microsoft و
PayPal و
Google .
ألم 3. API غير موثقة
يعد وجود التعليقات التوضيحية شرطًا ضروريًا ولكنه ليس كافيًا لبساطة العمل مع واجهة برمجة التطبيقات. يمكنك كتابة تعليق توضيحي حتى لا يدرك إمكاناته الكاملة. يحدث هذا عندما:
- لا توجد أوصاف كافية (للمعلمات والرؤوس والأخطاء ، إلخ) ؛
- لا توجد أمثلة كافية على الاستخدام ، لأنه يمكن استخدام المثال ليس فقط لتحسين الوثائق (المزيد من السياق للمطور والقدرة على اللعب مباشرة مع واجهة برمجة التطبيقات مباشرة من البوابة) ، ولكن أيضًا للاختبار (كنقطة انطلاق للإعجاب)) ؛
- هناك ميزات لا يحملون وثائق.
عادةً ما يحدث هذا عندما لا يكون لدى المطورين فهم واضح لسبب الحاجة إلى التعليقات التوضيحية اللازمة ، عندما لا يكون هناك اتصال بين الكتاب التقنيين والمبرمجين ، وأيضًا إذا لم يكتشف أحد تكلفة الشركة بسبب الوثائق الرديئة. وإذا حضروا إلى المبرمج وسحبوا بعد كل طلب للحصول على الدعم ، سيتم ملء جميع التعليقات التوضيحية بسرعة كبيرة.
العلاج:- توفر أدوات إنشاء مرجع API لبرمجي. إذا رأى المطور شكل وصف API الخاص به بالنسبة للزملاء والمستخدمين ، فسيحاول تحسين التعليق التوضيحي. الآثار الجانبية: يتطلب تكوين هذه الأدوات عمل يدوي إضافي.
- إعداد التفاعل بين جميع المعنيين : المبرمجين ، المبشرين ، موظفي الدعم. الآثار الجانبية: لقاء الجميع مع الجميع ، وتعقيد العمليات.
- استخدام الاختبارات بناءً على شرح API . تنفيذ الاختبارات الثابتة أعلاه في مستودعات CI مع التعليقات التوضيحية.
في Acronis ، يتم إنشاء واجهة برمجة تطبيقات التعليقات التوضيحية بناءً على التعليقات التوضيحية مع عملاء SDK وأقسام Try-It. بالإضافة إلى نماذج التعليمات البرمجية ووصف حالات الاستخدام ، فإنها تشكل مجموعة كاملة من الإضافات الضرورية والملائمة للمبرمجين. انظر بوابتنا في developer.acronis.com
يجب أن أقول أن هناك فئة كاملة من الأدوات لإنشاء مرجع API. بعض الشركات نفسها تطوير هذه الأدوات لتلبية احتياجاتهم الخاصة. يستخدم آخرون أدوات بسيطة ومجانية مثل
محرر Swagger . بعد بحث طويل (طويل جدًا) ، استقرنا في Acronis على Apimatic.io ، مفضلينه على REST United و Mulesoft AnyPoint وغيرها.
الألم 4. مشاكل التوافق مع الإصدارات السابقة
قد يكون ضعف التوافق الخلفي بسبب أي تافه. على سبيل المثال ، يكتب مبرمج Vasya الكلمة التوافق في كل مرة مع الخطأ المطبعي: التوافق. تم العثور على هذا الخطأ المطبعي في التعليمات البرمجية وفي التعليقات وفي معلمة استعلام واحد. بعد أن لاحظت وجود خطأ ، تقوم Vasya باستبدال هذه الكلمة في جميع أنحاء المشروع وبدون النظر ترسل التغييرات إلى الإنتاج. بالطبع ، سيتم التوافق التوافق مع الوراء وسوف تنخفض الخدمة لعدة ساعات.
لماذا يمكن أن تحدث مثل هذه الأحداث؟ السبب الرئيسي هو سوء فهم لدورة حياة واجهة برمجة التطبيقات ، والتي يمكن أن تظهر في كسر التكامل ، في سياسات EOL (نهاية الحياة) التي لا يمكن التنبؤ بها ، وفي إصدارات واجهة برمجة التطبيقات الغامضة.
العلاج:- مراجعة معمارية. كما هو الحال دائمًا ، فإن اليد القوية للمهندس المعماري يمكن أن تمنع التوافق الخلفي. ومع ذلك ، فإن مهمتها الرئيسية هي شرح تكلفة دعم العديد من الإصدارات والبحث عن خيارات لإجراء تغييرات دون كسر واجهة برمجة التطبيقات الحالية.
- التحقق من التوافق مع الإصدارات السابقة. إذا تضمن التعليق التوضيحي لـ API وصفًا محدثًا ، فيمكن التحقق من انتهاكات التوافق مع الإصدارات السابقة في مرحلة CI ؛
- في الوقت المناسب تحديث الوثائق. يجب تحديث مرجع API ووصف API في نفس الوقت الذي يتغير فيه رمز الخدمة. للقيام بذلك ، يمكنك على الأقل بدء قوائم تدقيق موحدة ، على الأقل إعداد إشعارات للتغييرات ، على الأقل تدريب قدرات فائقة لإنشاء كل شيء من كل شيء ... هام! يجب أن يكون قسم الوثائق على دراية بجميع التغييرات المخططة حتى تتاح لهم الفرصة لتخطيط الموارد اللازمة لتحديث الوثائق وكتابة أدلة الترقية. يعد دليل الترقية ، الذي تم اختباره والتحقق منه ، سمة محزنة لأي إعادة تسمية بدأت في واجهة برمجة التطبيقات.
تغيير الإدارة
تسمى القواعد التي تصف الأنشطة المرتبطة بدورة حياة واجهة برمجة التطبيقات سياسات إدارة التغيير.
إذا كان لديك نسختين من التعليقات "الحالية" و "الجديدة" ، فإن التحقق من التوافق مع الإصدارات السابقة بسيط من الناحية الفنية: فقط قم بتحليل كلا التعليقات التوضيحية وتحقق من وجود الحقول اللازمة
لقد كتبنا أداة خاصة تسمح لك بمقارنة جميع المعلمات المهمة للتوافق مع الإصدارات السابقة في CI. على سبيل المثال ، عند تغيير نص الاستجابة في طلب GET / healthcheck ، سيتم عرض رسالة مشابهة للرسالة التالية:
استنتاج
يحلم كل مهندس معماري بالتخلص من مشاكل واجهة برمجة التطبيقات. يحلم كل مدير بعدم معرفة مشكلات واجهة برمجة التطبيقات. :). هناك العديد من الأدوية ، ولكن لكل منها سعره الخاص وآثاره الجانبية. شاركنا خيارات العلاج الخاصة بنا لأبسط أمراض الطفولة مع API ، ثم تنشأ مشاكل أكثر خطورة. استنتاجات من مقالتنا "النقباء": تبدأ مشكلات واجهة برمجة التطبيقات برئيس وتعليم الناس الممارسات الجيدة هي الضمان الرئيسي للنجاح. كل شيء آخر هو مجرد مسألة تقنية. وما هي المشاكل التي واجهتها وما هي وسائل الحل التي اخترتها في مؤسستك؟
الأدوية ل API سيئة.سنكون سعداء بأي أفكار وتقييمات وتعليقات وآراء وأسئلة!