{"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\/et\/blog\/administrirovanie\/tak-vse-taki-raml-ili-oas-swagger","title":{"rendered":"Kas siiski RAML v\u00f5i OAS (Swagger)?","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

D\u00fcnaamilises mikros\u00fcsteemide maailmas v\u00f5ib k\u00f5ik muutuda \u2014 iga komponent v\u00f5ib olla kirjutatud teises keeles, kasutades teisi raamistikke ja arhet\u00fc\u00fcpe. Ainsateks muutumatuks j\u00e4\u00e4vateks elementideks peavad olema lepingud, et oleks v\u00f5imalik mikros\u00fcsteemiga suhelda v\u00e4ljaspool setkust kindlal alusel, olenemata sisemistest metamorfoosidest. T\u00e4na r\u00e4\u00e4gime oma probleemist lepingute kirjeldamise formaadi valimisel ja jagame leitud artefakte. <\/p>\n

\"Kas
\n<\/a><\/noindex>
\nPostituse koostas Anna Melekova<\/a><\/noindex> ja Vladimir Lapatin<\/a><\/noindex> <\/p>\n

Mikros\u00fcsteemid.<\/b> Acronis Cyber Cloud'i arendamisel m\u00f5istsime, et me ei saa neist m\u00f6\u00f6da minna. Ja mikros\u00fcsteemi projekteerimine on v\u00f5imatu ilma lepingu formaliseerimiseta, mis on mikros\u00fcsteemi liides.<\/p>\n

Kuid kui toote sees on rohkem kui \u00fcks komponent ning lepingu arendamine muutub regulaarseks tegevuseks, hakkad automaatselt m\u00f5tlema protsessi optimeerimisele. On ilmne, et liides (leping) ja rakendus (mikros\u00fcsteem) peavad \u00fcksteisele vastama, et erinevad komponendid peaksid tegema samu asju samal moel, ja et ilma k\u00f5igi nende otsuste keskse vastuv\u00f5tu korral peab iga meeskond taas ja taas aega kulutama nende saamiseks. <\/p>\n

\"Kas
\nAmazon'i mikros\u00fcsteemide skeem tweet<\/a><\/noindex> Werner Vogels, Amazon'i CTO<\/i>
\nKus seisneb dilemma? De facto on mikros\u00fcsteemide suhtlemiseks kaks viisi \u2013 HTTP Rest ja Google'i gRPC. Soovimata sattuda Google'i tehnoloogiakuhja, valisime HTTP Rest. HTTP REST lepingute annotatsioonid kirjeldatakse k\u00f5ige sagedamini kahes formaadis: RAML ja OAS, varem tuntud kui Swagger. Seega seisab iga arendajate meeskond silmitsi vajadusega valida \u00fche standardi kasuks. Kuid, nagu selgus, v\u00f5ib see valik olla v\u00e4ga keeruline.<\/p>\n

Miks on annotatsioonid vajalikud?<\/h3>\n

\nAnnotatsioon on vajalik, et v\u00e4line kasutaja saaks h\u00f5lpsasti aru, mida saab teie teenusega teha l\u00e4bi selle HTTP-liidese. See t\u00e4hendab, et alusel peab annotatsioon sisaldama v\u00e4hemalt loetelu saadaval olevatest ressurssidest, nende HTTP-meetoditest, p\u00e4ringu kehadest, parameetrite loendist, n\u00f5utud ja toetatavate pealkirjade m\u00e4\u00e4ratlemisest, samuti tagastuskoode ja vastuse vormate. \u00c4\u00e4rmiselt oluline on ka lepingute annotatsioonide s\u00f5naline kirjeldus (\"mida juhtub, kui lisada see p\u00e4ringu parameeter?\", \"millisel juhul tagastatakse kood 400?\")<\/p>\n

Kuid kui r\u00e4\u00e4kida suure hulga mikroteenuste arendamisest, tahaks lisaks tuua ka rohkem kasu kirjutatud annotatsioonidest. N\u00e4iteks RAML\/Swaggeri alusel saab genereerida nii kliendi- kui serverikoodi paljudes programmeerimiskeeltes. Samuti on v\u00f5imalik automaatselt saada mikroteenuse dokumentatsiooni ja laadida see teie arendaja portaalile : ).<\/p>\n

\"Kas
\nStruktureeritud lepingute kirjelduse n\u00e4ide<\/i><\/p>\n

Harvemini on praktika testida mikroteenuseid lepingute kirjelduste p\u00f5hjal. Kui olete kirjutanud nii annotatsiooni kui ka komponendi, on v\u00f5imalik luua automaatne test, mis kontrollib teenuse t\u00f6\u00f6 sobivust erinevate t\u00fc\u00fcpi andmete sisenemisel. Kas teenus tagastab vastuskoodi, mida annotatsioonis ei ole kirjeldatud? Kas see suudab \u00f5igesti t\u00f6\u00f6delda teadlikult valeid andmeid?<\/p>\n

Lisaks v\u00f5imaldab kvaliteetne rakendamine mitte ainult lepingute, vaid ka annotatsioonide visualiseerimise t\u00f6\u00f6riistade lihtsustamist mikroteenuste t\u00f6\u00f6s. See t\u00e4hendab, et kui arhitekt kirjeldas lepingut kvaliteetselt, saavad disainerid ja arendajad teenust teistesse toodetesse rakendada ilma t\u00e4iendavate ajakuludeta.<\/p>\n

T\u00f6\u00f6 jaoks t\u00e4iendavates t\u00f6\u00f6riistades v\u00f5ivad nii RAML kui OAS v\u00f5imaldada lisada metainfot, mida standard ei ennusta (n\u00e4iteks nii tehakse OAS-is<\/a><\/noindex>).<\/p>\n

\u00dcldiselt on lepingute rakendamiseks mikroteenustes loovuse jaoks tohutu ruum\u2026 v\u00e4hemalt teoreetiliselt<\/p>\n

Siili ja r\u00e4stiku v\u00f5rdlemine<\/h3>\n

\nPraegu on Acronise prioriteetne suund Acronis Cyber Platformi arendamine. Acronis Cyber Platform on uued integratsioonipunktid kolmandate osapoolte teenuste ja Acronis Cyber Cloudi ning agentuuriosade vahel. Kuigi meie sisemised API-d, mis on kirjeldatud RAML-is, on meid rahule j\u00e4tnud, t\u00f5stis vajadus API avaldamise k\u00fcsimuse: milline annotatsioonistandard oleks meie t\u00f6\u00f6 jaoks parem?<\/p>\n

Esialgu tundus, et lahendusi on kaks \u2014 enim levinud arendused RAML ja Swagger (v\u00f5i OAS). Kuid tegelikult selgus, et alternatiive on v\u00e4hemalt 2, vaid 3 v\u00f5i enam.<\/p>\n

\u00dchelt poolt on olemas RAML \u2013 v\u00f5imas ja efektiivne keel. Sellel on h\u00e4sti realiseeritud hierarhia ja p\u00e4rimine, nii et see formaat sobib paremini suurtele ettev\u00f5tetele, kellel on palju kirjeldusi \u2014 mitte \u00fcks toode, vaid palju mikroteenuseid, millel on \u00fchised lepingu osad \u2014 autentimise skeemid, samad andmet\u00fc\u00fcbid, vigade kehad.<\/p>\n

Kuid RAMLi arendaja, ettev\u00f5te Mulesoft, liitus Open API konsortsiumiga, mis tegeleb arendamisega Swagger<\/a><\/noindex>. Seet\u00f5ttu on RAMLi areng peatunud. Kujutage ette, et Linuxi peamiste komponentide hooldajad on t\u00f6\u00f6le l\u00e4inud Microsofti. Selline olukord loob eeldused Swaggeri kasutamiseks, mis areneb d\u00fcnaamiliselt ja praeguses \u2014 kolmandas versioonis \u2014 saavutab RAML-i paindlikkuse ja funktsionaalsuse.<\/p>\n

Kuid on \u00fcks aga...<\/h3>\n

\nKuidas osutus, et kaugeltki mitte k\u00f5ik avatud l\u00e4htekoodiga utiliidid pole uuendatud versioonile OAS 3.0. Go mikroteenuste jaoks on k\u00f5ige kriitilisem OAS 3.0. standardi uus versiooniga kohandamise puudumine go-swagger<\/a><\/noindex> . Kuid erinevus Swagger 2 ja Swagger 3 vahel on \u2014 hiiglaslik<\/a><\/noindex>. N\u00e4iteks kolmandas versioonis parandasid arendajad:<\/p>\n