In der dynamischen Welt der Microservices kann sich alles ändern – jede Komponente kann in einer anderen Sprache und unter Verwendung anderer Frameworks und Architekturen neu geschrieben werden. Lediglich die Verträge sollten unverändert bleiben, damit unabhängig von internen Metamorphosen dauerhaft von außen mit dem Microservice interagiert werden kann. Und heute werden wir über unser Problem bei der Wahl eines Formats zur Beschreibung von Verträgen sprechen und die gefundenen Artefakte teilen.
Beitrag vorbereitet и
Mikrodienste. Bei der Entwicklung von Acronis Cyber Cloud wurde uns klar, dass wir ihnen nicht entkommen konnten. Und das Entwerfen eines Microservices ist ohne die Formalisierung des Vertrags, der die Schnittstelle des Microservices darstellt, unmöglich.
Aber wenn ein Produkt mehr als eine Komponente enthält und die Vertragsentwicklung zu einer regelmäßigen Tätigkeit wird, kommt man nicht umhin, über Prozessoptimierung nachzudenken. Es wird deutlich, dass die Schnittstelle (Vertrag) und die Implementierung (Microservice) zueinander passen müssen, dass verschiedene Komponenten die gleichen Dinge auf die gleiche Weise tun müssen und dass jedes Team ohne eine zentrale Entscheidungsfindung all dieser Entscheidungen dazu gezwungen sein wird Nehmen Sie sich immer wieder Zeit, um sie zu bekommen.
Amazon Microservices-Diagramm von Werner Vogelis, CTO Amazon
Was ist das Dilemma? De facto gibt es zwei Möglichkeiten, mit Microservices zu interagieren – HTTP Rest und gRPC von Google. Da wir nicht in Googles Technologie-Stack verstrickt sein wollten, haben wir uns für HTTP Rest entschieden. HTTP-REST-Vertragsanmerkungen werden am häufigsten in einem von zwei Formaten beschrieben: RAML und OAS, früher bekannt als Swagger. Daher steht jedes Entwicklungsteam vor der Notwendigkeit, einen der Standards auszuwählen. Es stellt sich jedoch heraus, dass diese Entscheidung sehr schwierig sein kann.
Warum werden Anmerkungen benötigt?
Die Anmerkung wird benötigt, damit ein externer Benutzer leicht herausfinden kann, was mit Ihrem Dienst über seine HTTP-Schnittstelle gemacht werden kann. Das heißt, auf einer grundlegenden Ebene muss die Annotation mindestens eine Liste der verfügbaren Ressourcen, ihrer HTTP-Methoden, Anforderungstexte, eine Auflistung der Parameter, eine Angabe der erforderlichen und unterstützten Header sowie Rückgabecodes und Antwortformate enthalten. Ein äußerst wichtiges Element der Vertragsanmerkung ist ihre verbale Beschreibung („Was passiert, wenn Sie diesen Abfrageparameter zur Anfrage hinzufügen?“, „In welchem Fall wird Code 400 zurückgegeben?“).
Wenn es jedoch darum geht, eine große Anzahl von Microservices zu entwickeln, möchten Sie aus den schriftlichen Annotationen einen Mehrwert 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 diese auf Ihr Entwicklerportal hochladen :).
Beispiel einer strukturierten Vertragsbeschreibung
Weniger verbreitet ist die Praxis, Microservices anhand von Vertragsbeschreibungen zu testen. Wenn Sie sowohl eine Annotation als auch eine Komponente geschrieben haben, können Sie einen Autotest erstellen, der die Angemessenheit des Dienstes mit verschiedenen 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, offensichtlich falsche Daten korrekt zu verarbeiten?
Darüber hinaus ermöglicht die qualitativ hochwertige Implementierung nicht nur der Verträge selbst, sondern auch der Tools zur Visualisierung von Anmerkungen, die Arbeit mit dem Microservice zu vereinfachen. Das heißt, wenn der Architekt den Vertrag qualitativ beschrieben hat, werden Designer und Entwickler auf dieser Grundlage die Dienstleistung ohne zusätzlichen Zeitaufwand in andere Produkte umsetzen.
Um zusätzliche Tools zu ermöglichen, haben sowohl RAML als auch OAS die Möglichkeit, Metadaten hinzuzufügen, die nicht im Standard vorgesehen sind ().
Generell ist der Spielraum für Kreativität bei der Nutzung von Verträgen für Microservices enorm – zumindest theoretisch.
Vergleich eines Igels mit einer Schlange
Derzeit liegt der vorrangige Entwicklungsbereich bei Acronis in der Entwicklung der Acronis Cyber Platform. Die Acronis Cyber Platform bietet neue Punkte für die Integration von Drittanbieterdiensten mit der Acronis Cyber Cloud und dem Agententeil. Obwohl wir mit unseren in RAML beschriebenen internen APIs zufrieden waren, warf die Notwendigkeit, die API zu veröffentlichen, erneut die Frage auf: Welcher Annotationsstandard eignet sich am besten für unsere Arbeit?
Zunächst schien es zwei Lösungen zu geben – die häufigsten Entwicklungen waren RAML und Swagger (oder OAS). Tatsächlich stellte sich aber heraus, dass es zumindest nicht 2 Alternativen gibt, sondern 3 oder mehr.
Da ist zum einen RAML – eine mächtige und effiziente Sprache. Es implementiert Hierarchie und Vererbung gut, 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 Vertragsbestandteile haben – Authentifizierungsschemata, dieselben Datentypen, Fehlerkörper .
Aber der Entwickler von RAML, Mulesoft, hat sich dem Open API-Konsortium angeschlossen, das sich in der Entwicklung befindet . Daher hat RAML seine Entwicklung eingestellt. Um sich das Format der Veranstaltung vorzustellen, stellen Sie sich vor, dass die Betreuer der wichtigsten Linux-Komponenten zu Microsoft gegangen sind, um dort zu arbeiten. Diese Situation schafft die Voraussetzungen für den Einsatz von Swagger, das sich dynamisch weiterentwickelt und in der neuesten – dritten Version – in puncto Flexibilität und Funktionalität praktisch zu RAML aufschließt.
Wenn nicht für eine Sache, aber ...
Wie sich herausstellt, wurden nicht alle Open-Source-Dienstprogramme auf OAS 3.0 aktualisiert. Bei Microservices in Go wird der Mangel an Anpassung das Wichtigste sein für die neueste Version des Standards. Allerdings besteht der Unterschied zwischen Swagger 2 und Swagger 3 . In der dritten Version haben die Entwickler beispielsweise Folgendes getan:
- verbesserte Beschreibung von Authentifizierungsschemata
- JSON-Schema-Unterstützung
- Die Möglichkeit, Beispiele hinzuzufügen, wurde verbessert
Die Situation ist komisch: Bei der Auswahl eines Standards müssen Sie RAML, Swagger 2 und Swagger 3 als separate Alternativen berücksichtigen. Allerdings bietet nur Swagger 2 eine gute Unterstützung für OpenSource-Tools. RAML ist sehr flexibel ... und komplex, und Swagger 3 wird von der Community kaum unterstützt, sodass Sie proprietäre Tools oder kommerzielle Lösungen verwenden müssen, die in der Regel recht teuer sind.
Darüber hinaus gibt es in Swagger viele nette Funktionen, wie zum Beispiel ein vorgefertigtes Portal , auf dem Sie eine Anmerkung hochladen und deren Visualisierung mit einer detaillierten Beschreibung, Links und Verbindungen erhalten können, dann gibt es für das grundlegendere und weniger benutzerfreundliche RAML keine solche Möglichkeit. Ja, Sie können unter Projekten auf GitHub nach etwas suchen, dort ein Analogon finden und es selbst bereitstellen. In jedem Fall muss jedoch jemand das Portal warten, was für den einfachen Gebrauch oder Testzwecke nicht so praktisch ist. Darüber hinaus ist Swagger eher „prinzipienlos“ oder liberaler – es kann aus Kommentaren im Code generiert werden, was natürlich gegen das API-First-Prinzip verstößt und von keinem der RAML-Dienstprogramme unterstützt wird.
Wir begannen einmal mit RAML als einer flexibleren Sprache zu arbeiten und mussten daher viele Dinge selbst erledigen. Beispielsweise verwendet eines der Projekte das Dienstprogramm in Unit-Tests, die nur RAML 0.8 unterstützen. Also mussten wir Krücken hinzufügen, damit das Dienstprogramm RAML Version 1.0 „fressen“ konnte.
Müssen Sie wählen?
Nachdem wir an der Vervollständigung des Lösungsökosystems für RAML gearbeitet hatten, kamen wir zu dem Schluss, dass wir RAML in Swagger 2 konvertieren und darin die gesamte Automatisierung, Verifizierung, Prüfung und anschließende Optimierung durchführen müssen. Dies ist eine gute Möglichkeit, sowohl die Flexibilität von RAML als auch die Community-Tooling-Unterstützung von Swagger zu nutzen.
Um dieses Problem zu lösen, gibt es zwei OpenSource-Tools, die eine Vertragskonvertierung ermöglichen sollen:
- ist ein derzeit nicht unterstütztes Dienstprogramm. Während wir damit arbeiteten, stellten wir fest, dass es eine Reihe von Problemen mit komplexen RAMLs gibt, die über eine große Anzahl von Dateien „verteilt“ sind. Dieses Programm ist in JavaScript geschrieben und führt eine rekursive Durchquerung eines 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 aussterbendes Dienstprogramm zu schreiben.
- - ein Werkzeug derselben Firma, die behauptet, bereit zu sein, alles und jedes und in jede Richtung umzuwandeln. Bisher wurde Unterstützung für RAML 0.8, RAML 1.0 und Swagger 2.0 angekündigt. Zum Zeitpunkt unserer Recherche war der Nutzen jedoch noch vorhanden feucht und unbrauchbar. Entwickler erstellen eine Art Dadurch können sie in Zukunft schnell neue Standards hinzufügen. Aber bisher funktioniert es einfach nicht.
Und das sind noch nicht alle Schwierigkeiten, auf die wir gestoßen sind. Einer der Schritte in unserer Pipeline besteht darin, zu überprüfen, ob der RAML aus dem Repository im Verhältnis zur Spezifikation korrekt ist. Wir haben mehrere Dienstprogramme ausprobiert. Überraschenderweise beschimpften sie alle unsere Anmerkungen an unterschiedlichen Stellen und mit völlig unterschiedlichen Schimpfwörtern. Und nicht immer auf den Punkt :).
Am Ende haben wir uns für ein mittlerweile veraltetes Projekt entschieden, das ebenfalls eine Reihe von Problemen aufweist (manchmal stürzt es aus heiterem Himmel ab, es gibt Probleme bei der Arbeit mit regulären Ausdrücken). Daher haben wir keine Möglichkeit gefunden, die Probleme der Validierung und Konvertierung auf der Grundlage kostenloser Tools zu lösen, und haben uns für die Verwendung eines kommerziellen Dienstprogramms entschieden. In Zukunft, wenn OpenSource-Tools ausgereifter werden, könnte dieses Problem einfacher zu lösen sein. Mittlerweile schienen uns die Arbeits- und Zeitkosten für die „Veredelung“ bedeutender zu sein als die Kosten einer kommerziellen Dienstleistung.
Abschluss
Nach alledem möchten wir unsere Erfahrungen teilen und darauf hinweisen, dass Sie vor der Auswahl eines Tools zur Vertragsbeschreibung klar definieren müssen, was Sie davon erwarten und welches Budget Sie bereit sind zu investieren. Wenn wir OpenSource vergessen, gibt es bereits eine Vielzahl von Diensten und Produkten, die Ihnen bei der Prüfung, Konvertierung und Validierung helfen. Aber sie sind teuer und manchmal sehr teuer. Für ein großes Unternehmen sind solche Kosten erträglich, für ein Startup können sie jedoch zu einer großen Belastung werden.
Bestimmen Sie die Tools, die Sie später verwenden werden. Wenn Sie beispielsweise nur einen Vertrag anzeigen müssen, ist es einfacher, Swagger 2 zu verwenden, das über eine schöne API verfügt, da Sie den Dienst in RAML selbst erstellen und warten müssen.
Je mehr Aufgaben Sie haben, desto größer wird der Bedarf an Tools sein, und diese sind für verschiedene Plattformen unterschiedlich. Es ist besser, sich sofort mit den verfügbaren Versionen vertraut zu machen, um eine Wahl zu treffen, die Ihre Kosten in Zukunft minimiert.
Es ist jedoch anzuerkennen, dass alle heute existierenden Ökosysteme unvollkommen sind. Wenn es also Fans im Unternehmen gibt, die gerne in RAML arbeiten, weil „es es einem ermöglicht, Gedanken flexibler auszudrücken“ oder im Gegenteil Swagger bevorzugen, weil „es klarer ist“, ist es am besten, sie arbeiten zu lassen in dem, was sie sind Sie sind daran gewöhnt und wollen es, weil die Tools aller Formate eine Änderung mit einer Datei erfordern.
Was unsere Erfahrungen betrifft, werden wir in den folgenden Beiträgen darüber sprechen, welche statischen und dynamischen Prüfungen wir auf Basis unserer RAML-Swagger-Architektur durchführen, welche Dokumentation wir aus Verträgen generieren und wie das alles funktioniert.
An der Umfrage können nur registrierte Benutzer teilnehmen. bitte.
In welcher Sprache kommentieren Sie Microservice-Verträge?
-
RAML 0.8
-
RAML 1.0
-
Prahlerei 2
-
OAS3 (auch bekannt als)
-
Entwurf
-
Andere
-
Nicht verwenden
100 Benutzer haben abgestimmt. 24 Benutzer enthielten sich der Stimme.
Source: habr.com