Дакле, да ли је то РАМЛ или ОАС (Сваггер)?

У динамичном свету микроуслуга, све се може променити — било која компонента може бити преписана на другом језику, користећи различите оквире и архитектуру. Само уговори треба да остану непромењени како би микросервис могао да комуницира споља на некој трајној основи, без обзира на унутрашње метаморфозе. А данас ћемо говорити о нашем проблему избора формата за описивање уговора и поделити артефакте које смо пронашли.

Пост припремљен Анна Мелекхова и Владимир Лапатин

Микроуслуге. Када смо развијали Ацронис Цибер Цлоуд, схватили смо да им не можемо побећи. А пројектовање микросервиса је немогуће без формализовања уговора, који представља интерфејс микросервиса.

Али када производ садржи више од једне компоненте, а развој уговора постане редовна активност, не можете а да не почнете да размишљате о оптимизацији процеса. Постаје очигледно да интерфејс (уговор) и имплементација (микросервис) морају да се подударају једни са другима, да различите компоненте морају да раде исте ствари на исти начин, и да ће без централизованог доношења одлука о свим тим одлукама, сваки тим бити приморан да проводите време изнова и изнова да бисте их добили.

Дијаграм Амазон микросервиса из твеет Вернер Вогелис, технички директор Амазона
У чему је дилема? Де фацто, постоје два начина за интеракцију микросервиса – ХТТП Рест и гРПЦ од Гоогле-а. Не желећи да будемо ухваћени у Гоогле-ов технолошки скуп, изабрали смо ХТТП Рест. ХТТП РЕСТ уговорне напомене се најчешће описују у једном од два формата: РАМЛ и ОАС, раније познатим као Сваггер, па се сваки развојни тим суочава са потребом да изабере један од стандарда. Али како се испоставило, доношење овог избора може бити веома тешко.

Зашто су потребне напомене?

Белешка је потребна како би спољни корисник могао лако да схвати шта се може урадити са вашом услугом преко њеног ХТТП интерфејса. То јест, на основном нивоу, анотација мора да садржи најмање листу доступних ресурса, њихове ХТТП методе, тела захтева, листу параметара, индикацију потребних и подржаних заглавља, као и повратне кодове и формате одговора. Изузетно важан елемент напомене уговора је њихов вербални опис („шта ће се десити ако захтеву додате овај параметар упита?“, „У ком случају ће бити враћен код 400?“)

Међутим, када је у питању развој великог броја микросервиса, желите да извучете додатну вредност из писаних напомена. На пример, на основу РАМЛ/Сваггер-а, можете генерисати и клијентски и серверски код у огромном броју програмских језика. Такође можете аутоматски да примите документацију за микросервис и да је отпремите на свој развојни портал :).

Пример структурираног описа уговора

Мање уобичајена је пракса тестирања микросервиса на основу описа уговора. Ако сте написали и напомену и компоненту, онда можете креирати аутотест који проверава адекватност услуге са различитим типовима улазних података. Да ли услуга враћа код одговора који није описан у напомени? Да ли ће моћи правилно да обради очигледно нетачне податке?

Штавише, квалитетна имплементација не само самих уговора, већ и алата за визуелизацију напомена омогућава поједностављење рада са микросервисом. То јест, ако је архитекта квалитативно описао уговор, на основу њега, дизајнери и програмери ће имплементирати услугу у друге производе без додатних временских трошкова.

Да би омогућили додатне алате, и РАМЛ и ОАС имају могућност додавања метаподатака који нису предвиђени стандардом (на пример, овако се ради у ОАС).

Генерално, простор за креативност у коришћењу уговора за микроуслуге је огроман... барем у теорији.

Поређење јежа са змијом

Тренутно, приоритетна развојна област у Ацронису је развој Ацронис сајбер платформе. Ацронис Цибер Платформ је нове тачке интеграције услуга трећих страна са Ацронис Цибер Цлоуд-ом и агентским делом. Иако смо били задовољни нашим интерним АПИ-јима описаним у РАМЛ-у, потреба да поново објавимо АПИ отворила је питање избора: који стандард напомена је најбоље користити за наш рад?

У почетку се чинило да постоје два решења - најчешћи развоји су били РАМЛ и Сваггер (или ОАС). Али у ствари се показало да постоје барем не 2 алтернативе, већ 3 или више.

С једне стране постоји РАМЛ - моћан и ефикасан језик. Добро имплементира хијерархију и наслеђивање, тако да је овај формат погоднији за велике компаније којима је потребно много описа – то јест, не један производ, већ много микросервиса који имају заједничке делове уговора – шеме за аутентификацију, исте типове података, тела грешака .

Али програмер РАМЛ-а, Мулесофт, придружио се Опен АПИ конзорцијуму, који се развија Сваггер. Због тога је РАМЛ обуставио свој развој. Да бисте замислили формат догађаја, замислите да су одржаваоци главних Линукс компоненти отишли ​​да раде у Мицрософту. Оваква ситуација ствара предуслове за коришћење Сваггер-а, који се динамично развија и у најновијој – трећој верзији – практично сустиже РАМЛ по флексибилности и функционалности.

Ако не због једног али...

Како се испоставило, нису сви услужни програми отвореног кода ажурирани на ОАС 3.0. За микросервисе у Го-у, најкритичнија ствар ће бити недостатак прилагођавања го-сваггер за најновију верзију стандарда. Међутим, разлика између Сваггера 2 и Сваггера 3 је огроман. На пример, у трећој верзији програмери:

• побољшан опис шема за аутентификацију
• завршено Подршка за ЈСОН шему
• надограђена могућност додавања примера

Ситуација је смешна: када бирате стандард, морате узети у обзир РАМЛ, Сваггер 2 и Сваггер 3 као засебне алтернативе. Међутим, само Сваггер 2 има добру подршку за ОпенСоурце алате. РАМЛ је веома флексибилан...и сложен, а Сваггер 3 је слабо подржан од стране заједнице, тако да ћете морати да користите власничке алате или комерцијална решења, која су обично прилично скупа.

Штавише, ако у Сваггер-у постоји много лепих функција, као што је готов портал едитор.сваггер.ио, на који можете да отпремите напомену и добијете њену визуелизацију са детаљним описом, везама и везама, онда за фундаменталнији и мање пријатељски РАМЛ не постоји таква могућност. Да, можете потражити нешто међу пројектима на ГитХуб-у, пронаћи аналогни тамо и сами га применити. Међутим, у сваком случају, неко ће морати да одржава портал, што није тако згодно за основну употребу или потребе тестирања. Поред тога, сваггер је „непринципијелнији“ или либералнији – може се генерисати из коментара у коду, што је, наравно, противно принципу првог АПИ-ја и не подржава га ниједан од РАМЛ услужних програма.

Својевремено смо почели да радимо са РАМЛ-ом као флексибилнијим језиком, и као резултат тога морали смо много ствари да радимо сами. На пример, један од пројеката користи услужни програм рамлфифицатионс у јединичним тестовима, који подржава само РАМЛ 0.8. Тако да смо морали да додамо штаке како би услужни програм могао да „поједе“ РАМЛ верзију 1.0.

Да ли треба да бирате?

Радећи на комплетирању екосистема решења за РАМЛ, дошли смо до закључка да је потребно да РАМЛ претворимо у Сваггер 2 и да у њему извршимо сву аутоматизацију, верификацију, тестирање и накнадну оптимизацију. Ово је добар начин да искористите и флексибилност РАМЛ-а и подршку алата заједнице од Сваггер-а.

Да бисте решили овај проблем, постоје два ОпенСоурце алата који би требало да обезбеде конверзију уговора:

1. оас-рамл-конвертер је тренутно неподржани услужни програм. Док смо радили са њим, открили смо да има низ проблема са сложеним РАМЛ-овима који су „распрострањени“ на велики број датотека. Овај програм је написан у ЈаваСцрипт-у и врши рекурзивно обилажење синтаксног стабла. Због динамичког куцања, постаје тешко разумети овај код, па смо одлучили да не губимо време на писање закрпа за умирући услужни програм.
2. вебапи-парсер - алат из исте компаније који тврди да је спреман да конвертује све и свашта, иу било ком правцу. До данас је најављена подршка за РАМЛ 0.8, РАМЛ 1.0 и Сваггер 2.0. Међутим, у време нашег истраживања, корисност је још увек била ИЗУЗЕТНО влажан и неупотребљив. Програмери стварају неку врсту IR, омогућавајући им да брзо додају нове стандарде у будућности. Али до сада то једноставно не функционише.

И то нису све потешкоће на које смо наишли. Један од корака у нашем цевоводу је да проверимо да ли је РАМЛ из спремишта исправан у односу на спецификацију. Пробали смо неколико услужних програма. Зачудо, сви су псовали наше коментаре на различитим местима и са потпуно различитим лошим речима. И не увек до тачке :).

На крају смо се одлучили за сада застарели пројекат, који такође има низ проблема (понекад се сруши из ведра неба, има проблема при раду са регуларним изразима). Дакле, нисмо пронашли начин да решимо проблеме валидације и конверзије засноване на бесплатним алатима и одлучили смо да користимо комерцијални услужни програм. У будућности, како ОпенСоурце алати постану зрелији, овај проблем може постати лакши за решавање. У међувремену, трошкови рада и времена за „дораду“ су нам се чинили значајнијим од трошкова комерцијалне услуге.

Закључак

Након свега овога, желели смо да поделимо своје искуство и напоменемо да пре него што изаберете алат за описивање уговора, морате јасно дефинисати шта желите од њега и који буџет сте спремни да уложите. Ако заборавимо на ОпенСоурце, већ постоји велики број услуга и производа који ће вам помоћи да проверите, конвертујете и потврдите. Али они су скупи, а понекад и веома скупи. За велику компанију такви трошкови су подношљиви, али за стартап могу постати велики терет.

Одредите скуп алата који ћете касније користити. На пример, ако само треба да прикажете уговор, биће лакше користити Сваггер 2, који има прелеп АПИ, јер ћете у РАМЛ-у морати сами да изградите и одржавате услугу.
Што више задатака имате, то ће бити већа потреба за алатима, а они су различити за различите платформе, а боље је одмах да се упознате са доступним верзијама како бисте направили избор који минимизира ваше трошкове у будућности.

Али вреди признати да су сви екосистеми који постоје данас несавршени. Стога, ако у компанији постоје обожаваоци који воле да раде у РАМЛ-у јер „омогућава флексибилније изражавање мисли“, или, напротив, више воле Сваггер јер је „јасније“, најбоље је оставити их да раде у ономе што јесу Навикли су на то и желе то, јер алати било ког формата захтевају модификацију помоћу датотеке.

Што се тиче нашег искуства, у наредним постовима ћемо говорити о томе које статичке и динамичке провере спроводимо на основу наше РАМЛ-Сваггер архитектуре, као и коју документацију генеришемо из уговора и како све то функционише.

Само регистровани корисници могу учествовати у анкети. Пријавите се, Добродошао си.

Који језик користите за означавање уговора о микросервисима?

• РАМЛ 0.8

• РАМЛ 1.0

• Сваггер 2

• ОАС3 (ака)

• Шематски план

• Друго

• Не користим

Гласало је 100 корисника. 24 корисника су била уздржана.

Извор: ввв.хабр.цом