Verwalten und Dokumentieren von API-Endpunkten vieler Anwendungen in einer Microservice-Architektur

Ich denke, einer der größten Probleme bei der Arbeit mit Microservices besteht darin, sicherzustellen, dass die APIs gut dokumentiert sind und APIs ihr Verhalten nicht ändern, ohne die nachgelagerten Anwendungen zu beeinträchtigen. Dieses Problem wird verstärkt, wenn Sie viele Dienste haben, die voneinander abhängig sind. Vielleicht machen Sie an diesem Punkt Microservices falsch, aber ich schweife ab.

Angenommen, wir haben 20 Microservices geerbt, die verschiedenen Teams gehören, und es gibt keine eindeutige Dokumentation darüber, welche Anwendung den API-Endpunkt anderer Anwendungen verwendet. Gibt es eine vorgeschriebene Möglichkeit, dies zu dokumentieren? Zuerst dachte ich daran, die Endpunkte jeder Anwendung zu analysieren und sie einer Datenbanktabelle hinzuzufügen, dann eine FK-Beziehung zwischen jeder Anwendung und der Route einer Anwendung in einer Viele-zu-Viele-Tabelle zu erstellen (fast alle davon sind Rails-Apps). Aber ich bin mir nicht sicher, ob dies ein guter Weg ist, um damit umzugehen, oder ob ich das Rad hier neu erfinde.

Rückblickend könnte dies eine nicht so schlechte Möglichkeit sein, die Anwendungsinteraktion zu dokumentieren, wenn Sie mit Microservices von Grund auf neu beginnen. Dies würde lediglich erzwingen, dass eine einzige Wahrheitsquelle über die Verwendung einer Datenbank aufrechterhalten wird und alle Änderungen an den Endpunkten in der Anwendung in Verbindung mit der Änderung der Datenbank vorgenommen werden. Gedanken?

api-design documentation microservices

— Hyde
quelle

Antworten:

Ein großer Teil des Vorteils einer "Microservice-Architektur" besteht darin, dass Sie nicht alle diese Beziehungen dokumentieren. Jeder Service ist ein eigenes Produkt. Und jeder Servicebesitzer ist für den Betrieb seines Service als eigenständiges Produkt verantwortlich. Das kann Dinge beinhalten wie:

Veröffentlichen von "Marketing" -Dokumenten, Benutzerdokumenten und Änderungsprotokollen (einschließlich Verfall )
Bieten Sie Kunden / Verbrauchern die Möglichkeit, Funktionen anzufordern / Fehler zu melden
Aufrechterhaltung einer SLA
Aktualisierungen so abwärtskompatibel wie möglich gestalten und Änderungen aufheben
Kennen und Ansehen von Newsfeeds für Dienste, die sie direkt nutzen
Bereinigen von Abhängigkeiten, wenn möglich
Verwerfen des gesamten Dienstes, wenn die Wartung irrelevant oder zu kostspielig wird

Und so weiter.

Vor allem möchte ich als einen der Hauptvorteile eines Microservices die Möglichkeit für Servicebesitzer hervorheben, sich wirklich auf das "eine" zu konzentrieren und sich darauf zu spezialisieren, was ihr Service tut.

Wo jeder Produkt- oder Servicebesitzer seine eigenen Abhängigkeiten dokumentieren sollte - dies sollte "natürlich" geschehen, wenn sie zur Konfiguration Ihres Compilers (oder zum Build-Skript) hinzugefügt werden. Wenn Sie wissen müssen, wovon ServiceA abhängt ServiceA/Configuration.xml(oder was auch immer ), werden Sie darüber informiert . Ich würde normalerweise erwarten auch jeder Service Eigentümer zunächst Diagramm ihre eigenen unmittelbaren Abhängigkeiten - aber nicht Abhängigkeiten von Abhängigkeiten und so weiter. Und da die Informationen bereits im Code enthalten sind, würde ich nicht unbedingt erwarten, dass diese Diagramme auch in Zukunft beibehalten werden.

^{Wenn Sie wirklich ein globales Bild wünschen, scannen Sie die Konfigurations- / Build-Skripte. Was Sie mit dieser Ausgabe tun, wie Sie sie speichern usw., hängt ganz davon ab, welche Entscheidungen die Daten Ihnen helfen.}

— svidgen
quelle

Ich denke, dies ist ein guter Weg, um das Problem anzugreifen, wenn Sie mit dem Erstellen mit Microservices beginnen. Für das vorhandene Setup plane ich jedoch, Apache-Protokolle zu analysieren, um einige Verwendungsinformationen zu erhalten und diese zu dokumentieren sowie ein Meeting mit der Anwendung abzuhalten Besitzer.

— Hyde

@hyde Sind Sie in einer Position, in der Sie vernünftigerweise verlangen können, dass die Servicebesitzer jeweils die Existenz ihres Service rechtfertigen? (Unterstützt mit Metriken und Protokolldaten?) Oder sind Sie der Dienstbesitzer? ... Haben Sie ein zentrales Repository mit Repositorys, mit denen Sie diese App-Konfigurationen nach Dienstreferenzen durchsuchen können?

— Svidgen

Nein, ich bin derzeit nicht in der Lage, die Art und Weise zu ändern, in der diese Anwendungen eingerichtet sind. Ich denke, Sie haben dies impliziert, indem Sie die Dienstbesitzer gebeten haben, ihre Existenz zu rechtfertigen. ;) Ich hatte das Glück, auf JSON-Dateien in unseren Produktionsservern zu stoßen, in denen Dienste und die URLs aufgelistet sind, mit denen sie diese erreichen. Dies liefert zwar kein vollständiges Bild des Setups, aber ich denke, es ist ein guter Ausgangspunkt.

— Hyde

Umm. Nicht wirklich das, was ich angedeutet habe. Aber ich habe meinen Kommentar sehr schlecht formuliert ... Wenn jeder Servicebesitzer die oben aufgeführten Dinge verantwortungsbewusst tut, sollte jeder Eigentümer Ihnen sagen können, wo sein Service hineinpasst und welche Abhängigkeiten er hat (oder ob er überhaupt vorhanden ist) benutzt).

— Svidgen

... Darüber hinaus sind die Service-Interaktionen in dem besonders großen Unternehmen, für das ich derzeit arbeite, so kompliziert, dass sie nicht vollständig grafisch dargestellt werden können. Und das ist in Ordnung. Jeder Eigentümer kennt die Abhängigkeiten seines Dienstes und verspricht seinen Verbrauchern eine Kombination aus vielversprechender Abwärtskompatibilität (normalerweise), Mailinglisten für die Ausnahmen und SLAs.

— Svidgen

Ich denke, eine gute Idee ist es, ein Integrationsdiagramm zu erstellen und dieses in Ihr Repository aufzunehmen. Wählen Sie ein kostenloses Tool (wie draw.io), mit dem Sie das Diagramm in eine XML- oder JSON-Datei exportieren und diese Datei in Ihrem Repository festschreiben können. Wenn Sie Github oder Gitlab verwenden, generieren Sie das Bild aus diesem Diagramm und fügen Sie es in das Wiki oder sogar in die Datei README.md ein, damit das Bild jedes Mal sichtbar ist, wenn der Entwickler das Repository im Browser visualisiert.

Die gleiche Strategie kann für die Datenbank verwendet werden.

In Bezug auf die API-Ressourcendokumentation ist Swagger eine gute Option.

Dieses Problem wird verstärkt, wenn Sie viele Dienste haben, die voneinander abhängig sind. Vielleicht machen Sie an diesem Punkt Microservices falsch, aber ich schweife ab.

Dies ist sicher ein Problem.

— Dherik
quelle

Es gibt andere Alternativen, aber es lohnt sich, ein Auge darauf zu werfen, welche API-Testumgebungen (wie PostMan) unterstützt werden. RAML ist eine weitere Option im selben Raum. Dieselbe Beschreibung JSON kann HTML-API-Dokumente generieren und verwendet werden, um Ihren Dienst anderen zu beschreiben. Das heißt, Sie können es verwenden, um Webbindungen zu generieren. (sowohl Swagger als auch RAML unterstützen dies).

— Berin Loritsch