🥇Nii kas RAML või OAS (Swagger)?

Dünaamilises mikroteenuste maailmas võib kõik muutuda — iga komponent võib olla ümber kirjutatud teises keeles, kasutades erinevaid raamistikke ja arhitektuuri. Muutumatuks peavad jääma vaid lepingud, et mikroteenusega saaks suhelda väljastpoolt teatud stabiilsusel, sõltumata sisemistest muutustest. Täna räägime meie valikuprobleemist lepingute kirjeldamise formaadi osas ja jagame leitud artefakte.

Postituse koostas Anna Melehkova ja Vladimir Lapatin

Mikroteenused. Acronis Cyber Cloud'i arendamisel mõistsime, et me ei pääse neist. Mikroteenuse projekteerimine ei ole võimalik ilma lepingu formaliseerimiseta, mis esindab mikroteenuse liidest.

Kuid kui tootest leiab rohkem kui üks komponent ja lepingu arendamisest saab regulaarne tegevus, hakkad paratamatult mõtlema protsessi optimeerimisele. On ilmne, et liides (leping) ja rakendamine (mikroteenus) peavad üksteisele vastama, et erinevad komponendid teeksid samu asju ühtviisi ning et ilma nende otsuste keskse vastuvõtmiseta peab iga meeskond ikka ja jälle kulutama aega nende hankimiseks.

Amazonile kuuluvate mikroteenuste skeem twiit Werner Vogels, Amazon'i CTO
Mis on dilemmas? De facto on kaks viisi mikroteenuste suhtlemiseks – HTTP Rest ja gRPC Google'ilt. Me ei soovinud olla seotud Google'i tehnoloogiatega, seetõttu valisime HTTP Rest'i. HTTP REST lepingute annotatsioonid on kõige sagedamini kirjeldatud ühes kahest formaadist: RAML ja OAS, mis oli varem tuntud kui Swagger. Seetõttu seisavad kõik arendajate meeskonnad silmitsi vajadusega valida ühe standardi kasuks. Kuid nagu selgus, võib selle valiku tegemine olla väga keeruline.

Miks on annotatsioonid vajalikud?

Annotatsioon aitab välistel kasutajatel kiiresti mõista, mida saavad nad teie teenusega selle HTTP-liidese kaudu teha. Selle põhitasandi puhul peaks annotatsioon sisaldama vähemalt loetelu saadaval olevatest ressursitest, nende HTTP-meetoditest, päringute kehast, parametrite loendist, nõutud ja toetatud päistest ning ka tagastatavatest koodidest ja vastuse formaatidest. Äärmiselt oluline element lepingu annotatsioonis on nende sõnaline kirjeldus ("mis juhtub, kui lisada see query-parameeter päringule?", "millal tagastatakse kood 400?")

Siiski, kui asi puudutab suurte mikroteenuste arendamist, on soov soovida saada rohkem kasu kirjutatud annotatsioonidest. Näiteks RAML-i / Swaggeri põhjal saab genereerida nii kliendi- kui ka serverikoodi paljusid programmeerimiskeeli. Samuti on võimalik automaatselt luua mikroteenuse dokumentatsioon ja laadida see üles teie arendaja portaalile :).

Struktureeritud lepingu kirjelduse näide

Harva praktika mikroteenuste testimiseks põhineb lepingute kirjeldustel. Kui olete kirjutanud nii annotatsiooni kui ka komponendi, on võimalik luua automaatne test, mis kontrollib teenuse toimivust erinevate andmetüüpide sisendiga. Kas teenus tagastab koodi, mida annotatsioonis ei ole kirjeldatud? Kas ta suudab korrektselt töödelda valeandmeid?

Lisaks võimaldab kvaliteetne lepingute rakendamine ja annotatsioonide visualiseerimise tööriistade arendamine hõlbustada mikroteenuste tööd. Kui arhitekt on lepingut kvaliteetselt kirjeldanud, saavad disainerid ja arendajad selle alusel teenuse teistesse toodetesse integreerida ilma täiendavate ajakulu.

Lisaks on nii RAML-l kui ka OAS-il võimalus lisada metainfot, mis ei ole standardiga ette nähtud (näiteks, nii tehakse OAS-is).

Kokkuvõttes on lepingute rakendamiseks mikroteenustes loomingulise vaba ruumi palju... vähemalt teoreetiliselt

Siili ja rästiku võrdlemine

Praegu 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õstis API-de avaldamise vajadus taas küsimuse: millist annotatsioonistandardit peaksime oma töös kasutama?

Alguses näis, et lahendusi on kaks — enim levinud arendused RAML ja Swagger (või OAS). Kuid tegelikult selgus, et alternatiive on vähemalt mitte 2, vaid 3 või rohkem.

Ühest küljest on RAML — võimas ja efektiivne keel. Sellel on hästi rakendatud hierarhia ja pärand, mistõttu sobib see formaat rohkem suurte ettevõtete jaoks, kellel on vaja palju kirjeldusi — mitte ühte toodet, vaid palju mikroteenuseid, millel on ühised lepingute osad — autentimisskeemid, ühesugused andmetüübid, veateated.

Kuid RAMLi arendaja, ettevõte Mulesoft, liitus Open API konsortsiumiga, mis tegeleb arendamisega. Swagger. Seetõttu on RAML oma arengu peatunud. Kujutle, et Linuxi peamiste komponentide hooldajad on läinud Microsofti tööle. Selline olukord loob eeldused, et kasutada Swaggerit, mis areneb dünaamiliselt ja viimases — kolmandas versioonis — jõuab RAML-iga võrreldes paindlikkuses ja funktsionaalsuses praktiliselt samale tasemele.

Kuid on üks aga...

Kuidas selgus, ei ole kõik avatud lähtekoodiga tööriistad uuendatud OAS 3.0 versioonile. Go põhiste mikroteenuste jaoks on kõige kriitilisem kohandamise puudumine go-swagger uue standardi versiooni jaoks. Kuid erinevus Swagger 2 ja Swagger 3 vahel on hiiglaslik. Näiteks kolmandas versioonis on arendajad:

parandanud autentimise skeemide kirjeldust
lõpetanud JSON Schema toe
parandanud näidiste lisamise võimalust

Situatsioon on lõbus: standardi valimisel tuleks RAML-i, Swagger 2 ja Swagger 3 käsitleda eraldi alternatiividena. Ainult Swagger 2-l on hea OpenSource tööriistade tugi. RAML on väga paindlik... ja keeruline, samas kui Swagger 3-l on nõrk toetav kogukond, mistõttu peate kasutama isejuhitavaid või kommertslahendusi, mis tavaliselt on üsna kallid.

Kuid Swagger pakub mitmeid meeldivaid võimalusi, nagu valmisportaal. editor.swagger.io, kuhu saab laadida annotatsiooni ja saada selle visualiseerimise koos detailse kirjelduse, linkide ja seostega, siis RAML-i puhul sellist võimalust ei ole. Jah, võib uurida projekte GitHub-is, leida sealt analooge ja need ise üles seada. Kuid igal juhul peab keegi portaalist hoolitsema, mis ei ole algtaseme kasutamiseks või testivajaduste jaoks mugav. Lisaks on swagger rohkem "printsipiaalne", või siis liberaalne — seda saab genereerida koodikommentaaridest, mis muidugi on vastuolus API esitluse põhimõttega ja ei saa RAML-i tööriistade poolt toetust.

Oleme kunagi alustanud RAML-iga kui paindlikuma keelega, ja lõpuks pidime palju ise tegema. Näiteks kasutatakse ühes projektis tööriista ramlfications üksustes, mis toetab ainult RAML 0.8. Seega pidime lisama tugistruktuure, et tööriist saaks "seedida" RAML versiooni 1.0.

Kas on vaja valida?

Olles uurinud lahenduste ökosüsteemi täiendamist RAML-i kaudu, oleme jõudnud arusaamisele, et peame RAML-i konverteerima Swagger 2-sse, et teostada kogu automatiseerimine, valideerimine, testimine ja edasine optimeerimine just seal. See on suurepärane viis kasutada nii RAML-i paindlikkust kui ka Swaggeri kogukonna tööriistade tuge.

Selle probleemi lahendamiseks on olemas kaks avatud lähtekoodiga tööriista, mis peaksid tagama lepingute konverteerimise:

oas-raml-converter – praegu mitte toetatud utiliit. Töötades sellega, avastasime, et tal on mitmeid probleeme keeruliste RAML-idega, mis on “jaotatud” suure hulga failide vahel. See programm on kirjutatud JavaScriptis ja teostab rekursiivset läbitöötamist süntakspuu kaudu. Dünaamilise tüpiseerimise tõttu on selles koodis orienteerumine keeruline, seega otsustasime mitte raisata aega sureva utiliidi patch'ide kirjutamisele.
webapi-parser — sama ettevõtte tööriist, mis väidab, et suudab konverteerida kõike ja igal pool, ning igas suunas. Täna on lubatud tugi RAML 0.8-le, RAML 1.0-le ja Swagger 2.0-le. Kuid meie uurimise ajal oli utiliit jõudnud veel ÄÄRMISE toores ja kasutamiseks kõlbmatu. Arendajad loovad teatud tüüpi IR, mis võimaldab neil tulevikus kiiresti uusi standardsid lisada. Kuid seni see kõik lihtsalt ei tööta.

Ja see pole veel kõik raskused, millega me silmitsi seisame. Üks meie töövoo samme on kontrollida, et RAML hoiab, mis on allkastis vastavuses spetsifikatsiooniga. Proovisime mitmeid tööriistu. Üllatavalt, aga kõik nad kritiseerisid meie annotatsioone erinevates kohtades ja täiesti erinevate halvasõnadega. Ja mitte alati õigustatult :).

Lõpuks jäime vananenud projekti juurde, millel on mitmeid probleeme (mõnikord langeb tühjast kohast, tekib probleeme regulaarsete avaldiste kasutamisel). Seega ei leidnud me tasuta tööriistade põhjal valideerimise ja konverteerimise ülesannete lahendamisel head lahendust ning otsustasime kasutada ärilahendust. Tulevikus, kui OpenSource vahendid arenevad edasi, võib selle ülesande lahendamine muutuda lihtsamaks. Seni tundusid meelespea lõpuleviimise töö- ja ajakulud olulisemad kui kommertsteenuse hind.

Kokkuvõte

Kogu selle jutu juures soovime jagada oma kogemust ja rõhutada, et lepingute kirjeldamiseks vajaliku tööriista valimisel on oluline selgelt määratleda, mida te sellelt soovite, ja milline eelarve teil on. Kui unustada avatud lähtekood, on juba praegu saadaval suur hulk teenuseid ja tooteid, mis aitavad kontrollida, konverteerida ja valideerida. Need aga on kallid, mõnikord isegi väga kallid. Suure ettevõtte jaoks on sellised kulud talutavad, kuid idufirmale võivad need olla suur koormus.

Määratlege tööriistade komplekt, mida kavatsete hiljem kasutada. Näiteks kui peate lihtsalt lepingut kuvama, siis on lihtsam kasutada Swagger 2, millel on ilus API, sest RAML-i puhul peate teenuse ise üles seadma ja hooldama.
Mida rohkem teil on ülesandeid, seda laiem on vajadus tööriistade järele, ja need on erinevad erinevate platvormide jaoks. Seetõttu on parem tutvuda olemasolevate versioonidega, et teha valik, mis minimeerib teie tulevased kulud.

Tuleb tunnistada, et kõik olemasolevad ökosüsteemid on täiuslikud. Seetõttu, kui ettevõttes on fänne, kes armastavad töötada RAML-is, kuna "see võimaldab mõtteid paindlikumalt väljendada", või vastupidi, eelistavad Swaggerit, kuna "see on arusaadavam", on kõige parem jätta nad töötama selles, milles nad on harjunud ja soovivad, kuna igasuguste formaatide tööriistad vajavad lihvimist.

Mis puutub meie kogemusse, siis järgmistes postitustes räägime sellest, milliseid - staatilisi ja dünaamilisi kontrollimisi teeme meie RAML-Swagger arhitektuuri põhjal, samuti sellest, millist dokumentatsiooni genereerime lepingutest ning kuidas see kõik töötab.

Ainult registreeritud kasutajad saavad küsitluses osaleda. Logige sisse, palun.