Dinamiškame mikro paslaugų pasaulyje viskas gali pasikeisti – bet kuris komponentas gali būti perrašytas kita kalba, naudojant skirtingas sistemas ir architektūrą. Tik sutartys turėtų likti nepakitusios, kad su mikropaslauga būtų galima nuolat bendrauti iš išorės, nepaisant vidinių metamorfozių. O šiandien kalbėsime apie sutarčių aprašymo formato pasirinkimo problemą ir pasidalinsime rastais artefaktais.
Įrašas paruoštas и
Mikropaslaugos. Kurdami Acronis Cyber Cloud supratome, kad negalime jų išvengti. O suprojektuoti mikropaslaugą neįmanoma neįforminus sutarties, kuri yra mikropaslaugos sąsaja.
Tačiau kai produkte yra daugiau nei vienas komponentas, o sutarčių kūrimas tampa įprasta veikla, negalima negalvoti apie proceso optimizavimą. Tampa akivaizdu, kad sąsaja (sutartis) ir diegimas (mikropaslauga) turi atitikti vienas kitą, kad skirtingi komponentai turi daryti tuos pačius dalykus vienodai ir kad be centralizuoto visų šių sprendimų sprendimų kiekviena komanda bus priversta vėl ir vėl praleiskite laiką, kad juos gautumėte.
„Amazon“ mikro paslaugų diagrama iš Werneris Vogelis, „Amazon“ technologijų vadovas
Kokia dilema? De facto yra du būdai sąveikauti su mikro paslaugomis – HTTP Rest ir gRPC iš Google. Nenorėdami įsitraukti į „Google“ technologijų krūvą, pasirinkome HTTP Rest. HTTP REST sutarčių anotacijos dažniausiai aprašomos vienu iš dviejų formatų: RAML ir OAS, anksčiau žinomi kaip Swagger, todėl kiekviena kūrėjų komanda susiduria su poreikiu pasirinkti vieną iš standartų. Tačiau, kaip paaiškėjo, šį pasirinkimą gali būti labai sunku.
Kodėl reikalingos anotacijos?
Anotacija reikalinga tam, kad išorinis vartotojas galėtų lengvai išsiaiškinti, ką galima padaryti su jūsų paslauga per HTTP sąsają. Tai reiškia, kad pagrindiniame lygmenyje anotacijoje turi būti bent turimų išteklių sąrašas, jų HTTP metodai, užklausos elementai, parametrų sąrašas, reikiamų ir palaikomų antraščių nuoroda, taip pat grąžinimo kodai ir atsakymų formatai. Itin svarbus sutarties anotacijos elementas yra jų žodinis aprašymas („kas bus, jei prie užklausos pridėsite šį užklausos parametrą?“, „Kokiu atveju bus grąžintas kodas 400?“)
Tačiau kalbant apie daugybės mikropaslaugų kūrimą, norite gauti papildomos vertės iš rašytinių anotacijų. Pavyzdžiui, remiantis RAML / Swagger, galite generuoti tiek kliento, tiek serverio kodą daugybe programavimo kalbų. Taip pat galite automatiškai gauti mikropaslaugos dokumentaciją ir įkelti ją į savo kūrėjo portalą :).
Struktūrizuoto sutarties aprašo pavyzdys
Mažiau paplitusi praktika mikropaslaugų testavimo pagal sutarčių aprašymus. Jei parašėte ir anotaciją, ir komponentą, galite sukurti automatinį testą, kuris patikrina paslaugos tinkamumą su įvairių tipų įvesties duomenimis. Ar paslauga grąžina atsakymo kodą, kuris nėra aprašytas anotacijoje? Ar jis galės teisingai apdoroti akivaizdžiai neteisingus duomenis?
Be to, kokybiškas ne tik pačių sutarčių įgyvendinimas, bet ir anotacijų vizualizavimo įrankiai leidžia supaprastinti darbą su mikropaslauga. Tai yra, jei architektas kokybiškai apibūdino sutartį, ja remdamiesi projektuotojai ir kūrėjai be papildomų laiko sąnaudų įdiegs paslaugą kituose gaminiuose.
Norėdami įjungti papildomus įrankius, tiek RAML, tiek OAS turi galimybę pridėti metaduomenų, kurių nenumato standartas ().
Apskritai, kūrybiškumo galimybės naudojant mikropaslaugų sutartis yra didžiulės... bent jau teoriškai.
Ežiuko palyginimas su gyvate
Šiuo metu prioritetinė „Acronis“ plėtros sritis yra „Acronis Cyber Platform“ kūrimas. „Acronis Cyber Platform“ yra nauji trečiųjų šalių paslaugų integravimo taškai su „Acronis Cyber Cloud“ ir agento dalimi. Nors buvome patenkinti savo vidinėmis API, aprašytomis RAML, poreikis publikuoti API vėl iškėlė pasirinkimo klausimą: kokį anotacijos standartą geriausia naudoti savo darbui?
Iš pradžių atrodė, kad yra du sprendimai – labiausiai paplitę buvo RAML ir Swagger (arba OAS). Bet iš tikrųjų pasirodė, kad yra bent ne 2 alternatyvos, o 3 ar daugiau.
Viena vertus, yra RAML – galinga ir efektyvi kalba. Puikiai įgyvendina hierarchiją ir paveldėjimą, todėl šis formatas labiau tinka didelėms įmonėms, kurioms reikia daug aprašymų – tai yra ne vieno produkto, o daug mikropaslaugų, kurios turi bendras sutarčių dalis – autentifikavimo schemas, tuos pačius duomenų tipus, klaidų korpusus. .
Tačiau RAML kūrėjas Mulesoft prisijungė prie Open API konsorciumo, kuris kuria . Todėl RAML sustabdė savo plėtrą. Norėdami įsivaizduoti renginio formatą, įsivaizduokite, kad pagrindinių Linux komponentų prižiūrėtojai išvyko dirbti į Microsoft. Tokia situacija sukuria prielaidas naudoti Swagger, kuris dinamiškai vystosi ir naujausia – trečia versija – praktiškai lenkia RAML savo lankstumu ir funkcionalumu.
Jei ne vienas dalykas...
Kaip paaiškėjo, ne visos atvirojo kodo paslaugos buvo atnaujintos į OAS 3.0. „Go“ mikropaslaugoms svarbiausias dalykas bus pritaikymo trūkumas naujausiai standarto versijai. Tačiau „Swagger 2“ ir „Swagger 3“ skiriasi . Pavyzdžiui, trečiojoje versijoje kūrėjai:
- patobulintas autentifikavimo schemų aprašymas
- JSON schemos palaikymas
- atnaujinta galimybė pridėti pavyzdžių
Situacija juokinga: renkantis standartą, kaip atskiras alternatyvas reikia laikyti RAML, Swagger 2 ir Swagger 3. Tačiau tik „Swagger 2“ gerai palaiko atvirojo kodo įrankius. RAML yra labai lankstus ir sudėtingas, o Swagger 3 menkai palaiko bendruomenė, todėl turėsite naudoti patentuotus įrankius arba komercinius sprendimus, kurie paprastai yra gana brangūs.
Be to, jei „Swagger“ yra daug gražių funkcijų, pavyzdžiui, paruoštas portalas , ant kurio galite įkelti anotaciją ir gauti jos vizualizaciją su detaliu aprašymu, nuorodomis ir ryšiais, tada fundamentalesniam ir mažiau draugiškam RAML tokios galimybės nėra. Taip, galite ieškoti ko nors tarp „GitHub“ projektų, rasti analogą ir patys jį įdiegti. Tačiau bet kokiu atveju kažkam teks prižiūrėti portalą, kuris nėra toks patogus elementariems naudojimo ar testavimo poreikiams. Be to, „swagger“ yra „neprincipingesnis“ arba liberalesnis - jį galima sugeneruoti iš komentarų kode, o tai, žinoma, prieštarauja API pirmajam principui ir nepalaiko jokios RAML paslaugų.
Vienu metu pradėjome dirbti su RAML kaip lankstesnė kalba, todėl daug ką teko daryti patiems. Pavyzdžiui, vienas iš projektų naudoja naudingumą vienetų testuose, kurie palaiko tik RAML 0.8. Taigi turėjome pridėti ramentus, kad programa galėtų „suvalgyti“ RAML 1.0 versiją.
Ar reikia rinktis?
Padirbėję kurdami RAML sprendimų ekosistemą, priėjome išvados, kad turime konvertuoti RAML į Swagger 2 ir joje atlikti visą automatizavimą, tikrinimą, testavimą ir tolesnį optimizavimą. Tai geras būdas panaudoti RAML lankstumą ir bendruomenės įrankių palaikymą iš Swagger.
Norėdami išspręsti šią problemą, yra du atvirojo kodo įrankiai, kurie turėtų užtikrinti sutarties konvertavimą:
- yra šiuo metu nepalaikoma programa. Dirbdami su juo sužinojome, kad ji turi daug problemų su sudėtingais RAML, kurie yra „išskirstyti“ per daug failų. Ši programa parašyta JavaScript ir atlieka rekursinį sintaksės medžio perėjimą. Dėl dinaminio spausdinimo šį kodą suprasti tampa sunku, todėl nusprendėme negaišti laiko rašydami mirštančios programos pataisas.
- - įrankis iš tos pačios įmonės, kuri teigia esanti pasiruošusi konvertuoti bet ką ir viską, ir bet kuria kryptimi. Iki šiol buvo paskelbtas RAML 0.8, RAML 1.0 ir Swagger 2.0 palaikymas. Tačiau mūsų tyrimo metu naudingumas vis dar buvo drėgnas ir netinkamas naudoti. Kūrėjai sukuria savotišką , todėl ateityje jie gali greitai pridėti naujų standartų. Bet kol kas tai tiesiog neveikia.
Ir tai dar ne visi sunkumai, su kuriais susidūrėme. Vienas iš mūsų veiksmų yra patikrinti, ar RAML iš saugyklos atitinka specifikaciją. Išbandėme keletą komunalinių paslaugų. Keista, bet jie visi mūsų anotacijas keikėsi skirtingose vietose ir visai skirtingais negražiais žodžiais. Ir ne visada iki esmės :).
Galų gale apsistojome ties pasenusiu projektu, kuris taip pat turi nemažai problemų (kartais jis užstringa netikėtai, kyla problemų dirbant su reguliariosiomis išraiškomis). Taigi, mes neradome būdo, kaip išspręsti patvirtinimo ir konvertavimo problemas, pagrįstas nemokamais įrankiais, ir nusprendėme naudoti komercinę priemonę. Ateityje, kai atvirojo kodo įrankiai taps brandesni, šią problemą bus lengviau išspręsti. Tuo tarpu darbo ir laiko sąnaudos „apdailavimui“ mums atrodė didesnės nei komercinės paslaugos kaina.
išvada
Po viso to norėjome pasidalinti savo patirtimi ir pastebėti, kad prieš renkantis sutarčių aprašymo įrankį reikia aiškiai apsibrėžti, ko iš jo norite ir į kokį biudžetą esate pasirengę investuoti. Jei pamirštume apie OpenSource, jau yra daugybė paslaugų ir produktų, kurie padės patikrinti, konvertuoti ir patvirtinti. Bet jie yra brangūs, o kartais ir labai brangūs. Didelei įmonei tokios išlaidos yra pakenčiamos, tačiau startuoliui jos gali tapti didele našta.
Nustatykite įrankių rinkinį, kurį naudosite vėliau. Pavyzdžiui, jei jums reikia tik parodyti sutartį, bus lengviau naudoti Swagger 2, kuris turi gražią API, nes RAML turėsite patys kurti ir prižiūrėti paslaugą.
Kuo daugiau užduočių turėsite, tuo didesnis bus įrankių poreikis, o skirtingoms platformoms jie yra skirtingi, todėl geriau iš karto susipažinti su turimomis versijomis, kad galėtumėte pasirinkti, kas sumažintų jūsų išlaidas ateityje.
Tačiau verta pripažinti, kad visos šiandien egzistuojančios ekosistemos yra netobulos. Todėl jei kompanijoje yra gerbėjų, kurie mėgsta dirbti RAML, nes „tai leidžia lanksčiau reikšti mintis“, arba, priešingai, teikia pirmenybę Swagger, nes „taip aiškiau“, geriausia juos palikti dirbti. kokie jie yra Jie yra pripratę ir nori, nes bet kurio formato įrankius reikia modifikuoti su failu.
Kalbant apie savo patirtį, kituose įrašuose kalbėsime apie tai, kokius statinius ir dinaminius patikrinimus atliekame remdamiesi savo RAML-Swagger architektūra, taip pat kokius dokumentus generuojame iš sutarčių ir kaip visa tai veikia.
Apklausoje gali dalyvauti tik registruoti vartotojai. , Prašau.
Kokia kalba komentuojate mikropaslaugų sutartis?
-
RAML 0.8
-
RAML 1.0
-
Swagger 2
-
OAS3 (dar žinomas kaip)
-
Projektas
-
Kitas
-
Nenaudojant
Balsavo 100 vartotojų. 24 vartotojai susilaikė.
Šaltinis: www.habr.com