{"id":38022,"date":"2019-10-31T22:21:14","date_gmt":"2019-10-31T19:21:14","guid":{"rendered":"https:\/\/prohoster.info\/blog\/tak-vse-taki-raml-ili-oas-swagger\/"},"modified":"2019-10-31T22:21:14","modified_gmt":"2019-10-31T19:21:14","slug":"tak-vse-taki-raml-ili-oas-swagger","status":"publish","type":"post","link":"https:\/\/prohoster.info\/da\/blog\/administrirovanie\/tak-vse-taki-raml-ili-oas-swagger","title":{"rendered":"S\u00e5 er det RAML eller OAS (Swagger)?","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

I en dynamisk verden af mikrotjenester kan alt \u00e6ndre sig \u2014 enhver komponent kan genskrives i et andet sprog ved hj\u00e6lp af forskellige rammer og arkitektur. Kun kontrakterne skal forblive u\u00e6ndrede, s\u00e5 mikrotjenesten kan interagere eksternt p\u00e5 en stabil basis uanset de interne transformationer. I dag vil vi fort\u00e6lle om vores problem med at v\u00e6lge formatet til beskrivelse af kontrakter og dele de artefakter, vi har fundet. <\/p>\n

\"S\u00e5
\n<\/a><\/noindex>
\nIndl\u00e6gget er forberedt af Anna Melekhova<\/a><\/noindex> og Vladimir Lapatin<\/a><\/noindex> <\/p>\n

Mikrotjenester.<\/b> Ved udviklingen af Acronis Cyber Cloud inds\u00e5 vi, at vi ikke kunne undg\u00e5 dem. Og designet af en mikrotjeneste er umuligt uden at formalisere kontrakten, som repr\u00e6senterer mikrotjenestens interface.<\/p>\n

Men n\u00e5r produktet indeholder mere end \u00e9n komponent, og udviklingen af kontrakten bliver en regelm\u00e6ssig aktivitet, begynder man uundg\u00e5eligt at t\u00e6nke over optimering af processen. Det bliver klart, at interface (kontrakt) og implementering (mikrotjeneste) skal matche hinanden, at forskellige komponenter skal udf\u00f8re de samme opgaver p\u00e5 samme m\u00e5de, og at uden en centraliseret beslutningsproces vil hvert team v\u00e6re n\u00f8dt til at bruge tid p\u00e5 at opn\u00e5 dem igen og igen. <\/p>\n

\"S\u00e5
\nSkema for mikrotjenester fra Amazon fra tweeten<\/a><\/noindex> af Werner Vogels, CTO Amazon<\/i>
\nHvad er dilemmaet? De facto er der to m\u00e5der, hvorp\u00e5 mikrotjenester kan interagere \u2013 HTTP Rest og gRPC fra Google. Uden at \u00f8nske at blive involveret i Googles teknologistak, valgte vi HTTP Rest. Annotationer til HTTP REST-kontrakter beskrives oftest i et af to formater: RAML og OAS, tidligere kendt som Swagger. Derfor st\u00e5r hvert udviklerteam over for valget af \u00e9n standard. Men som det viste sig, kan det v\u00e6re meget sv\u00e6rt at tr\u00e6ffe dette valg.<\/p>\n

Hvorfor er annotationer n\u00f8dvendige?<\/h3>\n

\nEn annotation er n\u00f8dvendig, s\u00e5 eksterne brugere nemt kan forst\u00e5, hvad de kan g\u00f8re med din service gennem dens HTTP-interface. P\u00e5 et grundl\u00e6ggende niveau skal annotationen indeholde mindst en liste over tilg\u00e6ngelige ressourcer, deres HTTP-metoder, anmodningernes krop, opregning af parametre, angivelse af n\u00f8dvendige og underst\u00f8ttede overskrifter samt statuskoder og svarformater. Et ekstremt vigtigt element i kontraktannotation er ogs\u00e5 deres beskrivende forklaring (\"hvad sker der, hvis man tilf\u00f8jer denne query-parameter til anmodningen?\", \"hvorn\u00e5r bliver statuskode 400 returneret?\")<\/p>\n

N\u00e5r der er tale om udvikling af et stort antal mikrotjenester, er det dog \u00f8nskeligt at udvinde ekstra v\u00e6rdi fra de skrevne annotationer. For eksempel kan man baseret p\u00e5 RAML\/Swagger generere b\u00e5de klient- og serverkode p\u00e5 et enormt antal programmeringssprog. Man kan ogs\u00e5 automatisk generere dokumentation til mikrotjenesten og uploade den til din udviklerportal :).<\/p>\n

\"S\u00e5
\nEksempel p\u00e5 struktureret kontraktbeskrivelse<\/i><\/p>\n

Det er sj\u00e6ldnere at se praksis med at teste mikrotjenester baseret p\u00e5 kontraktbeskrivelser. Hvis du har skrevet b\u00e5de annotationen og komponenten, kan du oprette en automatisk test, der kontrollerer, om servicen fungerer korrekt med forskellige typer data som input. Returnerer servicen en svarkode, der ikke er beskrevet i annotationen? Kan den h\u00e5ndtere forskriftsm\u00e6ssigt forkerte data korrekt?<\/p>\n

Desuden g\u00f8r en kvalitetsimplementering af b\u00e5de kontrakterne og v\u00e6rkt\u00f8jer til visualisering af annotationer arbejdet med mikrotjenesten lettere. Det vil sige, hvis arkitekten har beskrevet kontrakten grundigt, vil designere og udviklere kunne integrere servicen i andre produkter uden yderligere tidsomkostninger.<\/p>\n

For brug af yderligere v\u00e6rkt\u00f8jer kan b\u00e5de RAML og OAS tilf\u00f8je metadata, som ikke er omfattet af standarden (for eksempel hvordan dette g\u00f8res i OAS<\/a><\/noindex>).<\/p>\n

Generelt er der et enormt kreativt rum i anvendelsen af kontrakter til mikrotjenester... i det mindste teoretisk<\/p>\n

Sammenligning af en igle med en snog<\/h3>\n

\nI \u00f8jeblikket er Acronis' prioriterede udviklingsretning Acronis Cyber Platform. Acronis Cyber Platform er de nye integrationspunkter for tredjepartstjenester med Acronis Cyber Cloud og agentdelen. Selvom vores interne API'er, beskrevet i RAML, var tilstr\u00e6kkelige, rejste behovet for at offentligg\u00f8re API'et igen sp\u00f8rgsm\u00e5let om, hvilken standard for annoteringer der er bedst at bruge til vores arbejde?<\/p>\n

Oprindeligt s\u00e5 det ud til, at der var to l\u00f8sninger \u2014 de mest udbredte udviklinger RAML og Swagger (eller OAS). Men i praksis viste det sig, at der er mindst tre, hvis ikke flere alternativer.<\/p>\n

P\u00e5 den ene side er der RAML \u2014 et kraftfuldt og effektivt sprog. Det har en god implementering af hierarki og arv, s\u00e5 dette format passer bedre til store virksomheder, der har brug for mange beskrivelser \u2014 det vil sige ikke \u00e9t produkt, men mange mikrotjenester, som har f\u00e6lles elementer i deres kontrakter \u2014 autentificeringsskemaer, ens datatyper, fejlmeddelelser.<\/p>\n

Men udvikleren af RAML, Mulesoft, har tilsluttet sig konsortiet Open API, som arbejder p\u00e5 udviklingen af Swagger<\/a><\/noindex>. Derfor er udviklingen af RAML blevet sat p\u00e5 pause. For at forestille sig formatet af begivenheden, kan man t\u00e6nke p\u00e5, at vedligeholderne af de prim\u00e6re komponenter i Linux gik over til Microsoft. En s\u00e5dan situation skaber foruds\u00e6tninger for at bruge Swagger, som udvikler sig dynamisk, og i den seneste \u2014 tredje version \u2014 n\u00e6sten indhenter RAML n\u00e5r det kommer til fleksibilitet og funktionalitet.<\/p>\n

Hvis det ikke var for \u00e9n ting\u2026<\/h3>\n

\nDet viste sig, at langt fra alle open-source v\u00e6rkt\u00f8jer var opdateret til OAS 3.0-versionen. For mikrotjenester skrevet i Go vil det kritiske v\u00e6re frav\u00e6ret af tilpasning go-swagger<\/a><\/noindex> til den nye version af standarden. Men forskellen mellem Swagger 2 og Swagger 3 er enorm<\/a><\/noindex>. For eksempel har udviklerne i den tredje version:<\/p>\n