У дынамічным свеце мікрасэрвісаў змяніцца можа ўсё што заўгодна - любы кампанент можна перапісаць на іншай мове, выкарыстоўваючы іншыя фрэймворкі і архітэктуру. Нязменнымі павінны заставацца толькі кантракты, для таго, каб з мікрасэрвісам можна было ўзаемадзейнічаць звонку на нейкай сталай аснове, па-за залежнасцю ад унутраных метамарфоз. І сёння мы раскажам аб нашай праблеме выбару фармату апісання кантрактаў і падзелімся знойдзенымі артэфактамі.
Пост падрыхтавалі и
Мікрасэрвісы. Пры распрацоўцы Acronis Cyber Cloud мы зразумелі, што нам нікуды ад іх не падзецца. А праектаванне мікрасэрвісу немагчымае без фармалізацыі кантракту, які ўяўляе сабой інтэрфейс мікрасэрвісу.
Але калі ў прадукце ўтрымоўваецца больш за адзін кампанент, і распрацоўка кантракту становіцца рэгулярнай актыўнасцю, мімаволі пачынаеш задумвацца аб аптымізацыі працэсу. Становіцца відавочным, што інтэрфейс (кантракт) і імплементацыя (мікрасэрвіс) павінны адно аднаму адпавядаць, што розныя кампаненты павінны рабіць адны і тыя ж рэчы аднолькава, і што без цэнтралізаванага прыняцця ўсіх гэтых рашэнняў кожная каманда будзе вымушана зноў і зноў марнаваць час на іх атрыманне. .
Схема мкрасэрвісаў Amazon з Вернера Вагеліса, СTO Amazon
У чым жа заключаецца дылема? Дэ факта ёсць два спосабу ўзаемадзеяння мікрасэрвісаў - HTTP Rest і gRPC ад кампаніі Google. Не жадаючы быць уцягнутымі ў стэк тэхналогій Google, мы абралі HTTP Rest. Анатацыі да кантрактаў HTTP REST часцей за ўсё апісваюцца адным з двух фарматаў: RAML і OAS, раней вядомы як Swagger. Таму кожная каманда распрацоўнікаў сутыкаецца з неабходнасцю зрабіць выбар на карысць аднаго з стандартаў. Але, як высветлілася, зрабіць гэты выбар можа быць вельмі няпроста.
Навошта патрэбны анатацыі?
Анатацыя патрэбна для таго, каб вонкавы карыстач мог лёгка разабрацца, што можна рабіць з вашым сэрвісам праз яго HTTP-інтэрфейс. Гэта значыць на базавым узроўні анатацыя павінна змяшчаць як мінімум спіс даступных рэсурсаў, іх HTTP-метадаў, целы запытаў, пералік параметраў, указанне неабходных і падтрымоўваных загалоўкаў, а таксама кодаў звароту і фарматаў адказаў. Вельмі важным элементам анатацыі кантракту з'яўляецца і іх слоўнае апісанне ("што будзе, калі дадаць гэты query-параметр да запыту?", "у якім выпадку вернецца код 400?")
Тым не менш, калі гаворка ідзе аб распрацоўцы вялікай колькасці мікрасэрвісаў, жадаецца здабываць дадатковую карысць з напісаных анатацый. Напрыклад, на аснове RAML / Swagger можна генераваць і кліенцкі, і серверны код на велізарнай колькасці моў праграмавання. А яшчэ можна аўтаматычна атрымліваць дакументацыю да мікрасэрвісу і заліваць яе на ваш developer-portal :).
Прыклад структураванага апісання кантракта
Радзей сустракаецца практыка тэсціравання мікрасэрвісаў на базе апісанняў кантрактаў. Калі вы напісалі і анатацыю, і кампанент, то можна стварыць аўтатэст, які правярае адэкватнасць працы сэрвісу з рознымі тыпамі дадзеных на ўваходзе. Ці не вяртае сэрвіс код адказу, не апісаны ў анатацыі? Ці зможа карэктна апрацаваць заведама няправільныя дадзеныя?
Больш за тое, якасная рэалізацыя не толькі саміх кантрактаў, але таксама інструментара для візуалізацыі анатацый дазваляе спрасціць працу з мікрасэрвісам. Гэта значыць калі архітэктар якасна апісаў кантракт, на яго падставе дызайнеры і распрацоўшчыкі будуць укараняць сэрвіс у іншыя прадукты без дадатковых часавых затрат.
Для працы дадатковых прылад і 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 па гнуткасці і функцыянальнасці.
Калі б не адно але…
Як аказалася, далёка не ўсе open-source утыліты абнавіліся да версіі OAS 3.0. Для мікрасэрвісаў на Go самым крытычным будзе адсутнасць адаптацыі пад свежую версію стандарта. Аднак розніца паміж Swagger 2 і Swagger 3 . Напрыклад, у трэцяй версіі распрацоўшчыкі:
- палепшылі апісанне схем аўтэнтыфікацыі
- падтрымку JSON Schema
- прапампавалі магчымасць дадання прыкладаў
Сітуацыя атрымліваецца пацешная: пры выбары стандарту трэба разглядаць RAML, Swagger 2 і Swagger 3 як асобныя альтэрнатывы. Пры гэтым толькі Swagger 2 мае добрую падтрымку інструментара OpenSource. RAML - вельмі гнуткі ... і складаны, а Swagger 3 слаба падтрымліваюцца кам'юніці, так што вам давядзецца карыстацца інструментамі ўласнай распрацоўкі або камерцыйнымі рашэннямі, якія, як правіла, каштуюць вельмі дорага.
Пры гэтым калі ў Swagger існуе шмат прыемных магчымасцяў, такіх як гатовы партал , на які можна загрузіць анатацыю і атрымаць яе візуалізацыю з падрабязным апісаннем, спасылкамі і сувязямі, то для больш фундаментальнага і меней прыязнага RAML такой магчымасці няма. Так, можна пашукаць нешта сярод праектаў на GitHub, знайсці там аналаг і самастойна яго разгарнуць. Аднак у любым выпадку нехта павінен будзе падтрымліваць партал, што не так зручна для базавага выкарыстання або тэставых патрэб. Акрамя таго, swagger больш "беспрынцыповы", ну ці ліберальны - яго можна генераваць з каментароў у кодзе, што, вядома, ідзе насуперак з прынцыпам API first і не падтрымліваецца ніводнай з утыліт 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 (aka )
-
План
-
Іншы
-
Не выкарыстоўваю
Прагаласавалі 100 карыстальнікаў. Устрымаліся 24 карыстальніка.
Крыніца: habr.com