I den dynamiske verdenen av mikrotjenester kan alt endres – enhver komponent kan skrives om på et annet språk, ved å bruke forskjellige rammer og arkitektur. Kun kontrakter bør forbli uendret slik at mikrotjenesten kan samhandles med fra utsiden på en eller annen permanent basis, uavhengig av interne metamorfoser. Og i dag skal vi snakke om problemet vårt med å velge et format for å beskrive kontrakter og dele artefaktene vi fant.
Post klargjort и
Mikrotjenester. Da vi utviklet Acronis Cyber Cloud, innså vi at vi ikke kunne unnslippe dem. Og å designe en mikrotjeneste er umulig uten å formalisere kontrakten, som representerer grensesnittet til mikrotjenesten.
Men når et produkt inneholder mer enn én komponent, og kontraktsutvikling blir en vanlig aktivitet, kan du ikke unngå å begynne å tenke på prosessoptimalisering. Det blir åpenbart at grensesnittet (kontrakten) og implementeringen (mikrotjenesten) må matche hverandre, at ulike komponenter må gjøre de samme tingene på samme måte, og at uten en sentralisert beslutningstaking av alle disse beslutningene, vil hvert team bli tvunget til å bruke tid igjen og igjen for å få dem.
Amazon mikrotjenester diagram fra Werner Vogelis, CTO Amazon
Hva er dilemmaet? De facto er det to måter å samhandle med mikrotjenester – HTTP Rest og gRPC fra Google. Da vi ikke ønsket å bli fanget opp i Googles teknologistabel, valgte vi HTTP Rest. HTTP REST-kontraktkommentarer er oftest beskrevet i ett av to formater: RAML og OAS, tidligere kjent som Swagger.Derfor står hvert utviklingsteam overfor behovet for å velge en av standardene. Men som det viser seg, kan det være veldig vanskelig å ta dette valget.
Hvorfor er det nødvendig med merknader?
Merknaden er nødvendig slik at en ekstern bruker enkelt kan finne ut hva som kan gjøres med tjenesten din gjennom HTTP-grensesnittet. Det vil si at på et grunnleggende nivå må merknaden minst inneholde en liste over tilgjengelige ressurser, deres HTTP-metoder, forespørselsorganer, en liste over parametere, en indikasjon på nødvendige og støttede overskrifter, samt returkoder og svarformater. Et ekstremt viktig element i kontraktsanmerkningen er deres verbale beskrivelse ("hva vil skje hvis du legger til denne spørringsparameteren i forespørselen?", "I hvilket tilfelle vil kode 400 bli returnert?")
Men når det gjelder å utvikle et stort antall mikrotjenester, ønsker du å trekke ut ekstra verdi fra de skriftlige kommentarene. For eksempel, basert på RAML/Swagger, kan du generere både klient- og serverkode i et stort antall programmeringsspråk. Du kan også automatisk motta dokumentasjon for mikrotjenesten og laste den opp til utviklerportalen din :).
Eksempel på strukturert kontraktsbeskrivelse
Mindre vanlig er praksisen med å teste mikrotjenester basert på kontraktsbeskrivelser. Hvis du har skrevet både en merknad og en komponent, kan du lage en autotest som sjekker tilstrekkeligheten til tjenesten med ulike typer inndata. Returnerer tjenesten en svarkode som ikke er beskrevet i merknaden? Vil den være i stand til å behandle åpenbart feil data riktig?
Dessuten gjør implementering av høy kvalitet av ikke bare selve kontraktene, men også verktøyene for å visualisere merknader det mulig å forenkle arbeidet med mikrotjenesten. Det vil si at hvis arkitekten kvalitativt beskrev kontrakten, basert på den, vil designere og utviklere implementere tjenesten i andre produkter uten ekstra tidskostnader.
For å aktivere ytterligere verktøy, har både RAML og OAS muligheten til å legge til metadata som ikke er gitt av standarden ().
Generelt er mulighetene for kreativitet ved bruk av kontrakter for mikrotjenester enormt... i hvert fall i teorien.
Sammenligning av et pinnsvin med en slange
For øyeblikket er det prioriterte utviklingsområdet hos Acronis utviklingen av Acronis Cyber Platform. Acronis Cyber Platform er nye integreringspunkter for tredjepartstjenester med Acronis Cyber Cloud og agentdelen. Selv om vi var fornøyd med våre interne API-er beskrevet i RAML, reiste behovet for å publisere API-en igjen spørsmålet om valg: hvilken annotasjonsstandard er best å bruke for arbeidet vårt?
I utgangspunktet så det ut til at det var to løsninger - de vanligste utviklingene var RAML og Swagger (eller OAS). Men faktisk viste det seg at det i hvert fall ikke er 2 alternativer, men 3 eller flere.
På den ene siden er det RAML - et kraftig og effektivt språk. Den implementerer hierarki og arv godt, så dette formatet er mer egnet for store selskaper som trenger mange beskrivelser - det vil si ikke ett produkt, men mange mikrotjenester som har felles deler av kontrakter - autentiseringsskjemaer, samme datatyper, feilkropper .
Men utvikleren av RAML, Mulesoft, har sluttet seg til Open API-konsortiet, som utvikler . Derfor stanset RAML utviklingen. For å forestille deg formatet til arrangementet, forestill deg at vedlikeholderne av de viktigste Linux-komponentene dro for å jobbe for Microsoft. Denne situasjonen skaper forutsetninger for å bruke Swagger, som utvikler seg dynamisk og i siste – tredje versjon – praktisk talt innhenter RAML når det gjelder fleksibilitet og funksjonalitet.
Hvis ikke for en ting...
Som det viser seg, har ikke alle åpen kildekode-verktøy blitt oppdatert til OAS 3.0. For mikrotjenester i Go vil det mest kritiske være mangelen på tilpasning for siste versjon av standarden. Forskjellen mellom Swagger 2 og Swagger 3 er imidlertid . For eksempel, i den tredje versjonen:
- forbedret beskrivelse av autentiseringsordninger
- Støtte for JSON-skjema
- oppgradert muligheten til å legge til eksempler
Situasjonen er morsom: når du velger en standard, må du vurdere RAML, Swagger 2 og Swagger 3 som separate alternativer. Det er imidlertid bare Swagger 2 som har god støtte for OpenSource-verktøy. RAML er veldig fleksibel ... og kompleks, og Swagger 3 støttes dårlig av fellesskapet, så du må bruke proprietære verktøy eller kommersielle løsninger, som pleier å være ganske dyre.
Dessuten, hvis det er mange fine funksjoner i Swagger, for eksempel en ferdig portal , hvor du kan laste opp en merknad og få dens visualisering med en detaljert beskrivelse, lenker og koblinger, så for den mer grunnleggende og mindre vennlige RAML er det ingen slik mulighet. Ja, du kan søke etter noe blant prosjekter på GitHub, finne en analog der og distribuere den selv. Imidlertid vil noen i alle fall måtte vedlikeholde portalen, som ikke er så praktisk for grunnleggende bruk eller testbehov. I tillegg er swagger mer "prinsippløst", eller mer liberalt - det kan genereres fra kommentarer i koden, som selvfølgelig går mot API-førsteprinsippet og ikke støttes av noen av RAML-verktøyene.
På et tidspunkt begynte vi å jobbe med RAML som et mer fleksibelt språk, og som et resultat måtte vi gjøre mange ting selv. For eksempel bruker et av prosjektene verktøyet i enhetstester, som kun støtter RAML 0.8. Så vi måtte legge til krykker slik at verktøyet kunne "spise" RAML versjon 1.0.
Trenger du å velge?
Etter å ha jobbet med å fullføre økosystemet av løsninger for RAML, kom vi til den konklusjon at vi må konvertere RAML til Swagger 2 og utføre all automatisering, verifisering, testing og påfølgende optimalisering i den. Dette er en god måte å utnytte både fleksibiliteten til RAML og fellesskapsverktøystøtten fra Swagger.
For å løse dette problemet er det to OpenSource-verktøy som skal gi kontraktkonvertering:
- er et verktøy som for øyeblikket ikke støttes. Mens vi jobbet med det, oppdaget vi at det har en rekke problemer med komplekse RAML-er som er "spredt ut" over et stort antall filer. Dette programmet er skrevet i JavaScript og utfører en rekursiv traversering av et syntakstre. På grunn av dynamisk skriving blir det vanskelig å forstå denne koden, så vi bestemte oss for å ikke kaste bort tid på å skrive patcher for et døende verktøy.
- - et verktøy fra samme selskap som hevder å være klar til å konvertere alt og alt, og i alle retninger. Til dags dato har støtte blitt annonsert for RAML 0.8, RAML 1.0 og Swagger 2.0. På tidspunktet for vår forskning var imidlertid nytten fortsatt fuktig og ubrukelig. Utviklere lager en slags , slik at de raskt kan legge til nye standarder i fremtiden. Men så langt fungerer det bare ikke.
Og dette er ikke alle vanskelighetene vi har møtt. Et av trinnene i vår pipeline er å verifisere at RAML fra depotet er korrekt i forhold til spesifikasjonen. Vi prøvde flere verktøy. Overraskende nok bannet de alle til våre merknader på forskjellige steder og med helt forskjellige stygge ord. Og ikke alltid til poenget :).
Til slutt slo vi oss på et nå utdatert prosjekt, som også har en del problemer (noen ganger krasjer det ut av det blå, har problemer når man jobber med regulære uttrykk). Dermed fant vi ikke en måte å løse problemene med validering og konvertering basert på gratisverktøy, og bestemte oss for å bruke et kommersielt verktøy. I fremtiden, ettersom OpenSource-verktøy blir mer modne, kan dette problemet bli lettere å løse. I mellomtiden virket arbeids- og tidskostnadene for "etterbehandling" mer betydelige enn kostnadene for en kommersiell tjeneste.
Konklusjon
Etter alt dette ønsket vi å dele vår erfaring og merke oss at før du velger et verktøy for å beskrive kontrakter, må du klart definere hva du ønsker fra det og hvilket budsjett du er villig til å investere. Hvis vi glemmer OpenSource, finnes det allerede et stort antall tjenester og produkter som vil hjelpe deg å sjekke, konvertere og validere. Men de er dyre, og noen ganger veldig dyre. For et stort selskap er slike kostnader tålelige, men for en oppstart kan de bli en stor belastning.
Bestem settet med verktøy du skal bruke senere. Hvis du for eksempel bare trenger å vise en kontrakt, vil det være lettere å bruke Swagger 2, som har en vakker API, fordi i RAML må du bygge og vedlikeholde tjenesten selv.
Jo flere oppgaver du har, desto bredere vil behovet for verktøy være, og de er forskjellige for forskjellige plattformer, og det er bedre å umiddelbart gjøre deg kjent med de tilgjengelige versjonene for å ta et valg som minimerer kostnadene dine i fremtiden.
Men det er verdt å erkjenne at alle økosystemer som eksisterer i dag er ufullkomne. Derfor, hvis det er fans i selskapet som liker å jobbe i RAML fordi "det lar deg uttrykke tanker mer fleksibelt," eller tvert imot, foretrekker Swagger fordi "det er klarere", er det best å la dem jobbe i hva de er De er vant til det og vil ha det, fordi verktøyene til alle formatene krever modifikasjon med en fil.
Når det gjelder vår erfaring, vil vi i de følgende innleggene snakke om hvilke statiske og dynamiske kontroller vi utfører basert på vår RAML-Swagger-arkitektur, samt hvilken dokumentasjon vi genererer fra kontrakter, og hvordan det hele fungerer.
Kun registrerte brukere kan delta i undersøkelsen. , vær så snill.
Hvilket språk bruker du for å kommentere mikrotjenestekontrakter?
-
RAML 0.8
-
RAML 1.0
-
Swagger 2
-
OAS3 (aka)
-
Blueprint
-
Andre
-
Bruker ikke
100 brukere stemte. 24 brukere avsto.
Kilde: www.habr.com