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

Dünaamilises mikrosüsteemide maailmas võib kõik muutuda — iga komponent võib olla kirjutatud teises keeles, kasutades teisi raamistikke ja arhetüüpe. Ainsateks muutumatuks jäävateks elementideks peavad olema lepingud, et oleks võimalik mikrosüsteemiga suhelda väljaspool setkust kindlal alusel, olenemata sisemistest metamorfoosidest. Täna räägime oma probleemist lepingute kirjeldamise formaadi valimisel ja jagame leitud artefakte.

Postituse koostas Anna Melekova ja Vladimir Lapatin

Mikrosüsteemid. Acronis Cyber Cloud'i arendamisel mõistsime, et me ei saa neist mööda minna. Ja mikrosüsteemi projekteerimine on võimatu ilma lepingu formaliseerimiseta, mis on mikrosüsteemi liides.

Kuid kui toote sees on rohkem kui üks komponent ning lepingu arendamine muutub regulaarseks tegevuseks, hakkad automaatselt mõtlema protsessi optimeerimisele. On ilmne, et liides (leping) ja rakendus (mikrosüsteem) peavad üksteisele vastama, et erinevad komponendid peaksid tegema samu asju samal moel, ja et ilma kõigi nende otsuste keskse vastuvõtu korral peab iga meeskond taas ja taas aega kulutama nende saamiseks.

Amazon'i mikrosüsteemide skeem tweet Werner Vogels, Amazon'i CTO
Kus seisneb dilemma? De facto on mikrosüsteemide suhtlemiseks kaks viisi – HTTP Rest ja Google'i gRPC. Soovimata sattuda Google'i tehnoloogiakuhja, valisime HTTP Rest. HTTP REST lepingute annotatsioonid kirjeldatakse kõige sagedamini kahes formaadis: RAML ja OAS, varem tuntud kui Swagger. Seega seisab iga arendajate meeskond silmitsi vajadusega valida ühe standardi kasuks. Kuid, nagu selgus, võib see valik olla väga keeruline.

Miks on annotatsioonid vajalikud?

Annotatsioon on vajalik, et väline kasutaja saaks hõlpsasti aru, mida saab teie teenusega teha läbi selle HTTP-liidese. See tähendab, et alusel peab annotatsioon sisaldama vähemalt loetelu saadaval olevatest ressurssidest, nende HTTP-meetoditest, päringu kehadest, parameetrite loendist, nõutud ja toetatavate pealkirjade määratlemisest, samuti tagastuskoode ja vastuse vormate. Äärmiselt oluline on ka lepingute annotatsioonide sõnaline kirjeldus ("mida juhtub, kui lisada see päringu parameeter?", "millisel juhul tagastatakse kood 400?")

Kuid kui rääkida suure hulga mikroteenuste arendamisest, tahaks lisaks tuua ka rohkem kasu kirjutatud annotatsioonidest. Näiteks RAML/Swaggeri alusel saab genereerida nii kliendi- kui serverikoodi paljudes programmeerimiskeeltes. Samuti on võimalik automaatselt saada mikroteenuse dokumentatsiooni ja laadida see teie arendaja portaalile : ).

Struktureeritud lepingute kirjelduse näide

Harvemini on praktika testida mikroteenuseid lepingute kirjelduste põhjal. Kui olete kirjutanud nii annotatsiooni kui ka komponendi, on võimalik luua automaatne test, mis kontrollib teenuse töö sobivust erinevate tüüpi andmete sisenemisel. Kas teenus tagastab vastuskoodi, mida annotatsioonis ei ole kirjeldatud? Kas see suudab õigesti töödelda teadlikult valeid andmeid?

Lisaks võimaldab kvaliteetne rakendamine mitte ainult lepingute, vaid ka annotatsioonide visualiseerimise tööriistade lihtsustamist mikroteenuste töös. See tähendab, et kui arhitekt kirjeldas lepingut kvaliteetselt, saavad disainerid ja arendajad teenust teistesse toodetesse rakendada ilma täiendavate ajakuludeta.

Töö jaoks täiendavates tööriistades võivad nii RAML kui OAS võimaldada lisada metainfot, mida standard ei ennusta (näiteks nii tehakse OAS-is).

Üldiselt on lepingute rakendamiseks mikroteenustes loovuse jaoks tohutu ruum… vähemalt teoreetiliselt

Siili ja rästiku võrdlemine

Praegu 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ätnud, tõstis vajadus API avaldamise küsimuse: milline annotatsioonistandard oleks meie töö jaoks parem?

Esialgu tundus, et lahendusi on kaks — enim levinud arendused RAML ja Swagger (või OAS). Kuid tegelikult selgus, et alternatiive on vähemalt 2, vaid 3 või enam.

Ühelt poolt on olemas RAML – võimas ja efektiivne keel. Sellel on hästi realiseeritud hierarhia ja pärimine, nii et see formaat sobib paremini suurtele ettevõtetele, kellel on palju kirjeldusi — mitte üks toode, vaid palju mikroteenuseid, millel on ühised lepingu osad — autentimise skeemid, samad andmetüübid, vigade kehad.

Kuid RAMLi arendaja, ettevõte Mulesoft, liitus Open API konsortsiumiga, mis tegeleb arendamisega Swagger. Seetõttu on RAMLi areng peatunud. Kujutage ette, et Linuxi peamiste komponentide hooldajad on tööle läinud Microsofti. Selline olukord loob eeldused Swaggeri kasutamiseks, mis areneb dünaamiliselt ja praeguses — kolmandas versioonis — saavutab RAML-i paindlikkuse ja funktsionaalsuse.

Kuid on üks aga...

Kuidas osutus, et kaugeltki mitte kõik avatud lähtekoodiga utiliidid pole uuendatud versioonile OAS 3.0. Go mikroteenuste jaoks on kõige kriitilisem OAS 3.0. standardi uus versiooniga kohandamise puudumine go-swagger . Kuid erinevus Swagger 2 ja Swagger 3 vahel on — hiiglaslik. Näiteks kolmandas versioonis parandasid arendajad:

parandasid autentimisskeemide kirjeldust
lõpetasid JSON Schema toe
parandasid näidete lisamise võimalust.

Oleme naljakas olukorras: standardi valimisel tuleb RAMLi, Swagger 2 ja Swagger 3 käsitleda kui eraldi alternatiive. Samal ajal on ainult Swagger 2-le head avatud lähtekoodiga tööriistade toetust. RAML on väga paindlik... ja keeruline, samas kui Swagger 3-l on nõrk toetamine kogukonna poolt, nii et peate kasutama oma arendustööriistu või kommertslahendusi, mis on tavaliselt üsna kallid.

Samas, kui Swagger pakub palju meeldivaid võimalusi, nagu valmis portaal. editor.swagger.io, kuhu saab laadida annotatsiooni ja saada selle visualiseerimise koos üksikasjalike kirjelduse, linkide ja seostega, ei ole sellist võimalust RAML-l, mis on rohkem fundamentaalne ja vähem kasutajasõbralik. Jah, võite otsida midagi GitHubi projektide hulgast, leida sealt sarnase ja selle ise üles seada. Kuid igal juhul peab keegi portaali toetama, mis ei ole nii mugav põhikasutuse või testimise vajaduste jaoks. Lisaks on swagger enam „printsiipidevaba”, või ütleme loominguline - seda saab genereerida koodis olevatest kommentaaridest, mis muidugi on vastuolus API first printsiibiga ja ei ole toetatud üheski RAML utiliidis.

Oleme kunagi alustanud RAML-iga, kui paindliku keelega, ja lõppkokkuvõttes pidime palju ise tegema. Näiteks ühes projektis kasutatakse utiliiti ramlfications ühiktestides, mis toetab ainult RAML 0.8. Nii tuli lisada kühveldamisi, et utiliit saaks „sööda” RAML versiooni 1.0.

Kas on vaja valida?

Pärast lahenduste ökosüsteemi RAML lähedal siiski tulime järeldusele, et peame konverteerima RAML Swagger 2-ks ja seejärel teostama kõik automatiseerimise, kontrollimise, testimise ja järgnevate optimeerimiste selles. See on hea viis kasutada nii RAML-i paindlikkust kui ka Swaggeri kogukonna tööriistade toetust.

Selle ülesande lahendamiseks on olemas kaks OpenSource tööriista, mis peaksid tagama lepingute konversiooni:

oas-raml-converter – praegu hooldamata utiliit. Töö käigus avastasime, et sellel on mitmeid probleeme keeruliste RAML-idega, mis on „jaotatud” suure hulga failide vahel. See programm on kirjutatud JavaScriptis ja teostab süntaksipuu rekursiivset läbimist. Dünaamilise tüüpimise tõttu on selle koodiga keeruline toime tulla, nii et otsustasime mitte raisata aega sureva utiliidi plaastrite kirjutamisele.
webapi-parser — sama ettevõtte tööriist, mis väidab, et suudab konverteerida kõike ja kõiki, veelgi enam, igasse suunda. Tänaseks on teada RAML 0.8, RAML 1.0 ja Swagger 2.0 tugi. Kuid meie uurimise hetkel oli utiliit endiselt ÄÄRMISELT toores ja kasutamiseks sobimatu. Arendajad loovad oma mõnes mõttes IR, mis võimaldab neil tulevikus kiiresti uusi standardeid lisada. Kuid seni lihtsalt ei tööta see.

Ja need ei ole kõik raskused, millega me silmitsi seisame. Üks meie protsessi samme on kontrollida, kas RAML meie repostas vastab spetsifikatsioonile. Oleme proovinud mitmeid tööriistu. Üllatav, kuid kõik need skeemitavad meie annotatsioonide üle erinevates kohtades ja täiesti erinevate inetute sõnadega. Samuti ei pruugi see alati asjakohane olla : ).

Lõpuks peatusime praegu aegunud projektile, millel on samuti mitmeid probleeme (mõnikord jookseb see kokku igasugustel põhjustel, tal on probleeme regulaaravaldiste töötlemisega). Seega ei leidnud me tasuta tööriistade põhjal viisi valideerimise ja konversiooni ülesannete lahendamiseks, ja otsustasime kasutada kommertstootes. Tulevikus, kui OpenSource vahendid arenevad, võib selle ülesande lahendamine muutuda lihtsamaks. Ainult praegu tundusid meeleheide ja ajakulu, mis kulus

Kokkuvõte

Pärast seda soovime jagada oma kogemust ja märkida, et enne tööriista valimist lepingute kirjeldamiseks tuleb selgelt välja selgitada, mida te soovite, ja millise eelarve olete valmis investeerima. Kui unustada OpenSource, on juba praegu saadaval palju teenuseid ja tooteid, mis aitavad kontrollida, konverteerida ja valideerida. Kuid need on kallid, mõnikord väga kallid. Suurettevõtte jaoks on sellised kulud talutavad, kuid idufirma jaoks võivad need olla suur koormus.

Määrake tööriistade komplekt, mida kavatsete hiljem kasutada. Näiteks, kui teil on lihtsalt vaja lepingut kuvada, on lihtsam kasutada Swagger 2, millel on ilus API, kuna RAML-is peate teenuse ise üles ehitama ja seda hooldama.
Mida rohkem ülesandeid teil on, seda laiem on tööriistade vajadus, ja need on erinevad erinevate platvormide jaoks. Parim on tutvuda olemasolevate versioonidega kohe, et teha valik, mis minimaliseerib teie tulevased kulud.

Kuid tuleb tunnustada, et kõik tänapäeval eksisteerivad ökosüsteemid on puudulikud. Seega, kui ettevõttes on entusiastid, kes armastavad töötada RAML-is, sest "see võimaldab mõtteid paindlikumalt väljendada", või vastupidi, eelistavad Swaggerit, sest "see on arusaadavam", on kõige parem lasta neil töötada sellega, millega nad on harjunud ja mida nad soovivad, sest igas formaadis tööriistade kasutamine nõuab viimistlemist.

Mis puudutab meie kogemust, siis järgmistes postitustes räägime, milliseid - staatilisi ja dünaamilisi kontrollimisi me teostame meie RAML-Swagger arhitektuuri alusel, samuti millist dokumentatsiooni me genereerime lepingutest ja kuidas see kõik toimib.

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