W dynamicznym świecie mikrousług wszystko może się zmienić – każdy komponent można przepisać w innym języku, przy użyciu różnych frameworków i architektury. Jedynie umowy powinny pozostać niezmienione, aby z mikroserwisem można było wchodzić w interakcję z zewnątrz na stałe, niezależnie od wewnętrznych metamorfoz. A dzisiaj porozmawiamy o naszym problemie z wyborem formatu opisywania umów i podzielimy się artefaktami, które znaleźliśmy.
Post przygotowany и
Mikrousługi. Tworząc Acronis Cyber Cloud, zdaliśmy sobie sprawę, że nie możemy od nich uciec. A zaprojektowanie mikrousługi nie jest możliwe bez sformalizowania umowy, która reprezentuje interfejs mikrousługi.
Kiedy jednak produkt zawiera więcej niż jeden komponent, a opracowywanie kontraktów staje się regularną czynnością, nie można nie zacząć myśleć o optymalizacji procesów. Staje się oczywiste, że interfejs (umowa) i implementacja (mikrousługa) muszą do siebie pasować, że różne komponenty muszą robić to samo w ten sam sposób i że bez scentralizowanego podejmowania wszystkich tych decyzji każdy zespół będzie zmuszony spędzać czas wielokrotnie, aby je zdobyć.
Schemat mikrousług Amazon z Werner Vogelis, dyrektor ds. technicznych Amazona
Jaki jest dylemat? De facto istnieją dwa sposoby interakcji z mikroserwisami – HTTP Rest i gRPC od Google. Nie chcąc dać się wciągnąć w stos technologii Google, wybraliśmy HTTP Rest. Adnotacje kontraktowe HTTP REST najczęściej opisywane są w jednym z dwóch formatów: RAML i OAS, dawniej znanym jako Swagger, dlatego każdy zespół programistów staje przed koniecznością wyboru jednego ze standardów. Jak się jednak okazuje, dokonanie takiego wyboru może być bardzo trudne.
Dlaczego potrzebne są adnotacje?
Adnotacja jest potrzebna, aby użytkownik zewnętrzny mógł łatwo dowiedzieć się, co można zrobić z Twoją usługą za pośrednictwem interfejsu HTTP. Oznacza to, że na poziomie podstawowym adnotacja musi zawierać przynajmniej listę dostępnych zasobów, ich metod HTTP, treści żądań, zestawienie parametrów, wskazanie wymaganych i obsługiwanych nagłówków, a także kody powrotu i formaty odpowiedzi. Niezwykle ważnym elementem adnotacji do umowy jest jej słowny opis („co się stanie, jeśli dodasz do zapytania ten parametr zapytania?”, „W jakim przypadku zostanie zwrócony kod 400?”).
Jednak jeśli chodzi o tworzenie dużej liczby mikroserwisów, chcesz wydobyć dodatkową wartość z pisemnych adnotacji. Na przykład w oparciu o RAML/Swagger można generować kod zarówno klienta, jak i serwera w ogromnej liczbie języków programowania. Możesz także automatycznie otrzymać dokumentację mikroserwisu i przesłać ją na swój portal deweloperski :).
Przykład ustrukturyzowanego opisu umowy
Mniej powszechna jest praktyka testowania mikrousług na podstawie opisów umów. Jeśli napisałeś zarówno adnotację, jak i komponent, możesz stworzyć autotest, który sprawdza adekwatność usługi z różnymi typami danych wejściowych. Czy usługa zwraca kod odpowiedzi, który nie jest opisany w adnotacji? Czy będzie w stanie poprawnie przetworzyć oczywiście nieprawidłowe dane?
Co więcej, wysokiej jakości wdrożenie nie tylko samych umów, ale także narzędzi do wizualizacji adnotacji, pozwala uprościć pracę z mikroserwisem. Oznacza to, że jeśli architekt jakościowo opisał umowę, na jej podstawie projektanci i programiści wdrożą usługę w innych produktach bez dodatkowych kosztów czasowych.
Aby umożliwić dodatkowe narzędzia, zarówno RAML, jak i OAS mają możliwość dodawania metadanych nieprzewidzianych przez standard ().
Generalnie pole do kreatywności w korzystaniu z kontraktów na mikrousługi jest ogromne...przynajmniej w teorii.
Porównanie jeża z wężem
Obecnie priorytetowym obszarem rozwoju w Acronis jest rozwój Platformy Acronis Cyber. Acronis Cyber Platform to nowe punkty integracji usług firm trzecich z Acronis Cyber Cloud i częścią agentową. Choć byliśmy zadowoleni z naszych wewnętrznych API opisanych w RAML, konieczność opublikowania API ponownie postawiła pytanie: jakiego standardu adnotacji najlepiej użyć w naszej pracy?
Początkowo wydawało się, że istnieją dwa rozwiązania - najczęstszymi rozwinięciami były RAML i Swagger (lub OAS). Ale tak naprawdę okazało się, że istnieją co najmniej nie 2 alternatywy, ale 3 lub więcej.
Z jednej strony RAML – potężny i wydajny język. Dobrze implementuje hierarchię i dziedziczenie, więc ten format jest bardziej odpowiedni dla dużych firm, które potrzebują wielu opisów - czyli nie jednego produktu, ale wielu mikrousług, które mają wspólne części umów - schematy uwierzytelniania, te same typy danych, ciała błędów .
Ale twórca RAML, Mulesoft, dołączył do konsorcjum Open API, które się rozwija . Dlatego RAML zawiesił swój rozwój. Aby wyobrazić sobie format wydarzenia, wyobraźmy sobie, że opiekunowie głównych komponentów Linuksa odeszli do pracy w Microsoft. Sytuacja ta stwarza przesłanki do wykorzystania Swaggera, który dynamicznie się rozwija i w najnowszej – trzeciej wersji – praktycznie dogania RAML-a pod względem elastyczności i funkcjonalności.
Gdyby nie jedna rzecz...
Jak się okazuje, nie wszystkie narzędzia typu open source zostały zaktualizowane do wersji OAS 3.0. Dla mikroserwisów w Go najbardziej krytyczny będzie brak adaptacji dla najnowszej wersji standardu. Jednak różnica między Swaggerem 2 i Swaggerem 3 jest taka . Na przykład w trzeciej wersji twórcy:
- ulepszony opis schematów uwierzytelniania
- Obsługa schematu JSON
- ulepszono możliwość dodawania przykładów
Sytuacja jest zabawna: wybierając standard, należy rozważyć RAML, Swagger 2 i Swagger 3 jako osobne alternatywy. Jednak tylko Swagger 2 ma dobrą obsługę narzędzi OpenSource. RAML jest bardzo elastyczny... i złożony, a Swagger 3 ma słabe wsparcie społeczności, więc będziesz musiał używać zastrzeżonych narzędzi lub rozwiązań komercyjnych, które zwykle są dość drogie.
Co więcej, jeśli w Swaggerze jest wiele fajnych funkcji, takich jak gotowy portal , na którym można wgrać adnotację i uzyskać jej wizualizację ze szczegółowym opisem, linkami i połączeniami, to dla bardziej podstawowego i mniej przyjaznego RAML-a nie ma takiej możliwości. Tak, możesz poszukać czegoś wśród projektów na GitHubie, znaleźć tam analogię i samodzielnie wdrożyć. Jednak w każdym razie ktoś będzie musiał utrzymać portal, co nie jest zbyt wygodne do podstawowego użytku lub potrzeb testowych. Ponadto swagger jest bardziej „bez zasad” lub bardziej liberalny - można go wygenerować z komentarzy w kodzie, co oczywiście jest sprzeczne z zasadą API First i nie jest obsługiwane przez żadne z narzędzi RAML.
W pewnym momencie zaczęliśmy pracować z RAML jako bardziej elastycznym językiem, w wyniku czego wiele rzeczy musieliśmy zrobić sami. Na przykład jeden z projektów korzysta z narzędzia w testach jednostkowych, które obsługują tylko RAML 0.8. Musieliśmy więc dodać kule, aby narzędzie mogło „zjeść” RAML w wersji 1.0.
Czy musisz wybierać?
Pracując nad skompletowaniem ekosystemu rozwiązań dla RAML, doszliśmy do wniosku, że musimy przekonwertować RAML do Swagger 2 i przeprowadzić w nim całą automatyzację, weryfikację, testowanie i późniejszą optymalizację. Jest to dobry sposób na wykorzystanie zarówno elastyczności RAML, jak i wsparcia narzędzi społecznościowych firmy Swagger.
Aby rozwiązać ten problem, istnieją dwa narzędzia OpenSource, które powinny zapewnić konwersję kontraktu:
- jest obecnie nieobsługiwanym narzędziem. Pracując z nim, odkryliśmy, że ma on wiele problemów ze złożonymi pamięciami RAML, które są „rozłożone” na dużą liczbę plików. Ten program jest napisany w JavaScript i wykonuje rekursywne przechodzenie przez drzewo składni. Ze względu na dynamiczne pisanie, zrozumienie tego kodu staje się trudne, dlatego postanowiliśmy nie tracić czasu na pisanie poprawek dla umierającego narzędzia.
- - narzędzie tej samej firmy, które twierdzi, że jest gotowe do konwersji wszystkiego i wszystkiego w dowolnym kierunku. Do tej pory ogłoszono wsparcie dla RAML 0.8, RAML 1.0 i Swagger 2.0. Jednak w momencie naszego badania użyteczność była nadal wilgotny i nie nadający się do użytku. Deweloperzy tworzą coś w rodzaju , co umożliwi im szybkie dodawanie nowych standardów w przyszłości. Ale jak dotąd to po prostu nie działa.
A to nie wszystkie trudności, jakie napotkaliśmy. Jednym z etapów naszego procesu jest sprawdzenie, czy pamięć RAML z repozytorium jest poprawna w odniesieniu do specyfikacji. Wypróbowaliśmy kilka narzędzi. Co zaskakujące, wszyscy przeklinali nasze adnotacje w różnych miejscach i zupełnie innymi wulgarnymi słowami. I nie zawsze na temat :).
Ostatecznie zdecydowaliśmy się na przestarzały już projekt, który również ma szereg problemów (czasami zawiesza się niespodziewanie, ma problemy podczas pracy z wyrażeniami regularnymi). Dlatego nie znaleźliśmy sposobu na rozwiązanie problemów związanych z walidacją i konwersją w oparciu o bezpłatne narzędzia i postanowiliśmy skorzystać z narzędzia komercyjnego. W przyszłości, gdy narzędzia OpenSource staną się bardziej dojrzałe, rozwiązanie tego problemu może stać się łatwiejsze. Tymczasem koszty robocizny i czasu na „wykończenie” wydawały nam się bardziej znaczące niż koszt usługi komercyjnej.
wniosek
Po tym wszystkim chcieliśmy podzielić się naszym doświadczeniem i zauważyć, że przed wyborem narzędzia do opisywania umów należy jasno określić, czego od niego oczekujesz i jaki budżet jesteś skłonny przeznaczyć. Jeśli zapomnimy o OpenSource, istnieje już duża liczba usług i produktów, które pomogą Ci sprawdzić, przekonwertować i zweryfikować. Ale są drogie, a czasem bardzo drogie. Dla dużej firmy takie koszty są do zniesienia, ale dla startupu mogą stać się dużym obciążeniem.
Określ zestaw narzędzi, z których będziesz korzystać później. Przykładowo, jeśli potrzebujesz tylko wyświetlić umowę, łatwiej będzie skorzystać z Swaggera 2, który ma piękne API, ponieważ w RAML będziesz musiał sam zbudować i utrzymać usługę.
Im więcej będziesz miał zadań, tym większe będzie zapotrzebowanie na narzędzia, a one są różne dla różnych platform i lepiej od razu zapoznać się z dostępnymi wersjami, aby dokonać wyboru, który zminimalizuje koszty w przyszłości.
Warto jednak przyznać, że wszystkie istniejące obecnie ekosystemy są niedoskonałe. Dlatego jeśli w firmie są fani, którzy lubią pracować w RAML, bo „pozwala to elastyczniej wyrażać myśli” lub wręcz przeciwnie, wolą Swaggera, bo „jest przejrzyściej”, najlepiej zostawić ich do pracy w czym są. Są do tego przyzwyczajeni i tego chcą, ponieważ narzędzia dowolnego formatu wymagają modyfikacji za pomocą pliku.
Jeśli chodzi o nasze doświadczenia, w kolejnych wpisach porozmawiamy o tym, jakie kontrole statyczne i dynamiczne przeprowadzamy w oparciu o naszą architekturę RAML-Swagger, a także jaką dokumentację generujemy z umów i jak to wszystko działa.
W ankiecie mogą brać udział tylko zarejestrowani użytkownicy. , Proszę.
Jakiego języka używasz do opisywania umów mikrousług?
-
RAML 0.8
-
RAML 1.0
-
Szaleństwo 2
-
OAS3 (aka)
-
Plan
-
Inny
-
Nie używam
Głosowało 100 użytkowników. 24 użytkowników wstrzymało się od głosu.
Źródło: www.habr.com