بنابراین آیا 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 توانایی اضافه کردن متادیتا را دارند که توسط استاندارد ارائه نشده است (به عنوان مثال، این روش در OAS انجام می شود).

به طور کلی، دامنه خلاقیت در استفاده از قراردادها برای خدمات خرد بسیار زیاد است ... حداقل در تئوری.

مقایسه جوجه تیغی با مار

در حال حاضر، حوزه توسعه اولویت در Acronis، توسعه پلت فرم سایبری Acronis است. Acronis Cyber ​​Platform نقاط جدید ادغام خدمات شخص ثالث با Acronis Cyber ​​Cloud و بخش عامل است. اگرچه ما از APIهای داخلی خود که در RAML توضیح داده شده بود خوشحال بودیم، اما نیاز به انتشار API دوباره این سؤال انتخاب را ایجاد کرد: کدام استاندارد حاشیه نویسی برای کارمان بهتر است؟

در ابتدا، به نظر می رسید که دو راه حل وجود دارد - رایج ترین پیشرفت ها RAML و Swagger (یا OAS) بودند. اما در واقع معلوم شد که حداقل نه 2 جایگزین، بلکه 3 یا بیشتر وجود دارد.

از یک طرف RAML وجود دارد - یک زبان قدرتمند و کارآمد. سلسله مراتب و وراثت را به خوبی پیاده سازی می کند، بنابراین این قالب برای شرکت های بزرگی که به توضیحات زیادی نیاز دارند - یعنی نه یک محصول، بلکه بسیاری از ریزسرویس ها که بخش های مشترک قراردادها دارند - طرح های احراز هویت، انواع داده های مشابه، بدنه های خطا، مناسب تر است. .

اما توسعه دهنده RAML، Mulesoft، به کنسرسیوم Open API ملحق شده است که در حال توسعه است. سوگگر. بنابراین، RAML توسعه خود را به حالت تعلیق درآورد. برای تصور فرمت رویداد، تصور کنید که نگهبانان اجزای اصلی لینوکس برای کار در مایکروسافت ترک کردند. این وضعیت پیش نیازها را برای استفاده از 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 به عنوان یک زبان انعطاف پذیرتر کردیم و در نتیجه مجبور شدیم کارهای زیادی را خودمان انجام دهیم. به عنوان مثال، یکی از پروژه ها از ابزار استفاده می کند حواشی در تست های واحد که فقط از RAML 0.8 پشتیبانی می کند. بنابراین ما مجبور شدیم عصا را اضافه کنیم تا ابزار بتواند نسخه 1.0 RAML را "خورد".

آیا نیاز به انتخاب دارید؟

پس از کار بر روی تکمیل اکوسیستم راه حل های RAML، به این نتیجه رسیدیم که باید RAML را به Swagger 2 تبدیل کنیم و تمام اتوماسیون، تأیید، آزمایش و بهینه سازی های بعدی را در آن انجام دهیم. این یک راه خوب برای استفاده از انعطاف پذیری RAML و پشتیبانی ابزار جامعه از سوی Swagger است.

برای حل این مشکل، دو ابزار OpenSource وجود دارد که باید تبدیل قرارداد را فراهم کنند:

1. مبدل oas-raml یک ابزار در حال حاضر پشتیبانی نشده است. در حین کار با آن، متوجه شدیم که دارای تعدادی مشکلات با RAML های پیچیده است که روی تعداد زیادی فایل "گسترش یافته اند". این برنامه به زبان جاوا اسکریپت نوشته شده است و پیمایش بازگشتی یک درخت نحو را انجام می دهد. به دلیل تایپ پویا، درک این کد دشوار می شود، بنابراین تصمیم گرفتیم زمان را برای نوشتن وصله برای یک ابزار در حال مرگ تلف نکنیم.
2. تجزیه کننده وباپی - ابزاری از همان شرکت که ادعا می کند آماده تبدیل همه چیز و همه چیز و در هر جهت است. تا به امروز، پشتیبانی از RAML 0.8، RAML 1.0 و Swagger 2.0 اعلام شده است. با این حال، در زمان تحقیق ما، ابزار هنوز وجود داشت به شدت مرطوب و غیر قابل استفاده توسعه دهندگان ایجاد نوعی از IR، به آنها اجازه می دهد تا به سرعت استانداردهای جدیدی را در آینده اضافه کنند. اما تا اینجا فقط کار نمی کند.

و این همه مشکلاتی نیست که با آن مواجه شدیم. یکی از مراحل در خط لوله ما این است که تأیید کنیم که RAML از مخزن نسبت به مشخصات صحیح است. ما چندین ابزار کاربردی را امتحان کردیم. در کمال تعجب، همه آنها در جاهای مختلف و با کلمات بد کاملاً متفاوت به حاشیه نویسی ما فحش می دادند. و نه همیشه به نقطه :).

در پایان، ما روی یک پروژه منسوخ شده مستقر شدیم که چندین مشکل نیز دارد (گاهی اوقات به طور ناگهانی خراب می شود، هنگام کار با عبارات منظم مشکل دارد). بنابراین، ما راهی برای حل مشکلات اعتبار سنجی و تبدیل بر اساس ابزارهای رایگان پیدا نکردیم و تصمیم گرفتیم از یک ابزار تجاری استفاده کنیم. در آینده، با بالغ شدن ابزارهای OpenSource، این مشکل ممکن است آسان تر شود. در این میان، هزینه‌های کار و زمان برای «تمام» به نظر ما مهم‌تر از هزینه خدمات تجاری بود.

نتیجه

پس از همه اینها، ما می خواستیم تجربه خود را به اشتراک بگذاریم و توجه داشته باشیم که قبل از انتخاب ابزاری برای توصیف قراردادها، باید به وضوح مشخص کنید که از آن چه می خواهید و چه بودجه ای را می خواهید سرمایه گذاری کنید. اگر OpenSource را فراموش کنیم، در حال حاضر تعداد زیادی خدمات و محصولات وجود دارد که به شما در بررسی، تبدیل و اعتبارسنجی کمک می‌کند. اما آنها گران هستند و گاهی اوقات بسیار گران هستند. برای یک شرکت بزرگ، چنین هزینه هایی قابل تحمل است، اما برای یک استارتاپ می تواند به یک بار بزرگ تبدیل شود.

مجموعه ابزارهایی را که بعداً استفاده خواهید کرد را تعیین کنید. به عنوان مثال، اگر فقط نیاز به نمایش قرارداد دارید، استفاده از Swagger 2 که دارای API زیبایی است، راحت تر خواهد بود، زیرا در RAML باید خودتان سرویس را بسازید و نگهداری کنید.
هر چه وظایف بیشتری داشته باشید نیاز به ابزارها بیشتر می شود و برای پلتفرم های مختلف متفاوت هستند و بهتر است بلافاصله با نسخه های موجود آشنا شوید تا در آینده انتخابی داشته باشید که هزینه های شما را به حداقل برساند.

اما شایان ذکر است که تمام اکوسیستم هایی که امروزه وجود دارند ناقص هستند. بنابراین، اگر طرفدارانی در شرکت وجود دارند که دوست دارند در RAML کار کنند زیرا "به شما امکان می دهد افکار را با انعطاف بیشتری بیان کنید" یا برعکس، Swagger را ترجیح می دهند زیرا "روشن تر است"، بهتر است آنها را به کار بسپارید. در آنچه هستند آنها به آن عادت کرده اند و آن را می خواهند، زیرا ابزارهای هر یک از فرمت ها نیاز به اصلاح با یک فایل دارند.

در مورد تجربه ما، در پست‌های بعدی در مورد اینکه چه بررسی‌های ایستا و پویا بر اساس معماری RAML-Swagger انجام می‌دهیم، و همچنین اینکه چه اسنادی از قراردادها تولید می‌کنیم و چگونه کار می‌کند صحبت خواهیم کرد.

فقط کاربران ثبت نام شده می توانند در نظرسنجی شرکت کنند. ورود، لطفا.

از چه زبانی برای حاشیه نویسی قراردادهای میکروسرویس استفاده می کنید؟

• RAML 0.8

• RAML 1.0

• سواگر 2

• OAS3 (با نام مستعار)

• چاپ اوزالید که برای کپیه نقشه و رسم های فنی بکار میرود

• دیگر

• استفاده نکردن

100 کاربر رای دادند. 24 کاربر رای ممتنع دادند.

منبع: www.habr.com