In die dinamiese wêreld van mikrodienste kan enigiets verander - enige komponent kan in 'n ander taal herskryf word, deur verskillende raamwerke en argitektuur te gebruik. Slegs kontrakte moet onveranderd bly sodat daar op 'n permanente basis met die mikrodiens van buite af interaksie kan word, ongeag interne metamorfoses. En vandag sal ons praat oor ons probleem met die keuse van 'n formaat vir die beskrywing van kontrakte en deel die artefakte wat ons gevind het.
Pos voorberei и
Mikrodienste. Toe ons Acronis Cyber Cloud ontwikkel het, het ons besef dat ons hulle nie kon ontsnap nie. En die ontwerp van 'n mikrodiens is onmoontlik sonder om die kontrak te formaliseer, wat die koppelvlak van die mikrodiens verteenwoordig.
Maar wanneer 'n produk meer as een komponent bevat, en kontrakontwikkeling 'n gereelde aktiwiteit word, kan jy nie anders as om aan prosesoptimering te begin dink nie. Dit word duidelik dat die koppelvlak (kontrak) en implementering (mikrodiens) by mekaar moet pas, dat verskillende komponente dieselfde dinge op dieselfde manier moet doen, en dat sonder 'n gesentraliseerde besluitneming van al hierdie besluite, elke span gedwing sal word om spandeer keer op keer tyd om hulle te kry.
Amazon mikrodienste diagram van Werner Vogelis, uitvoerende hoof van Amazon
Wat is die dilemma? De facto is daar twee maniere om interaksie met mikrodienste te hê - HTTP Rest en gRPC van Google. Omdat ons nie in Google se tegnologiestapel vasgevang wil raak nie, het ons HTTP Rest gekies. HTTP REST-kontrakaantekeninge word meestal in een van twee formate beskryf: RAML en OAS, voorheen bekend as Swagger.Daarom word elke ontwikkelingspan gekonfronteer met die behoefte om een van die standaarde te kies. Maar soos dit blyk, kan dit baie moeilik wees om hierdie keuse te maak.
Hoekom is aantekeninge nodig?
Die aantekening is nodig sodat 'n eksterne gebruiker maklik kan uitvind wat met jou diens gedoen kan word deur sy HTTP-koppelvlak. Dit wil sê, op 'n basiese vlak moet die annotasie ten minste 'n lys van beskikbare bronne, hul HTTP-metodes, versoekliggame, 'n lys van parameters, 'n aanduiding van die vereiste en ondersteunde opskrifte bevat, sowel as terugstuurkodes en antwoordformate. 'n Uiters belangrike element van die kontrakaantekening is hul verbale beskrywing ("wat sal gebeur as jy hierdie navraagparameter by die versoek voeg?", "In watter geval sal kode 400 teruggestuur word?")
As dit egter by die ontwikkeling van 'n groot aantal mikrodienste kom, wil u bykomende waarde uit die geskrewe aantekeninge onttrek. Byvoorbeeld, gebaseer op RAML/Swagger, kan jy beide kliënt- en bedienerkode genereer in 'n groot aantal programmeertale. Jy kan ook outomaties dokumentasie vir die mikrodiens ontvang en dit na jou ontwikkelaarportaal oplaai :).
Voorbeeld van 'n gestruktureerde kontrakbeskrywing
Minder algemeen is die praktyk om mikrodienste op grond van kontrakbeskrywings te toets. As jy beide 'n aantekening en 'n komponent geskryf het, kan jy 'n outotoets skep wat die toereikendheid van die diens met verskillende tipes invoerdata nagaan. Gee die diens 'n antwoordkode terug wat nie in die aantekening beskryf word nie? Sal dit klaarblyklik verkeerde data korrek kan verwerk?
Boonop maak hoëgehalte-implementering van nie net die kontrakte self nie, maar ook die gereedskap vir die visualisering van aantekeninge dit moontlik om die werk met die mikrodiens te vereenvoudig. Dit wil sê, as die argitek die kontrak kwalitatief beskryf, op grond daarvan, sal ontwerpers en ontwikkelaars die diens in ander produkte implementeer sonder bykomende tydskoste.
Om bykomende nutsgoed te aktiveer, het beide RAML en OAS die vermoë om metadata by te voeg waarvoor die standaard nie voorsiening maak nie ().
Oor die algemeen is die ruimte vir kreatiwiteit in die gebruik van kontrakte vir mikrodienste groot ... ten minste in teorie.
Vergelyking van 'n krimpvarkie met 'n slang
Tans is die prioriteitsontwikkelingsarea by Acronis die ontwikkeling van die Acronis Cyber Platform. Acronis Cyber Platform is nuwe punte van integrasie van derdeparty-dienste met Acronis Cyber Cloud en die agent-deel. Alhoewel ons tevrede was met ons interne API's wat in RAML beskryf word, het die behoefte om die API te publiseer weer die vraag na keuse laat ontstaan: watter annotasiestandaard is die beste om vir ons werk te gebruik?
Aanvanklik het dit gelyk of daar twee oplossings was – die mees algemene ontwikkelings was RAML en Swagger (of OAS). Maar eintlik het dit geblyk dat daar ten minste nie 2 alternatiewe is nie, maar 3 of meer.
Aan die een kant is daar RAML - 'n kragtige en doeltreffende taal. Dit implementeer hiërargie en oorerwing goed, so hierdie formaat is meer geskik vir groot maatskappye wat baie beskrywings benodig - dit wil sê nie een produk nie, maar baie mikrodienste wat gemeenskaplike dele van kontrakte het - verifikasieskemas, dieselfde datatipes, foutliggame .
Maar die ontwikkelaar van RAML, Mulesoft, het by die Open API-konsortium aangesluit, wat besig is om te ontwikkel . Daarom het RAML sy ontwikkeling opgeskort. Om die formaat van die geleentheid voor te stel, stel jou voor dat die instandhouers van die hoof Linux-komponente weg is om vir Microsoft te werk. Hierdie situasie skep die voorvereistes vir die gebruik van Swagger, wat dinamies ontwikkel en in die jongste - derde weergawe - feitlik inhaal met RAML in terme van buigsaamheid en funksionaliteit.
As nie vir een ding nie...
Soos dit blyk, is nie alle oopbronhulpprogramme opgedateer na OAS 3.0 nie. Vir mikrodienste in Go is die gebrek aan aanpassing die mees kritieke ding vir die nuutste weergawe van die standaard. Die verskil tussen Swagger 2 en Swagger 3 is egter . Byvoorbeeld, in die derde weergawe die ontwikkelaars:
- verbeterde beskrywing van stawingskemas
- JSON Skema ondersteuning
- die vermoë om voorbeelde by te voeg, opgegradeer
Die situasie is snaaks: wanneer jy 'n standaard kies, moet jy RAML, Swagger 2 en Swagger 3 as aparte alternatiewe oorweeg. Slegs Swagger 2 het egter goeie ondersteuning vir OpenSource-nutsgoed. RAML is baie buigsaam ... en kompleks, en Swagger 3 word swak deur die gemeenskap ondersteun, so jy sal eie gereedskap of kommersiële oplossings moet gebruik, wat geneig is om redelik duur te wees.
Verder, as daar baie lekker funksies in Swagger is, soos 'n klaargemaakte portaal , waarop jy 'n aantekening kan oplaai en die visualisering daarvan kan kry met 'n gedetailleerde beskrywing, skakels en verbindings, dan is daar vir die meer fundamentele en minder vriendelike RAML nie so 'n geleentheid nie. Ja, jy kan iets tussen projekte op GitHub soek, 'n analoog daar vind en dit self ontplooi. Iemand sal egter in elk geval die portaal moet onderhou, wat nie so gerieflik is vir basiese gebruik of toetsbehoeftes nie. Boonop is swagger meer "beginselloos", of meer liberaal - dit kan gegenereer word uit opmerkings in die kode, wat natuurlik in stryd is met die API-eerste beginsel en nie deur enige van die RAML-nutsprogramme ondersteun word nie.
Ons het op 'n tyd met RAML as 'n meer buigsame taal begin werk, en gevolglik moes ons baie dinge self doen. Byvoorbeeld, een van die projekte gebruik die hulpprogram in eenheidstoetse, wat slegs RAML 0.8 ondersteun. Ons moes dus krukke byvoeg sodat die hulpprogram RAML weergawe 1.0 kon "eet".
Moet jy kies?
Nadat ons gewerk het aan die voltooiing van die ekosisteem van oplossings vir RAML, het ons tot die gevolgtrekking gekom dat ons RAML in Swagger 2 moet omskakel en al die outomatisering, verifikasie, toetsing en daaropvolgende optimalisering daarin moet uitvoer. Dit is 'n goeie manier om beide die buigsaamheid van RAML en die gemeenskapswerktuigondersteuning van Swagger te benut.
Om hierdie probleem op te los, is daar twee OpenSource-instrumente wat kontrakomskakeling moet verskaf:
- is 'n hulpprogram wat tans nie ondersteun word nie. Terwyl ons daarmee gewerk het, het ons ontdek dat dit 'n aantal probleme het met komplekse RAML's wat oor 'n groot aantal lêers "verspreid" is. Hierdie program is in JavaScript geskryf en voer 'n rekursiewe deurkruising van 'n sintaksboom uit. As gevolg van dinamiese tik, word dit moeilik om hierdie kode te verstaan, so ons het besluit om nie tyd te mors om pleisters vir 'n sterwende nut te skryf nie.
- - 'n instrument van dieselfde maatskappy wat beweer dat dit gereed is om enigiets en alles te omskep, en in enige rigting. Tot op hede is ondersteuning aangekondig vir RAML 0.8, RAML 1.0 en Swagger 2.0. Ten tyde van ons navorsing was die nut egter nog steeds klam en onbruikbaar. Ontwikkelaars skep 'n soort van , wat hulle in staat stel om vinnig nuwe standaarde in die toekoms by te voeg. Maar tot dusver werk dit net nie.
En dit is nie al die probleme wat ons teëgekom het nie. Een van die stappe in ons pyplyn is om te verifieer dat die RAML vanaf die bewaarplek korrek is relatief tot die spesifikasie. Ons het verskeie nutsprogramme probeer. Verbasend genoeg het hulle almal op verskillende plekke en met heeltemal verskillende slegte woorde op ons aantekeninge gevloek. En nie altyd tot die punt nie :).
Op die ou end het ons besluit op 'n nou verouderde projek, wat ook 'n aantal probleme het (soms val dit uit die bloute in, het probleme wanneer daar met gewone uitdrukkings gewerk word). Ons het dus nie 'n manier gevind om die probleme van validering en omskakeling op grond van gratis gereedskap op te los nie, en het besluit om 'n kommersiële nutsprogram te gebruik. In die toekoms, soos OpenSource-nutsmiddels meer volwasse word, kan hierdie probleem makliker word om op te los. Intussen het die arbeids- en tydkoste vir "afwerking" vir ons meer betekenisvol gelyk as die koste van 'n kommersiële diens.
Gevolgtrekking
Na dit alles wou ons ons ervaring deel en daarop let dat voordat u 'n instrument kies om kontrakte te beskryf, u duidelik moet definieer wat u daaruit wil hê en watter begroting u bereid is om te belê. As ons van OpenSource vergeet, is daar reeds 'n groot aantal dienste en produkte wat jou sal help om na te gaan, om te skakel en te valideer. Maar hulle is duur, en soms baie duur. Vir 'n groot maatskappy is sulke kostes draaglik, maar vir 'n begin kan dit 'n groot las word.
Bepaal die stel gereedskap wat jy later sal gebruik. As jy byvoorbeeld net 'n kontrak moet vertoon, sal dit makliker wees om Swagger 2 te gebruik, wat 'n pragtige API het, want in RAML sal jy self die diens moet bou en in stand hou.
Hoe meer take jy het, hoe wyer sal die behoefte aan gereedskap wees, en hulle verskil vir verskillende platforms, en dit is beter om jouself dadelik vertroud te maak met die beskikbare weergawes om 'n keuse te maak wat jou koste in die toekoms tot die minimum beperk.
Maar dit is die moeite werd om te erken dat alle ekosisteme wat vandag bestaan, onvolmaak is. Daarom, as daar aanhangers in die maatskappy is wat daarvan hou om in RAML te werk omdat "dit jou toelaat om gedagtes meer buigsaam uit te druk," of, inteendeel, Swagger verkies omdat "dit duideliker is", is dit die beste om hulle te laat werk in wat hulle is Hulle is gewoond daaraan en wil dit hê, want die gereedskap van enige van die formate vereis wysiging met 'n lêer.
Wat ons ervaring betref, sal ons in die volgende plasings praat oor watter statiese en dinamiese kontroles ons uitvoer op grond van ons RAML-Swagger-argitektuur, sowel as watter dokumentasie ons uit kontrakte genereer, en hoe dit alles werk.
Slegs geregistreerde gebruikers kan aan die opname deelneem. , asseblief.
Watter taal gebruik jy om mikrodienskontrakte aan te teken?
-
RAML 0.8
-
RAML 1.0
-
Swanger 2
-
OAS3 (ook bekend as)
-
Blueprint
-
Ander
-
Gebruik nie
100 gebruikers het gestem. 24 gebruikers het buite stemming gebly.
Bron: will.com