I mikrotjänsternas dynamiska värld kan allt förändras – vilken komponent som helst kan skrivas om på ett annat språk, med hjälp av olika ramverk och arkitektur. Endast kontrakt bör förbli oförändrade så att mikrotjänsten kan interageras utifrån på någon permanent basis, oavsett interna metamorfoser. Och idag kommer vi att prata om vårt problem med att välja ett format för att beskriva kontrakt och dela artefakterna vi hittade.
Inlägg förberett и
Mikrotjänster. När vi utvecklade Acronis Cyber Cloud insåg vi att vi inte kunde undgå dem. Och att designa en mikrotjänst är omöjlig utan att formalisera kontraktet, som representerar mikrotjänstens gränssnitt.
Men när en produkt innehåller mer än en komponent, och kontraktsutveckling blir en vanlig aktivitet, kan man inte låta bli att börja tänka på processoptimering. Det blir uppenbart att gränssnittet (kontraktet) och implementeringen (mikrotjänsten) måste matcha varandra, att olika komponenter måste göra samma saker på samma sätt och att utan ett centraliserat beslutsfattande av alla dessa beslut kommer varje team att tvingas att spendera tid om och om igen för att få dem.
Amazon mikrotjänster diagram från Werner Vogelis, CTO Amazon
Vad är dilemmat? De facto finns det två sätt att interagera med mikrotjänster - HTTP Rest och gRPC från Google. Eftersom vi inte ville fastna i Googles teknikstack valde vi HTTP Rest. HTTP REST-kontraktsanteckningar beskrivs oftast i ett av två format: RAML och OAS, tidigare känt som Swagger.Därför står varje utvecklingsteam inför behovet av att välja en av standarderna. Men som det visar sig kan det vara mycket svårt att göra detta val.
Varför behövs anteckningar?
Anteckningen behövs så att en extern användare enkelt kan ta reda på vad som kan göras med din tjänst genom dess HTTP-gränssnitt. Det vill säga, på en grundläggande nivå måste anteckningen innehålla åtminstone en lista över tillgängliga resurser, deras HTTP-metoder, begärandekroppar, en lista över parametrar, en indikation på de obligatoriska och stödda rubrikerna, samt returkoder och svarsformat. En extremt viktig del av kontraktsanteckningen är deras verbala beskrivning ("vad händer om du lägger till den här frågeparametern i begäran?", "I vilket fall kommer kod 400 att returneras?")
Men när det gäller att utveckla ett stort antal mikrotjänster vill du extrahera ytterligare värde från de skrivna anteckningarna. Till exempel, baserat på RAML/Swagger, kan du generera både klient- och serverkod i ett stort antal programmeringsspråk. Du kan också automatiskt få dokumentation för mikrotjänsten och ladda upp den till din utvecklarportal :).
Exempel på strukturerad avtalsbeskrivning
Mindre vanligt är praxis att testa mikrotjänster baserat på kontraktsbeskrivningar. Om du har skrivit både en anteckning och en komponent kan du skapa ett autotest som kontrollerar tjänstens lämplighet med olika typer av indata. Returnerar tjänsten en svarskod som inte beskrivs i anteckningen? Kommer den att kunna behandla uppenbart felaktiga uppgifter korrekt?
Dessutom gör högkvalitativ implementering av inte bara själva kontrakten utan också verktygen för att visualisera kommentarer det möjligt att förenkla arbetet med mikrotjänsten. Det vill säga, om arkitekten beskrev kontraktet på ett högkvalitativt sätt, baserat på det, kommer designers och utvecklare att implementera tjänsten i andra produkter utan extra tidskostnader.
För att aktivera ytterligare verktyg har både RAML och OAS möjlighet att lägga till metadata som inte tillhandahålls av standarden ().
Generellt sett är utrymmet för kreativitet i att använda kontrakt för mikrotjänster enormt... åtminstone i teorin.
Jämförelse av en igelkott med en orm
För närvarande är det prioriterade utvecklingsområdet hos Acronis utvecklingen av Acronis Cyber Platform. Acronis Cyber Platform är nya integrationspunkter för tredjepartstjänster med Acronis Cyber Cloud och agentdelen. Även om vi var nöjda med våra interna API:er som beskrivs i RAML, väckte behovet av att publicera API:n igen frågan om valet: vilken annoteringsstandard är bäst att använda för vårt arbete?
Till en början verkade det som om det fanns två lösningar - de vanligaste utvecklingarna var RAML och Swagger (eller OAS). Men i själva verket visade det sig att det åtminstone inte finns 2 alternativ, utan 3 eller fler.
Å ena sidan finns RAML - ett kraftfullt och effektivt språk. Den implementerar hierarki och arv väl, så det här formatet är mer lämpligt för stora företag som behöver många beskrivningar - det vill säga inte en produkt, utan många mikrotjänster som har gemensamma delar av kontrakt - autentiseringsscheman, samma datatyper, felkroppar .
Men utvecklaren av RAML, Mulesoft, har gått med i Open API-konsortiet, som utvecklar . Därför avbröt RAML sin utveckling. För att föreställa dig formatet på evenemanget, föreställ dig att underhållarna av de viktigaste Linux-komponenterna lämnade för att arbeta för Microsoft. Denna situation skapar förutsättningar för att använda Swagger, som utvecklas dynamiskt och i den senaste - tredje versionen - praktiskt taget kommer ikapp RAML vad gäller flexibilitet och funktionalitet.
Om inte för en men...
Som det visar sig har inte alla verktyg med öppen källkod uppdaterats till OAS 3.0. För mikrotjänster i Go kommer det mest kritiska att vara bristen på anpassning för den senaste versionen av standarden. Men skillnaden mellan Swagger 2 och Swagger 3 är . Till exempel, i den tredje versionen:
- förbättrad beskrivning av autentiseringssystem
- JSON-schemastöd
- uppgraderat möjligheten att lägga till exempel
Situationen är rolig: när du väljer en standard måste du överväga RAML, Swagger 2 och Swagger 3 som separata alternativ. Det är dock bara Swagger 2 som har bra stöd för OpenSource-verktyg. RAML är mycket flexibelt...och komplext, och Swagger 3 stöds dåligt av samhället, så du måste använda proprietära verktyg eller kommersiella lösningar, som brukar vara ganska dyra.
Dessutom, om det finns många trevliga funktioner i Swagger, till exempel en färdig portal , där du kan ladda upp en anteckning och få dess visualisering med en detaljerad beskrivning, länkar och anslutningar, så för den mer grundläggande och mindre vänliga RAML finns det ingen sådan möjlighet. Ja, du kan söka efter något bland projekt på GitHub, hitta en analog där och distribuera den själv. Men i alla fall kommer någon att behöva underhålla portalen, vilket inte är så bekvämt för grundläggande användning eller testbehov. Dessutom är swagger mer "principlös" eller mer liberal - den kan genereras från kommentarer i koden, vilket naturligtvis går emot API:s första princip och inte stöds av något av RAML-verktygen.
En gång i tiden började vi arbeta med RAML som ett mer flexibelt språk, och som ett resultat var vi tvungna att göra många saker själva. Till exempel använder ett av projekten verktyget i enhetstester, som endast stöder RAML 0.8. Så vi var tvungna att lägga till kryckor så att verktyget kunde "äta" RAML version 1.0.
Behöver du välja?
Efter att ha arbetat med att färdigställa ekosystemet av lösningar för RAML, kom vi till slutsatsen att vi måste konvertera RAML till Swagger 2 och utföra all automatisering, verifiering, testning och efterföljande optimering i den. Detta är ett bra sätt att dra nytta av både flexibiliteten hos RAML och communityts verktygsstöd från Swagger.
För att lösa detta problem finns det två OpenSource-verktyg som ska ge kontraktskonvertering:
- är ett verktyg som för närvarande inte stöds. När vi arbetade med det upptäckte vi att det har ett antal problem med komplexa RAML:er som är "utspridda" över ett stort antal filer. Detta program är skrivet i JavaScript och utför en rekursiv genomgång av ett syntaxträd. På grund av dynamisk typning blir det svårt att förstå den här koden, så vi bestämde oss för att inte slösa tid på att skriva patchar för ett döende verktyg.
- - ett verktyg från samma företag som säger sig vara redo att konvertera allt och allt, och åt alla håll. Hittills har stöd aviserats för RAML 0.8, RAML 1.0 och Swagger 2.0. Men vid tidpunkten för vår forskning var nyttan fortfarande kvar fuktig och oanvändbar. Utvecklare skapar ett slags , vilket gör att de snabbt kan lägga till nya standarder i framtiden. Men än så länge fungerar det bara inte.
Och det är inte alla svårigheter vi stötte på. Ett av stegen i vår pipeline är att verifiera att RAML från förvaret är korrekt i förhållande till specifikationen. Vi provade flera verktyg. Överraskande nog svor de alla på våra kommentarer på olika ställen och med helt olika dåliga ord. Och inte alltid rakt på sak :).
Till slut kom vi på ett numera föråldrat projekt, som också har ett antal problem (ibland kraschar det ur det blå, har problem när man arbetar med reguljära uttryck). Således hittade vi inte ett sätt att lösa problemen med validering och konvertering baserat på gratisverktyg, och beslutade att använda ett kommersiellt verktyg. I framtiden, när OpenSource-verktygen blir mer mogna, kan detta problem bli lättare att lösa. Under tiden verkade arbets- och tidskostnaderna för att "efterbehandla" oss mer betydande än kostnaden för en kommersiell tjänst.
Slutsats
Efter allt detta ville vi dela med oss av vår erfarenhet och notera att innan du väljer ett verktyg för att beskriva kontrakt måste du tydligt definiera vad du vill ha av det och vilken budget du är villig att investera. Om vi glömmer OpenSource finns det redan ett stort antal tjänster och produkter som hjälper dig att kontrollera, konvertera och validera. Men de är dyra, och ibland väldigt dyra. För ett stort företag är sådana kostnader acceptabelt, men för en start kan de bli en stor börda.
Bestäm uppsättningen verktyg som du kommer att använda senare. Om du till exempel bara behöver visa ett kontrakt blir det lättare att använda Swagger 2, som har ett vackert API, eftersom du i RAML måste bygga och underhålla tjänsten själv.
Ju fler uppgifter du har, desto bredare blir behovet av verktyg, och de är olika för olika plattformar, och det är bättre att omedelbart bekanta dig med de tillgängliga versionerna för att göra ett val som minimerar dina kostnader i framtiden.
Men det är värt att inse att alla ekosystem som finns idag är ofullkomliga. Därför, om det finns fans i företaget som gillar att arbeta i RAML för att "det låter dig uttrycka tankar mer flexibelt", eller tvärtom, föredrar Swagger för att "det är tydligare", är det bäst att låta dem arbeta i vad de är De är vana vid det och vill ha det, eftersom verktygen i något av formaten kräver modifiering med en fil.
När det gäller vår erfarenhet kommer vi i följande inlägg att prata om vilka statiska och dynamiska kontroller vi utför baserat på vår RAML-Swagger-arkitektur, samt vilken dokumentation vi genererar från kontrakt, och hur det hela fungerar.
Endast registrerade användare kan delta i undersökningen. , Snälla du.
Vilket språk använder du för att kommentera mikroservicekontrakt?
-
RAML 0.8
-
RAML 1.0
-
Swagger 2
-
OAS3 (aka)
-
Blueprint
-
Andra
-
Använder inte
100 användare röstade. 24 användare avstod från att rösta.
Källa: will.com