Në një botë dinamike mikros services, gjithçka mund të ndryshojë - çdo komponent mund të riprogramohet në një gjuhë tjetër, duke përdorur frameworke dhe arkitektura të ndryshme. Ajo që duhet të mbetet e pandryshuar janë kontratat, në mënyrë që të ketë një ndërveprim të vazhdueshëm me mikros services, pavarësisht nga metamorfoza 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
Mikroserviset. Gjatë zhvillimit të Acronis Cyber Cloud, kuptuam se nuk kishim ku të iknim prej tyre. Dizajnimi i një mikros services nuk mund të realizohet pa formalizimin e kontratës, e cila përfaqëson ndërfaqen e mikros services.
Por kur në produkt ka më shumë se një komponent, dhe zhvillimi i kontratës bëhet një aktivitet i rregullt, fillon të mendosh për optimizimin e procesit. Bën të dukshme se ndërfaqja (kontrata) dhe implementimi (mikros services) duhet të përputhen, që komponentët e ndryshëm duhet të bëjnë të njëjtat gjëra njësoj, dhe se pa një pranimin qendror të të gjitha këtyre vendimeve, çdo ekip do të ishte i detyruar të humbte kohë përsëri dhe përsëri për t'i marrë ato.
Skema e mikroserviseve Amazon nga i Werner Vogels, CTO i Amazon
ĂfarĂ« Ă«shtĂ« dilema? NĂ« fakt, ka dy mĂ«nyra pĂ«r ndĂ«rveprimin e mikroserviseve - HTTP Rest dhe gRPC nga Google. TĂ« mos dĂ«shirojmĂ« tĂ« pĂ«rfshihemi nĂ« stek teknologjish tĂ« Google, ne zgjodhĂ«m HTTP Rest. Annotationet e kontratave HTTP REST zakonisht pĂ«rshkruhen nĂ« njĂ« nga dy formate: RAML dhe OAS, i njohur mĂ« parĂ« si Swagger. Prandaj, çdo ekip zhvilluesish pĂ«rballet me nevojĂ«n pĂ«r tĂ« bĂ«rĂ« njĂ« zgjedhje midis njĂ«rit prej standardeve. Por, siç u zbulua, tĂ« bĂ«sh kĂ«tĂ« zgjedhje mund tĂ« jetĂ« shumĂ« e vĂ«shtirĂ«.
Pse nevojiten annotationet?
NjĂ« pĂ«rmbledhje Ă«shtĂ« e nevojshme qĂ« pĂ«rdoruesi i jashtĂ«m tĂ« mund tĂ« kuptojĂ« lehtĂ«sisht se çfarĂ« mund tĂ« bĂ«jĂ« me shĂ«rbimin tuaj nĂ«pĂ«rmjet ndĂ«rfaqes sĂ« tij HTTP. KĂ«shtu qĂ«, nĂ« njĂ« nivel bazik, pĂ«rmbledhja duhet tĂ« pĂ«rmbajĂ« tĂ« paktĂ«n njĂ« listĂ« tĂ« burimeve tĂ« disponueshme, metodave tĂ« tyre HTTP, trupit tĂ« kĂ«rkesave, njohjen e parametrave, specifikimin e titujve tĂ« nevojshĂ«m dhe tĂ« mbĂ«shtetur, si dhe kodeve tĂ« kthimit dhe formateve tĂ« pĂ«rgjigjeve. NjĂ« element jashtĂ«zakonisht tĂ« rĂ«ndĂ«sishĂ«m tĂ« pĂ«rmbledhjes sĂ« kontratĂ«s Ă«shtĂ« dhe pĂ«rshkrimi i tyre me fjalĂ« (âçfarĂ« do tĂ« ndodhĂ« nĂ«se shtohet ky parametrat e kĂ«rkesĂ«s?â, ânĂ« cilin rast do tĂ« kthehet kodi 400?â)
Megjithatë, kur flitet për zhvillimin e një numri të madh mikrosherbimesh, dëshira është të nxirret dobi shtesë nga përmbledhjet e shkruara. Për shembull, mbi bazën e RAML/SWAGGER mund të gjenerohet kod klienti dhe serveri në një numër të madh gjuhësh programimi. Po ashtu, mund të përfitohet automatikisht dokumentacioni për mikrosherbimin dhe ta ngarkoni atë në portalin tuaj për zhvilluesit :).
Shembulli i përshkrimit të strukturuar të kontratës
Praktika e testimit të mikrosherbimeve mbi bazën e përshkrimeve të kontratave është më e rrallë. Nëse keni shkruar si përmbledhjen ashtu edhe komponentin, mund të krijoni një test automatik që kontrollon funksionimin e shërbimit me lloje të ndryshme të të dhënave në hyrje. A kthen shërbimi një kod përgjigjeje që nuk është përshkruar në përmbledhje? A do të jetë në gjendje të përpunojë të dhëna të gabuara?
Për më tepër, një zbatim cilësor jo vetëm i kontratave të vetme, por gjithashtu i mjeteve për vizualizimin e përmbledhjeve aktualizon punën me mikrosherbimin. Kështu që nëse arkitekti e ka përshkruar mirë kontratën, në bazë të saj dizajnerët dhe zhvilluesit do ta integrojnë shërbimin në produkte të tjera pa shpenzuar kohë shtesë.
Për të punuar me mjete shtesë, si RAML ashtu edhe OAS kanë mundësinë e shtimit të metadatatve, që nuk janë parashikuar nga standardi ().
Në përgjithësi, fusha për krijimtari në aplikimin e kontratave për mikrosherbime është e madhe... të paktën teoritikisht
Krahasimi i jezit me ujku
Aktualisht, drejtimi kryesor i zhvillimit në Acronis është zhvillimi 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. Edhe pse API-të tona të brendshme, të përshkruara në RAML, na kënaqin, nevoja për publikimin e API-ve e ngre përsëri pyetjen: cili standard i anotimeve është më i mirë për punën tonë?
Fillimisht dukej se kishte dy zgjidhje â ato janĂ« zhvillimet mĂ« tĂ« zakonshme RAML dhe Swagger (ose OAS). Por nĂ« fakt u tregua se alternativat janĂ« tĂ« paktĂ«n 3 ose mĂ« shumĂ«.
Nga njĂ«ra anĂ«, ka RAML â njĂ« gjuhĂ« e fuqishme dhe efektive. Ajo realizon 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 â pra, jo vetĂ«m njĂ« produkt, por shumĂ« mikro shĂ«rbime qĂ« kanĂ« pjesĂ« tĂ« pĂ«rbashkĂ«ta tĂ« kontratave â skemat e autentifikimit, tĂ« njĂ«jtat tipe tĂ« dhĂ«nash, 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. TĂ« imagjinoni formatin e ngjarjes, imagjinoni qĂ« mbajtĂ«sit e komponenteve kryesore tĂ« Linux shkuan tĂ« punojnĂ« nĂ« Microsoft. NjĂ« situatĂ« e tillĂ« krijon premisat pĂ«r tĂ« pĂ«rdorur Swagger, i cili zhvillohet dinamike dhe nĂ« versionin e tij tĂ« tretĂ« â praktikisht arrin RAML nĂ« fleksibilitet dhe funksionalitet.
Nëse nuk do të ishte një por...
Siç doli, shumë prej mjeteve open-source nuk janë përditësuar në versionin OAS 3.0. Për mikro shërbimet në Go, më kritikja do të ishte mungesa e adaptimit të për versionin e rinovuar të standardit. Megjithatë, ndryshimi mes 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
- përmirësuan mundësinë e shtimit të shembujve.
Situata rezulton të jetë e çuditshme: kur zgjidhni standardin duhet të merrni parasysh RAML, Swagger 2 dhe Swagger 3 si alternativa të veçanta. Në të njëjtën kohë, vetëm Swagger 2 ka mbështetje të mirë për mjetet OpenSource. RAML është shumë fleksibël⊠dhe i komplikuar, ndërsa Swagger 3 mbështetet dobët nga komuniteti, kështu që do t'ju duhet të përdorni mjete të zhvillimit tuaj ose zgjidhje komerciale, të cilat zakonisht janë mjaft të shtrenjta.
MegjithatĂ«, nĂ«se nĂ« Swagger ekzistojnĂ« shumĂ« mundĂ«si interesante, tĂ« tilla si portali i gatshĂ«m. , nĂ« tĂ« cilin mund tĂ« ngarkohet njĂ« annotim dhe tĂ« merret vizatimi i tij me njĂ« pĂ«rshkrim tĂ« hollĂ«sishĂ«m, lidhje dhe marrĂ«dhĂ«nie, nuk Ă«shtĂ« njĂ« mundĂ«si pĂ«r RAML, i cili Ă«shtĂ« mĂ« themelor dhe mĂ« pak miqĂ«sor. Po, mund tĂ« kĂ«rkoni diçka ndĂ«rmjet projekteve nĂ« GitHub, tĂ« gjeni njĂ« ekuivalent dhe ta zhvilloni vetĂ«. MegjithatĂ«, nĂ« çdo rast, dikush duhet ta mbajĂ« portalin, gjĂ« qĂ« nuk Ă«shtĂ« aq e pĂ«rshtatshme pĂ«r pĂ«rdorim bazik ose nevoja testuese. PĂ«r mĂ« tepĂ«r, swagger Ă«shtĂ« mĂ« âpa parimeâ, ose mĂ« liberal â mund tĂ« gjenerohet nga komentet nĂ« kod, qĂ« natyrisht Ă«shtĂ« nĂ« kundĂ«rshtim me parimin API first dhe nuk mbĂ«shtetet nga asnjĂ« nga utilitat e RAML.
Ne filluam tĂ« punojmĂ« me RAML, si njĂ« gjuhĂ« mĂ« fleksibile, dhe pĂ«rfundimisht duhet tĂ« bĂ«nim shumĂ« gjĂ«ra me duar. PĂ«r shembull, nĂ« njĂ« nga projektet pĂ«rdoret utilita nĂ« testet unit, e cila mbĂ«shtet vetĂ«m RAML 0.8. Pra, duhej tĂ« shtonim kĂ«ste, qĂ« utilita tĂ« mund tĂ« âhanĂ«â RAML versionin 1.0.
A duhet të zgjedhim?
Pas përpjekjeve me shtimin e ekosistemit të zgjidhjeve për RAML, arritëm në përfundimin se na duhej të konvertonim RAML në Swagger 2 dhe të bënim të gjithë automatizimin, verifikimin, testimin dhe optimizimin e mëvonshëm në të. Kjo është një mënyrë e mirë për të përdorur njëkohësisht fleksibilitetin e RAML dhe mbështetje nga mjetet e komunitetit të Swagger.
Për zgjidhjen e këtij problemi ekzistojnë dy mjete OpenSource, të cilat duhet të sigurojnë konvertimin e kontratave:
- â njĂ« utilitet i mbĂ«shtetur mĂ« parĂ«. GjatĂ« punĂ«s me tĂ«, zbuluam se ka njĂ« sĂ«rĂ« problemi me RAML-tĂ« e ndĂ«rlikuara qĂ« janĂ« âshtrirĂ«â nĂ« njĂ« numĂ«r tĂ« madh skedash. Ky program Ă«shtĂ« shkruar nĂ« JavaScript dhe bĂ«n njĂ« traversim recursiv tĂ« pemĂ«s sintaksore. PĂ«r shkak tĂ« tipizimit dinamik, bĂ«het e vĂ«shtirĂ« tĂ« kuptohet ky kod, prandaj vendosĂ«m tĂ« mos humbim kohĂ« duke shkruar patches pĂ«r njĂ« utilitet qĂ« Ă«shtĂ« duke vdekur.
- â njĂ« mjet nga e njĂ«jta kompani, i cili pretendon se Ă«shtĂ« i gatshĂ«m tĂ« konvertojĂ« gjithçka, pĂ«rveç çdo gjĂ«je, dhe nĂ« çdo drejtim. Aktualisht, Ă«shtĂ« shpallur mbĂ«shtetje pĂ«r RAML 0.8, RAML 1.0 dhe Swagger 2.0. MegjithatĂ«, nĂ« momentin e hetimit tonĂ«, utilita ishte ende e papjekur dhe e papĂ«rdorshme. Zhvilluesit po krijojnĂ« njĂ« tĂ« tillĂ« , qĂ« do t'i lejojĂ« ata tĂ« shtojnĂ« shpejt standarde tĂ« reja nĂ« tĂ« ardhmen. Por pĂ«r momentin, kjo thjesht nuk funksionon.
Dhe kjo nuk është e gjitha, sepse ne jemi përballur me disa sfida. Një nga hapat e pipeline-it tonë është të verifikohet se RAML nga repository është e saktë në raport me specifikimin. Ne provuam disa mjete. Për të habitur, ato të gjitha gjykuan për anotacionet tona në vende të ndryshme me fjalë të këqija të ndryshme. Dhe jo gjithmonë për arsye të mira : ).
NĂ« fund, ne u ndalĂ«m nĂ« njĂ« projekt qĂ« tani Ă«shtĂ« i vjetruar, i cili gjithashtu ka disa probleme (ndonjĂ«herĂ« dĂ«shton pa ndonjĂ« arsye, ka probleme me shprehjet e rregullta). Prandaj, ne nuk gjetĂ«m njĂ« mĂ«nyrĂ« pĂ«r tĂ« zgjidhur problemet e validimit dhe konvertimit duke pĂ«rdorur mjete falas, dhe vendosĂ«m tĂ« pĂ«rdorim njĂ« mjet komercial. NĂ« tĂ« ardhmen, kur mjetet OpenSource tĂ« bĂ«hen mĂ« tĂ« zhvilluara, ndoshta kjo detyrĂ« do tĂ« bĂ«het mĂ« e lehtĂ«. Deri atĂ«herĂ«, kostot e punĂ«s dhe kohĂ«s pĂ«r âpĂ«rfundiminâ e saj na dukeshin mĂ« tĂ« mĂ«dha se sa kostoja e shĂ«rbimit komercial.
PĂ«rfundim
Pas të gjitha këtyre, na erdhi dëshira për të ndarë përvojën dhe për të theksuar se para se të zgjidhni mjetin për përshkrimin e kontratave, është e rëndësishme të përcaktoni saktësisht se çfarë dëshoni prej tij dhe sa buxhet jeni të gatshëm të investoni. Nëse harrojmë për OpenSource, tashmë ka një numër të madh shërbimesh dhe produkteve që mund të ndihmojnë me verifikimin, konvertimin, dhe validimin. Por ato janë të shtrenjta, ndonjëherë jashtëzakonisht të shtrenjta. Për një kompani të madhe, këto shpenzime janë të pranueshme, por për një startup ato mund të bëhen një ngarkesë e madhe.
Përcaktoni një grup mjete që do të përdorni më vonë. Për shembull, nëse ju nevojitet thjesht të shfaqni kontratën, do të ishte më e lehtë të përdornit Swagger 2, i cili ka një API të bukur, pasi në RAML do t'ju duheshin të ngrinit dhe të mbani shërbimin vetë.
Sa më shumë detyra të keni, aq më e madhe do të jetë nevoja për mjete, dhe ato janë të ndryshme për platforma të ndryshme, kështu që është më mirë të njiheni me versionet e disponueshme menjëherë për të bërë një zgjedhje që minimizon shpenzimet tuaja në të ardhmen.
Por të qenë të sinqertë, të gjitha ekosistemat ekzistuese sot janë të papërkryera. Prandaj, nëse në kompani ka adhurues që pëlqejnë të punojnë me RAML, sepse "ai lejon shprehjen më të fleksibël të mendimeve", ose, përkundrazi, ata që preferojnë Swagger, sepse "ai është më i kuptueshëm", është më mirë t'i lejoni ata të punojnë me atë që janë të zakonshëm dhe dëshirojnë, sepse mjeti i çdo formati kërkon përmirësim.
Sa i përket përvojës sonë, në postimet e ardhshme do të flasim për kontrollet - statike dhe dinamike që realizojmë në bazë të arkitekturës sonë RAML-Swagger, si dhe për dokumentacionin që gjenerojmë nga kontratat dhe se si funksionon gjithçka kjo.
Vetëm përdoruesit e regjistruar mund të marrin pjesë në anketë. , ju lutem.
Cilin gjuhë përdorni për annotimin e kontratave të mikroshërbimeve?
RAML 0.8
RAML 1.0
Swagger 2
OAS3 (e njohur gjithashtu si)
Blueprint
Tjetër
Nuk përdori
100 përdorues kanë votuar. 24 përdorues abstenuan.
Burimi: habr.com
