Also alle gleich RAML oder OAS (Swagger)?

In der dynamischen Welt der Microservices kann sich alles ändern - jede Komponente kann mit anderen Frameworks und Architekturen in einer anderen Sprache umgeschrieben werden. Nur Verträge sollten unverändert bleiben, damit unabhängig von internen Metamorphosen eine konstante Interaktion mit dem Microservice von außen möglich ist. Und heute werden wir über unser Problem sprechen, ein Format für die Beschreibung von Verträgen zu wählen und gefundene Artefakte zu teilen.



Der Beitrag wurde von Anna Melekhova und Vladimir Lapatin vorbereitet

Microservices. Bei der Entwicklung der Acronis Cyber ​​Cloud haben wir festgestellt, dass wir ihnen nicht entkommen können. Das Entwerfen eines Microservices ist ohne die Formalisierung eines Vertrags, der die Schnittstelle eines Microservices darstellt, nicht möglich.

Wenn ein Produkt jedoch mehr als eine Komponente enthält und die Entwicklung eines Vertrags zu einer regelmäßigen Aktivität wird, beginnen Sie unwillkürlich, über eine Optimierung des Prozesses nachzudenken. Es wird deutlich, dass die Schnittstelle (Vertrag) und die Implementierung (Microservice) einander entsprechen müssen, dass verschiedene Komponenten dasselbe tun müssen und dass jedes Team ohne eine zentralisierte Übernahme all dieser Entscheidungen gezwungen sein wird, Zeit damit zu verbringen, sie immer wieder zu erhalten .


Amazon Microservice Layout von Werner Vogelis Tweet , Amazon CTO
Was ist das Dilemma? De facto gibt es zwei Möglichkeiten, wie Microservices interagieren: HTTP Rest und gRPC von Google. Wir wollten uns nicht auf den Google-Technologie-Stack einlassen und haben uns für HTTP Rest entschieden. Anmerkungen zu HTTP-REST-Verträgen werden am häufigsten in einem von zwei Formaten beschrieben: RAML und OAS, früher bekannt als Swagger. Daher muss jedes Entwicklungsteam einen der Standards auswählen. Es stellte sich jedoch heraus, dass es sehr schwierig sein kann, diese Wahl zu treffen.

Warum Anmerkungen?

Es sind Anmerkungen erforderlich, damit ein externer Benutzer über die HTTP-Schnittstelle leicht herausfinden kann, was mit Ihrem Dienst getan werden kann. Das heißt, auf einer grundlegenden Ebene sollte die Anmerkung mindestens eine Liste der verfügbaren Ressourcen, ihrer HTTP-Methoden, Anforderungskörper, eine Aufzählung von Parametern, eine Angabe der erforderlichen und unterstützten Header sowie Rückkehrcodes und Antwortformate enthalten. Ein äußerst wichtiges Element der Vertragsanmerkung ist ihre mündliche Beschreibung ("Was passiert, wenn Sie diesen Abfrageparameter zur Anforderung hinzufügen?", "In welchem ​​Fall wird der 400-Code zurückgegeben?").

Wenn ich jedoch eine große Anzahl von Mikrodiensten entwickeln möchte, möchte ich aus den schriftlichen Anmerkungen einen zusätzlichen Nutzen ziehen. Basierend auf RAML / Swagger können Sie beispielsweise sowohl Client- als auch Servercode in einer Vielzahl von Programmiersprachen generieren. Sie können auch automatisch eine Dokumentation für den Microservice erhalten und auf Ihr Entwicklerportal hochladen :).


Ein Beispiel für eine strukturierte Vertragsbeschreibung

Weniger verbreitet ist das Testen von Microservices anhand von Vertragsbeschreibungen. Wenn Sie eine Anmerkung und eine Komponente geschrieben haben, können Sie einen Autotest erstellen, der die Angemessenheit des Dienstes anhand verschiedener Arten von Eingabedaten überprüft. Gibt der Dienst einen Antwortcode zurück, der nicht in der Anmerkung beschrieben ist? Wird es in der Lage sein, wissentlich falsche Daten korrekt zu verarbeiten?

Darüber hinaus erleichtert die qualitativ hochwertige Implementierung nicht nur der Verträge selbst, sondern auch der Tools zur Visualisierung von Anmerkungen die Arbeit mit dem Microservice. Das heißt, wenn der Architekt den Vertrag qualitativ beschrieben hat, werden Designer und Entwickler den Service auf seiner Basis ohne zusätzliche Zeitkosten in andere Produkte implementieren.

Für den Betrieb zusätzlicher Tools können sowohl RAML als auch OAS Metadaten hinzufügen, die nicht vom Standard bereitgestellt werden ( dies erfolgt beispielsweise in OAS ).

Im Allgemeinen ist das Feld für Kreativität bei der Anwendung von Verträgen für Mikrodienstleistungen riesig ... zumindest theoretisch

Vergleich eines Igels mit einer Schlange

Derzeit ist der vorrangige Entwicklungsbereich von Acronis die Entwicklung der Acronis Cyber ​​Platform. Acronis Cyber ​​Platform - Dies sind neue Punkte für die Integration von Diensten von Drittanbietern in die Acronis Cyber ​​Cloud und den Agententeil. Obwohl unsere in RAML beschriebenen internen APIs für uns in Ordnung waren, warf die Notwendigkeit, die API erneut zu veröffentlichen, die Frage der Wahl auf: Welcher Anmerkungsstandard ist für unsere Arbeit besser zu verwenden?

Anfangs schien es zwei Lösungen zu geben - dies waren die häufigsten Entwicklungen von RAML und Swagger (oder OAS). Tatsächlich stellte sich jedoch heraus, dass die Alternativen mindestens nicht 2, sondern 3 oder mehr sind.

Einerseits gibt es RAML - eine leistungsstarke und effektive Sprache. Hierarchie und Vererbung lassen sich gut implementieren, sodass dieses Format besser für große Unternehmen geeignet ist, die viele Beschreibungen benötigen - das heißt, nicht ein Produkt, sondern viele Microservices, die gemeinsame Teile von Verträgen haben - Authentifizierungsschemata, dieselben Datentypen, Fehlerkörper.

Der RAML-Entwickler Mulesoft hat sich jedoch dem Open API-Konsortium angeschlossen, das Swagger entwickelt. Daher hat RAML seine Entwicklung eingestellt. Um sich das Format des Ereignisses vorzustellen, stellen Sie sich vor, dass die Betreuer der wichtigsten Linux-Komponenten bei Microsoft gearbeitet haben. Diese Situation schafft die Voraussetzungen für die Verwendung von Swagger, das sich dynamisch entwickelt und in der neuesten - dritten Version - RAML in Bezug auf Flexibilität und Funktionalität praktisch einholt.

Wenn nicht für einen, aber ...

Wie sich herausstellte, wurden nicht alle Open-Source-Dienstprogramme auf Version OAS 3.0 aktualisiert. Für Microservices on Go ist die fehlende Anpassung von go-swagger an die neueste Version des Standards am kritischsten. Der Unterschied zwischen Swagger 2 und Swagger 3 ist jedoch enorm . Zum Beispiel in der dritten Version die Entwickler:

• verbesserte Beschreibung von Authentifizierungsschemata
• Unterstützung für JSON-Schema abgeschlossen
• pumpte die Fähigkeit, Beispiele hinzuzufügen

Die Situation ist lustig: Bei der Auswahl eines Standards müssen Sie RAML, Swagger 2 und Swagger 3 als separate Alternativen betrachten. Allerdings unterstützt nur Swagger 2 das OpenSource-Toolkit gut. RAML ist sehr flexibel ... und komplex, und Swagger 3 wird von der Community nur unzureichend unterstützt. Daher müssen Sie proprietäre Tools oder kommerzielle Lösungen verwenden, die normalerweise sehr teuer sind.

Wenn es in Swagger viele nette Funktionen gibt, wie zum Beispiel das vorgefertigte Portal editor.swagger.io , auf das Sie die Anmerkung herunterladen und ihre Visualisierung mit einer detaillierten Beschreibung, Links und Links erhalten können, gibt es keine solche Möglichkeit für eine grundlegendere und weniger benutzerfreundliche RAML. Ja, Sie können auf GitHub nach etwas unter den Projekten suchen, dort ein Analogon finden und es selbst bereitstellen. In jedem Fall muss jedoch jemand das Portal unterstützen, was für die grundlegende Verwendung oder Testanforderungen nicht so praktisch ist. Darüber hinaus ist Swagger eher "prinzipienlos", gut oder liberal - es kann aus Kommentaren im Code generiert werden, was natürlich zuerst dem API-Prinzip zuwiderläuft und von keinem der RAML-Dienstprogramme unterstützt wird.

Einmal haben wir angefangen, mit RAML als flexiblerer Sprache zu arbeiten, und deshalb mussten wir viel mit unseren eigenen Händen tun. Beispielsweise verwendet eines der Projekte das Dienstprogramm ramlfications in Komponententests , das nur RAML 0.8 unterstützt. Also musste ich Krücken hinzufügen, damit das Dienstprogramm RAML Version 1.0 "essen" konnte.

Muss ich wählen

Nachdem wir uns mit dem Hinzufügen eines Ökosystems von Lösungen für RAML befasst hatten, kamen wir zu dem Schluss, dass wir RAML in Swagger 2 konvertieren müssen und bereits die gesamte Automatisierung, Verifizierung, Prüfung und anschließende Optimierung darin durchführen müssen. Dies ist eine gute Möglichkeit, sowohl die Flexibilität von RAML als auch die Unterstützung von Community-Tools von Swagger zu nutzen.

Um dieses Problem zu lösen, gibt es zwei OpenSource-Tools, die die Konvertierung von Verträgen sicherstellen sollen:

1. oas-raml-converter ist jetzt ein nicht unterstütztes Dienstprogramm. Während der Arbeit mit ihr stellten wir fest, dass sie eine Reihe von Problemen mit komplexen RAMLs hat, die über eine große Anzahl von Dateien verteilt sind. Dieses Programm ist in JavaScript geschrieben und führt eine rekursive Durchquerung des Syntaxbaums durch. Aufgrund der dynamischen Eingabe wird es schwierig, diesen Code zu verstehen. Daher haben wir beschlossen, keine Zeit damit zu verschwenden, Patches für ein sterbendes Dienstprogramm zu schreiben.
2. webapi-parser ist ein Tool desselben Unternehmens, das behauptet, bereit zu sein, alles und jeden in jede Richtung zu konvertieren. Bisher wurde die Unterstützung von RAML 0.8, RAML 1.0 und Swagger 2.0 angekündigt. Zum Zeitpunkt unserer Studie war der Nutzen jedoch EXTREM roh und unbrauchbar. Entwickler erstellen eine Art IR , mit der sie in Zukunft schnell neue Standards hinzufügen können. Aber im Moment funktioniert das alles einfach nicht.

Und das sind nicht alle Schwierigkeiten, auf die wir gestoßen sind. Einer der Schritte in unserer Pipeline besteht darin, zu überprüfen, ob die RAML aus dem Repository in Bezug auf die Spezifikation korrekt ist. Wir haben verschiedene Dienstprogramme ausprobiert. Überraschenderweise verfluchten sie alle unsere Anmerkungen an verschiedenen Orten und mit völlig unterschiedlichen schlechten Worten. Und nicht immer der Fall :).

Am Ende haben wir uns für das mittlerweile veraltete Projekt entschieden, das auch eine Reihe von Problemen aufweist (manchmal fällt es aus heiterem Himmel, hat Probleme bei der Arbeit mit regulären Ausdrücken). Daher haben wir keine Möglichkeit gefunden, die Validierungs- und Konvertierungsaufgaben basierend auf kostenlosen Tools zu lösen, und haben uns für ein kommerzielles Dienstprogramm entschieden. In Zukunft, wenn OpenSource-Tools weiterentwickelt werden, wird die Lösung dieses Problems möglicherweise einfacher. In der Zwischenzeit schien uns der Zeit- und Arbeitsaufwand für das „Finishing“ bedeutender zu sein als die Kosten einer kommerziellen Dienstleistung.

Fazit

Nach all dem wollten wir unsere Erfahrungen teilen und feststellen, dass Sie vor der Auswahl eines Tools zur Beschreibung von Verträgen klar bestimmen müssen, was Sie davon wollen und welches Budget Sie investieren möchten. Wenn Sie OpenSource vergessen, gibt es jetzt eine große Anzahl von Diensten und Produkten, mit denen Sie prüfen, konvertieren und validieren können. Aber sie sind teuer und manchmal sehr teuer. Für ein großes Unternehmen sind solche Kosten tolerierbar, für ein Startup kann dies jedoch zu einer großen Belastung werden.

Definieren Sie eine Reihe von Tools, die Sie später verwenden werden. Wenn Sie beispielsweise nur den Vertrag anzeigen müssen, ist es einfacher, Swagger 2 zu verwenden, das über eine schöne API verfügt, da Sie in RAML den Service selbst aufheben und warten müssen.
Je mehr Aufgaben Sie haben, desto größer ist der Bedarf an Tools, und diese sind für verschiedene Plattformen unterschiedlich. Es ist besser, sich sofort mit den verfügbaren Versionen vertraut zu machen, um eine Auswahl zu treffen, die Ihre Kosten in Zukunft minimiert.

Es ist jedoch zu beachten, dass alle heute existierenden Ökosysteme unvollkommen sind. Wenn das Unternehmen Fans hat, die gerne in RAML arbeiten, weil „Sie damit Ihre Gedanken flexibler ausdrücken können“ oder im Gegenteil Swagger bevorzugen, weil „es verständlicher ist“, ist es am besten, sie in dem zu lassen, was sie tun Sie sind es gewohnt und wollen es, weil das Toolkit eines der Formate mit einer Datei finalisiert werden muss.

In den folgenden Beiträgen werden wir erfahren, welche statischen und dynamischen Überprüfungen wir basierend auf unserer RAML-Swagger-Architektur durchführen, welche Dokumentation wir aus Verträgen generieren und wie alles funktioniert.