V dynamickém světě mikroslužeb se může cokoliv změnit – kteroukoli komponentu lze přepsat do jiného jazyka pomocí různých rámců a architektury. Pouze smlouvy by měly zůstat nezměněny, aby bylo možné s mikroslužbou interagovat zvenčí na nějakém trvalém základě, bez ohledu na vnitřní metamorfózy. A dnes si povíme o našem problému výběru formátu pro popis smluv a sdílení nalezených artefaktů.
Příspěvek připraven и
Mikroslužby. Při vývoji Acronis Cyber Cloud jsme si uvědomili, že jim nemůžeme uniknout. A navrhnout mikroslužbu je nemožné bez formalizace smlouvy, která představuje rozhraní mikroslužby.
Když ale produkt obsahuje více než jednu komponentu a vývoj smluv se stane běžnou činností, nemůžete si pomoct a začnete přemýšlet o optimalizaci procesů. Je zřejmé, že rozhraní (smlouva) a implementace (mikroservis) se musí navzájem shodovat, že různé komponenty musí dělat stejné věci stejným způsobem a že bez centralizovaného rozhodování o všech těchto rozhodnutích bude každý tým nucen trávit čas znovu a znovu, abyste je získali.
Diagram mikroslužeb Amazon od Werner Vogelis, technický ředitel Amazonu
jaké je to dilema? De facto existují dva způsoby interakce s mikroslužbami – HTTP Rest a gRPC od Googlu. Protože jsme nechtěli uvíznout v technologickém zásobníku Google, zvolili jsme HTTP Rest. HTTP REST smluvní anotace jsou nejčastěji popisovány v jednom ze dvou formátů: RAML a OAS, dříve známý jako Swagger, a proto se každý vývojový tým potýká s nutností vybrat si jeden ze standardů. Jak se ale ukazuje, tato volba může být velmi obtížná.
Proč jsou potřebné anotace?
Anotace je potřeba k tomu, aby externí uživatel mohl snadno zjistit, co lze s vaší službou provést prostřednictvím jejího HTTP rozhraní. To znamená, že anotace musí na základní úrovni obsahovat alespoň seznam dostupných zdrojů, jejich HTTP metody, těla požadavků, výpis parametrů, označení požadovaných a podporovaných hlaviček a také návratové kódy a formáty odpovědí. Mimořádně důležitým prvkem anotace smlouvy je jejich slovní popis („co se stane, když do požadavku přidáte tento parametr dotazu?“, „V jakém případě bude vrácen kód 400?“)
Pokud však jde o vývoj velkého počtu mikroslužeb, chcete z písemných anotací získat další hodnotu. Například na základě RAML/Swagger můžete generovat klientský i serverový kód v obrovském množství programovacích jazyků. Můžete také automaticky obdržet dokumentaci k mikroslužbě a nahrát ji na svůj vývojářský portál :).
Příklad popisu strukturované smlouvy
Méně běžná je praxe testování mikroslužeb na základě popisu smlouvy. Pokud jste napsali anotaci i komponentu, můžete vytvořit autotest, který ověří adekvátnost služby s různými typy vstupních dat. Vrátí služba kód odpovědi, který není popsán v anotaci? Bude schopen správně zpracovat zjevně nesprávná data?
Kvalitní implementace nejen samotných smluv, ale i nástrojů pro vizualizaci anotací navíc umožňuje zjednodušit práci s mikroslužbou. Tedy pokud architekt zakázku kvalitativně popsal, na jejím základě projektanti a vývojáři bez dalších časových nákladů implementují službu do dalších produktů.
Aby bylo možné povolit další nástroje, mají RAML i OAS možnost přidávat metadata, která standard neposkytuje ().
Obecně je prostor pro kreativitu při využívání smluv na mikroslužby obrovský... alespoň teoreticky.
Srovnání ježka s hadem
V současné době je prioritní oblastí vývoje ve společnosti Acronis vývoj platformy Acronis Cyber Platform. Acronis Cyber Platform je nové body integrace služeb třetích stran s Acronis Cyber Cloud a agentskou částí. Přestože jsme byli spokojeni s našimi interními API popsanými v RAML, potřeba publikovat API znovu vyvolala otázku volby: který anotační standard je nejlepší použít pro naši práci?
Zpočátku se zdálo, že existují dvě řešení - nejběžnějším vývojem byly RAML a Swagger (nebo OAS). Ale ve skutečnosti se ukázalo, že existují alespoň ne 2 alternativy, ale 3 nebo více.
Na jedné straně je RAML - výkonný a efektivní jazyk. Dobře implementuje hierarchii a dědičnost, takže tento formát je vhodnější pro velké společnosti, které potřebují hodně popisů – tedy ne jeden produkt, ale mnoho mikroslužeb, které mají společné části smluv – autentizační schémata, stejné datové typy, těla chyb .
Ale vývojář RAML, Mulesoft, se připojil ke konsorciu Open API, které vyvíjí . RAML proto pozastavil svůj vývoj. Chcete-li si představit formát události, představte si, že správci hlavních součástí Linuxu odešli pracovat pro Microsoft. Tato situace vytváří předpoklady pro používání Swaggeru, který se dynamicky vyvíjí a v poslední - třetí verzi - flexibilitou a funkčností prakticky dohání RAML.
Pokud ne pro jednoho, ale...
Jak se ukázalo, ne všechny open-source nástroje byly aktualizovány na OAS 3.0. U mikroslužeb v Go bude nejkritičtější věcí nedostatek přizpůsobení pro nejnovější verzi standardu. Rozdíl mezi Swagger 2 a Swagger 3 však je . Například ve třetí verzi vývojáři:
- vylepšený popis autentizačních schémat
- Podpora schématu JSON
- vylepšena schopnost přidávat příklady
Situace je úsměvná: při výběru standardu je třeba zvážit RAML, Swagger 2 a Swagger 3 jako samostatné alternativy. Pouze Swagger 2 má však dobrou podporu pro nástroje OpenSource. RAML je velmi flexibilní...a komplexní a Swagger 3 je málo podporován komunitou, takže budete muset používat proprietární nástroje nebo komerční řešení, která bývají poměrně drahá.
Navíc, pokud je v Swaggeru mnoho pěkných funkcí, jako je například hotový portál , na který si můžete nahrát anotaci a získat její vizualizaci s podrobným popisem, odkazy a souvislostmi, pak pro zásadnější a méně přívětivé RAML taková možnost neexistuje. Ano, můžete si něco vyhledat mezi projekty na GitHubu, najít tam analog a sami si to nasadit. Portál však v každém případě bude muset někdo udržovat, což pro základní použití nebo potřeby testování není tak pohodlné. Swagger je navíc více „neprincipiální“ nebo liberálnější – lze jej generovat z komentářů v kódu, což je samozřejmě v rozporu s principem API first a není podporováno žádnou z utilit RAML.
Svého času jsme začali pracovat s RAML jako s flexibilnějším jazykem a v důsledku toho jsme museli spoustu věcí dělat sami. Například jeden z projektů používá nástroj v jednotkových testech, které podporují pouze RAML 0.8. Museli jsme tedy přidat berličky, aby nástroj mohl „sežrat“ RAML verze 1.0.
Potřebujete si vybrat?
Po práci na dokončení ekosystému řešení pro RAML jsme došli k závěru, že musíme RAML převést na Swagger 2 a provést v něm veškerou automatizaci, ověřování, testování a následnou optimalizaci. Je to dobrý způsob, jak využít flexibilitu RAML a komunitní podporu nástrojů od Swagger.
K vyřešení tohoto problému existují dva nástroje OpenSource, které by měly zajistit konverzi smlouvy:
- je aktuálně nepodporovaný nástroj. Při práci s ním jsme zjistili, že má řadu problémů se složitými RAML, které jsou „rozprostřeny“ do velkého počtu souborů. Tento program je napsán v JavaScriptu a provádí rekurzivní procházení syntaktického stromu. Kvůli dynamickému psaní je obtížné porozumět tomuto kódu, takže jsme se rozhodli neztrácet čas psaním oprav pro umírající utilitu.
- - nástroj od stejné společnosti, která tvrdí, že je připravena převést cokoli a všechno a v jakémkoli směru. K dnešnímu dni byla oznámena podpora pro RAML 0.8, RAML 1.0 a Swagger 2.0. V době našeho výzkumu však byla užitečnost stále vlhké a nepoužitelné. Vývojáři vytvářejí druh , což jim umožňuje v budoucnu rychle přidávat nové standardy. Ale zatím to prostě nejde.
A to nejsou všechny potíže, se kterými jsme se setkali. Jedním z kroků v našem kanálu je ověřit, že RAML z úložiště je správný vzhledem ke specifikaci. Vyzkoušeli jsme několik utilit. Na naše anotace kupodivu všichni nadávali na různých místech a úplně jinými zlými slovy. A ne vždy k věci :).
Nakonec jsme se dohodli na dnes již zastaralém projektu, který má také řadu problémů (někdy z ničeho nic spadne, má problémy při práci s regulárními výrazy). Proto jsme nenašli způsob, jak vyřešit problémy s ověřováním a konverzí na základě bezplatných nástrojů, a rozhodli jsme se použít komerční nástroj. V budoucnu, jak budou nástroje OpenSource vyspělejší, může být řešení tohoto problému snazší. Mezitím se nám náklady na práci a čas na „dokončení“ zdály významnější než náklady na komerční službu.
Závěr
Po tom všem jsme se chtěli podělit o naše zkušenosti a poznamenat, že před výběrem nástroje pro popis smluv je potřeba jasně definovat, co od něj chcete a jaký rozpočet jste ochotni investovat. Pokud zapomeneme na OpenSource, existuje již velké množství služeb a produktů, které vám pomohou zkontrolovat, převést a ověřit. Ale jsou drahé a někdy velmi drahé. Pro velkou společnost jsou takové náklady únosné, ale pro startup se mohou stát velkou zátěží.
Určete sadu nástrojů, které budete později používat. Pokud potřebujete například jen zobrazit smlouvu, bude jednodušší použít Swagger 2, který má krásné API, protože v RAML si budete muset službu budovat a udržovat sami.
Čím více úkolů budete mít, tím širší bude potřeba nástrojů, které se liší pro různé platformy, a je lepší se okamžitě seznámit s dostupnými verzemi, abyste si mohli vybrat, která v budoucnu minimalizuje vaše náklady.
Ale stojí za to si uvědomit, že všechny ekosystémy, které dnes existují, jsou nedokonalé. Pokud jsou tedy ve firmě fanoušci, kteří rádi pracují v RAML, protože „umožňuje flexibilněji vyjadřovat myšlenky“, nebo naopak preferují Swagger, protože „je přehlednější“, je nejlepší je nechat pracovat v čem jsou Jsou na to zvyklí a chtějí to, protože nástroje kteréhokoli z formátů vyžadují úpravu pomocí souboru.
Pokud jde o naše zkušenosti, v následujících příspěvcích si povíme, jaké statické a dynamické kontroly provádíme na základě naší architektury RAML-Swagger, jakou dokumentaci generujeme ze smluv a jak to celé funguje.
Průzkumu se mohou zúčastnit pouze registrovaní uživatelé. , prosím.
Jaký jazyk používáte k anotaci smluv o mikroslužbách?
-
RAML 0.8
-
RAML 1.0
-
Šoupat se 2
-
OAS3 (také znám jako)
-
Modrák
-
Další
-
Nepoužívám
Hlasovalo 100 uživatelů. 24 uživatelů se zdrželo hlasování.
Zdroj: www.habr.com