V dynamickom svete mikroslužieb sa môže čokoľvek zmeniť – každý komponent môže byť prepísaný do iného jazyka pomocou rôznych rámcov a architektúry. Len zmluvy by mali zostať nezmenené, aby bolo možné s mikroslužbou interagovať zvonku na nejakom trvalom základe, bez ohľadu na vnútorné premeny. A dnes si povieme niečo o našom probléme výberu formátu na popis zmlúv a zdieľania nájdených artefaktov.
Príspevok pripravený и
Mikroslužby. Pri vývoji Acronis Cyber Cloud sme si uvedomili, že im nemôžeme uniknúť. A navrhnutie mikroslužby je nemožné bez formalizácie zmluvy, ktorá predstavuje rozhranie mikroslužby.
Ale keď produkt obsahuje viac ako jednu zložku a vývoj zmlúv sa stáva bežnou činnosťou, nedá sa nezačať myslieť na optimalizáciu procesov. Je zrejmé, že rozhranie (zmluva) a implementácia (mikroservis) sa musia navzájom zhodovať, že rôzne komponenty musia robiť rovnaké veci rovnakým spôsobom a že bez centralizovaného rozhodovania o všetkých týchto rozhodnutiach bude každý tím nútený tráviť čas znova a znova, aby ste ich získali.
Diagram mikroslužieb Amazon z Werner Vogelis, technický riaditeľ Amazonu
aká je dilema? De facto existujú dva spôsoby interakcie s mikroslužbami – HTTP Rest a gRPC od Google. Keďže sme nechceli uviaznuť v technologickom balíku Google, vybrali sme HTTP Rest. HTTP REST zmluvné anotácie sú najčastejšie popisované v jednom z dvoch formátov: RAML a OAS, predtým známy ako Swagger.Preto každý vývojársky tím stojí pred potrebou vybrať si jeden zo štandardov. Ale ako sa ukazuje, urobiť túto voľbu môže byť veľmi ťažké.
Prečo sú potrebné anotácie?
Anotácia je potrebná, aby externý používateľ mohol ľahko zistiť, čo sa dá s vašou službou urobiť prostredníctvom jej HTTP rozhrania. To znamená, že anotácia musí na základnej úrovni obsahovať aspoň zoznam dostupných zdrojov, ich HTTP metódy, telá požiadaviek, zoznam parametrov, označenie požadovaných a podporovaných hlavičiek, ako aj návratové kódy a formáty odpovedí. Mimoriadne dôležitým prvkom anotácie zmluvy je ich slovný popis („čo sa stane, ak do požiadavky pridáte tento parameter dopytu?“, „V akom prípade sa vráti kód 400?“)
Avšak, pokiaľ ide o vývoj veľkého počtu mikroslužieb, chcete získať dodatočnú hodnotu z písomných anotácií. Napríklad na základe RAML/Swagger môžete generovať klientsky aj serverový kód v obrovskom množstve programovacích jazykov. Môžete tiež automaticky získať dokumentáciu pre mikroslužbu a nahrať ju na váš vývojársky portál :).
Príklad popisu štruktúrovanej zmluvy
Menej bežná je prax testovania mikroslužieb na základe popisov zmlúv. Ak ste napísali anotáciu aj komponent, môžete vytvoriť autotest, ktorý skontroluje primeranosť služby s rôznymi typmi vstupných údajov. Vracia služba kód odpovede, ktorý nie je opísaný v anotácii? Dokáže správne spracovať zjavne nesprávne údaje?
Kvalitná implementácia nielen samotných zmlúv, ale aj nástrojov na vizualizáciu anotácií navyše umožňuje zjednodušiť prácu s mikroservisom. Teda ak architekt zákazku kvalitne opísal, na základe nej projektanti a developeri bez ďalších časových nákladov implementujú službu do ďalších produktov.
Na umožnenie ďalších nástrojov majú RAML aj OAS možnosť pridávať metadáta, ktoré štandard neposkytuje ().
Vo všeobecnosti je priestor pre kreativitu pri využívaní zmlúv na mikroslužby obrovský... aspoň teoreticky.
Porovnanie ježka s hadom
V súčasnosti je prioritnou oblasťou vývoja v spoločnosti Acronis vývoj kybernetickej platformy Acronis. Acronis Cyber Platform je novým bodom integrácie služieb tretích strán s Acronis Cyber Cloud a agentskou časťou. Hoci sme boli spokojní s našimi internými API popísanými v RAML, potreba publikovať API opäť vyvolala otázku voľby: ktorý anotačný štandard je najlepšie použiť pre našu prácu?
Spočiatku sa zdalo, že existujú dve riešenia - najbežnejšími vývojmi boli RAML a Swagger (alebo OAS). Ale v skutočnosti sa ukázalo, že existujú aspoň nie 2 alternatívy, ale 3 alebo viac.
Na jednej strane je RAML - výkonný a efektívny jazyk. Dobre implementuje hierarchiu a dedičnosť, takže tento formát je vhodnejší pre veľké spoločnosti, ktoré potrebujú veľa popisov - teda nie jeden produkt, ale veľa mikroslužieb, ktoré majú spoločné časti zmlúv - autentifikačné schémy, rovnaké dátové typy, telá chýb .
Ale vývojár RAML, Mulesoft, sa pripojil ku konzorciu Open API, ktoré vyvíja . RAML preto pozastavil svoj vývoj. Ak si chcete predstaviť formát udalosti, predstavte si, že správcovia hlavných komponentov Linuxu odišli pracovať do spoločnosti Microsoft. Táto situácia vytvára predpoklady na používanie Swaggeru, ktorý sa dynamicky vyvíja a v najnovšej - tretej verzii - flexibilitou a funkčnosťou prakticky dobieha RAML.
Ak nie pre jednu vec...
Ako sa ukázalo, nie všetky nástroje s otvoreným zdrojom boli aktualizované na OAS 3.0. Pre mikroslužby v Go bude najdôležitejšou vecou nedostatok prispôsobenia pre najnovšiu verziu štandardu. Rozdiel medzi Swagger 2 a Swagger 3 je však . Napríklad v tretej verzii vývojári:
- vylepšený popis schém autentifikácie
- Podpora schémy JSON
- vylepšená schopnosť pridávať príklady
Situácia je vtipná: pri výbere štandardu musíte zvážiť RAML, Swagger 2 a Swagger 3 ako samostatné alternatívy. Avšak iba Swagger 2 má dobrú podporu pre nástroje OpenSource. RAML je veľmi flexibilný...a komplexný a Swagger 3 je slabo podporovaný komunitou, takže budete musieť použiť proprietárne nástroje alebo komerčné riešenia, ktoré bývajú dosť drahé.
Navyše, ak je v Swaggeri veľa pekných funkcií, ako napríklad hotový portál , na ktorý si môžete nahrať anotáciu a získať jej vizualizáciu s podrobným popisom, odkazmi a prepojeniami, potom pre zásadnejšie a menej prívetivé RAML takáto možnosť neexistuje. Áno, môžete hľadať niečo medzi projektmi na GitHub, nájsť tam analóg a nasadiť ho sami. Portál však v každom prípade bude musieť niekto udržiavať, čo nie je až také pohodlné na základné používanie či potreby testovania. Okrem toho je swagger viac „neprincipovaný“ alebo liberálnejší – môže byť generovaný z komentárov v kóde, čo je, samozrejme, v rozpore s prvým princípom API a nie je podporované žiadnym z nástrojov RAML.
Svojho času sme začali pracovať s RAML ako flexibilnejším jazykom a výsledkom bolo, že sme si veľa vecí museli robiť sami. Napríklad jeden z projektov používa tento nástroj v jednotkových testoch, ktorý podporuje iba RAML 0.8. Museli sme teda pridať barličky, aby nástroj mohol „zožrať“ RAML verzie 1.0.
Potrebujete si vybrať?
Po práci na dokončení ekosystému riešení pre RAML sme dospeli k záveru, že musíme RAML previesť na Swagger 2 a vykonať v ňom všetku automatizáciu, overovanie, testovanie a následnú optimalizáciu. Je to dobrý spôsob, ako využiť flexibilitu RAML a komunitnú podporu nástrojov od Swagger.
Na vyriešenie tohto problému existujú dva nástroje OpenSource, ktoré by mali poskytovať konverziu zmlúv:
- je momentálne nepodporovaný nástroj. Pri práci s ním sme zistili, že má množstvo problémov s komplexnými RAML, ktoré sú „rozložené“ vo veľkom počte súborov. Tento program je napísaný v JavaScripte a vykonáva rekurzívne prechádzanie syntaktického stromu. Kvôli dynamickému písaniu je ťažké porozumieť tomuto kódu, preto sme sa rozhodli nestrácať čas písaním záplat pre umierajúci nástroj.
- - nástroj od tej istej spoločnosti, ktorá tvrdí, že je pripravená previesť čokoľvek a všetko a v akomkoľvek smere. K dnešnému dňu bola oznámená podpora pre RAML 0.8, RAML 1.0 a Swagger 2.0. V čase nášho výskumu však bola užitočnosť stále vlhké a nepoužiteľné. Vývojári vytvárajú druh , čo im umožňuje v budúcnosti rýchlo pridávať nové štandardy. Ale zatiaľ to jednoducho nejde.
A to nie sú všetky ťažkosti, s ktorými sme sa stretli. Jedným z krokov v našom potrubí je overenie správnosti RAML z úložiska vzhľadom na špecifikáciu. Vyskúšali sme niekoľko nástrojov. Prekvapivo všetci nadávali na naše anotácie na rôznych miestach a úplne inými zlými slovami. A nie vždy k veci :).
Nakoniec sme sa dohodli na dnes už zastaranom projekte, ktorý má tiež množstvo problémov (niekedy z ničoho nič spadne, má problémy pri práci s regulárnymi výrazmi). Preto sme nenašli spôsob, ako vyriešiť problémy s validáciou a konverziou na základe bezplatných nástrojov, a rozhodli sme sa použiť komerčnú utilitu. V budúcnosti, keď budú nástroje OpenSource vyspelejšie, bude možno tento problém vyriešiť jednoduchšie. Medzitým sa nám náklady na prácu a čas na „dokončenie“ zdali významnejšie ako náklady na komerčnú službu.
Záver
Po tomto všetkom sme sa chceli podeliť o naše skúsenosti a podotknúť, že pred výberom nástroja na popis zmlúv si treba jasne definovať, čo od neho chcete a aký rozpočet ste ochotný investovať. Ak zabudneme na OpenSource, už teraz existuje veľké množstvo služieb a produktov, ktoré vám pomôžu kontrolovať, konvertovať a overovať. Ale sú drahé a niekedy veľmi drahé. Pre veľkú firmu sú takéto náklady únosné, no pre startup sa môžu stať veľkou záťažou.
Určite sadu nástrojov, ktoré budete neskôr používať. Napríklad, ak potrebujete len zobraziť zmluvu, bude jednoduchšie použiť Swagger 2, ktorý má krásne API, pretože v RAML si budete musieť službu vybudovať a udržiavať sami.
Čím viac úloh máte, tým širšia bude potreba nástrojov a líšia sa pre rôzne platformy a je lepšie sa okamžite zoznámiť s dostupnými verziami, aby ste si vybrali, čo v budúcnosti minimalizuje vaše náklady.
Ale stojí za to uznať, že všetky ekosystémy, ktoré dnes existujú, sú nedokonalé. Preto, ak sú vo firme fanúšikovia, ktorí radi pracujú v RAML, pretože „umožňuje flexibilnejšie vyjadrovať myšlienky“, alebo naopak uprednostňujú Swagger, pretože „je prehľadnejší“, je najlepšie ich nechať pracovať v čom sú Sú na to zvyknutí a chcú to, pretože nástroje ktoréhokoľvek z formátov vyžadujú úpravu pomocou súboru.
Čo sa týka našich skúseností, v nasledujúcich príspevkoch si povieme, aké statické a dynamické kontroly vykonávame na základe našej architektúry RAML-Swagger, ako aj akú dokumentáciu generujeme zo zmlúv a ako to celé funguje.
Do prieskumu sa môžu zapojiť iba registrovaní užívatelia. Prosím.
Aký jazyk používate na anotáciu zmlúv o mikroslužbách?
-
RAML 0.8
-
RAML 1.0
-
Švihať sa 2
-
OAS3 (alias)
-
Poľná
-
Ďalšie
-
Nepoužíva sa
Hlasovalo 100 užívateľov. 24 používatelia sa zdržali hlasovania.
Zdroj: hab.com