W dynamicznym świecie mikroserwisów wszystko może się zmienić — każdy komponent można napisać w innym języku, korzystając z innych frameworków i architektury. Nie mogą zmieniać się jedynie kontrakty, aby można było w jakiś stały sposób interagować z mikroserwisem, niezależnie od wewnętrznych metamorfoz. Dziś opowiemy o naszym problemie z wyborem formatu opisu kontraktów i podzielimy się znalezionymi artefaktami.
Post przygotował i
Mikroserwisy. Podczas rozwoju Acronis Cyber Cloud zrozumieliśmy, że nie możemy ich uniknąć. A projektowanie mikroserwisu jest niemożliwe bez sformalizowania kontraktu, który stanowi interfejs mikroserwisu.
Jednak gdy w produkcie znajduje się więcej niż jeden komponent, a tworzenie kontraktu staje się regularną aktywnością, zaczynasz się zastanawiać nad optymalizacją procesu. Oczywiste staje się, że interfejs (kontrakt) i implementacja (mikroserwis) muszą się nawzajem zgadzać, różne komponenty muszą wykonywać te same czynności w ten sam sposób, a bez centralnego podejmowania wszystkich tych decyzji każda drużyna będzie zmuszona wciąż i wciąż tracić czas na ich pozyskiwanie.
Schemat mikroserwisów Amazon z Wernera Vogelsa, CTO Amazon
Na czym polega dylemat? De facto istnieją dwa sposoby interakcji mikroserwisów – HTTP Rest i gRPC firmy Google. Nie chcąc być zaangażowanym w technologię Google, wybraliśmy HTTP Rest. Adnotacje do kontraktów HTTP REST najczęściej opisuje się jednym z dwóch formatów: RAML i OAS, wcześniej znanym jako Swagger. Dlatego każda drużyna deweloperów staje przed koniecznością wyboru jednego z standardów. Jak się okazało, podjęcie tego wyboru może być bardzo trudne.
Po co są adnotacje?
Adnotacja jest potrzebna, aby zewnętrzny użytkownik mógł łatwo zrozumieć, co można robić z Twoim serwisem za pośrednictwem jego interfejsu HTTP. Oznacza to, że na podstawowym poziomie adnotacja powinna zawierać przynajmniej listę dostępnych zasobów, ich metod HTTP, ciał żądań, wyliczenie parametrów, wskazanie wymaganych i wspieranych nagłówków, a także kodów odpowiedzi i formatów odpowiedzi. Niezwykle ważnym elementem adnotacji kontraktu jest również ich opis słowny („co się stanie, jeśli dodasz ten parametr zapytania do żądania?”, „w jakiej sytuacji zostanie zwrócony kod 400?”)
Jednak gdy mówimy o rozwijaniu dużej liczby mikroserwisów, chcemy wyciągnąć dodatkową korzyść z napisanych adnotacji. Na przykład, na podstawie RAML/Swagger można generować zarówno kod kliencki, jak i serwerowy w ogromnej liczbie języków programowania. Można również automatycznie uzyskiwać dokumentację mikroserwisu i umieszczać ją na swoim portalu dewelopera :)
Przykład ustrukturyzowanego opisu kontraktu
Rzadziej spotyka się praktykę testowania mikroserwisów na podstawie opisów kontraktów. Jeśli napisałeś zarówno adnotację, jak i komponent, można stworzyć autotest, który sprawdzi adekwatność działania serwisu z różnymi typami danych wejściowych. Czy serwis nie zwraca kodu odpowiedzi, który nie jest opisany w adnotacji? Czy będzie w stanie poprawnie obsłużyć oczywiście błędne dane?
Co więcej, jakościowe wdrożenie nie tylko samych kontraktów, ale także narzędzi do wizualizacji adnotacji pozwala uprościć pracę z mikroserwisem. Oznacza to, że jeśli architekt dobrze opisał kontrakt, to na jego podstawie projektanci i programiści będą wdrażać serwis w inne produkty bez dodatkowych nakładów czasowych.
Dla pracy dodatkowych narzędzi zarówno RAML, jak i OAS mają możliwość dodawania metadanych, które nie są przewidziane przez standard ().
Ogólnie rzecz biorąc, pole dla kreatywności w zastosowaniu kontraktów dla mikroserwisów — ogromne… przynajmniej teoretycznie
Porównanie jeża z wężem
Obecnie priorytetowym kierunkiem rozwoju w Acronis jest rozwój Acronis Cyber Platform. Acronis Cyber Platform to nowe punkty integracji zewnętrznych usług z Acronis Cyber Cloud oraz częścią agenta. Choć nasze wewnętrzne API, opisane w RAML, są zadowalające, konieczność publikacji API ponownie wywołała pytanie: który standard anotacji jest najlepszy do naszej pracy?
Początkowo wydawało się, że istnieją dwa rozwiązania — to najczęściej stosowane opracowania RAML i Swagger (lub OAS). Okazało się jednak, że alternatyw jest co najmniej nie 2, a 3 lub więcej.
Z jednej strony mamy RAML — potężny i efektywny język. Dobrze zrealizowana jest w nim hierarchia i dziedziczenie, więc ten format lepiej nadaje się dla dużych firm, które potrzebują wielu opisów — to znaczy nie jednego produktu, a wielu mikrousług, które mają wspólne części kontraktów — schematu autoryzacji, takie same typy danych, ciała błędów.
Jednak twórca RAML, firma Mulesoft, dołączyła do konsorcjum Open API, które zajmuje się rozwojem . Dlatego rozwój RAML został wstrzymany. Aby wyobrazić sobie format zdarzenia, wyobraź sobie, że główni maintainerzy komponentów Linux przeszli do pracy w Microsoft. Taka sytuacja stwarza przesłanki do używania Swagger, który rozwija się dynamicznie i w ostatniej — trzeciej wersji — praktycznie dogania RAML pod względem elastyczności i funkcjonalności.
Gdyby nie jeden ale...
Okazało się, że nie wszystkie narzędzia open-source zaktualizowały się do wersji OAS 3.0. Dla mikrousług w Go kluczowe będzie brak adaptacji do świeżej wersji standardu. Jednak różnica między Swagger 2 a Swagger 3 — Na przykład w trzeciej wersji deweloperzy:
- ulepszyli opis schematów autoryzacji,
- wsparcie dla JSON Schema,
- wzmocnili możliwość dodawania przykładów.
Sytuacja staje się zabawna: przy wyborze standardu należy rozważać RAML, Swagger 2 i Swagger 3 jako odrębne alternatywy. Przy tym tylko Swagger 2 ma dobrą obsługę narzędzi OpenSource. RAML jest bardzo elastyczny… i skomplikowany, a Swagger 3 jest słabo wspierany przez społeczność, więc będziesz musiał korzystać z narzędzi własnej produkcji lub rozwiązań komercyjnych, które zazwyczaj kosztują dość dużo.
Jednak w Swagger istnieje wiele przyjemnych możliwości, takich jak gotowy portal. , na który można załadować adnotację i otrzymać wizualizację z jej szczegółowym opisem, linkami i powiązaniami, nie ma takiej możliwości w bardziej fundamentalnym i mniej przyjaznym RAML. Tak, można poszukać czegoś w projektach na GitHubie, znaleźć tam odpowiednik i samodzielnie go uruchomić. Jednak w każdym przypadku ktoś musi utrzymywać portal, co nie jest zbyt wygodne do podstawowego wykorzystania lub potrzeb testowych. Dodatkowo, swagger jest bardziej „bezpryncypialny”, albo liberalny — można go generować z komentarzy w kodzie, co, oczywiście, stoi w sprzeczności z zasadą API first i nie jest wspierane przez żadne z narzędzi RAML.
My kiedyś zaczęliśmy pracować z RAML jako bardziej elastycznym językiem i w efekcie musieliśmy wiele robić własnoręcznie. Na przykład w jednym z projektów korzystamy z narzędzia w testach jednostkowych, które wspiera tylko RAML 0.8. Tak więc musieliśmy dodać obejścia, aby narzędzie mogło „przyjąć” RAML wersji 1.0.
Czy trzeba dokonywać wyboru?
Po wielu eksperymentach związanych z rozszerzaniem ekosystemu rozwiązań pod RAML doszliśmy do wniosku, że musimy przekonwertować RAML na Swagger 2 i już w nim przeprowadzać całą automatyzację, weryfikację, testowanie i późniejszą optymalizację. To dobry sposób, aby jednocześnie skorzystać z elastyczności RAML i wsparcia narzędzi społeczności od Swagger.
Do rozwiązania tego zadania istnieją dwa narzędzia OpenSource, które powinny zapewniać konwersję kontraktów:
- – obecnie nieobsługiwane narzędzie. W trakcie pracy z nim odkryliśmy, że ma szereg problemów z bardziej złożonymi RAML, które są „rozproszone” w dużej liczbie plików. Program ten jest napisany w JavaScript i wykonuje rekurencyjne przeszukiwanie drzewa składniowego. Z powodu dynamicznego typowania, zrozumienie tego kodu staje się trudne, więc postanowiliśmy nie tracić czasu na pisanie poprawek do umierającego narzędzia.
- — narzędzie tej samej firmy, które twierdzi, że jest gotowe do konwersji wszystkiego i wszędzie, w każdym kierunku. Na dzień dzisiejszy zadeklarowano wsparcie dla RAML 0.8, RAML 1.0 i Swagger 2.0. Jednak w momencie naszych badań narzędzie było jeszcze niedopracowane i nieodpowiednie do użycia. Programiści tworzą swoisty , co pozwoli im w przyszłości szybko dodawać nowe standardy. Ale na razie to wszystko po prostu nie działa.
I to jeszcze nie wszystkie trudności, z którymi się zmagamy. Jednym z kroków naszego procesu jest sprawdzenie, czy RAML z repozytorium jest poprawne w stosunku do specyfikacji. Przetestowaliśmy kilka narzędzi. Co dziwne, wszystkie one miały uwagi do naszych adnotacji w różnych miejscach, używając różnych nieprzyjemnych słów. Przy czym nie zawsze miały rację :).
Ostatecznie zdecydowaliśmy się na obecnie przestarzały projekt, który również ma szereg problemów (czasami się zawiesza, ma problemy z wyrażeniami regularnymi). W ten sposób nie znaleźliśmy sposobu na rozwiązanie problemów z walidacją i konwersją przy użyciu darmowych narzędzi, i postanowiliśmy korzystać z komercyjnego oprogramowania. W przyszłości, gdy narzędzia OpenSource staną się bardziej rozwinięte, rozwiązanie tego zadania może stać się prostsze. Na razie koszty pracy i czasu na „doprowadzenie do porządku” wydają się nam większe niż cena usługi komercyjnej.
Podsumowanie
Po tym wszystkim chcieliśmy podzielić się doświadczeniem i zauważyć, że przed wyborem narzędzia do opisywania kontraktów należy dokładnie określić, czego się od niego oczekuje i jaki budżet jest się gotowym przeznaczyć. Jeśli zapomnieć o OpenSource, już teraz istnieje wiele usług i produktów, które pomogą w weryfikacji, konwersji i walidacji. Ale są one drogie, a czasami – bardzo drogie. Dla dużej firmy takie wydatki są akceptowalne, ale dla startupu mogą stanowić dużą ciężar.
Określ zestaw narzędzi, których będziesz używać później. Na przykład, jeśli potrzebujesz tylko wyświetlić kontrakt, łatwiej będzie użyć Swagger 2, który ma ładne API, ponieważ w RAML będziesz musiał samodzielnie uruchomić i utrzymywać usługę.
Im więcej zadań będziesz miał, tym większe będzie zapotrzebowanie na narzędzia, a one różnią się w zależności od platform, dlatego lepiej od razu poznać dostępne wersje, aby podjąć decyzję minimalizującą przyszłe koszty.
Należy jednak przyznać, że wszystkie istniejące dzisiaj ekosystemy są niedoskonałe. Dlatego jeśli w firmie są entuzjaści, którzy preferują pracę w RAML, ponieważ "pozwala to na bardziej elastyczne wyrażanie myśli", lub przeciwnie, wolą Swagger, ponieważ "jest bardziej zrozumiały" — najlepiej pozostawić ich do pracy w tym, co lubią i w czym są przyzwyczajeni, ponieważ narzędzia każdego z tych formatów wymagają dopracowania.
Jeśli chodzi o nasze doświadczenie, w kolejnych postach opowiemy o tym, jakie — statyczne i dynamiczne kontrole wykonujemy na podstawie naszej architektury RAML-Swagger, a także o tym, jaką dokumentację generujemy z kontraktów i w jaki sposób to wszystko działa.
Tylko zarejestrowani użytkownicy mogą brać udział w ankiecie. , proszę.
Jakiego języka używasz do adnotacji kontraktów mikrousług?
RAML 0.8
RAML 1.0
Swagger 2
OAS3 (znany również jako)
Blueprint
Inny
Nie używam
Głosowało 100 użytkowników. 24 użytkowników się wstrzymało.
Źródło: habr.com
