A mikroszolgáltatások dinamikus világában bármi megváltozhat – bármely komponens átírható más nyelven, más keretrendszer és architektúra használatával. Csak a szerződések maradjanak változatlanok, hogy a mikroszolgáltatással valamilyen állandó jelleggel, a belső metamorfózisoktól függetlenül, kívülről is kommunikálni lehessen. Ma pedig a szerződések leírásának formátumának kiválasztásával kapcsolatos problémánkról fogunk beszélni, és megosztjuk a talált műtermékeket.
Hozzászólás előkészítve и
Mikroszolgáltatások. Az Acronis Cyber Cloud fejlesztése során rájöttünk, hogy nem kerülhetjük el őket. A mikroszolgáltatás tervezése pedig lehetetlen a szerződés formalizálása nélkül, amely a mikroszolgáltatás interfészét jelenti.
Ám amikor egy termék egynél több komponenst tartalmaz, és a szerződésfejlesztés rendszeres tevékenységgé válik, nem lehet nem gondolkodni a folyamatoptimalizáláson. Nyilvánvalóvá válik, hogy az interfésznek (szerződésnek) és a megvalósításnak (mikroszolgáltatásnak) meg kell felelnie egymásnak, hogy a különböző komponenseknek ugyanazokat a dolgokat ugyanúgy kell elvégezniük, és mindezen döntések központi döntéshozatala nélkül minden csapat kénytelen lesz töltsön időt újra és újra, hogy megszerezze őket.
Amazon mikroszolgáltatások diagramja innen Werner Vogelis, az Amazon műszaki igazgatója
Mi a dilemma? Valójában két módja van a mikroszolgáltatások interakciójának – HTTP Rest és gRPC a Google-tól. Mivel nem akartunk belemerülni a Google technológiai halmazába, a HTTP Rest-et választottuk. A HTTP REST szerződéses megjegyzéseket leggyakrabban két formátum egyikében írják le: RAML és OAS, korábban Swagger néven, ezért minden fejlesztőcsapatnak szembe kell néznie azzal, hogy valamelyik szabványt válassza. De mint kiderült, ezt a választást nagyon nehéz lehet meghozni.
Miért van szükség megjegyzésekre?
Az annotációra azért van szükség, hogy egy külső felhasználó könnyen rájöhessen, mit lehet tenni az Ön szolgáltatásával a HTTP-felületen keresztül. Azaz alapszinten az annotációnak tartalmaznia kell legalább az elérhető erőforrások listáját, azok HTTP metódusait, a kérés törzseit, a paraméterek listáját, a szükséges és támogatott fejlécek megjelölését, valamint a visszatérési kódokat és válaszformátumokat. A szerződéses megjegyzés rendkívül fontos eleme a szóbeli leírásuk ("mi történik, ha hozzáadja ezt a lekérdezési paramétert a kéréshez?", "Milyen esetben ad vissza 400-as kódot?")
Ha azonban nagyszámú mikroszolgáltatás fejlesztéséről van szó, további értéket szeretne kivonni az írott megjegyzésekből. Például a RAML/Swagger alapján számos programozási nyelven generálhat kliens- és szerverkódot is. Ezenkívül automatikusan megkaphatja a mikroszolgáltatás dokumentációját, és feltöltheti a fejlesztői portáljára :).
Példa strukturált szerződésleírásra
Kevésbé elterjedt a mikroszolgáltatások szerződésleírások alapján történő tesztelésének gyakorlata. Ha annotációt és komponenst is írt, akkor létrehozhat egy automatikus tesztet, amely különféle típusú bemeneti adatokkal ellenőrzi a szolgáltatás megfelelőségét. A szolgáltatás olyan válaszkódot ad vissza, amely nincs leírva a megjegyzésben? Képes lesz a nyilvánvalóan hibás adatok helyes feldolgozására?
Sőt, nemcsak maguknak a szerződéseknek, hanem a megjegyzések megjelenítésére szolgáló eszközöknek a minőségi megvalósítása is lehetővé teszi a mikroszolgáltatással való munka egyszerűsítését. Vagyis ha az építész a szerződést minőségileg leírta, az alapján a tervezők, fejlesztők további időköltség nélkül más termékekben is megvalósítják a szolgáltatást.
A további eszközök engedélyezéséhez a RAML és az OAS is képes olyan metaadatok hozzáadására, amelyeket a szabvány nem biztosít ().
Általánosságban elmondható, hogy a mikroszolgáltatásokra vonatkozó szerződések felhasználásában óriási a kreativitás lehetősége... legalábbis elméletben.
A sündisznó és a kígyó összehasonlítása
Jelenleg az Acronis kiemelt fejlesztési területe az Acronis Cyber Platform fejlesztése. Az Acronis Cyber Platform a harmadik féltől származó szolgáltatások új integrációs pontja az Acronis Cyber Clouddal és az ügynökrésszel. Bár elégedettek voltunk a RAML-ben leírt belső API-jainkkal, az API közzétételének szükségessége ismét felvetette a választás kérdését: melyik annotációs szabványt érdemes a legjobban használni munkánkhoz?
Kezdetben úgy tűnt, hogy két megoldás létezik – a leggyakoribb fejlesztések a RAML és a Swagger (vagy OAS) voltak. De valójában kiderült, hogy legalább nem 2 alternatíva van, hanem 3 vagy több.
Egyrészt ott van a RAML – egy erőteljes és hatékony nyelv. Jól valósítja meg a hierarchiát és az öröklődést, így ez a formátum jobban megfelel a nagy cégeknek, amelyeknek sok leírásra van szükségük - vagyis nem egy termékre, hanem sok olyan mikroszolgáltatásra, amelyeknek közös szerződésrészei vannak - hitelesítési sémák, azonos adattípusok, hibatestek .
A RAML fejlesztője, a Mulesoft azonban csatlakozott a fejlesztés alatt álló Open API konzorciumhoz. . Ezért a RAML felfüggesztette fejlesztését. Az esemény formátumának elképzeléséhez képzeljük el, hogy a fő Linux-összetevők karbantartói a Microsoftnál dolgoztak. Ez a helyzet megteremti az előfeltételeket a dinamikusan fejlődő Swagger használatához, amely a legújabb - harmadik verzióban - gyakorlatilag utoléri a RAML-t rugalmasságban és funkcionalitásban.
Ha nem is egynek, de...
Mint kiderült, nem minden nyílt forráskódú segédprogramot frissítettek OAS 3.0-ra. A Go mikroszolgáltatásainál a legkritikusabb dolog az alkalmazkodás hiánya lesz a szabvány legújabb verziójához. A Swagger 2 és a Swagger 3 közötti különbség azonban az . Például a harmadik verzióban a fejlesztők:
- a hitelesítési sémák jobb leírása
- JSON-séma támogatás
- frissítette a példák hozzáadásának képességét
A helyzet vicces: a szabvány kiválasztásakor külön alternatívaként kell figyelembe venni a RAML-t, a Swagger 2-t és a Swagger 3-at. Azonban csak a Swagger 2 támogatja jól a nyílt forráskódú eszközöket. A RAML nagyon rugalmas... és összetett, a Swagger 3-at pedig a közösség nem támogatja, ezért szabadalmaztatott eszközöket vagy kereskedelmi megoldásokat kell használnia, amelyek általában meglehetősen drágák.
Sőt, ha sok szép funkció van a Swaggerben, mint például egy kész portál , amelyre fel lehet tölteni egy annotációt és annak vizualizációját részletes leírással, linkekkel és kapcsolatokkal ellátva, akkor az alapvetőbb és kevésbé barátságos RAML számára nincs ilyen lehetőség. Igen, kereshet valamit a GitHubon lévő projektek között, találhat ott analógot, és saját maga telepítheti. Mindenesetre valakinek karban kell tartania a portált, ami nem annyira kényelmes az alapvető használatra vagy tesztelési igényekre. Ráadásul a swagger „elvtelenebb”, vagy liberálisabb – a kód megjegyzéseiből generálható, ami természetesen ellenkezik az API first elvével, és egyik RAML segédprogram sem támogatja.
Egy időben elkezdtünk dolgozni a RAML-lel, mint rugalmasabb nyelvvel, és ennek következtében sok mindent magunknak kellett megcsinálnunk. Például az egyik projekt a segédprogramot használja egységtesztekben, amely csak a RAML 0.8-at támogatja. Így hát mankókat kellett hozzáadnunk ahhoz, hogy a segédprogram „megegye” a RAML 1.0-s verzióját.
Választani kell?
Miután dolgoztunk a RAML megoldások ökoszisztémájának befejezésén, arra a következtetésre jutottunk, hogy a RAML-t át kell alakítanunk Swagger 2-be, és el kell végeznünk benne az összes automatizálást, ellenőrzést, tesztelést és az azt követő optimalizálást. Ez egy jó módszer a RAML rugalmasságának és a Swagger közösségi eszköztámogatásának kihasználására.
A probléma megoldásához két nyílt forráskódú eszköz létezik, amelyek szerződéskonverziót biztosítanak:
- jelenleg nem támogatott segédprogram. Munka közben rájöttünk, hogy számos problémája van az összetett RAML-ekkel, amelyek nagyszámú fájlon „terjedtek el”. Ez a program JavaScriptben íródott, és rekurzív bejárást hajt végre egy szintaktikai fán. A dinamikus gépelés miatt nehéz megérteni ezt a kódot, ezért úgy döntöttünk, hogy nem pazaroljuk az időt egy haldokló segédprogram javításainak írására.
- - ugyanattól a cégtől származó eszköz, amely azt állítja, hogy kész bármit és mindent átalakítani, bármilyen irányba. A mai napig bejelentették a RAML 0.8, RAML 1.0 és Swagger 2.0 támogatását. Kutatásunk idején azonban a hasznosság még mindig az volt nedves és használhatatlan. A fejlesztők egyfajta , lehetővé téve számukra, hogy a jövőben gyorsan új szabványokat adjanak hozzá. De eddig egyszerűen nem működik.
És ez nem minden nehézség, amellyel szembesültünk. A folyamat egyik lépése annak ellenőrzése, hogy a tárolóból származó RAML megfelel-e a specifikációnak. Több segédprogramot is kipróbáltunk. Meglepő módon mindannyian más-más helyen és teljesen más rossz szavakkal káromkodtak a jegyzeteinkre. És nem mindig a lényegre:).
Végül egy már elavult projekt mellett döntöttünk, aminek szintén számos problémája van (néha hirtelen összeomlik, gondjai vannak a reguláris kifejezésekkel való munka során). Így nem találtuk meg az ingyenes eszközökön alapuló validálási és átalakítási problémák megoldásának módját, és egy kereskedelmi segédprogram mellett döntöttünk. A jövőben, ahogy az OpenSource eszközök egyre érettebbé válnak, ez a probléma könnyebben megoldhatóvá válhat. Mindeközben a „kikészítés” munka- és időköltsége jelentősebbnek tűnt számunkra, mint egy kereskedelmi szolgáltatás költsége.
Következtetés
Mindezek után szerettük volna megosztani tapasztalatainkat, és megjegyezni, hogy mielőtt kiválasztaná a szerződésleíró eszközt, egyértelműen meg kell határoznia, hogy mit szeretne belőle, és milyen költségvetést hajlandó befektetni. Ha megfeledkezünk az OpenSource-ról, máris rengeteg szolgáltatás és termék létezik, amelyek segítenek az ellenőrzésben, a konvertálásban és az érvényesítésben. De drágák, és néha nagyon drágák. Egy nagy cégnél az ilyen költségek elviselhetőek, de egy startup számára nagy teherré válhatnak.
Határozza meg a később használni kívánt eszközkészletet. Például, ha csak egy szerződést kell megjeleníteni, akkor egyszerűbb lesz a Swagger 2 használata, aminek gyönyörű API-ja van, mert a RAML-ben magának kell felépítenie és karbantartania a szolgáltatást.
Minél több feladata van, annál szélesebb körű lesz az eszközök iránti igény, és ezek a különböző platformokon eltérőek, és jobb, ha azonnal megismerkednek az elérhető verziókkal, hogy a jövőben olyan választást hozhassanak, amely minimalizálja költségeit.
De érdemes felismerni, hogy minden ma létező ökoszisztéma tökéletlen. Ezért ha vannak a társaságban olyan rajongók, akik szeretnek a RAML-ben dolgozni, mert „az rugalmasabban fejezheti ki gondolatait”, vagy éppen ellenkezőleg, inkább a Swaggert részesíti előnyben, mert „az egyértelműbb”, akkor a legjobb, ha hagyjuk őket dolgozni. mikben vannak. Megszokták és akarják, mert bármelyik formátum eszközei fájllal történő módosítást igényelnek.
Ami tapasztalatainkat illeti, a következő bejegyzésekben arról lesz szó, hogy milyen statikus és dinamikus ellenőrzéseket végzünk a RAML-Swagger architektúránk alapján, valamint arról, hogy milyen dokumentációt generálunk a szerződésekből, és mindez hogyan működik.
A felmérésben csak regisztrált felhasználók vehetnek részt. , kérem.
Milyen nyelven írja meg a mikroszolgáltatási szerződéseket?
-
RAML 0.8
-
RAML 1.0
-
Swagger 2
-
OAS3 (más néven)
-
Tervrajz
-
más
-
Nem használ
100 felhasználó szavazott. 24 felhasználó tartózkodott.
Forrás: will.com