🥇Tehát RAML vagy OAS (Swagger)?

A dinamikus mikroszervizek világában bármi megváltozhat – bármely komponenst át lehet írni más nyelven, különböző keretrendszereket és architektúrákat használva. Csak a szerződéseknek kell állandónak maradniuk, hogy a mikroszervizzel külsőleg folyamatosan lehetett interakcióba lépni, függetlenül a belső metamorfózisoktól. Ma arról fogunk beszélni, hogy miért nehéz a szerződések leírásának formátumát választani, és megosztjuk a felfedezett artefaktumokat.

A bejegyzést készítette Anna Melekhova és Vladimir Lapatin

Mikroszervizek. Az Acronis Cyber Cloud fejlesztése során rájöttünk, hogy nem élhetünk nélkülük. A mikroszerviz tervezése lehetetlen a szerződés formalizálása nélkül, amely a mikroszerviz interfészeként funkcionál.

De amikor a termék több mint egy komponenst tartalmaz, és a szerződés fejlesztése rendszeres tevékenységgé válik, elkerülhetetlenül az optimalizálási folyamaton kezdjük gondolkodni. Nyilvánvalóvá válik, hogy az interfész (szerződés) és az implementáció (mikroszerviz) összhangban kell legyen egymással, hogy a különböző komponenseknek ugyanazt a feladatot azonos módon kell elvégezniük, és hogy a központosított döntéshozatal nélkül minden csapatnak újra és újra időt kell költenie ezek megszerzésére.

Az Amazon mikroszervizes architektúrája tweetből Werner Vogels, az Amazon CTO-jának
Mi is a dilemma? De facto két módon léteznek a mikroszervizek közötti interakciók – HTTP Rest és a Google által kifejlesztett gRPC. A Google technológiai stackjébe való bevonódás elkerülése érdekében a HTTP Rest mellett döntöttünk. A HTTP REST szerződésekhez való annotációk általában az alábbi két formátum egyikében találhatók: RAML és OAS, amely korábban Swagger néven volt ismert. Ezért minden fejlesztőcsapatnak szembe kell néznie azzal a szükséggel, hogy válasszon az egyik szabvány mellett. De ahogy kiderült, ez a választás nem mindig könnyű.

Miért van szükség annotációkra?

Az annotáció arra szolgál, hogy a külső felhasználó könnyen megértse, mit lehet tenni a szolgáltatással a HTTP interfésze révén. Az alapvető szinten az annotációnak legalább az elérhető erőforrások listáját, azok HTTP metódusait, a kérés törzsét, a paraméterek felsorolását, a szükséges és támogatott fejlécek megjelölését, valamint a visszatérési kódokat és a válaszformátumokat kell tartalmaznia. Az annotációs szerződés rendkívül fontos eleme a szóbeli leírásuk is (“mi történik, ha ezt a query-paramétert hozzáadjuk a kéréshez?”, “mikor tér vissza a 400-as kód?”)

Mindazonáltal, amikor sok mikroszolgáltatás fejlesztéséről van szó, érdemes további előnyöket kinyerni az írt annotációkból. Például a RAML/Swagger alapján generálhatunk kliens- és szerveroldali kódot számos programozási nyelven. Ráadásul automatikusan dokumentációt is kaphatunk a mikroszolgáltatásról, és feltölthetjük azt a fejlesztői portálunkra :).

A szerződés strukturált leírásának példája

Ritkábban találkozni azzal a gyakorlattal, hogy mikroszolgáltatásokat tesztelnek a szerződések leírásai alapján. Ha írtál annotációt és komponenst is, akkor létrehozhatsz egy automatikus tesztet, amely ellenőrzi a szolgáltatás megfelelő működését különböző típusú bemeneti adatokkal. Visszaad-e a szolgáltatás olyan válaszkódot, amely nincs leírva az annotációban? Képes-e helyesen kezelni a szándékosan hibás adatokat?

Továbbá, a szerződések és az annotációk vizualizációs eszközeinek minőségi megvalósítása lehetővé teszi a mikroszolgáltatásokkal való munkavégzés egyszerűsítését. Tehát, ha az építész megfelelően írta le a szerződést, akkor annak alapján a dizájnerek és a fejlesztők anélkül integrálják a szolgáltatást más termékekbe, hogy további időráfordításra lenne szükségük.

A RAML és az OAS olyan lehetőségeket kínál, amelyek lehetővé teszik nem szabványos metaadatok hozzáadását más eszközök működéséhez (például, így történik az OAS-ban).

Összességében a szerződések mikroszolgáltatásokban való alkalmazására hatalmas a kreativitás területe... legalábbis elméletileg

A sündisznó és a vipera összehasonlítása

Jelenleg az Acronis fejlesztési prioritása az Acronis Cyber Platform fejlesztése. Az Acronis Cyber Platform új integrációs pontokat nyújt harmadik féltől származó szolgáltatásoknak az Acronis Cyber Cloud és az ügynöki részek között. Bár a RAML-ben leírt belső API-jaink megfeleltek, az API közzétételének szükségessége ismét felvetette a kérdést: melyik annotációs szabványt érdemes használni a munkánkhoz?

Kezdetben úgy tűnt, hogy két megoldás létezik - a legelterjedtebb RAML és Swagger (vagy OAS). De valójában kiderült, hogy legalább három vagy annál több alternatíva létezik.

Egyrészt itt van a RAML - egy erős és hatékony nyelv. Jól megvalósítja a hierarchiát és az öröklődést, így ez a forma jobban megfelel a nagy vállalatoknak, amelyeknek sok leírásra van szükségük - nem egy termékre, hanem sok mikroszolgáltatásra, amelyek közös szerződéses elemekkel rendelkeznek - autentikációs sémák, azonos típusú adatok, hibák törzsei.

De a RAML fejlesztője, a Mulesoft, csatlakozott az Open API konzorciumhoz, amely a fejlődési lehetőségekkel foglalkozik. Swagger. Ezért a RAML leállította a fejlődését. Ha elképzeljük az esemény formátumát, gondoljunk arra, hogy a Linux fő komponenseinek karbantartói átmentek dolgozni a Microsofthoz. Ez a helyzet kedvez a Swagger használatának, amely dinamikusan fejlődik, és a legújabb - harmadik verziójában - gyakorlatilag utoléri a RAML-t rugalmasság és funkcionális szempontból.

Ha nem lenne egy kis probléma...

Kiderült, hogy nem minden open-source eszköz frissült az OAS 3.0 verzióra. A Go alapú mikroszolgáltatások esetében a legkritikusabb a go-swagger új szabvány frissítésének hiánya. Azonban a különbség a Swagger 2 és Swagger 3 között - óriási. Például, a harmadik verzióban a fejlesztők:

javították az autentikációs sémák leírását
befejezték a JSON Schema támogatását
feldobták a példák hozzáadásának lehetőségét

A helyzet vicces: a szabvány kiválasztásánál a RAML-t, Swagger 2-t és Swagger 3-t külön alternatívaként kell figyelembe venni. Ebben az esetben csak a Swagger 2-nek van jó open-source eszköztámogatása. A RAML - nagyon rugalmas... és bonyolult, míg a Swagger 3 közösségi támogatása gyenge, így a saját fejlesztésű vagy kereskedelmi megoldások eszközeivel kell dolgoznia, amelyek általában elég drágák.

Miközben a Swagger rengeteg kellemes lehetőséget kínál, mint például a kész portál editor.swagger.io, ahová fel lehet tölteni egy annotációt, és részletes leírást, linkeket és kapcsolatokat kaphatunk róla. A RAML esetében azonban nincs ilyen lehetőség, mivel sokkal alapvetőbb és kevésbé felhasználóbarát. Persze lehet kutatni a GitHub projektei között, találni ott egy analógot, és saját kezűleg telepíteni. Mindenesetre valakinek támogatnia kell a portált, ami nem annyira kényelmes alapvető használatra vagy tesztelési igényekre. Ezen kívül a swagger „elnézőbb” vagy „liberálisabb” — a kód megjegyzéseiből generálható, ami nyilvánvalóan szembemegy az API first elvével, és egyik RAML eszköz sem támogatja.

Mi időben a RAML-lal kezdtünk dolgozni, mint egy rugalmasabb nyelvvel, és végül sok mindent saját kezűleg kellett megoldanunk. Például az egyik projektben egy ramlfications nevű eszközt használunk az egység tesztekhez, amely csak a RAML 0.8-at támogatja. Így hát át kellett hidalni, hogy az eszköz „megehesse” a RAML 1.0 verzióját.

Szükséges-e választani?

Miután sokat kísérleteztünk a RAML exoszisztéma bővítésével, arra a következtetésre jutottunk, hogy a RAML-t Swagger 2-re kell konvertálnunk, és már ezen végezni el az automatizálást, ellenőrzést, tesztelést és a további optimalizálást. Ez egy jó módja annak, hogy egyszerre kihasználjuk a RAML rugalmasságát és a Swagger közösségi eszközeinek támogatását.

Erre a feladatra két OpenSource eszköz áll rendelkezésre, amelyek a szerződések konvertálását kell, hogy biztosítsák:

oas-raml-converter – jelenleg nem támogatott eszköz. Munka közben rájöttünk, hogy számos problémája van a bonyolult RAML fájlokkal, amelyek nagy mennyiségű fájlra vannak szétterítve. Ez a program JavaScript-ben íródott, és rekurzív bejárást végez a szintaktikai fában. A dinamikus típusosság miatt nehéz kibogozni ezt a kódot, így úgy döntöttünk, hogy nem pazaroljuk az időnket a kihaló eszköz javítására.
webapi-parser — ugyanannak a cégnek az eszköze, amely azt állítja, hogy kész konvertálni mindent és minden irányba. Jelenleg támogatja a RAML 0.8, RAML 1.0 és Swagger 2.0 verziókat. Azonban a kutatásunk idején az eszköz még TIMÁR nyers volt és használhatatlan. A fejlesztők egyfajta IR, ami lehetővé teszi számukra, hogy a jövőben gyorsan új szabványokat adjanak hozzá. De jelenleg ez az egész egyszerűen nem működik.

És ez még nem minden nehézség, amivel találkoztunk. A folyamatunk egyik lépése annak ellenőrzése, hogy a RAML a tárolóból helyes-e a specifikációval szemben. Több eszközt is kipróbáltunk. Meglepő módon mindegyik valamilyen különböző maró kifejezéssel kritizálta a megjegyzéseinket. És nem mindig megalapozottan :) .

Végül egy elavult projektre esett a választásunk, amely szintén számos problémával küzd (néha a semmiből összeomlik, és problémái vannak a reguláris kifejezésekkel). Így nem találtunk módot a validálás és konvertálás feladatainak megoldására ingyenes eszközök segítségével, és úgy döntöttünk, hogy kereskedelmi eszközt használunk. A jövőben, amikor az OpenSource eszközök kifinomultabbá válnak, talán egyszerűbbé válik ennek a feladatnak a megoldása. Jelenleg azonban a „finomhangolás” munkaidő és költség igénye jelentősebbnek tűnt számunkra, mint a kereskedelmi szolgáltatás költsége.

Zárás

Mindezek után szeretnénk megosztani tapasztalatainkat, és megjegyezni, hogy az eszköz kiválasztása előtt világosan meg kell határozni, mit várunk el tőle, és mekkora költségvetést vagyunk hajlandóak ráfordítani. Ha eltekintünk az OpenSource megoldásoktól, már most rengeteg szolgáltatás és termék létezik, amelyek segíthetnek a validálásban, konvertálásban. De ezek drágák, néha pedig nagyon drágák. Egy nagy cég számára ezek a költségek elviselhetők, de egy startup számára hatalmas terhet jelenthetnek.

Határozzon meg egy eszközkészletet, amelyet később használni fog. Például, ha csak a szerződést szeretné megjeleníteni, a Swagger 2 használata egyszerűbb lesz, mivel szép API-ja van, hiszen a RAML esetében saját magának kell felépítenie és karbantartania a szolgáltatást.
Minél több feladatot kell megoldania, annál nagyobb lesz az igény az eszközökre, és ezek különbözőek a különböző platformokon, ezért érdemes előre megismerkedni a rendelkezésre álló verziókkal, hogy minimalizálja a jövőbeli költségeit.

De el kell ismerni, hogy a ma létező ökoszisztémák mind tökéletlenek. Ezért, ha a cégnél vannak olyan rajongók, akik a RAML-t kedvelik, mert "rugalmasságot ad a gondolatok kifejezésében", vagy éppen ellenkezőleg, akik a Swaggert kedvelik, mert "érthetőbb", a legjobb, ha hagyjuk őket abban dolgozni, amiben megszokták, és amit szeretnének, mert bármelyik formátum eszköztára finomításra szorul.

A mi tapasztalatainkról a következő posztokban beszélni fogunk arról, hogy milyen statikus és dinamikus ellenőrzéseket végzünk a RAML-Swagger architektúra alapján, valamint arról, hogy milyen dokumentációt generálunk a szerződésekből, és hogyan működik mindez.

Csak a regisztrált felhasználók vehetnek részt a szavazáson. Kérem, jelentkezzen be., kérem.