Ve dynamickém světě mikroslužeb se může cokoliv změnit — jakákoliv komponenta může být přeprogramována v jiném jazyce, s použitím jiných frameworků a architektury. Jedině smlouvy by měly zůstat neměnné, aby bylo možné s mikroslužbou interagovat z vnějšku na nějakém stálém základě, bez ohledu na vnitřní metamorfózy. Dnes se podělíme o naši problémovou volbu formátu popisu smluv a najdeme artefakty.
Příspěvek připravila a
Mikroslužby. Při vývoji Acronis Cyber Cloud jsme si uvědomili, že se jim nelze vyhnout. A navrhování mikroslužby je nemožné bez formalizace smlouvy, která představuje rozhraní mikroslužby.
Ale když v produktu je více než jedna komponenta a vývoj smlouvy se stává pravidelnou činností, nevyhnutelně začnete uvažovat o optimalizaci procesu. Stává se zřejmým, že rozhraní (smlouva) a implementace (mikroslužba) by si měly odpovídat, že různé komponenty by měly dělat stejné věci stejně, a že bez centralizovaného rozhodování o těchto záležitostech bude každé týmu neustále trávit čas jejich získáváním znovu a znovu.
Schéma mikroslužeb Amazon z Wernera Vogeliusa, CTO Amazon
V čem spočívá dilema? De facto existují dva způsoby interakce mikroslužeb – HTTP Rest a gRPC od společnosti Google. Nechtějíce se zaplést do technologie Google, jsme zvolili HTTP Rest. Anotace smluv HTTP REST se nejčastěji popisují jedním ze dvou formátů: RAML a OAS, dříve známý jako Swagger. Proto se každý tým vývojářů setkává s potřebou zvolit si jeden ze standardů. Jak se ukázalo, učinit tuto volbu může být velmi obtížné.
Proč jsou anotace potřebné?
Anotace je potřeba, aby se externí uživatel mohl snadno orientovat v tom, co může se svým službou provádět prostřednictvím jejího HTTP rozhraní. To znamená, že na základní úrovni by anotace měla obsahovat minimálně seznam dostupných zdrojů, jejich HTTP metody, těla žádostí, výčet parametrů, specifikaci potřebných a podporovaných hlaviček, jakož i kódy návratu a formáty odpovědí. Krajně důležitým prvkem anotace kontraktu je také jejich slovní popis („co se stane, když přidáte tento dotazový parametr k žádosti?“, „v jakém případě se vrátí kód 400?“)
Nicméně, pokud jde o vývoj velkého množství mikroslužeb, chceme z napsaných anotací získat další užitek. Například na základě RAML/Swagger můžeme generovat jak klientský, tak serverový kód v obrovském množství programovacích jazyků. A můžeme také automaticky získat dokumentaci k mikroslužbě a nahrát ji na váš developerský portál :).
Příklad strukturovaného popisu kontraktu
Méně častou praxí je testování mikroslužeb na základě popisů kontraktů. Pokud jste napsali jak anotaci, tak komponent, můžete vytvořit automatizovaný test, který zkontroluje adekvátnost fungování služby s různými typy dat na vstupu. Nevrací služba kód odpovědi, který není popsán v anotaci? Bude schopna správně zpracovat zjevně chybná data?
Více než to, kvalitní implementace nejen samotných kontraktů, ale také nástrojů pro vizualizaci anotací usnadňuje práci s mikroslužbou. To znamená, že pokud architekt kvalitně popsal kontrakt, na jeho základě budou designéři a vývojáři implementovat službu do jiných produktů bez dodatečných časových nákladů.
Pro práci s dalšími nástroji mají jak RAML, tak OAS možnost přidávat metadata, která nejsou ve standardu zahrnuta ().
Obecně platí, že prostor pro kreativitu v aplikaci kontraktů pro mikroslužby je obrovský… alespoň teoreticky
Srovnání ježka s užovkou
V současné době je prioritním směrem vývoje v Acronis vývoj Acronis Cyber Platform. Acronis Cyber Platform – to jsou nová místa integrace externích služeb s Acronis Cyber Cloud a agentní částí. Ačkoli naše interní API, popsaná v RAML, nás uspokojovala, potřeba zveřejnění API znovu vyvolala otázku výběru: který standard anotací je pro naši práci lepší?
Na začátku se zdálo, že existují dvě řešení – nejrozšířenější vývoj RAML a Swagger (nebo OAS). Ale ve skutečnosti se ukázalo, že alternativ je minimálně 3 nebo více.
Na jedné straně je tu RAML – mocný a efektivní jazyk. Má dobře implementovanou hierarchii a dědičnost, takže tento formát je více vhodný pro velké společnosti, které potřebují hodně popisů – tedy ne jeden produkt, ale mnoho mikroservisů, které mají společné části kontraktů – schémata autentizace, stejné typy dat, těla chyb.
Ale vývojář RAML, společnost Mulesoft, se připojil k konsorciu Open API, které se zabývá vývojem . Proto RAML pozastavil svůj vývoj. Představte si formát události jako situaci, kdy hlavní údržbáři hlavních komponent Linuxu odešli pracovat do Microsoftu. Taková situace vytváří podmínky pro použití Swaggeru, který se dynamicky vyvíjí a v poslední – třetí verzi – téměř dohání RAML co do flexibility a funkčnosti.
Kdyby nebylo jednoho ale…
Jak se ukázalo, daleko ne všechny open-source nástroje se aktualizovaly na verzi OAS 3.0. Pro mikroservisy na Go bude nejkritičtější absence adaptace na novou verzi standardu. Rozdíl mezi Swagger 2 a Swagger 3 je však . Například v třetí verzi vývojáři:
- vylepšili popis schémat autentizace
- podporu JSON Schema
- zlepšili možnosti přidávání příkladů
Situace je poměrně vtipná: při výběru standardu je nutné považovat RAML, Swagger 2 a Swagger 3 za samostatné alternativy. Přičemž pouze Swagger 2 má dobrou podporu open-source nástrojů. RAML je velmi flexibilní… a složitý, a Swagger 3 má slabou podporu komunity, takže budete muset používat nástroje vlastní produkce nebo komerční řešení, která obvykle stojí poměrně draho.
Přičemž pokud ve Swaggeru existuje mnoho příjemných možností, jako je hotový portál , na který lze nahrát anotaci a získat její vizualizaci s podrobným popisem, odkazy a vazbami, tak u RAML, který je více základní a méně přívětivý, tato možnost neexistuje. Ano, lze něco hledat mezi projekty na GitHubu, najít tam analog a sami ho nasadit. Nicméně v každém případě se musí někdo postarát o portál, což není tak pohodlné pro základní používání nebo testovací potřeby. Kromě toho je swagger více "bezzásadový", nebo liberální — lze jej generovat z komentářů v kódu, což samozřejmě odporuje principu API first a není podporováno žádnou z utilit RAML.
V určitém okamžiku jsme začali pracovat s RAML, jako s flexibilnějším jazykem, a nakonec jsme museli mnoho věcí dělat vlastními rukama. Například v jednom z projektů se používá utilita v unit testech, která podporuje pouze RAML 0.8. Takže jsme museli přidávat záplaty, aby utilita mohla "zpracovávat" RAML verze 1.0.
Je nutné vybírat?
Po zkušenostech s dopisováním ekosystému řešení pod RAML jsme dospěli k závěru, že potřebujeme konvertovat RAML na Swagger 2 a již v něm provádět celou automatizaci, kontrolu, testování a následnou optimalizaci. To je dobrý způsob, jak současně využívat flexibilitu RAML a podporu nástrojů komunity od Swagger.
Pro vyřešení tohoto úkolu existují dva nástroje OpenSource, které by měly zajišťovat konverzi kontraktů:
- – v současnosti nepodporovaná utilita. Během práce s ní jsme zjistili, že má řadu problémů se složitými RAML, které jsou "rozprostřeny" na velkém množství souborů. Tento program je napsán v JavaScriptu a provádí rekurzivní procházení syntaktického stromu. Kvůli dynamickému typování se v tomto kódu těžko vyznává, takže jsme se rozhodli věnovat čas psaní záplat pro umírající utilitu.
- — nástroj od téže společnosti, který se snaží být připraven na konverzi všeho a všemožného, a to oběma směry. Dnes je deklarována podpora RAML 0.8, RAML 1.0 a Swagger 2.0. Nicméně v okamžiku našeho zkoumání byla utilita ještě nedorobena a nepoužitelná. Vývojáři vytvářejí jakýsi , což jim v budoucnu umožní rychle přidávat nové standardy. Ale zatím to všechno prostě nefunguje.
A to ještě nejsou všechny potíže, se kterými jsme se setkali. Jedním z kroků našeho pipeline je ověření, že RAML z repozitáře je správná podle specifikace. Vyzkoušeli jsme několik nástrojů. Udivující je, že všechny si stěžovaly na naše anotace na různých místech a zcela různými nepříjemnými slovy. A to ne vždy oprávněně :).
Nakonec jsme se rozhodli pro nyní zastaralý projekt, který má také řadu problémů (někdy padá na prázdném místě, má potíže s prací s regulárními výrazy). Takže jsme nenalezli způsob, jak vyřešit úkoly validace a konverze pomocí bezplatných nástrojů, a rozhodli se používat komerční utilitu. V budoucnu, až se nástroje OpenSource stanou rozvinutějšími, by mohlo být vyřešení tohoto úkolu jednodušší. A zatím nám časová a pracovní náročnost 'dokončování' připadala významnější než cena komerčního servisu.
Závěr
Po tom všem jsme chtěli sdílet naše zkušenosti a zdůraznit, že před volbou nástroje pro popis smluv je třeba jasně určit, co od něho očekáváte a jaký rozpočet jste ochotni vložit. Pokud zapomenete na OpenSource, už nyní existuje velké množství služeb a produktů, které pomohou provést ověření, konverzi a validaci. Ale stojí hodně, a někdy — velmi hodně. Pro velkou společnost jsou takové náklady únosné, ale pro startup se mohou stát velkým břemenem.
Určete soubor nástrojů, které budete používat později. Například, pokud potřebujete jen zobrazit smlouvu, bude jednodušší použít Swagger 2, který má krásné API, protože v RAML budete muset spustit a udržovat službu sami.
Čím více úkolů budete mít, tím širší bude potřeba po nástrojích, a ty jsou různé pro různé platformy, a je lepší se nejprve seznámit s dostupnými verzemi, abyste učinili výběr, který minimalizuje vaše náklady v budoucnu.
Je třeba uznat, že všechny ekosystémy, které dnes existují, nejsou dokonalé. Pokud tedy ve firmě jsou fanoušci, kteří rádi pracují s RAML, protože "umožňuje flexibilněji vyjadřovat myšlenky", nebo naopak preferují Swagger, protože "je srozumitelnější", je nejlepší nechat je pracovat v tom, na co jsou zvyklí a co chtějí, protože nástroje jakéhokoliv formátu vyžadují ladění.
Co se týče naší zkušenosti, v následujících příspěvcích se podělíme o to, jaké statické a dynamické kontroly provádíme na základě naší architektury RAML-Swagger, stejně jako o tom, jakou dokumentaci generujeme z kontraktů a jak to vše funguje.
Pouze registrovaní uživatelé se mohou účastnit ankety. , prosím.
Jaký jazyk používáte pro anotace kontraktů mikroservisů?
RAML 0.8
RAML 1.0
Swagger 2
OAS3 (jak se také nazývá)
Blueprint
Jiný
Nepoužívám
Hlasovalo 100 uživatelů. Zdrželo se 24 uživatelů.
Zdroj: habr.com
