DinamiskajÄ mikropakalpojumu pasaulÄ viss var mainÄ«ties ā jebkuru komponentu var pÄrrakstÄ«t citÄ valodÄ, izmantojot dažÄdus ietvarus un arhitektÅ«ru. NemainÄ«tiem vajadzÄtu palikt tikai lÄ«gumiem, lai ar mikropakalpojumu varÄtu pastÄvÄ«gi mijiedarboties no Ärpuses neatkarÄ«gi no iekÅ”ÄjÄm metamorfozÄm. Un Å”odien mÄs runÄsim par mÅ«su problÄmu, izvÄloties formÄtu lÄ«gumu aprakstam, un dalÄ«simies ar atrastajiem artefaktiem.
Pasts sagatavots Šø
Mikropakalpojumi. IzstrÄdÄjot Acronis Cyber āāāāCloud, mÄs sapratÄm, ka nevaram no tiem izvairÄ«ties. Un mikropakalpojuma projektÄÅ”ana nav iespÄjama bez lÄ«guma formalizÄÅ”anas, kas ir mikropakalpojuma saskarne.
Bet, ja produkts satur vairÄk nekÄ vienu komponentu, un lÄ«guma izstrÄde kļūst par regulÄru darbÄ«bu, jÅ«s nevarat nesÄkt domÄt par procesa optimizÄciju. Kļūst acÄ«mredzams, ka saskarnei (lÄ«gumam) un ievieÅ”anai (mikropakalpojumam) ir jÄatbilst viens otram, ka dažÄdiem komponentiem ir jÄveic vienas un tÄs paÅ”as lietas vienÄdi un ka bez centralizÄtas lÄmumu pieÅemÅ”anas par visiem Å”iem lÄmumiem katra komanda bÅ«s spiesta pavadiet laiku atkal un atkal, lai tos iegÅ«tu.
Amazon mikropakalpojumu diagramma no Verners Vogeliss, Amazon CTO
KÄda ir dilemma? Faktiski ir divi veidi, kÄ mijiedarboties ar mikropakalpojumiem ā HTTP Rest un gRPC no Google. NevÄloties iekļūt Google tehnoloÄ£iju kaudzÄ, mÄs izvÄlÄjÄmies HTTP Rest. HTTP REST lÄ«gumu anotÄcijas visbiežÄk tiek aprakstÄ«tas vienÄ no diviem formÄtiem: RAML un OAS, kas agrÄk bija zinÄmi kÄ Swagger, tÄpÄc katra izstrÄdes komanda saskaras ar nepiecieÅ”amÄ«bu izvÄlÄties kÄdu no standartiem. Bet, kÄ izrÄdÄs, izdarÄ«t Å”o izvÄli var bÅ«t ļoti grÅ«ti.
KÄpÄc ir vajadzÄ«gas anotÄcijas?
AnotÄcija ir nepiecieÅ”ama, lai ÄrÄjs lietotÄjs varÄtu viegli saprast, ko var paveikt ar jÅ«su pakalpojumu, izmantojot tÄ HTTP saskarni. Tas ir, pamatlÄ«menÄ« anotÄcijÄ ir jÄsatur vismaz pieejamo resursu saraksts, to HTTP metodes, pieprasÄ«juma struktÅ«ras, parametru saraksts, norÄde par nepiecieÅ”amajÄm un atbalstÄ«tajÄm galvenÄm, kÄ arÄ« atgrieÅ”anas kodi un atbildes formÄti. Ä»oti svarÄ«gs lÄ«guma anotÄcijas elements ir to verbÄlais apraksts (ākas notiks, ja pieprasÄ«jumam pievienosi Å”o vaicÄjuma parametru?ā, āKÄdÄ gadÄ«jumÄ tiks atgriezts kods 400?ā)
TomÄr, ja runa ir par liela skaita mikropakalpojumu izstrÄdi, jÅ«s vÄlaties iegÅ«t papildu vÄrtÄ«bu no rakstiskajÄm anotÄcijÄm. PiemÄram, pamatojoties uz RAML/Swagger, jÅ«s varat Ä£enerÄt gan klienta, gan servera kodu daudzÄs programmÄÅ”anas valodÄs. Varat arÄ« automÄtiski saÅemt mikropakalpojuma dokumentÄciju un augÅ”upielÄdÄt to savÄ izstrÄdÄtÄja portÄlÄ :).
StrukturÄta lÄ«guma apraksta piemÄrs
MazÄk izplatÄ«ta ir mikropakalpojumu testÄÅ”anas prakse, pamatojoties uz lÄ«gumu aprakstiem. Ja esat uzrakstÄ«jis gan anotÄciju, gan komponentu, varat izveidot automÄtisko testu, kas pÄrbauda pakalpojuma atbilstÄ«bu ar dažÄda veida ievaddatiem. Vai pakalpojums atgriež atbildes kodu, kas nav aprakstÄ«ts anotÄcijÄ? Vai tas spÄs pareizi apstrÄdÄt acÄ«mredzami nepareizus datus?
TurklÄt kvalitatÄ«va ne tikai paÅ”u lÄ«gumu izpilde, bet arÄ« anotÄciju vizualizÄcijas rÄ«ki ļauj vienkÄrÅ”ot darbu ar mikropakalpojumu. Tas ir, ja arhitekts kvalitatÄ«vi aprakstÄ«ja lÄ«gumu, pamatojoties uz to, dizaineri un izstrÄdÄtÄji ieviesÄ«s pakalpojumu citos produktos bez papildu laika izmaksÄm.
Lai iespÄjotu papildu rÄ«kus, gan RAML, gan OAS ir iespÄja pievienot metadatus, kas nav paredzÄti standartÄ ().
KopumÄ radoÅ”uma iespÄjas mikropakalpojumu lÄ«gumu izmantoÅ”anÄ ir milzÄ«gas... vismaz teorÄtiski.
EzÄ«Å”a salÄ«dzinÄjums ar ÄÅ«sku
PaÅ”laik Acronis prioritÄrÄ attÄ«stÄ«bas joma ir Acronis Cyber āāāāplatformas attÄ«stÄ«ba. Acronis Cyber āāāāPlatform ir jauni treÅ”o puÅ”u pakalpojumu integrÄcijas punkti ar Acronis Cyber āāāāCloud un aÄ£enta daļu. Lai gan mÄs bijÄm apmierinÄti ar mÅ«su iekÅ”ÄjÄm API, kas aprakstÄ«tas RAML, nepiecieÅ”amÄ«ba publicÄt API atkal radÄ«ja jautÄjumu par izvÄli: kuru anotÄcijas standartu vislabÄk izmantot mÅ«su darbam?
SÄkotnÄji Ŕķita, ka ir divi risinÄjumi ā visizplatÄ«tÄkÄs izstrÄdes bija RAML un Swagger (vai OAS). Bet patiesÄ«bÄ izrÄdÄ«jÄs, ka ir vismaz nevis 2 alternatÄ«vas, bet 3 vai vairÄk.
No vienas puses, ir RAML - spÄcÄ«ga un efektÄ«va valoda. Tas labi realizÄ hierarhiju un pÄrmantoÅ”anu, tÄpÄc Å”is formÄts ir vairÄk piemÄrots lieliem uzÅÄmumiem, kuriem nepiecieÅ”ams daudz aprakstu - tas ir, nevis viens produkts, bet daudzi mikropakalpojumi, kuriem ir kopÄ«gas lÄ«gumu daļas - autentifikÄcijas shÄmas, vienÄdi datu tipi, kļūdu korpusi .
Bet RAML izstrÄdÄtÄjs Mulesoft ir pievienojies Open API konsorcijam, kas izstrÄdÄ . TÄpÄc RAML apturÄja savu attÄ«stÄ«bu. Lai iztÄlotos pasÄkuma formÄtu, iedomÄjieties, ka galveno Linux komponentu uzturÄtÄji aizgÄja strÄdÄt pie Microsoft. Å Ä« situÄcija rada priekÅ”nosacÄ«jumus Swagger izmantoÅ”anai, kas attÄ«stÄs dinamiski un jaunÄkajÄ - treÅ”ajÄ versijÄ - elastÄ«bas un funkcionalitÄtes ziÅÄ praktiski panÄk RAML.
Ja ne par vienu lietu...
KÄ izrÄdÄs, ne visas atvÄrtÄ pirmkoda utilÄ«tas ir atjauninÄtas uz OAS 3.0. Mikropakalpojumiem Go viskritiskÄkais bÅ«s pielÄgoÅ”anÄs trÅ«kums jaunÄkajai standarta versijai. TomÄr atŔķirÄ«ba starp Swagger 2 un Swagger 3 ir . PiemÄram, treÅ”ajÄ versijÄ izstrÄdÄtÄji:
- uzlabots autentifikÄcijas shÄmu apraksts
- JSON shÄmas atbalsts
- uzlabota iespÄja pievienot piemÄrus
SituÄcija ir smieklÄ«ga: izvÄloties standartu, jums ir jÄapsver RAML, Swagger 2 un Swagger 3 kÄ atseviŔķas alternatÄ«vas. TomÄr tikai Swagger 2 ir labs OpenSource rÄ«ku atbalsts. RAML ir ļoti elastÄ«gs un sarežģīts, un sabiedrÄ«ba Swagger 3 slikti atbalsta, tÄpÄc jums bÅ«s jÄizmanto patentÄti rÄ«ki vai komerciÄli risinÄjumi, kas parasti ir diezgan dÄrgi.
TurklÄt, ja Swagger ir daudz jauku iespÄju, piemÄram, gatavs portÄls , kurÄ var augÅ”upielÄdÄt anotÄciju un iegÅ«t tÄs vizualizÄciju ar detalizÄtu aprakstu, saitÄm un savienojumiem, tad fundamentÄlÄkam un mazÄk draudzÄ«gam RAML tÄdas iespÄjas nav. JÄ, jÅ«s varat meklÄt kaut ko starp GitHub projektiem, atrast tur analogu un pats to izvietot. TaÄu jebkurÄ gadÄ«jumÄ kÄdam bÅ«s jÄuztur portÄls, kas nav tik Ärts elementÄrai lietoÅ”anai vai testÄÅ”anas vajadzÄ«bÄm. TurklÄt swagger ir ābezprincipÄlÄksā vai liberÄlÄks - to var Ä£enerÄt no komentÄriem kodÄ, kas, protams, ir pretrunÄ API pirmÄ principam un to neatbalsta neviena no RAML utilÄ«tprogrammÄm.
Savulaik sÄkÄm strÄdÄt ar RAML kÄ elastÄ«gÄku valodu, un rezultÄtÄ daudzas lietas nÄcÄs darÄ«t paÅ”iem. PiemÄram, vienÄ no projektiem tiek izmantota utilÄ«ta vienÄ«bu testos, kas atbalsta tikai RAML 0.8. TÄpÄc mums bija jÄpievieno kruÄ·i, lai utilÄ«ta varÄtu "apÄst" RAML versiju 1.0.
Vai jums ir nepiecieÅ”ams izvÄlÄties?
StrÄdÄjot pie RAML risinÄjumu ekosistÄmas pabeigÅ”anas, mÄs nonÄcÄm pie secinÄjuma, ka mums ir jÄpÄrvÄrÅ” RAML par Swagger 2 un tajÄ jÄveic visa automatizÄcija, pÄrbaude, testÄÅ”ana un turpmÄkÄ optimizÄcija. Tas ir labs veids, kÄ izmantot gan RAML elastÄ«bu, gan kopienas rÄ«ku atbalstu no Swagger.
Lai atrisinÄtu Å”o problÄmu, ir divi atvÄrtÄ koda rÄ«ki, kuriem jÄnodroÅ”ina lÄ«guma konvertÄÅ”ana:
- ir paÅ”laik neatbalstÄ«ta utilÄ«ta. StrÄdÄjot ar to, mÄs atklÄjÄm, ka tai ir vairÄkas problÄmas ar sarežģītiem RAML failiem, kas ir āizkliedÄtiā lielÄ skaitÄ failu. Å Ä« programma ir uzrakstÄ«ta JavaScript un veic sintakses koka rekursÄ«vu pÄrvietoÅ”anos. DinamiskÄs rakstÄ«Å”anas dÄļ ir grÅ«ti saprast Å”o kodu, tÄpÄc mÄs nolÄmÄm netÄrÄt laiku, rakstot ielÄpus mirstoÅ”ai utilÄ«tai.
- - rÄ«ks no tÄ paÅ”a uzÅÄmuma, kas apgalvo, ka ir gatavs pÄrveidot jebko un visu, un jebkurÄ virzienÄ. LÄ«dz Å”im ir paziÅots par RAML 0.8, RAML 1.0 un Swagger 2.0 atbalstu. TomÄr mÅ«su pÄtÄ«juma laikÄ lietderÄ«ba joprojÄm bija mitrs un nederÄ«gs. IzstrÄdÄtÄji rada sava veida , ļaujot viÅiem Ätri pievienot jaunus standartus nÄkotnÄ. Bet lÄ«dz Å”im tas vienkÄrÅ”i nedarbojas.
Un tÄs vÄl nav visas grÅ«tÄ«bas, ar kurÄm saskÄrÄmies. Viena no mÅ«su konveijera darbÄ«bÄm ir pÄrbaudÄ«t, vai RAML no repozitorija ir pareizs attiecÄ«bÄ pret specifikÄciju. MÄs izmÄÄ£inÄjÄm vairÄkas utilÄ«tas. PÄrsteidzoÅ”i, viÅi visi zvÄrÄja mÅ«su anotÄcijas dažÄdÄs vietÄs un ar pavisam citiem sliktiem vÄrdiem. Un ne vienmÄr uz lietu :).
Beigu beigÄs mÄs nokÄrtojÄmies uz nu jau novecojuÅ”u projektu, kuram arÄ« ir vairÄkas problÄmas (dažreiz avÄrijas no zila gaisa, rodas problÄmas, strÄdÄjot ar regulÄrÄm izteiksmÄm). TÄdÄjÄdi mÄs neatradÄm veidu, kÄ atrisinÄt validÄcijas un konvertÄÅ”anas problÄmas, pamatojoties uz bezmaksas rÄ«kiem, un nolÄmÄm izmantot komerciÄlu utilÄ«tu. NÄkotnÄ, atvÄrtÄ koda rÄ«kiem kļūstot arvien nobrieduÅ”Äkiem, Ŕī problÄma var kļūt vieglÄk atrisinÄma. TikmÄr darbaspÄka un laika izmaksas āapdareiā mums Ŕķita bÅ«tiskÄkas nekÄ komercpakalpojuma izmaksas.
SecinÄjums
PÄc visa Ŕī mÄs vÄlÄjÄmies dalÄ«ties pieredzÄ un atzÄ«mÄt, ka pirms lÄ«gumu aprakstÄ«Å”anas rÄ«ka izvÄles ir skaidri jÄdefinÄ, ko no tÄ vÄlaties un kÄdu budžetu esat gatavs ieguldÄ«t. Ja aizmirstam par OpenSource, jau ir liels skaits pakalpojumu un produktu, kas palÄ«dzÄs pÄrbaudÄ«t, konvertÄt un apstiprinÄt. Bet tie ir dÄrgi, un dažreiz ļoti dÄrgi. Lielam uzÅÄmumam Å”Ädas izmaksas ir pieļaujamas, bet startup tÄs var kļūt par lielu slogu.
Nosakiet rÄ«ku komplektu, ko izmantosit vÄlÄk. PiemÄram, ja jums vienkÄrÅ”i jÄattÄlo lÄ«gums, bÅ«s vieglÄk izmantot Swagger 2, kuram ir skaista API, jo RAML jums bÅ«s jÄveido un jÄuztur pakalpojums paÅ”am.
Jo vairÄk uzdevumu jums bÅ«s, jo plaÅ”Äka bÅ«s nepiecieÅ”amÄ«ba pÄc rÄ«kiem, turklÄt dažÄdÄm platformÄm tie ir atŔķirÄ«gi, un labÄk uzreiz iepazÄ«ties ar pieejamajÄm versijÄm, lai izdarÄ«tu izvÄli, kas nÄkotnÄ samazina izmaksas.
Bet ir vÄrts atzÄ«t, ka visas Å”odien pastÄvoÅ”Äs ekosistÄmas ir nepilnÄ«gas. TÄpÄc, ja uzÅÄmumÄ ir fani, kuriem patÄ«k strÄdÄt RAML, jo "tas ļauj elastÄ«gÄk izteikt domas", vai, gluži pretÄji, dod priekÅ”roku Swagger, jo "tas ir skaidrÄks", labÄk ir atstÄt viÅus strÄdÄt. kÄdÄ tie ir ViÅi ir pieraduÅ”i un vÄlas, jo jebkura formÄta rÄ«ki prasa modifikÄciju ar failu.
RunÄjot par mÅ«su pieredzi, turpmÄkajos ierakstos mÄs runÄsim par to, kÄdas statiskÄs un dinamiskÄs pÄrbaudes mÄs veicam, pamatojoties uz mÅ«su RAML-Swagger arhitektÅ«ru, kÄ arÄ« to, kÄdu dokumentÄciju mÄs Ä£enerÄjam no lÄ«gumiem un kÄ tas viss darbojas.
AptaujÄ var piedalÄ«ties tikai reÄ£istrÄti lietotÄji. , lÅ«dzu.
KÄdu valodu izmantojat, lai anotÄtu mikropakalpojumu lÄ«gumus?
-
RAML 0.8
-
RAML 1.0
-
Swagger 2
-
OAS3 (aka)
-
projekts
-
Cits
-
Nelietojot
Nobalsoja 100 lietotÄji. 24 lietotÄji atturÄjÄs.
Avots: www.habr.com