I den dynamiske verden af mikrotjenester kan alt ændre sig - enhver komponent kan omskrives til et andet sprog ved hjælp af forskellige rammer og arkitektur. Kun kontrakter bør forblive uændrede, så mikrotjenesten kan interageres udefra på en eller anden permanent basis, uanset interne metamorfoser. Og i dag vil vi tale om vores problem med at vælge et format til at beskrive kontrakter og dele de artefakter, vi fandt.
Post forberedt и
Mikrotjenester. Da vi udviklede Acronis Cyber Cloud, indså vi, at vi ikke kunne undslippe dem. Og det er umuligt at designe en mikroservice uden at formalisere kontrakten, som repræsenterer mikroservicens grænseflade.
Men når et produkt indeholder mere end én komponent, og kontraktudvikling bliver en fast aktivitet, kan man ikke undgå at begynde at tænke på procesoptimering. Det bliver tydeligt, at grænsefladen (kontrakten) og implementeringen (microservice) skal matche hinanden, at forskellige komponenter skal gøre de samme ting på samme måde, og at uden en centraliseret beslutningstagning af alle disse beslutninger, vil hvert team være tvunget til at bruge tid igen og igen på at få dem.
Amazon microservices diagram fra Werner Vogelis, CTO Amazon
Hvad er dilemmaet? De facto er der to måder at interagere med mikrotjenester - HTTP Rest og gRPC fra Google. Da vi ikke ville blive fanget af Googles teknologistack, valgte vi HTTP Rest. HTTP REST kontraktannoteringer er oftest beskrevet i et af to formater: RAML og OAS, tidligere kendt som Swagger.Derfor står hvert udviklingsteam over for behovet for at vælge en af standarderne. Men som det viser sig, kan det være meget svært at træffe dette valg.
Hvorfor er der brug for anmærkninger?
Annoteringen er nødvendig, så en ekstern bruger nemt kan finde ud af, hvad der kan gøres med din tjeneste gennem dens HTTP-grænseflade. Det vil sige, at på et grundlæggende niveau skal annoteringen mindst indeholde en liste over tilgængelige ressourcer, deres HTTP-metoder, anmodningsorganer, en liste over parametre, en indikation af de påkrævede og understøttede overskrifter, samt returkoder og svarformater. Et ekstremt vigtigt element i kontraktannoteringen er deres verbale beskrivelse ("hvad vil der ske, hvis du tilføjer denne forespørgselsparameter til anmodningen?", "I hvilket tilfælde vil kode 400 blive returneret?")
Men når det kommer til at udvikle et stort antal mikrotjenester, ønsker du at udtrække yderligere værdi fra de skriftlige annoteringer. For eksempel kan du, baseret på RAML/Swagger, generere både klient- og serverkode i et stort antal programmeringssprog. Du kan også automatisk modtage dokumentation for mikrotjenesten og uploade den til din udviklerportal :).
Eksempel på en struktureret kontraktbeskrivelse
Mindre almindelig er praksis med at teste mikrotjenester baseret på kontraktbeskrivelser. Hvis du har skrevet både en anmærkning og en komponent, så kan du oprette en autotest, der kontrollerer tjenestens tilstrækkelighed med forskellige typer inputdata. Returnerer tjenesten en svarkode, der ikke er beskrevet i annotationen? Vil det være i stand til at behandle åbenlyst forkerte data korrekt?
Desuden gør højkvalitetsimplementering af ikke kun selve kontrakterne, men også værktøjerne til visualisering af annoteringer det muligt at forenkle arbejdet med mikrotjenesten. Det vil sige, at hvis arkitekten beskrev kontrakten på en måde af høj kvalitet, baseret på den, vil designere og udviklere implementere tjenesten i andre produkter uden ekstra tidsomkostninger.
For at aktivere yderligere værktøjer har både RAML og OAS mulighed for at tilføje metadata, der ikke er fastsat af standarden ().
Generelt er mulighederne for kreativitet i at bruge kontrakter til mikrotjenester enorm... i hvert fald i teorien.
Sammenligning af et pindsvin med en slange
I øjeblikket er det prioriterede udviklingsområde hos Acronis udviklingen af Acronis Cyber Platform. Acronis Cyber Platform er nye integrationspunkter for tredjepartstjenester med Acronis Cyber Cloud og agentdelen. Selvom vi var tilfredse med vores interne API'er beskrevet i RAML, rejste behovet for at udgive API'en igen spørgsmålet om valg: hvilken annotationsstandard er bedst at bruge til vores arbejde?
I første omgang så det ud til, at der var to løsninger - de mest almindelige udviklinger var RAML og Swagger (eller OAS). Men faktisk viste det sig, at der i hvert fald ikke er 2 alternativer, men 3 eller flere.
På den ene side er der RAML - et kraftfuldt og effektivt sprog. Det implementerer hierarki og nedarvning godt, så dette format er mere velegnet til store virksomheder, der har brug for mange beskrivelser - det vil sige ikke ét produkt, men mange mikrotjenester, der har fælles dele af kontrakter - autentificeringsskemaer, de samme datatyper, fejltekster .
Men udvikleren af RAML, Mulesoft, har sluttet sig til Open API-konsortiet, som er ved at udvikle . Derfor indstillede RAML sin udvikling. For at forestille dig formatet af begivenheden, forestil dig, at vedligeholderne af de vigtigste Linux-komponenter gik for at arbejde for Microsoft. Denne situation skaber forudsætningerne for at bruge Swagger, som udvikler sig dynamisk og i den seneste - tredje version - praktisk talt indhenter RAML med hensyn til fleksibilitet og funktionalitet.
Hvis ikke for én ting...
Som det viser sig, er ikke alle open source-værktøjer blevet opdateret til OAS 3.0. For mikrotjenester i Go vil det mest kritiske være manglen på tilpasning for den seneste version af standarden. Forskellen mellem Swagger 2 og Swagger 3 er dog . For eksempel, i den tredje version:
- forbedret beskrivelse af autentificeringsordninger
- JSON Schema support
- opgraderet muligheden for at tilføje eksempler
Situationen er sjov: Når du vælger en standard, skal du overveje RAML, Swagger 2 og Swagger 3 som separate alternativer. Det er dog kun Swagger 2, der har god understøttelse af OpenSource-værktøjer. RAML er meget fleksibel ... og kompleks, og Swagger 3 er dårligt understøttet af fællesskabet, så du bliver nødt til at bruge proprietære værktøjer eller kommercielle løsninger, som plejer at være ret dyre.
Desuden, hvis der er mange fine funktioner i Swagger, såsom en færdiglavet portal , hvorpå du kan uploade en annotering og få dens visualisering med en detaljeret beskrivelse, links og forbindelser, så er der ikke for den mere grundlæggende og mindre venlige RAML en sådan mulighed. Ja, du kan søge efter noget blandt projekter på GitHub, finde en analog der og implementere den selv. Men under alle omstændigheder bliver nogen nødt til at vedligeholde portalen, hvilket ikke er så praktisk til grundlæggende brug eller testbehov. Derudover er swagger mere "principløs" eller mere liberal - den kan genereres fra kommentarer i koden, som selvfølgelig går imod API-første princippet og ikke understøttes af nogen af RAML-værktøjerne.
På et tidspunkt begyndte vi at arbejde med RAML som et mere fleksibelt sprog, og som følge heraf måtte vi lave en masse ting selv. For eksempel bruger et af projekterne værktøjet i enhedstest, som kun understøtter RAML 0.8. Så vi var nødt til at tilføje krykker, så værktøjet kunne "spise" RAML version 1.0.
Skal du vælge?
Efter at have arbejdet på at færdiggøre økosystemet af løsninger til RAML, kom vi til den konklusion, at vi skal konvertere RAML til Swagger 2 og udføre al automatisering, verifikation, test og efterfølgende optimering i det. Dette er en god måde at udnytte både fleksibiliteten i RAML og community-værktøjsstøtten fra Swagger.
For at løse dette problem er der to OpenSource-værktøjer, der skal give kontraktkonvertering:
- er et i øjeblikket ikke-understøttet hjælpeprogram. Mens vi arbejdede med det, opdagede vi, at det har en række problemer med komplekse RAML'er, der er "spredt ud" over et stort antal filer. Dette program er skrevet i JavaScript og udfører en rekursiv gennemgang af et syntakstræ. På grund af dynamisk indtastning bliver det svært at forstå denne kode, så vi besluttede ikke at spilde tid på at skrive patches til et døende hjælpeprogram.
- - et værktøj fra samme virksomhed, der hævder at være klar til at konvertere alt og alt, og i enhver retning. Til dato er der blevet annonceret support til RAML 0.8, RAML 1.0 og Swagger 2.0. Men på tidspunktet for vores forskning var nytten stadig fugtig og ubrugelig. Udviklere skaber en slags , hvilket giver dem mulighed for hurtigt at tilføje nye standarder i fremtiden. Men indtil videre går det bare ikke.
Og det er ikke alle de vanskeligheder, vi stødte på. Et af trinene i vores pipeline er at verificere, at RAML fra depotet er korrekt i forhold til specifikationen. Vi prøvede flere hjælpeprogrammer. Overraskende nok bandede de alle til vores anmærkninger forskellige steder og med helt forskellige dårlige ord. Og ikke altid til sagen :).
Til sidst slog vi os fast på et nu forældet projekt, som også har en del problemer (nogle gange styrter det ud af det blå, har problemer, når man arbejder med regulære udtryk). Således fandt vi ikke en måde at løse problemerne med validering og konvertering baseret på gratis værktøjer og besluttede at bruge et kommercielt hjælpeprogram. I fremtiden, efterhånden som OpenSource-værktøjer bliver mere modne, kan dette problem blive lettere at løse. I mellemtiden forekom arbejds- og tidsomkostningerne til at "efterbehandle" os mere betydelige end omkostningerne ved en kommerciel tjeneste.
Konklusion
Efter alt dette ønskede vi at dele vores erfaring og bemærke, at før du vælger et værktøj til at beskrive kontrakter, skal du klart definere, hvad du vil have ud af det, og hvilket budget du er villig til at investere. Hvis vi glemmer OpenSource, er der allerede et stort antal tjenester og produkter, som vil hjælpe dig med at tjekke, konvertere og validere. Men de er dyre, og nogle gange meget dyre. For en stor virksomhed er sådanne omkostninger tolerable, men for en startup kan de blive en stor belastning.
Bestem det sæt værktøjer, du vil bruge senere. Skal du for eksempel blot vise en kontrakt, bliver det nemmere at bruge Swagger 2, som har en smuk API, fordi du i RAML selv skal bygge og vedligeholde tjenesten.
Jo flere opgaver du har, jo bredere vil behovet for værktøjer være, og de er forskellige for forskellige platforme, og det er bedre straks at sætte dig ind i de tilgængelige versioner for at træffe et valg, der minimerer dine omkostninger i fremtiden.
Men det er værd at erkende, at alle økosystemer, der eksisterer i dag, er ufuldkomne. Derfor, hvis der er fans i virksomheden, der kan lide at arbejde i RAML, fordi "det giver dig mulighed for at udtrykke tanker mere fleksibelt", eller tværtimod foretrækker Swagger, fordi "det er klarere", er det bedst at lade dem arbejde i, hvad de er De er vant til det og vil have det, fordi værktøjerne i et hvilket som helst af formaterne kræver modifikation med en fil.
Hvad angår vores erfaring, vil vi i de følgende indlæg tale om, hvilke statiske og dynamiske kontroller vi udfører baseret på vores RAML-Swagger-arkitektur, samt hvilken dokumentation vi genererer fra kontrakter, og hvordan det hele fungerer.
Kun registrerede brugere kan deltage i undersøgelsen. , Vær venlig.
Hvilket sprog bruger du til at kommentere mikroservicekontrakter?
-
RAML 0.8
-
RAML 1.0
-
Swagger 2
-
OAS3 (alias)
-
Blueprint
-
Andet
-
Bruger ikke
100 brugere stemte. 24 brugere undlod at stemme.
Kilde: www.habr.com