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?

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.}

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.