{"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":"Nii et kas RAML v\u00f5i OAS (Swagger)?","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

D\u00fcnaamilises mikroteenuste maailmas v\u00f5ib k\u00f5ik muutuda \u2014 iga komponent v\u00f5ib olla \u00fcmber kirjutatud teises keeles, kasutades erinevaid raamistikke ja arhitektuuri. Muutumatuks peavad j\u00e4\u00e4ma vaid lepingud, et mikroteenusega saaks suhelda v\u00e4ljastpoolt teatud stabiilsusel, s\u00f5ltumata sisemistest muutustest. T\u00e4na r\u00e4\u00e4gime meie valikuprobleemist lepingute kirjeldamise formaadi osas ja jagame leitud artefakte. <\/p>\n

\"Nii
\n<\/a><\/noindex>
\nPostituse koostas Anna Melehkova<\/a><\/noindex> ja Vladimir Lapatin<\/a><\/noindex> <\/p>\n

Mikroteenused.<\/b> Acronis Cyber Cloud'i arendamisel m\u00f5istsime, et me ei p\u00e4\u00e4se neist. Mikroteenuse projekteerimine ei ole v\u00f5imalik ilma lepingu formaliseerimiseta, mis esindab mikroteenuse liidest.<\/p>\n

Kuid kui tootest leiab rohkem kui \u00fcks komponent ja lepingu arendamisest saab regulaarne tegevus, hakkad paratamatult m\u00f5tlema protsessi optimeerimisele. On ilmne, et liides (leping) ja rakendamine (mikroteenus) peavad \u00fcksteisele vastama, et erinevad komponendid teeksid samu asju \u00fchtviisi ning et ilma nende otsuste keskse vastuv\u00f5tmiseta peab iga meeskond ikka ja j\u00e4lle kulutama aega nende hankimiseks. <\/p>\n

\"Nii
\nAmazonile kuuluvate mikroteenuste skeem twiit<\/a><\/noindex> Werner Vogels, Amazon'i CTO<\/i>
\nMis on dilemmas? De facto on kaks viisi mikroteenuste suhtlemiseks \u2013 HTTP Rest ja gRPC Google'ilt. Me ei soovinud olla seotud Google'i tehnoloogiatega, seet\u00f5ttu valisime HTTP Rest'i. HTTP REST lepingute annotatsioonid on k\u00f5ige sagedamini kirjeldatud \u00fches kahest formaadist: RAML ja OAS, mis oli varem tuntud kui Swagger. Seet\u00f5ttu seisavad k\u00f5ik arendajate meeskonnad silmitsi vajadusega valida \u00fche standardi kasuks. Kuid nagu selgus, v\u00f5ib selle valiku tegemine olla v\u00e4ga keeruline.<\/p>\n

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

\nAnnotatsioon aitab v\u00e4listel kasutajatel kiiresti m\u00f5ista, mida saavad nad teie teenusega selle HTTP-liidese kaudu teha. Selle p\u00f5hitasandi puhul peaks annotatsioon sisaldama v\u00e4hemalt loetelu saadaval olevatest ressursitest, nende HTTP-meetoditest, p\u00e4ringute kehast, parametrite loendist, n\u00f5utud ja toetatud p\u00e4istest ning ka tagastatavatest koodidest ja vastuse formaatidest. \u00c4\u00e4rmiselt oluline element lepingu annotatsioonis on nende s\u00f5naline kirjeldus (\"mis juhtub, kui lisada see query-parameeter p\u00e4ringule?\", \"millal tagastatakse kood 400?\")<\/p>\n

Siiski, kui asi puudutab suurte mikroteenuste arendamist, on soov soovida saada rohkem kasu kirjutatud annotatsioonidest. N\u00e4iteks RAML-i \/ Swaggeri p\u00f5hjal saab genereerida nii kliendi- kui ka serverikoodi paljusid programmeerimiskeeli. Samuti on v\u00f5imalik automaatselt luua mikroteenuse dokumentatsioon ja laadida see \u00fcles teie arendaja portaalile :).<\/p>\n

\"Nii
\nStruktureeritud lepingu kirjelduse n\u00e4ide<\/i><\/p>\n

Harva praktika mikroteenuste testimiseks p\u00f5hineb lepingute kirjeldustel. Kui olete kirjutanud nii annotatsiooni kui ka komponendi, on v\u00f5imalik luua automaatne test, mis kontrollib teenuse toimivust erinevate andmet\u00fc\u00fcpide sisendiga. Kas teenus tagastab koodi, mida annotatsioonis ei ole kirjeldatud? Kas ta suudab korrektselt t\u00f6\u00f6delda valeandmeid?<\/p>\n

Lisaks v\u00f5imaldab kvaliteetne lepingute rakendamine ja annotatsioonide visualiseerimise t\u00f6\u00f6riistade arendamine h\u00f5lbustada mikroteenuste t\u00f6\u00f6d. Kui arhitekt on lepingut kvaliteetselt kirjeldanud, saavad disainerid ja arendajad selle alusel teenuse teistesse toodetesse integreerida ilma t\u00e4iendavate ajakulu.<\/p>\n

Lisaks on nii RAML-l kui ka OAS-il v\u00f5imalus lisada metainfot, mis ei ole standardiga ette n\u00e4htud (n\u00e4iteks, nii tehakse OAS-is<\/a><\/noindex>).<\/p>\n

Kokkuv\u00f5ttes on lepingute rakendamiseks mikroteenustes loomingulise vaba ruumi palju... v\u00e4hemalt teoreetiliselt<\/p>\n

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

\nPraegu on Acronise arenduste peamine suund Acronis Cyber Platformi arendamine. Acronis Cyber Platform on uus koht, kus integreerida kolmandate osapoolte teenuseid Acronis Cyber Cloudiga ja agentuuriosaga. Kuigi meie sisemised API-d, mis on kirjeldatud RAML-is, olid rahuldavad, t\u00f5stis API-de avaldamise vajadus taas k\u00fcsimuse: millist annotatsioonistandardit peaksime oma t\u00f6\u00f6s kasutama?<\/p>\n

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

\u00dchest k\u00fcljest on RAML \u2014 v\u00f5imas ja efektiivne keel. Sellel on h\u00e4sti rakendatud hierarhia ja p\u00e4rand, mist\u00f5ttu sobib see formaat rohkem suurte ettev\u00f5tete jaoks, kellel on vaja palju kirjeldusi \u2014 mitte \u00fchte toodet, vaid palju mikroteenuseid, millel on \u00fchised lepingute osad \u2014 autentimisskeemid, \u00fchesugused andmet\u00fc\u00fcbid, veateated.<\/p>\n

Kuid RAMLi arendaja, ettev\u00f5te Mulesoft, liitus Open API konsortsiumiga, mis tegeleb arendamisega. Swagger<\/a><\/noindex>. Seet\u00f5ttu on RAML oma arengu peatunud. Kujutle, et Linuxi peamiste komponentide hooldajad on l\u00e4inud Microsofti t\u00f6\u00f6le. Selline olukord loob eeldused, et kasutada Swaggerit, mis areneb d\u00fcnaamiliselt ja viimases \u2014 kolmandas versioonis \u2014 j\u00f5uab RAML-iga v\u00f5rreldes paindlikkuses ja funktsionaalsuses praktiliselt samale tasemele.<\/p>\n

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

\nKuidas selgus, ei ole k\u00f5ik avatud l\u00e4htekoodiga t\u00f6\u00f6riistad uuendatud OAS 3.0 versioonile. Go p\u00f5histe mikroteenuste jaoks on k\u00f5ige kriitilisem kohandamise puudumine go-swagger<\/a><\/noindex> uue standardi versiooni jaoks. Kuid erinevus Swagger 2 ja Swagger 3 vahel on hiiglaslik<\/a><\/noindex>. N\u00e4iteks kolmandas versioonis on arendajad:<\/p>\n