Yn 'e dynamyske wrâld fan mikrotsjinsten kin alles feroarje - elke komponint kin opnij skreaun wurde yn in oare taal, mei ferskate kaders en arsjitektuer. Allinich kontrakten moatte ûnferoare bliuwe, sadat de mikrotsjinst op ien of oare permaninte basis fan bûten ynteraksje kin wurde, nettsjinsteande ynterne metamorfoazen. En hjoed sille wy prate oer ús probleem fan it kiezen fan in formaat foar it beskriuwen fan kontrakten en diele de artefakten dy't wy fûnen.
Post taret и
Mikrotsjinsten. By it ûntwikkeljen fan Acronis Cyber Cloud realisearren wy dat wy har net koene ûntkomme. En it ûntwerpen fan in mikrotsjinst is ûnmooglik sûnder it kontrakt te formalisearjen, dat de ynterface fan 'e mikrotsjinst fertsjintwurdiget.
Mar as in produkt mear as ien komponint befettet, en kontraktûntwikkeling wurdt in reguliere aktiviteit, kinne jo net helpe om te begjinnen nei te tinken oer prosesoptimalisaasje. It wurdt dúdlik dat de ynterface (kontrakt) en ymplemintaasje (mikroservice) mei-inoar oerienkomme moatte, dat ferskate komponinten deselde dingen op deselde wize moatte dwaan, en dat sûnder in sintralisearre beslútfoarming fan al dizze besluten elk team twongen wurde om besteegje hieltyd wer tiid om se te krijen.
Amazon microservices diagram fan Werner Vogelis, CTO Amazon
Wat is it dilemma? De facto binne d'r twa manieren om mikrotsjinsten te ynteraksje - HTTP Rest en gRPC fan Google. Net wollen wurde fongen yn Google syn technology stack, wy keas HTTP Rest. HTTP REST kontraktannotaasjes wurde meastentiids beskreaun yn ien fan twa formaten: RAML en OAS, eartiids bekend as Swagger. Dêrom wurdt elk ûntwikkelingsteam konfrontearre mei de needsaak om ien fan 'e noarmen te kiezen. Mar sa docht bliken, it meitsjen fan dizze kar kin hiel lestich.
Wêrom binne annotaasjes nedich?
De annotaasje is nedich sadat in eksterne brûker maklik kin útfine wat kin dien wurde mei jo tsjinst fia syn HTTP-ynterface. Dat is, op in basisnivo moat de annotaasje op syn minst in list mei beskikbere boarnen befetsje, har HTTP-metoaden, oanfraachorganen, in list fan parameters, in yndikaasje fan 'e fereaske en stipe kopteksten, lykas weromkoades en antwurdformaten. In ekstreem wichtich elemint fan 'e kontraktannotaasje is har ferbale beskriuwing ("wat sil barre as jo dizze queryparameter tafoegje oan it fersyk?", "Yn hokker gefal sil koade 400 weromjûn wurde?")
As it lykwols giet om it ûntwikkeljen fan in grut oantal mikrotsjinsten, wolle jo ekstra wearde ekstrahearje út 'e skreaune annotaasjes. Bygelyks, basearre op RAML / Swagger, kinne jo sawol client- as serverkoade generearje yn in grut oantal programmeartalen. Jo kinne ek automatysk dokumintaasje ûntfange foar de mikrotsjinst en it uploade nei jo ûntwikkelderportaal :).
Foarbyld fan in strukturearre kontrakt beskriuwing
Minder gewoan is de praktyk fan testen fan mikrotsjinsten basearre op kontraktbeskriuwingen. As jo sawol in annotaasje as in komponint hawwe skreaun, dan kinne jo in autotest meitsje dy't de adekwaatheid fan 'e tsjinst kontrolearret mei ferskate soarten ynfiergegevens. Jout de tsjinst in antwurdkoade werom dy't net is beskreaun yn 'e annotaasje? Sil it yn steat wêze om fansels ferkearde gegevens korrekt te ferwurkjen?
Boppedat makket de ymplemintaasje fan hege kwaliteit fan net allinich de kontrakten sels, mar ek de ark foar it visualisearjen fan annotaasjes it mooglik om it wurk mei de mikrotsjinst te ferienfâldigjen. Dat is, as de arsjitekt kwalitatyf beskreaun it kontrakt, basearre op it, ûntwerpers en ûntwikkelders sille útfiere de tsjinst yn oare produkten sûnder ekstra tiid kosten.
Om ekstra ark yn te skeakeljen, hawwe sawol RAML as OAS de mooglikheid om metadata ta te foegjen dy't net foarsjoen binne troch de standert ().
Yn 't algemien is de romte foar kreativiteit by it brûken fan kontrakten foar mikrotsjinsten enoarm ... teminsten yn teory.
Fergeliking fan in egel mei in slang
Op it stuit is it prioritêre ûntwikkelingsgebiet by Acronis de ûntwikkeling fan it Acronis Cyber Platform. Acronis Cyber Platform is nije punten fan yntegraasje fan tsjinsten fan tredden mei Acronis Cyber Cloud en it agentdiel. Hoewol wy bliid wiene mei ús ynterne API's beskreaun yn RAML, brocht de needsaak om de API te publisearjen de fraach fan kar op: hokker annotaasjestandert is it bêste om te brûken foar ús wurk?
Yn earste ynstânsje like it dat d'r twa oplossingen wiene - de meast foarkommende ûntjouwings wiene RAML en Swagger (of OAS). Mar yn feite die bliken dat der op syn minst net 2 alternativen, mar 3 of mear.
Oan 'e iene kant is d'r RAML - in krêftige en effisjinte taal. It ymplementearret hiërargy en erfenis goed, sadat dit formaat mear geskikt is foar grutte bedriuwen dy't in protte beskriuwings nedich binne - dat is net ien produkt, mar in protte mikrotsjinsten dy't mienskiplike dielen fan kontrakten hawwe - autentikaasjeskema's, deselde gegevenstypen, flaterorganen .
Mar de ûntwikkelder fan RAML, Mulesoft, hat meidien oan it Open API-konsortium, dat ûntwikkelet . Dêrom stoppe RAML syn ûntwikkeling. Om it formaat fan it evenemint foar te stellen, stel jo foar dat de ûnderhâlders fan 'e wichtichste Linux-komponinten oerbleaun binne om te wurkjen foar Microsoft. Dizze situaasje skept de betingsten foar it brûken fan Swagger, dy't dynamysk ûntwikkelet en yn 'e lêste - tredde ferzje - praktysk ynhellet mei RAML yn termen fan fleksibiliteit en funksjonaliteit.
As net foar ien ding ...
Sa't bliken docht, binne net alle iepen boarne-nutsbedriuwen bywurke nei OAS 3.0. Foar mikrotsjinsten yn Go sil it meast krityske ding it gebrek oan oanpassing wêze foar de lêste ferzje fan de standert. It ferskil tusken Swagger 2 en Swagger 3 is lykwols . Bygelyks, yn 'e tredde ferzje de ûntwikkelders:
- ferbettere beskriuwing fan autentikaasjeskema's
- JSON Schema stipe
- opwurdearre de mooglikheid om te foegjen foarbylden
De situaasje is grappich: as jo in standert kieze, moatte jo RAML, Swagger 2 en Swagger 3 beskôgje as aparte alternativen. Allinich Swagger 2 hat lykwols goede stipe foar OpenSource-ark. RAML is heul fleksibel ... en kompleks, en Swagger 3 wurdt min stipe troch de mienskip, dus jo moatte proprietêre ark of kommersjele oplossings brûke, dy't de neiging hawwe om frij djoer te wêzen.
Boppedat, as der in protte moaie funksjes yn Swagger, lykas in ready-made portal , wêrop jo in annotaasje kinne uploade en syn fisualisaasje krije mei in detaillearre beskriuwing, keppelings en ferbinings, dan is foar de mear fûnemintele en minder freonlike RAML sa'n kâns net. Ja, jo kinne wat sykje ûnder projekten op GitHub, dêr in analoog fine en it sels ynsette. Lykwols, yn alle gefallen, immen sil moatte ûnderhâlde it portaal, dat is net sa handich foar basis gebrûk of teste behoeften. Derneist is swagger mear "prinsipeloos", of liberaaler - it kin wurde generearre út opmerkingen yn 'e koade, dy't, fansels, tsjin it API-earste prinsipe yn giet en net wurdt stipe troch ien fan' e RAML-nutsbedriuwen.
Eartiids begûnen wy mei RAML te wurkjen as in fleksibeler taal, en dêrtroch moasten wy in soad dingen sels dwaan. Bygelyks, ien fan 'e projekten brûkt it nut yn unit tests, dy't allinnich stipet RAML 0.8. Dat wy moasten krukken tafoegje sadat it hulpprogramma RAML ferzje 1.0 koe "ite".
Moatte jo kieze?
Nei't wy wurke hawwe oan it foltôgjen fan it ekosysteem fan oplossingen foar RAML, kamen wy ta de konklúzje dat wy RAML moatte konvertearje yn Swagger 2 en alle automatisearring, ferifikaasje, testen en folgjende optimalisaasje dêryn útfiere. Dit is in goede manier om sawol de fleksibiliteit fan RAML as de stipe foar community-ark fan Swagger te benutten.
Om dit probleem op te lossen binne d'r twa OpenSource-ark dy't kontraktkonverzje moatte leverje:
- is in op it stuit net-stipe hulpprogramma. Wylst wy wurkje mei it, wy ûntdutsen dat it hat in oantal problemen mei komplekse RAMLs dy't "ferspraat" oer in grut oantal triemmen. Dit programma is skreaun yn JavaSkript en fiert in rekursive trochgong fan in syntaksisbeam. Troch dynamysk typen wurdt it dreech om dizze koade te begripen, dus wy besletten gjin tiid te fergrieme mei it skriuwen fan patches foar in stjerrende nut.
- - in ark fan itselde bedriuw dat beweart ree te wêzen om alles en alles te konvertearjen, en yn elke rjochting. Oant no ta is stipe oankundige foar RAML 0.8, RAML 1.0 en Swagger 2.0. Yn 'e tiid fan ús ûndersyk wie it nut lykwols noch fochtich en ûnbrûkber. Untwikkelders meitsje in soarte fan , wêrtroch't se yn 'e takomst fluch nije noarmen kinne tafoegje. Mar oant no ta wurket it gewoan net.
En dat binne net alle swierrichheden dy't wy tsjinkamen. Ien fan 'e stappen yn ús pipeline is om te kontrolearjen dat de RAML fan it repository korrekt is relatyf oan de spesifikaasje. Wy hawwe ferskate nutsbedriuwen besocht. Ferrassend, se swarden allegearre op ferskillende plakken op ús annotaasjes en mei folslein oare minne wurden. En net altyd nei it punt :).
Uteinlik hawwe wy fêstlein op in no ferâldere projekt, dat hat ek in oantal problemen (soms crasht it út 'e blau, hat problemen by it wurkjen mei reguliere útdrukkingen). Sa hawwe wy gjin manier fûn om de problemen fan falidaasje en konverzje op te lossen basearre op fergese ark, en besletten om in kommersjeel nut te brûken. Yn 'e takomst, as OpenSource-ark folwoeksener wurde, kin dit probleem makliker wurde om op te lossen. Yn 'e tuskentiid, de arbeid en tiid kosten foar "finishing" like ús wichtiger as de kosten fan in kommersjele tsjinst.
konklúzje
Nei dit alles woene wy ús ûnderfining diele en konstatearje dat foardat jo in ark kieze foar it beskriuwen fan kontrakten, jo moatte dúdlik definiearje wat jo derfan wolle en hokker budzjet jo ree binne om te ynvestearjen. As wy OpenSource ferjitte, binne d'r al in grut oantal tsjinsten en produkten dy't jo sille helpe te kontrolearjen, konvertearje en falidearje. Mar se binne djoer, en soms hiel djoer. Foar in grut bedriuw binne sokke kosten tolerabel, mar foar in opstart kinne se in grutte lêst wurde.
Bepaal de set ark dy't jo letter sille brûke. Bygelyks, as jo gewoan in kontrakt werjaan moatte, sil it makliker wêze om Swagger 2 te brûken, dy't in prachtige API hat, om't jo yn RAML de tsjinst sels bouwe en ûnderhâlde moatte.
Hoe mear taken jo hawwe, hoe breder it ferlet fan ark sil wêze, en se binne oars foar ferskate platfoarms, en it is better om jo daliks bekend te meitsjen mei de beskikbere ferzjes om in kar te meitsjen dy't jo kosten yn 'e takomst minimalisearje.
Mar it is it wurdich te erkennen dat alle ekosystemen dy't hjoeddedei besteane, ûnfolslein binne. Dêrom, as d'r fans yn it bedriuw binne dy't graach yn RAML wurkje, om't "it jo tinzen fleksibeler kinne útdrukke," of, krekt oarsom, Swagger leaver hawwe, om't "it dúdliker is", is it it bêste om se oan it wurk te litten yn wat se binne.
Wat ús ûnderfining oangiet, sille wy yn 'e folgjende berjochten prate oer hokker statyske en dynamyske kontrôles wy fiere op basis fan ús RAML-Swagger-arsjitektuer, lykas hokker dokumintaasje wy generearje út kontrakten, en hoe't it allegear wurket.
Allinnich registrearre brûkers kinne meidwaan oan 'e enkête. , asjebleaft.
Hokker taal brûke jo om mikroservicekontrakten te annotearjen?
-
RAML 0.8
-
RAML 1.0
-
Wurger 2
-
OAS3 (aka)
-
Blauwdruk
-
Oar
-
Net brûke
100 brûkers stimden. 24 brûkers ûntholden har.
Boarne: www.habr.com