In de dynamische wereld van microservices kan alles veranderen: elk onderdeel kan in een andere taal worden herschreven, met gebruikmaking van andere raamwerken en architectuur. Alleen contracten moeten ongewijzigd blijven, zodat er op een permanente basis van buitenaf met de microservice kan worden gecommuniceerd, ongeacht interne metamorfoses. En vandaag zullen we praten over ons probleem bij het kiezen van een formaat voor het beschrijven van contracten en de artefacten delen die we hebben gevonden.
Post voorbereid и
Microdiensten. Bij de ontwikkeling van Acronis Cyber Cloud realiseerden we ons dat we er niet aan konden ontkomen. En het ontwerpen van een microservice is onmogelijk zonder het contract te formaliseren, dat de interface van de microservice vertegenwoordigt.
Maar wanneer een product meer dan één component bevat en contractontwikkeling een reguliere activiteit wordt, kun je niet anders dan nadenken over procesoptimalisatie. Het wordt duidelijk dat de interface (contract) en implementatie (microservice) op elkaar moeten aansluiten, dat verschillende componenten dezelfde dingen op dezelfde manier moeten doen, en dat zonder een gecentraliseerde besluitvorming over al deze beslissingen elk team gedwongen zal worden om besteed steeds opnieuw tijd om ze te bemachtigen.
Amazon-microservicesdiagram van Werner Vogelis, CTO Amazon
Wat is het dilemma? De facto zijn er twee manieren om microservices te gebruiken: HTTP Rest en gRPC van Google. Omdat we niet verstrikt wilden raken in de technologiestapel van Google, kozen we voor HTTP Rest. HTTP REST-contractannotaties worden meestal beschreven in een van de twee formaten: RAML en OAS, voorheen bekend als Swagger. Daarom wordt elk ontwikkelteam geconfronteerd met de noodzaak om een van de standaarden te kiezen. Maar het blijkt dat het maken van deze keuze erg moeilijk kan zijn.
Waarom zijn annotaties nodig?
De annotatie is nodig zodat een externe gebruiker eenvoudig kan achterhalen wat er met uw service kan worden gedaan via de HTTP-interface. Dat wil zeggen, op een basisniveau moet de annotatie op zijn minst een lijst met beschikbare bronnen bevatten, hun HTTP-methoden, verzoekinstanties, een lijst met parameters, een indicatie van de vereiste en ondersteunde headers, evenals retourcodes en antwoordformaten. Een uiterst belangrijk element van de contractannotatie is hun mondelinge beschrijving (“wat gebeurt er als u deze queryparameter aan het verzoek toevoegt?”, “In welk geval wordt code 400 geretourneerd?”)
Als het echter gaat om het ontwikkelen van een groot aantal microservices, wil je extra waarde uit de geschreven annotaties halen. Op basis van RAML/Swagger kunt u bijvoorbeeld zowel client- als servercode genereren in een groot aantal programmeertalen. Je kunt ook automatisch documentatie voor de microservice ontvangen en deze uploaden naar je ontwikkelaarsportal :).
Voorbeeld van een gestructureerde contractbeschrijving
Minder gebruikelijk is de praktijk van het testen van microservices op basis van contractbeschrijvingen. Als u zowel een annotatie als een component heeft geschreven, kunt u een autotest maken die de geschiktheid van de dienst controleert met verschillende soorten invoergegevens. Retourneert de service een responscode die niet in de annotatie wordt beschreven? Zal zij klaarblijkelijk onjuiste gegevens correct kunnen verwerken?
Bovendien maakt een hoogwaardige implementatie van niet alleen de contracten zelf, maar ook de tools voor het visualiseren van annotaties het mogelijk om het werk met de microservice te vereenvoudigen. Dat wil zeggen, als de architect het contract kwalitatief heeft beschreven, op basis daarvan, zullen ontwerpers en ontwikkelaars de dienst in andere producten implementeren zonder extra tijdskosten.
Om extra tools mogelijk te maken, hebben zowel RAML als OAS de mogelijkheid om metadata toe te voegen die niet door de standaard wordt geboden ().
Over het algemeen is de ruimte voor creativiteit bij het gebruik van contracten voor microservices enorm... althans in theorie.
Vergelijking van een egel met een slang
Momenteel is het prioritaire ontwikkelingsgebied bij Acronis de ontwikkeling van het Acronis Cyber Platform. Acronis Cyber Platform is een nieuw integratiepunt van services van derden met Acronis Cyber Cloud en het agentgedeelte. Hoewel we blij waren met onze interne API's die in RAML zijn beschreven, riep de noodzaak om de API te publiceren opnieuw de keuzevraag op: welke annotatiestandaard kunnen we het beste gebruiken voor ons werk?
Aanvankelijk leek het erop dat er twee oplossingen waren: de meest voorkomende ontwikkelingen waren RAML en Swagger (of OAS). Maar feitelijk bleek dat er in ieder geval niet 2 alternatieven zijn, maar 3 of meer.
Aan de ene kant is er RAML - een krachtige en efficiënte taal. Het implementeert hiërarchie en overerving goed, dus dit formaat is geschikter voor grote bedrijven die veel beschrijvingen nodig hebben - dat wil zeggen niet één product, maar veel microservices die gemeenschappelijke delen van contracten hebben - authenticatieschema's, dezelfde gegevenstypen, foutlichamen .
Maar de ontwikkelaar van RAML, Mulesoft, heeft zich aangesloten bij het Open API-consortium, dat zich ontwikkelt . Daarom heeft RAML de ontwikkeling ervan opgeschort. Om je het formaat van het evenement voor te stellen, stel je voor dat de beheerders van de belangrijkste Linux-componenten vertrokken om voor Microsoft te werken. Deze situatie schept de voorwaarden voor het gebruik van Swagger, dat zich dynamisch ontwikkelt en in de nieuwste - derde versie - RAML praktisch inhaalt in termen van flexibiliteit en functionaliteit.
Als niet voor één maar...
Het blijkt dat niet alle open-sourcehulpprogramma's zijn bijgewerkt naar OAS 3.0. Voor microservices in Go zal het meest kritische punt het gebrek aan aanpassing zijn voor de nieuwste versie van de standaard. Het verschil tussen Swagger 2 en Swagger 3 is echter wel . In de derde versie doen de ontwikkelaars bijvoorbeeld het volgende:
- verbeterde beschrijving van authenticatieschema's
- Ondersteuning voor JSON-schema's
- De mogelijkheid om voorbeelden toe te voegen is geüpgraded
De situatie is grappig: bij het kiezen van een standaard moet je RAML, Swagger 2 en Swagger 3 als afzonderlijke alternatieven beschouwen. Alleen Swagger 2 biedt echter goede ondersteuning voor OpenSource-tools. RAML is erg flexibel...en complex, en Swagger 3 wordt slecht ondersteund door de gemeenschap, dus je zult eigen tools of commerciële oplossingen moeten gebruiken, die vaak behoorlijk duur zijn.
Bovendien zitten er veel leuke features in Swagger, zoals een kant-en-klaar portaal , waarop je een annotatie kunt uploaden en de visualisatie ervan kunt krijgen met een gedetailleerde beschrijving, links en verbindingen, dan is er voor de meer fundamentele en minder vriendelijke RAML zo'n mogelijkheid niet. Ja, je kunt naar iets tussen projecten op GitHub zoeken, daar een analoog zoeken en deze zelf implementeren. Hoe dan ook zal iemand de portal moeten onderhouden, wat niet zo handig is voor basisgebruik of testbehoeften. Bovendien is branie meer 'principieel' of liberaler - het kan worden gegenereerd op basis van opmerkingen in de code, wat uiteraard in strijd is met het API First-principe en niet wordt ondersteund door een van de RAML-hulpprogramma's.
Ooit zijn we met RAML gaan werken als een flexibelere taal, waardoor we veel dingen zelf moesten doen. Een van de projecten maakt bijvoorbeeld gebruik van het hulpprogramma in unit-tests, die alleen RAML 0.8 ondersteunen. We moesten dus krukken toevoegen zodat het hulpprogramma RAML versie 1.0 kon 'opeten'.
Moet je kiezen?
Nadat we hadden gewerkt aan het voltooien van het ecosysteem van oplossingen voor RAML, kwamen we tot de conclusie dat we RAML moeten omzetten in Swagger 2 en alle automatisering, verificatie, testen en daaropvolgende optimalisatie daarin moeten uitvoeren. Dit is een goede manier om zowel de flexibiliteit van RAML als de communitytoolingondersteuning van Swagger te benutten.
Om dit probleem op te lossen, zijn er twee OpenSource-tools die contractconversie moeten bieden:
- is een momenteel niet-ondersteund hulpprogramma. Terwijl we ermee werkten, ontdekten we dat het een aantal problemen heeft met complexe RAML's die "verspreid" zijn over een groot aantal bestanden. Dit programma is geschreven in JavaScript en voert een recursieve doorloop van een syntaxisboom uit. Vanwege dynamisch typen wordt het moeilijk om deze code te begrijpen, dus hebben we besloten geen tijd te verspillen aan het schrijven van patches voor een uitstervend hulpprogramma.
- - een tool van hetzelfde bedrijf dat beweert klaar te zijn om van alles en nog wat, en in welke richting dan ook, te converteren. Tot op heden is ondersteuning aangekondigd voor RAML 0.8, RAML 1.0 en Swagger 2.0. Ten tijde van ons onderzoek was het nut echter nog steeds aanwezig vochtig en onbruikbaar. Ontwikkelaars creëren een soort , waardoor ze in de toekomst snel nieuwe standaarden kunnen toevoegen. Maar tot nu toe werkt het gewoon niet.
En dat zijn nog niet alle moeilijkheden die we tegenkwamen. Een van de stappen in onze pijplijn is het verifiëren dat de RAML uit de repository correct is ten opzichte van de specificatie. We hebben verschillende hulpprogramma's geprobeerd. Verrassend genoeg vloekten ze allemaal op verschillende plaatsen en met totaal verschillende slechte woorden over onze annotaties. En niet altijd to the point :).
Uiteindelijk zijn we uitgekomen op een inmiddels verouderd project, dat ook een aantal problemen kent (soms crasht het uit het niets, heeft het problemen bij het werken met reguliere expressies). We vonden dus geen manier om de problemen van validatie en conversie op basis van gratis tools op te lossen, en besloten een commercieel hulpprogramma te gebruiken. In de toekomst, naarmate OpenSource-tools volwassener worden, kan dit probleem gemakkelijker op te lossen zijn. Intussen leken de arbeids- en tijdkosten voor de “afwerking” ons belangrijker dan de kosten van een commerciële dienst.
Conclusie
Na dit alles wilden we onze ervaring delen en opmerken dat voordat u een tool kiest voor het beschrijven van contracten, u duidelijk moet definiëren wat u ervan wilt en welk budget u bereid bent te investeren. Als we OpenSource vergeten, zijn er al een groot aantal diensten en producten die u helpen bij het controleren, converteren en valideren. Maar ze zijn duur, en soms erg duur. Voor een groot bedrijf zijn dergelijke kosten draaglijk, maar voor een startup kunnen ze een grote last worden.
Bepaal de set gereedschappen die u later gaat gebruiken. Als u bijvoorbeeld alleen een contract hoeft weer te geven, is het gemakkelijker om Swagger 2 te gebruiken, dat een prachtige API heeft, omdat u in RAML de service zelf moet bouwen en onderhouden.
Hoe meer taken je hebt, hoe groter de behoefte aan tools zal zijn, en ze zijn verschillend voor verschillende platforms, en het is beter om meteen vertrouwd te raken met de beschikbare versies om een keuze te maken die je kosten in de toekomst tot een minimum beperkt.
Maar het is de moeite waard om te erkennen dat alle ecosystemen die vandaag de dag bestaan onvolmaakt zijn. Daarom, als er fans in het bedrijf zijn die graag in RAML werken omdat 'je je gedachten flexibeler kunt uiten', of, integendeel, de voorkeur geven aan Swagger omdat 'het duidelijker is', kun je ze het beste aan het werk laten. in wat ze zijn Ze zijn eraan gewend en willen het, omdat de tools van elk van de formaten aanpassing met een bestand vereisen.
Wat onze ervaring betreft, zullen we in de volgende berichten praten over welke statische en dynamische controles we uitvoeren op basis van onze RAML-Swagger-architectuur, en welke documentatie we genereren uit contracten, en hoe het allemaal werkt.
Alleen geregistreerde gebruikers kunnen deelnemen aan het onderzoek. , Alsjeblieft.
Welke taal gebruikt u om microservicecontracten te annoteren?
-
RAML 0.8
-
RAML 1.0
-
Zwerver 2
-
OAS3 (ook bekend als)
-
plan
-
Другой
-
Niet gebruiken
100 gebruikers hebben gestemd. 24 gebruikers onthielden zich van stemming.
Bron: www.habr.com