NĂ« botĂ«n dinamike tĂ« mikroservicĂ«ve, gjithçka mund tĂ« ndryshojĂ« â çdo komponent mund tĂ« rikadohet nĂ« njĂ« gjuhĂ« tjetĂ«r, duke pĂ«rdorur framework-e dhe arkitekturĂ« tĂ« tjera. Ajo qĂ« duhet tĂ« mbetet e pandryshueshme janĂ« kontratat, pĂ«r t'u mundĂ«suar bashkĂ«veprimin me mikroservicin nga jashtĂ« nĂ« njĂ« bazĂ« tĂ« qĂ«ndrueshme, pavarĂ«sisht metamorfosave tĂ« brendshme. Sot do tĂ« flasim pĂ«r problemin tonĂ« tĂ« zgjedhjes sĂ« formatit tĂ« pĂ«rshkrimit tĂ« kontratave dhe do tĂ« ndajmĂ« artefaktet e gjetura.
Postimi është përgatitur nga dhe
Mikroservicët. Gjatë zhvillimit të Acronis Cyber Cloud, kuptuam se nuk mund të shmangnim mikroservicët. Projektimi i një mikroservici është i pamundur pa formalisht kontratën, e cila përbën ndërfaqen e mikroservicit.
Por kur në produkt ka më shumë se një komponent, dhe zhvillimi i kontratës bëhet një aktivitet i rregullt, fillon të shfaqet nevoja për optimizimin e procesit. Dukshëm është evidente se ndërfaqja (kontrata) dhe implementimi (mikroservici) duhet të harmonizohen, që komponentët e ndryshëm duhet të kryejnë të njëjtat funksione në mënyrë të njëjtë, dhe se pa një vendim të centralizuar për të gjithë këto, çdo ekip do të detyrohet të harxhojë kohë përsëri dhe përsëri për t'i marrë ato.
Skema e mikroservicëve të Amazon nga i Werner Vogels, CTO i Amazon
Cila Ă«shtĂ« dilema? NĂ« fakt, ka dy mĂ«nyra interaktoni me mikroservicĂ«t â HTTP Rest dhe gRPC nga Google. Duke mos dĂ«shiruar tĂ« pĂ«rfshihesh nĂ« stack-un e teknologjive tĂ« Google, ne zgjodhĂ«m HTTP Rest. Annotimet e kontratave HTTP REST shpesh pĂ«rshkruhen nĂ« njĂ« nga dy formate: RAML dhe OAS, tĂ« njohura mĂ« parĂ« si Swagger. Prandaj, çdo ekip zhvillues has nevojĂ«n pĂ«r tĂ« zgjedhur njĂ« nga standardet. Por, siç doli, tĂ« bĂ«sh kĂ«tĂ« zgjedhje mund tĂ« jetĂ« shumĂ« e vĂ«shtirĂ«.
Pse nevojiten annotimet?
Annotimi Ă«shtĂ« i nevojshĂ«m qĂ« pĂ«rdoruesi i jashtĂ«m tĂ« mund tĂ« kuptojĂ« lehtĂ«sisht se çfarĂ« mund tĂ« bĂ«jĂ« me shĂ«rbimin tuaj pĂ«rmes ndĂ«rfaqes sĂ« tij HTTP. KĂ«shtu, nĂ« nivelin bazik, annotimi duhet tĂ« pĂ«rmbajĂ« tĂ« paktĂ«n njĂ« listĂ« tĂ« burimeve tĂ« disponueshme, metodat e tyre HTTP, trupat e kĂ«rkesave, renditjen e parametrave, pĂ«rcaktimin e headereve tĂ« nevojshme dhe tĂ« mbĂ«shtetur, si dhe kodet e kthimit dhe formatet e pĂ«rgjigjeve. NjĂ« element shumĂ« i rĂ«ndĂ«sishĂ«m i annotimit tĂ« kontratĂ«s Ă«shtĂ« edhe pĂ«rshkrimi i tyre verbal (âçfarĂ« do tĂ« ndodhĂ« nĂ«se shtohet ky query-parametĂ«r nĂ« kĂ«rkesĂ«?â, ânĂ« cilat raste kthehet kodi 400?â)
Megjithatë, kur flitet për zhvillimin e një numri të madh të mikroservicëve, dëshirohet të nxirret një përfitim shtesë nga annotimet e shkruara. Për shembuj, në bazë të RAML/SWAGGER mund të gjenerohet një kod klienti dhe serveri në një numër të madh gjuhësh programuese. Po ashtu, mund të gjenerohet automatikisht dokumentacioni për mikroservicin dhe të ngarkohet në portalin tuaj të zhvilluesve :).
Shembulli i një përshkrimi të strukturuar të kontratës
Praktika e testimit të mikroservicëve në bazë të përshkrimeve të kontratave takohen më rrallë. Nëse keni shkruar si annotimin, ashtu edhe komponentin, mund të krijoni një test automatik që kontrollon adekuatësinë e punës së shërbimit me lloje të ndryshme të të dhënave në hyrje. A kthen shërbimi ndonjë kod përgjigjie, i cili nuk është përshkruar në annotim? A do të jetë në gjendje të procesojë të dhënat e gabuara në mënyrë të saktë?
Për më tepër, realizimi cilësor jo vetëm i kontratave, por edhe të mjeteve për vizualizimin e annotimeve, lejon të thjeshtësohet puna me mikroservicin. Kështu, nëse arkitekti e përshkruan me cilësi kontratën, mbi atë bazë dizajnerët dhe zhvilluesit do të integrojnë shërbimin në produkte të tjera pa shpenzuar kohë shtesë.
Për punën e mjeteve të tjera, si RAML ashtu edhe OAS kanë mundësinë e shtimit të metadatanave, të cilat nuk parashihen nga standardi ().
Në përgjithësi, fusha për krijimtarinë në aplikimin e kontratave për mikroservicët është e madhe... të paktën në teori
Krahasoni një gjel me një asfalt
Në këtë moment, drejtimi prioritar i zhvillimit në Acronis është përmirësimi i Acronis Cyber Platform. Acronis Cyber Platform është pikët e reja të integrimit të shërbimeve të jashtme me Acronis Cyber Cloud dhe pjesën agjente. Ndërsa API-të tona të brendshme, të përshkruara në RAML, na kënaqnin, nevojën për publikimin e API-rëve e rriti sërish pyetjen: cili është standardi më i mirë i annotimeve për punën tonë?
Fillimisht dukej se zgjidhjet ishin dy â janĂ« zhvillimet mĂ« tĂ« zakonshme RAML dhe Swagger (ose OAS). Por nĂ« fakt doli se alternativat janĂ« tĂ« paktĂ«n 2, por 3 ose mĂ« shumĂ«.
Në një anë është RAML - një gjuhë e fuqishme dhe efektive. Ajo implementon mirë hierarkinë dhe trashëgiminë, kështu që ky format është më i përshtatshëm për kompanitë e mëdha që kanë nevojë për shumë përshkrime - domethënë jo vetëm një produkt, por shumë mikroshërbime që kanë pjesë të përbashkëta të kontratave - skemat e autentifikimit, llojet e të dhënave të njëjta, trupat e gabimeve.
Por zhvilluesi i RAML, kompania Mulesoft, u bashkua me konsorciumin Open API, i cili merret me zhvillimin . Prandaj, RAML e ndali zhvillimin e tij. Për të imagjinuar formatin e ngjarjes, imagjinoni se mbajtësit e komponenteve kryesore të Linux u larguan për t'u punësuar në Microsoft. Një situatë e tillë krijon parakushte për të përdorur Swagger, i cili zhvillohet dinamik dhe në versionin e tij të tretë arrin praktikisht të përmbushë RAML në fleksibilitet dhe funksionalitet.
NĂ«se nuk do ishte njĂ« porâŠ
Siç rezulton, shumë nga mjetet open-source nuk janë përditësuar në versionin OAS 3.0. Për mikroshërbimet në Go, më kritike do të jetë mungesa e adaptimit të në versionin e ri të standardit. Megjithatë, diferenca midis Swagger 2 dhe Swagger 3 është Për shembull, në versionin e tretë zhvilluesit:
- përmirësuan përshkrimin e skemave të autentifikimit
- mbështetje për JSON Schema
- shpërndan mundësinë e shtimit të shembujve.
Situata del qesharake: kur zgjidhni standardin, duhet t'i shihni RAML, Swagger 2 dhe Swagger 3 si alternativa të veçanta. Në këtë rast, vetëm Swagger 2 ka mbështetje të mirë nga mjetet OpenSource. RAML është shumë fleksibël⊠dhe i ndërlikuar, ndërsa Swagger 3 mbështetet pak nga komuniteti, kështu që do të duhet të përdorni mjete të zhvillimit të brendshëm ose zgjidhje komerciale, të cilat, si rregull, janë shumë të shtrenjta.
Dhe megjithatë, nëse Swagger ka shumë mundësi të këndshme, siç është portali i gatshëm , ku mund të ngarkoni një annotim dhe të merrni vizualizimin e tij me përshkrim të detajuar, lidhje dhe marrëdhënie, për RAML, i cili është më themelor dhe më pak miqësor, nuk ka një mundësi të tillë. Po, mund të kërkoni diçka në projektet në GitHub, të gjeni atje një analog dhe ta zhvilloni vetë. Megjithatë, në çdo rast, dikush do të duhet ta mbajë portalin, që nuk është aq e përshtatshme për përdorim të thjeshtë ose nevoja testuese. Përveç kësaj, swagger është më "pa parime", ose më liberal - mund të gjenerohet nga komentet në kod, që natyrisht shkon në përputhje me parimin API first dhe nuk mbështetet nga asnjë nga mjetet RAML.
Në atë kohë filluam të punojmë me RAML si një gjuhë më fleksibile, dhe në fund duhej të bënim shumë gjëra me duar. Për shembull, në një nga projektet përdoret mjeti në testet e njësive, i cili mbështet vetëm RAML 0.8. Prandaj, duhej të shtonim 'bandages' që mjeti të mund të "hanë" RAML versionin 1.0.
A duhet të zgjidhet?
Pas një përpjekjeje me shtimin e ekosistemit të zgjidhjeve për RAML, arritëm në përfundimin se duhej ta konvertonim RAML në Swagger 2 dhe të realizonim të gjithë automatizimin, verifikimin, testimin dhe optimizimin e mëvonshëm brenda tij. Ky është një mënyrë e mirë për të përdorur, njëkohësisht, fleksibilitetin e RAML dhe mbështetje nga komuniteti të mjeteve të Swagger.
Për të zgjidhur këtë problem ekzistojnë dy mjete OpenSource, që duhet të sigurojnë konvertimin e kontratave:
- - një mjet që tani nuk mbështetet. Gjatë punës me të, zbuluam se kishte një sërë problemesh me RAML të komplikuara, të cilat "shtrihen" në shumë skedarë. Ky program është shkruar në JavaScript dhe kryen një kalim nëpër pemën sintaksore. Për shkak të tipizimit dinamik, kuptimi i këtij kodit bëhet i vështirë, kështu që vendosëm të mos shpenzojmë kohë mbi shkrimin e patch-eve për një mjet që po vdes.
- - njĂ« mjet nga e njĂ«jta kompani, qĂ« pretendon tĂ« jetĂ« gati tĂ« konvertojĂ« gjithçka dhe nĂ« çdo drejtim. Aktualisht, Ă«shtĂ« deklaruar mbĂ«shtetje pĂ«r RAML 0.8, RAML 1.0 dhe Swagger 2.0. MegjithatĂ«, nĂ« momentin e kĂ«rkimit tonĂ«, mjeti ishte ende i papĂ«rgatitur dhe i papĂ«rdorshĂ«m. Zhvilluesit po krijojnĂ« njĂ« lloj , qĂ« do tâu lejojĂ« atyre nĂ« tĂ« ardhmen tĂ« shtojnĂ« shpejt standarde tĂ« reja. Por pĂ«r momentin, kjo thjesht nuk funksionon.
Dhe kjo nuk është e gjitha, ndërlikimet me të cilat u përballëm. Një nga hapat e pipeline-it tonë është verifikimi që RAML nga repo është i saktë në marrëveshje me specifikimin. Provuam disa mjete. Mrekullisht, por të gjitha ato ankohej në anotimet tona në vende të ndryshme me fjalë të ndryshme të këqija. Dhe jo gjithmonë me të drejtë :).
NĂ« fund, u ndalĂ«m nĂ« njĂ« projekt qĂ« tani Ă«shtĂ« i vjetruar, i cili gjithashtu ka njĂ« sĂ«rĂ« problemesh (nĂ« disa raste bie pa arsye, ka vĂ«shtirĂ«si nĂ« punĂ«n me shprehjet e rregullta). KĂ«shtu, nuk gjetĂ«m njĂ« mĂ«nyrĂ« pĂ«r tĂ« zgjidhur detyrat e validimit dhe konvertimit me ndihmĂ«n e mjeteve falas, dhe vendosĂ«m tĂ« pĂ«rdorim njĂ« utilitare komerciale. NĂ« tĂ« ardhmen, kur mjetet OpenSource tĂ« avancohen mĂ« shumĂ«, zgjidhja e kĂ«saj problemi, ndoshta, do tĂ« bĂ«het mĂ« e lehtĂ«. NdĂ«rkohĂ«, kostot e punĂ«s dhe kohĂ«s pĂ«r âpĂ«rmirĂ«simeâ na dukeshin mĂ« tĂ« mĂ«dha se çmimi i shĂ«rbimit komercial.
PĂ«rfundimi
Pas të gjithave, na erdhi dëshira të ndajmë përvojën dhe të theksojmë se para se të zgjidhni një mjet për përshkrimin e kontratave, duhet të sqaroni qartë se çfarë dëshironi prej tij dhe çfarë buxheti jeni të gatshëm të investoni. Nëse e harroni OpenSource, tani ka një numër të madh shërbimesh dhe produkteve që ndihmojnë në verifikim, konvertim dhe validim. Por ato janë të shtrenjta, ndonjëherë - shumë të shtrenjta. Për një kompani të madhe, këto shpenzime janë të pranueshme, por për një startup mund të bëhen një ngarkesë e madhe.
Përcaktoni grupin e mjeteve që do të përdorni më vonë. Për shembull, nëse thjesht ju nevojitet të shfaqni kontratën, do të ishte më e lehtë të përdornit Swagger 2, i cili ka një API të bukur, ndërsa në RAML do t'ju nevojitet të ngrini dhe mbani shërbimin vetë.
Sa më shumë detyra të keni, aq më e madhe do të jetë nevoja juaj për mjete, dhe ato janë të ndryshme për platforma të ndryshme, dhe është më mirë që të njihni menjëherë versionet e disponueshme për të bërë një zgjedhje që minimizon shpenzimet tuaja në të ardhmen.
Por duhet pranuar se të gjitha ekosistemet ekzistuese sot janë të papërsosura. Prandaj, nëse në kompani ka entuziastë që preferojnë të punojnë me RAML, sepse "ai lejon shprehje më fleksibël të mendimeve", ose, përkundrazi, preferojnë Swagger, sepse "ai është më i qartë", është më mirë t'i lini ata të punojnë në atë që janë të zakonshëm dhe duan, sepse ari i çdo formati kërkon përmirësime të vogla.
Sa i përket përvojës tonë, në postimet e ardhshme do të ndajmë se cilat - kontrollime statike dhe dinamike ne realizojmë mbi bazën e arkitekturës sonë RAML-Swagger, si dhe dokumentacionin që ne gjenerojmë nga kontratat dhe se si funksionon e gjithë kjo.
Vetëm përdoruesit e regjistruar mund të marrin pjesë në anketë. , ju lutemi.
Cilin gjuhë përdorni për anotimet e kontratave të mikroshërbimeve?
RAML 0.8
RAML 1.0
Swagger 2
OAS3 (aka )
Blueprint
E tjera
Nuk përdor
100 përdorues votuan. 24 përdorues abstenuan.
Burimi: habr.com
