В динамичния свят на микроуслугите всичко може да се промени – всеки компонент може да бъде пренаписан на различен език, използвайки различни рамки и архитектура. Само договорите трябва да останат непроменени, така че микроуслугата да може да се взаимодейства отвън на някаква постоянна основа, независимо от вътрешните метаморфози. И днес ще говорим за нашия проблем с избора на формат за описание на договори и ще споделим артефактите, които открихме.
Постът е подготвен и
Микроуслуги. Когато разработвахме Acronis Cyber Cloud, осъзнахме, че не можем да им избягаме. И проектирането на микроуслуга е невъзможно без формализиране на договора, който представлява интерфейса на микроуслугата.
Но когато един продукт съдържа повече от един компонент и разработването на договори се превърне в редовна дейност, няма как да не започнете да мислите за оптимизиране на процеса. Става очевидно, че интерфейсът (договор) и изпълнението (микроуслуга) трябва да съвпадат един с друг, че различните компоненти трябва да правят едни и същи неща по един и същи начин и че без централизирано вземане на решения за всички тези решения, всеки екип ще бъде принуден да прекарвайте време отново и отново, за да ги получите.
Диаграма на микроуслуги на Amazon от Вернер Фогелис, технически директор на Amazon
Каква е дилемата? Де факто има два начина за взаимодействие между микроуслугите - 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 и агентската част. Въпреки че бяхме доволни от нашите вътрешни API, описани в RAML, необходимостта от публикуване на API отново повдигна въпроса за избор: кой стандарт за анотация е най-добре да използваме за нашата работа?
Първоначално изглеждаше, че има две решения - най-често срещаните разработки бяха RAML и Swagger (или OAS). Но всъщност се оказа, че има поне не 2 алтернативи, а 3 или повече.
От една страна е 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, като например готов портал , на който можете да качите анотация и да получите нейната визуализация с подробно описание, връзки и връзки, то за по-фундаменталния и по-малко приятелски RAML няма такава възможност. Да, можете да търсите нещо сред проекти в GitHub, да намерите аналог там и да го внедрите сами. Въпреки това, във всеки случай, някой ще трябва да поддържа портала, което не е толкова удобно за базова употреба или тестване. В допълнение, swagger е по-„безпринципно“ или по-либерално – може да се генерира от коментари в кода, което, разбира се, противоречи на първия принцип на API и не се поддържа от нито една от помощните програми на RAML.
По едно време започнахме да работим с RAML като по-гъвкав език и в резултат на това трябваше да правим много неща сами. Например, един от проектите използва помощната програма в модулни тестове, които поддържат само RAML 0.8. Така че трябваше да добавим патерици, за да може помощната програма да „изяде“ RAML версия 1.0.
Трябва ли да изберете?
След като работихме върху завършването на екосистемата от решения за RAML, стигнахме до извода, че трябва да конвертираме RAML в Swagger 2 и да извършим цялата автоматизация, проверка, тестване и последваща оптимизация в него. Това е добър начин да се възползвате както от гъвкавостта на RAML, така и от поддръжката на инструменти на общността от Swagger.
За да разрешите този проблем, има два OpenSource инструмента, които трябва да осигурят преобразуване на договори:
- е в момента неподдържана помощна програма. Докато работехме с него, открихме, че има редица проблеми със сложни RAML, които са „разпръснати“ върху голям брой файлове. Тази програма е написана на JavaScript и извършва рекурсивно обхождане на синтактично дърво. Поради динамичното писане става трудно да се разбере този код, затова решихме да не губим време в писане на пачове за умираща помощна програма.
- - инструмент от същата компания, който твърди, че е готов да конвертира всичко и всичко и във всяка посока. Към днешна дата е обявена поддръжка за RAML 0.8, RAML 1.0 и Swagger 2.0. Въпреки това, по време на нашето изследване, полезността беше все още влажна и неизползваема. Разработчиците създават вид , което им позволява бързо да добавят нови стандарти в бъдеще. Но засега просто не работи.
И това не са всички трудности, които срещнахме. Една от стъпките в нашия процес е да проверим дали RAML от хранилището е правилен спрямо спецификацията. Опитахме няколко помощни програми. Изненадващо, всички те псуваха анотациите ни на различни места и със съвсем различни лоши думи. И не винаги по същество :).
В крайна сметка се спряхме на вече остарял проект, който също има редица проблеми (понякога се срива внезапно, има проблеми при работа с регулярни изрази). По този начин не намерихме начин да решим проблемите с валидирането и преобразуването въз основа на безплатни инструменти и решихме да използваме комерсиална помощна програма. В бъдеще, когато инструментите на OpenSource станат по-зрели, този проблем може да стане по-лесен за разрешаване. Междувременно разходите за труд и време за „доработка“ ни се сториха по-значими от цената на търговска услуга.
Заключение
След всичко това, искахме да споделим нашия опит и да отбележим, че преди да изберете инструмент за описание на договори, трябва ясно да дефинирате какво искате от него и какъв бюджет сте готови да инвестирате. Ако забравим за OpenSource, вече има голям брой услуги и продукти, които ще ви помогнат да проверите, конвертирате и валидирате. Но те са скъпи, а понякога и много скъпи. За една голяма компания подобни разходи са поносими, но за стартиращ бизнес могат да се превърнат в голямо бреме.
Определете набора от инструменти, които ще използвате по-късно. Например, ако просто трябва да покажете договор, ще бъде по-лесно да използвате Swagger 2, който има красив API, защото в RAML ще трябва да изградите и поддържате услугата сами.
Колкото повече задачи имате, толкова по-голяма ще бъде нуждата от инструменти, а те са различни за различните платформи и е по-добре веднага да се запознаете с наличните версии, за да направите избор, който минимизира разходите ви в бъдеще.
Но си струва да се признае, че всички екосистеми, които съществуват днес, са несъвършени. Ето защо, ако в компанията има фенове, които обичат да работят в RAML, защото „това ви позволява да изразявате мислите си по-гъвкаво“ или, напротив, предпочитате Swagger, защото „е по-ясно“, най-добре е да ги оставите да работят в какви са Те са свикнали с това и го искат, защото инструментите на всеки от форматите изискват модификация с файл.
Що се отнася до нашия опит, в следващите публикации ще говорим за това какви статични и динамични проверки извършваме въз основа на нашата RAML-Swagger архитектура, както и каква документация генерираме от договори и как работи всичко това.
В анкетата могат да участват само регистрирани потребители. , Моля те.
Какъв език използвате за анотиране на договори за микроуслуги?
-
RAML 0.8
-
RAML 1.0
-
Напереност 2
-
OAS3 (известен още като)
-
План
-
Друг
-
Не се използва
100 потребители гласуваха. 24 потребители се въздържаха.
Източник: www.habr.com