Sa dinamikong kalibutan sa mga microservice, ang bisan unsa mahimong mausab-bisan unsa nga bahin mahimong isulat pag-usab sa lain nga pinulongan, gamit ang lain-laing mga frameworks ug arkitektura. Ang mga kontrata lamang ang kinahanglan magpabilin nga wala mausab aron ang microservice mahimong makig-uban gikan sa gawas sa pipila ka permanente nga basehan, bisan unsa pa ang internal nga metamorphoses. Ug karon maghisgot kami bahin sa among problema sa pagpili sa usa ka format alang sa paghulagway sa mga kontrata ug ipaambit ang mga artifact nga among nakit-an.
Giandam ang post ΠΈ
Microservices. Kung gipalambo ang Acronis Cyber ββββCloud, nahibal-an namon nga dili kami makaikyas kanila. Ug ang pagdesinyo sa usa ka microservice imposible kung walaβy pormal nga kontrata, nga nagrepresentar sa interface sa microservice.
Apan kung ang usa ka produkto adunay labaw pa sa usa ka sangkap, ug ang pagpauswag sa kontrata mahimong usa ka regular nga kalihokan, dili nimo malikayan nga magsugod sa paghunahuna bahin sa pag-optimize sa proseso. Kini nahimong dayag nga ang interface (kontrata) ug pagpatuman (microservice) kinahanglan nga motakdo sa usag usa, nga ang lain-laing mga component kinahanglan nga mobuhat sa sama nga mga butang sa samang paagi, ug nga walay sentralisadong paghimo sa desisyon sa tanan niini nga mga desisyon, ang matag team mapugos sa paggahin ug panahon pag-usab aron makuha sila.
Amazon microservices diagram gikan sa Werner Vogelis, CTO Amazon
Unsa ang dilemma? Sa pagkatinuod, adunay duha ka paagi sa interaksyon sa mga microservice - HTTP Rest ug gRPC gikan sa Google. Dili gusto nga madakpan sa Google's technology stack, among gipili ang HTTP Rest. Ang mga anotasyon sa kontrata sa HTTP REST kasagarang gihulagway sa usa sa duha ka mga format: RAML ug OAS, kanhi nailhan nga Swagger.Busa, ang matag development team nag-atubang sa panginahanglan sa pagpili sa usa sa mga sumbanan. Apan ingon nga kini nahimo, ang paghimo niini nga pagpili mahimong lisud kaayo.
Nganong gikinahanglan ang mga anotasyon?
Ang anotasyon gikinahanglan aron ang usa ka eksternal nga tiggamit dali nga mahibal-an kung unsa ang mahimo sa imong serbisyo pinaagi sa interface sa HTTP. Kana mao, sa usa ka sukaranan nga lebel, ang anotasyon kinahanglan adunay labing menos usa ka lista sa magamit nga mga kapanguhaan, ang ilang mga pamaagi sa HTTP, mga lawas sa paghangyo, usa ka lista sa mga parameter, usa ka timailhan sa gikinahanglan ug gisuportahan nga mga ulohan, ingon man mga code sa pagbalik ug mga format sa pagtubag. Usa ka hilabihan ka importante nga elemento sa annotation sa kontrata mao ang ilang verbal nga deskripsyon (βunsa ang mahitabo kon imong idugang kini nga parameter sa pangutana sa hangyo?β, βSa unsang kaso ibalik ang code 400?β)
Bisan pa, kung bahin sa pagpalambo sa daghang mga microservice, gusto nimong makuha ang dugang nga kantidad gikan sa mga sinulat nga anotasyon. Pananglitan, base sa RAML/Swagger, mahimo nimong makamugna ang kliyente ug server code sa daghang mga programming language. Mahimo ka usab nga awtomatiko nga makadawat mga dokumentasyon alang sa microservice ug i-upload kini sa imong developer-portal :).
Pananglitan sa usa ka structured nga paghulagway sa kontrata
Dili kaayo komon ang praktis sa pagsulay sa mga microservice base sa mga paghulagway sa kontrata. Kung gisulat nimo ang usa ka anotasyon ug usa ka sangkap, nan mahimo ka maghimo usa ka autotest nga nagsusi sa pagkaigo sa serbisyo nga adunay lainlaing mga klase sa data sa pag-input. Ang serbisyo ba nagbalik ug tubag nga code nga wala gihulagway sa anotasyon? Makahimo ba kini sa husto nga pagproseso nga klaro nga sayup nga datos?
Dugang pa, ang taas nga kalidad nga pagpatuman dili lamang sa mga kontrata sa ilang kaugalingon, apan usab ang mga himan alang sa paghanduraw sa mga anotasyon nagpaposible sa pagpayano sa trabaho sa microservice. Kana mao, kon ang arkitekto qualitatively naghulagway sa kontrata, base niini, ang mga tigdesinyo ug mga developers ipatuman ang serbisyo sa ubang mga produkto nga walay dugang nga gasto sa panahon.
Aron mahimo ang dugang nga mga himan, ang RAML ug OAS adunay katakus sa pagdugang sa metadata nga wala gihatag sa sumbanan ().
Sa kinatibuk-an, ang kasangkaran alang sa pagkamamugnaon sa paggamit sa mga kontrata alang sa mga microservice dako kaayo ... labing menos sa teorya.
Pagtandi sa usa ka hedgehog sa usa ka bitin
Sa pagkakaron, ang priority development area sa Acronis mao ang pagpalambo sa Acronis Cyber ββββPlatform. Ang Acronis Cyber ββββPlatform usa ka bag-ong punto sa paghiusa sa mga serbisyo sa ikatulo nga partido sa Acronis Cyber ββββCloud ug ang bahin sa ahente. Bisan kung nalipay kami sa among mga internal nga API nga gihulagway sa RAML, ang panginahanglan nga imantala ang API pag-usab nagpatunghag pangutana sa pagpili: unsa nga sumbanan sa annotation ang labing maayo nga gamiton alang sa among trabaho?
Sa sinugdan, ingon og adunay duha ka mga solusyon - ang labing kasagaran nga mga pag-uswag mao ang RAML ug Swagger (o OAS). Apan sa pagkatinuod kini nahimo nga adunay labing menos dili 2 nga mga alternatibo, apan 3 o labaw pa.
Sa usa ka bahin adunay RAML - usa ka gamhanan ug episyente nga pinulongan. Gipatuman niini ang hierarchy ug inheritance nga maayo, mao nga kini nga format mas angay alang sa dagkong mga kompaniya nga nagkinahanglan og daghang mga paghubit - nga mao, dili usa ka produkto, apan daghang mga microservice nga adunay komon nga mga bahin sa mga kontrata - mga pamaagi sa pag-authenticate, parehas nga tipo sa datos, mga lawas sa sayup .
Apan ang developer sa RAML, Mulesoft, miapil sa Open API consortium, nga nag-uswag . Busa, gisuspinde sa RAML ang pag-uswag niini. Aron mahanduraw ang pormat sa panghitabo, hunahunaa nga ang mga tigmentinar sa mga nag-unang sangkap sa Linux nahabilin aron magtrabaho sa Microsoft. Kini nga sitwasyon nagmugna sa mga kinahanglanon alang sa paggamit sa Swagger, nga nag-uswag nga dinamiko ug sa pinakabag-o - ikatulo nga bersyon - halos makaapas sa RAML sa mga termino sa pagka-flexible ug pagpaandar.
Kung dili tungod sa usa ka butang ...
Ingon nga kini nahimo, dili tanan nga bukas nga gigikanan nga mga utilities ang na-update sa OAS 3.0. Alang sa mga microservice sa Go, ang labing kritikal nga butang mao ang kakulang sa pagpahiangay para sa pinakabag-o nga bersyon sa standard. Bisan pa, ang kalainan tali sa Swagger 2 ug Swagger 3 mao . Pananglitan, sa ikatulo nga bersyon ang mga developers:
- gipaayo nga paghulagway sa mga laraw sa pag-authenticate
- Suporta sa JSON Schema
- gipauswag ang abilidad sa pagdugang mga pananglitan
Kataw-anan ang kahimtang: kung nagpili usa ka sukaranan, kinahanglan nimo nga tagdon ang RAML, Swagger 2 ug Swagger 3 ingon lahi nga mga alternatibo. Bisan pa, ang Swagger 2 ra ang adunay maayong suporta alang sa mga himan sa OpenSource. Ang RAML kay flexible kaayo...ug komplikado, ug ang Swagger 3 dili kaayo suportado sa komunidad, mao nga kinahanglan nimo gamiton ang proprietary nga mga himan o komersyal nga mga solusyon, nga lagmit mahal kaayo.
Dugang pa, kung adunay daghang nindot nga mga bahin sa Swagger, sama sa usa ka andam nga portal , diin mahimo nimong i-upload ang usa ka anotasyon ug makuha ang pagtan-aw niini nga adunay usa ka detalyado nga paghulagway, mga link ug mga koneksyon, unya alang sa labi ka sukaranan ug dili kaayo mahigalaon nga RAML walaβy ingon nga oportunidad. Oo, makapangita ka usa ka butang taliwala sa mga proyekto sa GitHub, pangitaa ang usa ka analogue didto ug i-deploy kini sa imong kaugalingon. Bisan pa, sa bisan unsang kaso, kinahanglan nga adunay usa nga magpadayon sa portal, nga dili kaayo kombenyente alang sa sukaranan nga paggamit o mga kinahanglanon sa pagsulay. Dugang pa, ang swagger mas "walay prinsipyo", o mas liberal - mahimo kini gikan sa mga komento sa code, nga, siyempre, supak sa unang prinsipyo sa API ug wala gisuportahan sa bisan unsang RAML utilities.
Sa usa ka higayon nagsugod kami sa pagtrabaho kauban ang RAML ingon usa ka labi ka dali nga sinultian, ug ingon usa ka sangputanan kinahanglan namon nga buhaton ang daghang mga butang sa among kaugalingon. Pananglitan, ang usa sa mga proyekto naggamit sa utility sa mga pagsulay sa yunit, nga nagsuporta lamang sa RAML 0.8. Mao nga kinahanglan namon nga idugang ang crutches aron ang utility "makakaon" RAML nga bersyon 1.0.
Kinahanglan ka ba nga mopili?
Ang pagtrabaho sa pagkompleto sa ekosistema sa mga solusyon alang sa RAML, nakahinapos kami nga kinahanglan namon nga i-convert ang RAML sa Swagger 2 ug ipatuman ang tanan nga automation, pag-verify, pagsulay ug sunud nga pag-optimize niini. Kini usa ka maayong paagi aron magamit ang pagka-flexible sa RAML ug ang suporta sa tool sa komunidad gikan sa Swagger.
Aron masulbad kini nga problema, adunay duha ka mga himan sa OpenSource nga kinahanglan maghatag pagbag-o sa kontrata:
- mao ang usa ka kasamtangan nga dili suportadong utility. Samtang nagtrabaho uban niini, among nadiskobrehan nga kini adunay ubay-ubay nga mga problema sa mga komplikadong RAML nga "nakaylap" sa daghang mga file. Kini nga programa gisulat sa JavaScript ug naghimo sa usa ka recursive traversal sa usa ka syntax tree. Tungod sa dinamikong pag-type, mahimong lisud sabton kini nga code, mao nga nakahukom kami nga dili mag-usik og oras sa pagsulat og mga patch alang sa usa ka himatyon nga gamit.
- - usa ka himan gikan sa parehas nga kompanya nga nag-angkon nga andam sa pag-convert sa bisan unsang butang ug tanan, ug sa bisan unsang direksyon. Hangtod karon, gipahibalo ang suporta alang sa RAML 0.8, RAML 1.0 ug Swagger 2.0. Bisan pa, sa panahon sa among panukiduki, ang gamit wala pa basa ug dili magamit. Ang mga developers naghimo og usa ka matang sa , nga nagtugot kanila sa dali nga pagdugang sa bag-ong mga sumbanan sa umaabot. Apan hangtod karon wala pa kini molihok.
Ug dili kana ang tanan nga mga kalisdanan nga among nasugatan. Usa sa mga lakang sa among pipeline mao ang pag-verify nga ang RAML gikan sa repository husto nga may kalabotan sa detalye. Gisulayan namo ang daghang mga utilities. Katingad-an, silang tanan nanumpa sa among mga anotasyon sa lainlaing mga lugar ug adunay lahi kaayo nga dili maayo nga mga pulong. Ug dili kanunay sa punto :).
Sa katapusan, kami nahusay sa usa ka karon outdated nga proyekto, nga usab adunay usa ka gidaghanon sa mga problema (usahay kini nahagsa gikan sa asul, adunay mga problema sa diha nga nagtrabaho uban sa regular nga mga ekspresyon). Sa ingon, wala kami makit-an nga paagi aron masulbad ang mga problema sa pag-validate ug pagkakabig base sa libre nga mga himan, ug nakahukom nga mogamit usa ka komersyal nga gamit. Sa umaabot, samtang ang mga himan sa OpenSource nahimong mas hamtong, kini nga problema mahimong mas sayon ββnga masulbad. Sa kasamtangan, ang mga gasto sa pagtrabaho ug oras alang sa "pagtapos" ingon kanamo nga mas hinungdanon kaysa sa gasto sa usa ka komersyal nga serbisyo.
konklusyon
Human sa tanan niini, gusto namong ipaambit ang among kasinatian ug timan-i nga sa dili pa mopili og usa ka himan alang sa paghulagway sa mga kontrata, kinahanglan nimo nga tin-aw nga ipasabut kung unsa ang imong gusto gikan niini ug unsa nga badyet ang imong andam nga mamuhunan. Kung makalimtan namo ang OpenSource, aduna nay daghang mga serbisyo ug produkto nga makatabang kanimo sa pagsusi, pag-convert, ug pag-validate. Apan kini mahal, ug usahay mahal kaayo. Alang sa usa ka dako nga kompanya, ang ingon nga mga gasto maagwanta, apan alang sa usa ka pagsugod mahimo silang usa ka dako nga palas-anon.
Tinoa ang hugpong sa mga himan nga imong gamiton sa ulahi. Pananglitan, kung kinahanglan nimo nga magpakita usa ka kontrata, mas dali gamiton ang Swagger 2, nga adunay usa ka matahum nga API, tungod kay sa RAML kinahanglan nimo nga tukuron ug ipadayon ang serbisyo sa imong kaugalingon.
Ang mas daghang mga buluhaton nga imong nabatonan, mas lapad ang panginahanglan alang sa mga himan, ug kini lahi alang sa lainlaing mga plataporma, ug mas maayo nga pamilyar dayon ang imong kaugalingon sa mga magamit nga bersyon aron makahimo usa ka kapilian nga makapamenos sa imong gasto sa umaabot.
Apan angay nga ilhon nga ang tanan nga ekosistema nga naglungtad karon dili hingpit. Busa, kung adunay mga fans sa kompanya nga gusto nga magtrabaho sa RAML tungod kay "kini nagtugot kanimo sa pagpahayag sa mga hunahuna nga mas flexible," o, sa kasukwahi, mas gusto ang Swagger tungod kay "kini mas klaro," mas maayo nga biyaan sila sa pagtrabaho. sa unsa sila Naanad na sila niini ug gusto kini, tungod kay ang mga himan sa bisan unsang mga format nanginahanglan pagbag-o sa usa ka file.
Sama sa alang sa among kasinatian, sa mga mosunud nga mga post kami maghisgot bahin sa kung unsang mga static ug dinamikong mga tseke ang among gihimo base sa among arkitektura sa RAML-Swagger, ingon man kung unsang dokumentasyon ang among nahimo gikan sa mga kontrata, ug kung giunsa kini tanan molihok.
Ang mga rehistradong tiggamit lamang ang makaapil sa survey. , walay sapayan.
Unsa nga pinulongan ang imong gigamit sa pag-annotate sa mga kontrata sa microservice?
-
RAML 0.8
-
RAML 1.0
-
Pag-uyog 2
-
OAS3 (aka)
-
Plano
-
Ang uban pa
-
Dili gamit
100 ka tiggamit ang miboto. 24 ka tiggamit ang nag- abstain.
Source: www.habr.com