Në botën dinamike të mikroshërbimeve, çdo gjë mund të ndryshojë - çdo komponent mund të rishkruhet në një gjuhë tjetër, duke përdorur korniza dhe arkitekturë të ndryshme. Vetëm kontratat duhet të mbeten të pandryshuara në mënyrë që mikroshërbimi të mund të ndërveprohet nga jashtë në një bazë të përhershme, pavarësisht nga metamorfozat e brendshme. Dhe sot do të flasim për problemin tonë të zgjedhjes së një formati për përshkrimin e kontratave dhe do të ndajmë artefaktet që gjetëm.
Postimi i përgatitur и
Mikroshërbime. Kur zhvillonim Acronis Cyber Cloud, kuptuam se nuk mund t'u shpëtonim atyre. Dhe dizenjimi i një mikroshërbimi është i pamundur pa zyrtarizuar kontratën, e cila përfaqëson ndërfaqen e mikroshërbimit.
Por kur një produkt përmban më shumë se një komponent dhe zhvillimi i kontratës bëhet një aktivitet i rregullt, nuk mund të mos filloni të mendoni për optimizimin e procesit. Bëhet e qartë se ndërfaqja (kontrata) dhe zbatimi (mikroshërbimi) duhet të përputhen me njëra-tjetrën, se komponentë të ndryshëm duhet të bëjnë të njëjtat gjëra në të njëjtën mënyrë dhe se pa një vendimmarrje të centralizuar të të gjitha këtyre vendimeve, çdo ekip do të detyrohet të kaloni kohë përsëri dhe përsëri për t'i marrë ato.
Diagrami i mikroshërbimeve të Amazon nga Werner Vogelis, CTO Amazon
Cila është dilema? De fakto, ekzistojnë dy mënyra për të bashkëvepruar me mikroshërbimet - HTTP Rest dhe gRPC nga Google. Duke mos dashur të kapemi në grupin e teknologjisë së Google, ne zgjodhëm HTTP Rest. Shënimet e kontratës HTTP REST përshkruhen më shpesh në një nga dy formatet: RAML dhe OAS, të njohura më parë si Swagger. Prandaj, çdo ekip zhvillimi përballet me nevojën për të zgjedhur një nga standardet. Por siç rezulton, bërja e kësaj zgjedhjeje mund të jetë shumë e vështirë.
Pse nevojiten shënimet?
Shënimi është i nevojshëm në mënyrë që një përdorues i jashtëm të kuptojë lehtësisht se çfarë mund të bëhet me shërbimin tuaj nëpërmjet ndërfaqes së tij HTTP. Kjo do të thotë, në një nivel bazë, shënimi duhet të përmbajë të paktën një listë të burimeve të disponueshme, metodat e tyre HTTP, trupat e kërkesave, një listë të parametrave, një tregues të titujve të kërkuar dhe të mbështetur, si dhe kodet e kthimit dhe formatet e përgjigjes. Një element jashtëzakonisht i rëndësishëm i shënimit të kontratës është përshkrimi i tyre verbal ("çfarë do të ndodhë nëse shtoni këtë parametër të pyetjes në kërkesë?", "Në cilin rast do të kthehet kodi 400?")
Megjithatë, kur bëhet fjalë për zhvillimin e një numri të madh mikroshërbimesh, ju dëshironi të nxirrni vlerë shtesë nga shënimet e shkruara. Për shembull, bazuar në RAML/Swagger, ju mund të gjeneroni kodin e klientit dhe serverit në një numër të madh gjuhësh programimi. Ju gjithashtu mund të merrni automatikisht dokumentacionin për mikroshërbimin dhe ta ngarkoni atë në portalin tuaj të zhvilluesit :).
Shembull i një përshkrimi të strukturuar të kontratës
Më pak e zakonshme është praktika e testimit të mikroshërbimeve bazuar në përshkrimet e kontratave. Nëse keni shkruar një shënim dhe një komponent, atëherë mund të krijoni një autotest që kontrollon përshtatshmërinë e shërbimit me lloje të ndryshme të të dhënave hyrëse. A kthen shërbimi një kod përgjigjeje që nuk përshkruhet në shënim? A do të jetë në gjendje të përpunojë saktë të dhënat dukshëm të pasakta?
Për më tepër, zbatimi me cilësi të lartë jo vetëm i vetë kontratave, por edhe i mjeteve për vizualizimin e shënimeve bën të mundur thjeshtimin e punës me mikroshërbimin. Kjo do të thotë, nëse arkitekti e përshkruan në mënyrë cilësore kontratën, bazuar në të, projektuesit dhe zhvilluesit do ta zbatojnë shërbimin në produkte të tjera pa kosto shtesë kohore.
Për të mundësuar mjete shtesë, si RAML ashtu edhe OAS kanë aftësinë të shtojnë meta të dhëna që nuk parashikohen nga standardi ().
Në përgjithësi, hapësira për kreativitet në përdorimin e kontratave për mikroshërbime është e madhe... të paktën në teori.
Krahasimi i një iriq me një gjarpër
Aktualisht, zona prioritare e zhvillimit në Acronis është zhvillimi i Platformës Kibernetike Acronis. Acronis Cyber Platform është pika e re e integrimit të shërbimeve të palëve të treta me Acronis Cyber Cloud dhe pjesën e agjentit. Edhe pse ishim të kënaqur me API-të tona të brendshme të përshkruara në RAML, nevoja për të publikuar API-në shtroi përsëri pyetjen e zgjedhjes: cili standard i shënimeve është më i mirë për t'u përdorur për punën tonë?
Fillimisht, dukej se kishte dy zgjidhje - zhvillimet më të zakonshme ishin RAML dhe Swagger (ose OAS). Por në fakt doli që ka të paktën jo 2 alternativa, por 3 ose më shumë.
Nga njëra anë është RAML - një gjuhë e fuqishme dhe efikase. Zbaton 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 një produkt, por shumë mikroshërbime që kanë pjesë të përbashkëta të kontratave - skema vërtetimi, të njëjtat lloje të dhënash, trupa gabimi .
Por zhvilluesi i RAML, Mulesoft, i është bashkuar konsorciumit Open API, i cili po zhvillon . Prandaj, RAML pezulloi zhvillimin e saj. Për të imagjinuar formatin e ngjarjes, imagjinoni që mirëmbajtësit e komponentëve kryesorë të Linux u larguan për të punuar për Microsoft. Kjo situatë krijon parakushtet për përdorimin e Swagger, i cili po zhvillohet në mënyrë dinamike dhe në versionin më të fundit - të tretë - praktikisht i afrohet RAML për nga fleksibiliteti dhe funksionaliteti.
Nëse jo për një gjë...
Siç rezulton, jo të gjitha shërbimet me burim të hapur janë përditësuar në OAS 3.0. Për mikroshërbimet në Go, gjëja më kritike do të jetë mungesa e përshtatjes për versionin më të fundit të standardit. Sidoqoftë, ndryshimi midis Swagger 2 dhe Swagger 3 është . Për shembull, në versionin e tretë zhvilluesit:
- përshkrim i përmirësuar i skemave të vërtetimit
- Mbështetje për skemën JSON
- përmirësoi aftësinë për të shtuar shembuj
Situata është qesharake: kur zgjidhni një standard, duhet të merrni parasysh RAML, Swagger 2 dhe Swagger 3 si alternativa të veçanta. Sidoqoftë, vetëm Swagger 2 ka mbështetje të mirë për mjetet OpenSource. RAML është shumë fleksibël...dhe kompleks, dhe Swagger 3 mbështetet dobët nga komuniteti, kështu që do t'ju duhet të përdorni mjete të pronarit ose zgjidhje komerciale, të cilat priren të jenë mjaft të shtrenjta.
Për më tepër, nëse ka shumë veçori të këndshme në Swagger, siç është një portal i gatshëm , në të cilën mund të ngarkoni një shënim dhe të merrni vizualizimin e tij me një përshkrim të detajuar, lidhje dhe lidhje, atëherë për RAML më themelore dhe më pak miqësore nuk ka një mundësi të tillë. Po, mund të kërkoni diçka midis projekteve në GitHub, të gjeni një analog atje dhe ta vendosni vetë. Sidoqoftë, në çdo rast, dikush do të duhet të mirëmbajë portalin, i cili nuk është aq i përshtatshëm për përdorim bazë ose nevoja testimi. Për më tepër, swagger është më "joparimor" ose më liberal - ai mund të gjenerohet nga komentet në kod, i cili, natyrisht, bie ndesh me parimin e parë të API dhe nuk mbështetet nga asnjë prej shërbimeve RAML.
Në një kohë filluam të punonim me RAML si një gjuhë më fleksibël, dhe si rezultat na u desh të bënim shumë gjëra vetë. Për shembull, një nga projektet përdor shërbimin në testet e njësisë, e cila mbështet vetëm RAML 0.8. Kështu që na duhej të shtonim paterica në mënyrë që programi të mund të "hante" versionin 1.0 RAML.
Keni nevojë të zgjidhni?
Pasi punuam në kompletimin e ekosistemit të zgjidhjeve për RAML, arritëm në përfundimin se duhet të konvertojmë RAML në Swagger 2 dhe të kryejmë të gjithë automatizimin, verifikimin, testimin dhe optimizimin pasues në të. Kjo është një mënyrë e mirë për të shfrytëzuar fleksibilitetin e RAML dhe mbështetjen e mjeteve të komunitetit nga Swagger.
Për të zgjidhur këtë problem, ekzistojnë dy mjete OpenSource që duhet të sigurojnë konvertimin e kontratës:
- është një program i pambështetur aktualisht. Gjatë punës me të, ne zbuluam se ai ka një sërë problemesh me RAML-të komplekse që janë "të shpërndara" në një numër të madh skedarësh. Ky program është shkruar në JavaScript dhe kryen një kalim rekurziv të një peme sintaksore. Për shkak të shtypjes dinamike, bëhet e vështirë për të kuptuar këtë kod, kështu që vendosëm të mos humbim kohë duke shkruar arna për një mjet që po vdes.
- - një mjet nga e njëjta kompani që pretendon se është gati të konvertojë gjithçka dhe gjithçka, dhe në çdo drejtim. Deri më sot, mbështetja është njoftuar për RAML 0.8, RAML 1.0 dhe Swagger 2.0. Megjithatë, në kohën e hulumtimit tonë, shërbimi ishte ende i lagësht dhe i papërdorshëm. Zhvilluesit krijojnë një lloj , duke i lejuar ata të shtojnë shpejt standarde të reja në të ardhmen. Por deri tani thjesht nuk funksionon.
Dhe nuk janë këto të gjitha vështirësitë që hasëm. Një nga hapat në tubacionin tonë është të verifikojmë që RAML nga depoja është e saktë në lidhje me specifikimet. Provuam disa shërbime. Çuditërisht, ata të gjithë betoheshin për shënimet tona në vende të ndryshme dhe me fjalë të këqija krejtësisht të ndryshme. Dhe jo gjithmonë në pikën :).
Në fund, ne u vendosëm në një projekt tashmë të vjetëruar, i cili gjithashtu ka një sërë problemesh (nganjëherë rrëzohet nga blu, ka probleme kur punon me shprehje të rregullta). Kështu, ne nuk gjetëm një mënyrë për të zgjidhur problemet e vlefshmërisë dhe konvertimit bazuar në mjete falas dhe vendosëm të përdorim një shërbim komercial. Në të ardhmen, ndërsa mjetet OpenSource bëhen më të pjekura, ky problem mund të bëhet më i lehtë për t'u zgjidhur. Ndërkohë, kostot e punës dhe kohës për "përfundim" na dukeshin më të rëndësishme sesa kostoja e një shërbimi tregtar.
Përfundim
Pas gjithë kësaj, ne donim të ndajmë përvojën tonë dhe të vërejmë se përpara se të zgjidhni një mjet për përshkrimin e kontratave, duhet të përcaktoni qartë se çfarë dëshironi prej tij dhe çfarë buxheti jeni të gatshëm të investoni. Nëse harrojmë OpenSource, ka tashmë një numër të madh shërbimesh dhe produktesh që do t'ju ndihmojnë të kontrolloni, konvertoni dhe vërtetoni. Por ato janë të shtrenjta, dhe ndonjëherë shumë të shtrenjta. Për një kompani të madhe, kosto të tilla janë të tolerueshme, por për një startup ato mund të bëhen një barrë e madhe.
Përcaktoni grupin e mjeteve që do të përdorni më vonë. Për shembull, nëse thjesht duhet të shfaqni një kontratë, do të jetë më e lehtë të përdorni Swagger 2, i cili ka një API të bukur, sepse në RAML do t'ju duhet ta ndërtoni dhe mirëmbani vetë shërbimin.
Sa më shumë detyra të keni, aq më e gjerë do të jetë nevoja për mjete, dhe ato janë të ndryshme për platforma të ndryshme, dhe është më mirë të njiheni menjëherë me versionet e disponueshme në mënyrë që të bëni një zgjedhje që minimizon kostot tuaja në të ardhmen.
Por ia vlen të pranohet se të gjitha ekosistemet që ekzistojnë sot janë të papërsosur. Prandaj, nëse ka fansa në kompani që duan të punojnë në RAML sepse "ju lejon të shprehni mendimet në mënyrë më fleksibël", ose, përkundrazi, preferoni Swagger sepse "është më e qartë", është më mirë t'i lini ata të punojnë. në atë që janë Ata janë mësuar me të dhe e duan atë, sepse veglat e cilitdo prej formateve kërkojnë modifikim me një skedar.
Sa i përket përvojës sonë, në postimet e mëposhtme do të flasim se çfarë kontrollesh statike dhe dinamike kryejmë bazuar në arkitekturën tonë RAML-Swagger, si dhe çfarë dokumentacioni gjenerojmë nga kontratat dhe si funksionon e gjithë kjo.
Vetëm përdoruesit e regjistruar mund të marrin pjesë në anketë. , te lutem
Çfarë gjuhe përdorni për të shënuar kontratat e mikroshërbimeve?
-
RAML 0.8
-
RAML 1.0
-
Kërcim 2
-
OAS3 (aka)
-
Plan
-
tjetër
-
Nuk përdoret
100 përdorues votuan. 24 përdorues abstenuan.
Burimi: www.habr.com