Was kann mit Anmerkungen zu Microservice-Verträgen getan werden?

Im letzten Beitrag haben wir darüber gesprochen, wie und warum wir bei Ancronis Anmerkungen für Microservices erstellen, und versprochen, unsere Praxis der Verwendung eines einzigen API-Formats für die gesamte Acronis Cyber ​​Platform zu teilen. Heute werden wir über unsere Erfahrungen mit statischen Annotationsprüfungen berichten - auch bekannt als der erste Schritt auf dem Weg zur Einführung von Annotationen in einem Unternehmen.



Angenommen, Sie haben bereits Anmerkungen für alle oder die meisten APIs. Eine vernünftige Frage, die uns unsere Kollegen auch gestellt haben: „Was kann man mit diesen magischen Objekten machen?“

Tatsächlich gibt es zwei Arten von Überprüfungen, die direkt durch Anmerkungen durchgeführt werden können. Statische Überprüfungen gehen direkt zu den Texten von Swagger- oder RAML-Anmerkungen. Sie brauchen nichts anderes und können zu Recht als der erste Vorteil der Verwendung formalisierter Microservice-Verträge angesehen werden.

Dynamische Überprüfungen können nur gestartet werden, wenn Sie einen funktionierenden Dienst haben. Sie sind etwas komplizierter, da Sie tiefer eintauchen und überprüfen können, wie gültig die Anmerkung überhaupt ist, die Stabilität des Dienstes testen und auch viel mehr tun können. Aber das ist das Thema des nächsten Beitrags, und heute werden wir uns auf die Statik konzentrieren.

Es lebe die API-Richtlinie!

Um sich selbst oder andere nicht zu verwirren, sollte sofort erwähnt werden, dass statische Annotationsprüfungen erstellt werden, um die Konformität der API-Annotationen (und hoffentlich der APIs selbst) mit den Unternehmensanforderungen zu kontrollieren. Dies kann entweder nur die vom Unternehmen angewandte Vorgehensweise sein oder eine vollwertige Richtlinien-API, die die Regeln für die Vorbereitung der API für Ihre Dienste formalisiert.



Wenn wir über die farbenfrohe Welt der Microservices sprechen, ist dies sehr wichtig, da jedes Team sein eigenes Framework, seine eigene Programmiersprache, einen einzigartigen Stack oder einige spezielle Bibliotheken haben kann. Unter dem Einfluss von Praktiken, die für den Mikroservice spezifisch sind, ändert sich die Darstellung der API für einen externen Beobachter. Dies schafft unnötige Abwechslung. Für eine effektive Interaktion von Elementen eines Ökosystems (oder einer Plattform) ist es erforderlich, die API so weit wie möglich auszurichten.

Hier ein Beispiel: 404-Code wird nur dann an die API einer Komponente zurückgegeben, wenn die Ressource nicht vorhanden ist. Das andere Team bindet diesen Fehler an die Anwendungslogik und die API gibt 404 zurück, wenn der Benutzer ein Produkt kaufen möchte, das im Warehouse beendet wurde. Atygaev hat diese Probleme hier sehr deutlich beschrieben. Diese Inkonsistenz beim Verständnis von 404-Code verlangsamt die Entwicklung und führt zu Fehlern, was unnötige Supportanfragen oder zusätzliche Stunden Debugging bedeutet, aber auf jeden Fall Probleme, gemessen in Geldbeträgen.

Die vom Unternehmen übernommenen Besonderheiten der Syntax und Benennung werden durch verschiedene Aspekte ergänzt, die für REST selbst spezifisch sind. Der Entwickler muss Fragen beantworten wie:

• Wird POST idempotent sein oder nicht?
• Welche Fehlercodes verwenden wir und was bedeuten sie?
• Kann ich Fehlercodes mit Geschäftslogik versehen?

Stellen Sie sich nun vor, dass jedes Team diese Antworten einzeln durchgehen sollte.

Das Format der Suchabfrage kann auch völlig anders sein. Beispielsweise gibt es etwa ein Dutzend Möglichkeiten, ein Beispiel zu erstellen, in dem nur die Benutzer aufgelistet werden, die über MacBookPro und häufige Virenangriffe verfügen. Bei der Arbeit an einem großen Projekt, das aus Dutzenden von Microservices besteht, muss die Syntax der Suchabfrage allen Versionen und Produkten des Unternehmens gemeinsam sein. Und wenn eine Person es gewohnt ist, sich auf eines der Produkte / Dienstleistungen Ihrer Entwicklung zu beziehen, erwartet sie, dass sie dieselbe Anforderungs- und Antwortstruktur in einer anderen findet. Andernfalls werden Erstaunen (und Trauer) nicht vermieden.

Viele Unternehmen, insbesondere Giganten wie Microsoft , PayPal und Google , haben ihre eigenen Richtlinien und sind sehr gut durchdacht. Die Verwendung der Richtlinien anderer Personen ist jedoch nicht immer möglich, da diese weitgehend an die Besonderheiten des Unternehmens gebunden sind. Darüber hinaus hat das Denken eines jeden eine andere Struktur, und die Regeln können einfach deshalb unterschiedlich sein, weil es für Menschen bequemer ist, auf diese Weise und nicht anders zu arbeiten.

Das Verständnis, dass Acronis eine eigene API-Richtlinie benötigt, kam nicht sofort, sondern mit der wachsenden Anzahl von Entwicklern, Microservices und tatsächlich externen Clients und Integrationen. Irgendwann musste das Architektenteam einheitliche Regeln für die Deklaration der API festlegen, wobei sowohl die Erfahrungen der oben genannten IT-Giganten als auch bereits etablierte De-facto-Praktiken in Entwicklungsteams berücksichtigt wurden.

Eines der Probleme bei dieser späten Implementierung der Richtlinien-API sind die vorhandenen veröffentlichten APIs, die die Anforderungen nicht erfüllen, was wiederum zu zusätzlichen Kosten für die Neugestaltung der Schnittstellen und die Aufrechterhaltung der Abwärtskompatibilität führt. Wenn Ihr Geschäftsmodell die zukünftige Integration und Veröffentlichung der API umfasst, müssen Sie daher so früh wie möglich über einheitliche Regeln nachdenken.



Natürlich hat die Übernahme der Richtlinien-APIs nicht automatisch alle APIs konstitutiv gemacht. Jede API musste analysiert werden, jeder Entwickler musste neue Anforderungen verstehen. Daher haben wir die Automatisierung von RAML-Prüfungen anhand der von uns entwickelten Richtlinien-API durchgeführt.
Statische Analyse

Zuerst müssen Sie entscheiden, was wir statisch analysieren. Nicht alle Richtlinien-API-Punkte können formalisiert werden. Daher müssen Sie zunächst eine Reihe von Regeln hervorheben, die anhand der API-Annotation leicht zu verstehen sind.

In der ersten Version haben wir die folgenden Regeln identifiziert:

1. Suchen Sie nach API-Beschreibungen. Wie bereits in unserem vorherigen Artikel erwähnt, können Sie anhand der API-Annotation eine schöne Dokumentation erstellen. Dies bedeutet, dass jede Ressource, jeder Abfrageparameter und jede Antwort eine Beschreibung haben sollte, die jedem Benutzer unserer API alle erforderlichen Informationen liefert. Es scheint eine Kleinigkeit zu sein, aber wie einfach ist es, Entwicklern zu zeigen, dass ihre Anmerkungen nicht reich an Beschreibungen sind!
2. Überprüfung auf Vorhandensein und Richtigkeit von Beispielen. Mit API-Anmerkungssprachen können Sie auch Beispiele beschreiben. Als Antwort können wir beispielsweise ein Beispiel für eine echte Serviceantwort hinzufügen, etwas aus dem realen Leben. Anhand von Beispielen wird erläutert, wie der Endpunkt verwendet werden soll und wie er funktioniert, und anhand statischer Analysen von Anmerkungen wird nach Beispielen gesucht.
3. Validierung von HTTP-Antwortcodes. Der HTTP-Standard definiert eine große Anzahl von Codes, die jedoch unterschiedlich interpretiert werden können. Unsere Richtlinie formalisiert die Verwendung von Codes. Wir beschränken auch die Anwendbarkeit verschiedener Codes gemäß der HTTP-Methode. Beispielsweise wird Code 201 gemäß der HTTP-Spezifikation zurückgegeben, wenn eine Ressource erstellt wird. Daher ist das GET, das 201 zurückgibt, ein Weckruf (entweder wird der Code falsch verwendet oder GET erstellt die Ressource). Daher verbietet unsere Richtlinien-API eine solche Verwendung. Darüber hinaus haben Architekten feste Codesätze für jede Methode, und jetzt überprüfen wir sie im statischen Modus auf der Ebene der Anmerkungen.
4. Überprüfen von HTTP-Methoden. Jeder weiß, dass das HTTP-Protokoll über eine Reihe von Standardmethoden (GET, POST, PUT usw.) verfügt und auch die Verwendung benutzerdefinierter Methoden ermöglicht. Unsere Richtlinien-API beschreibt zulässige Methoden, die zulässig, aber unerwünscht (OPTIONEN) sowie vollständig verboten sind (kann nur mit dem Segen von Architekten verwendet werden). Verboten sind die Standard-HEAD-Methode sowie alle benutzerdefinierten Methoden. All dies lässt sich auch leicht in den Anmerkungen zu den Verträgen überprüfen.
5. Überprüfung der Zugriffsrechte. Wir hoffen, dass der Bedarf an Autorisierungsunterstützung im Jahr 2019 keine zusätzlichen Erläuterungen erfordert. Eine gute Dokumentation sollte Informationen darüber enthalten, welche Rollen die API unterstützt und welche API-Methoden für jede Rolle verfügbar sind. Neben der Dokumentation von Informationen zum Vorbild, die auf Annotationsebene aufgezeichnet wurden, können Sie viel interessantere Dinge in der Dynamik tun. Wir werden jedoch im nächsten Artikel darauf eingehen.
6. Validierung der Benennung. Lindert Kopfschmerzen bei der Verwendung unterschiedlicher Ansätze zur Benennung von Entitäten. Im Allgemeinen gibt es zwei „Lager“ - Unterstützer von CamelCase und snake_case.Camelcase - wenn jedes Wort mit einem Großbuchstaben beginnt, und snake_case - wenn Wörter durch Unterstriche getrennt sind und alles in kleinen Buchstaben geschrieben ist. In verschiedenen Sprachen ist es üblich, Namen auf unterschiedliche Weise zu vergeben. Beispielsweise wird snake_case in Python akzeptiert und CamelCase in Go oder Java. Wir haben unsere eigene Auswahl für alle Projekte universell getroffen und in der API-Richtlinie festgelegt. Daher überprüfen wir durch Anmerkungen die Namen von Ressourcen und Parametern statisch.
7. Validierung von benutzerdefinierten Headern. Dies ist ein weiteres Beispiel für eine Namensprüfung, die jedoch speziell an Köpfe gebunden ist. Bei uns in Acronis ist es üblich, das Format des Formulars X-Custom-Header-Name zu verwenden (obwohl dieses Format veraltet ist). Und wir kontrollieren die Einhaltung auf der Ebene der Anmerkungen.
8. Überprüfen Sie die HTTPS-Unterstützung. Jeder moderne Dienst sollte HTTPS unterstützen, und einige glauben, dass die Arbeit mit HTTP heutzutage im Allgemeinen eine schlechte Nachricht ist. Daher sollte die Annotation RAML oder Swagger angegeben werden. dass der Microservice HTTPS ohne HTTP unterstützt.
9. Überprüfen Sie die Struktur des URI. In prähistorischen Zeiten, dh vor der Veröffentlichung der Richtlinien-API, sah der Anforderungs-URI in verschiedenen Diensten unterschiedlich aus: irgendwo / api / 2, irgendwo / api / service_name / v2 und so weiter. In unserer Richtlinie ist jetzt eine Standard-URI-Struktur für alle unsere APIs definiert. Das Handbuch beschreibt, wie sie aussehen sollten, um keine Verwirrung zu stiften.
10. Überprüfen der Kompatibilität neuer Versionen. Ein weiterer Faktor, den jeder API-Autor berücksichtigen sollte, ist die Abwärtskompatibilität. Es ist wichtig zu überprüfen, ob der auf der alten API basierende Code mit der neuen Version funktioniert. Basierend auf dieser Änderung kann in zwei Kategorien unterteilt werden: Aufheben der Abwärtskompatibilität und Kompatibilität. Jeder weiß, dass das Brechen von Änderungen inakzeptabel ist. Wenn Sie etwas dramatisch „verbessern“ möchten, sollte der Entwickler eine neue Version der API veröffentlichen. Jeder kann sich jedoch irren. Daher besteht unser anderes Ziel bei statischen Überprüfungen darin, nur kompatible Änderungen zu überspringen und auf inkompatible Änderungen zu schwören. Es wird davon ausgegangen, dass die Annotation wie der Code im Repository gespeichert ist und daher den gesamten Änderungsverlauf aufweist. Daher können wir unseren HTTP-REST auf Abwärtskompatibilität überprüfen. Beispielsweise verstößt das Hinzufügen von (Methode, Parameter, Antwortcode) Kompatibilität nicht, und das Entfernen kann durchaus zu einem Verlust der Kompatibilität führen. Und dies kann bereits auf der Annotationsebene überprüft werden.

Wenn es keine Beschreibungen gibt

Wenn es Beschreibungen gibt

Schlussfolgerungen

Eine statische Analyse der Anmerkungen ist erforderlich, um zu überprüfen (nein, nicht die Servicequalität), sondern die Qualität der API. In dieser Phase können Sie die Programmschnittstellen so aufeinander abstimmen, dass die Mitarbeiter in einer klaren und verständlichen Umgebung arbeiten, in der alles ziemlich vorhersehbar ist.

Natürlich ist es nur in ausreichend großen Unternehmen notwendig, sich mit einem solchen Formalismus zu befassen, wenn die manuelle Überprüfung aller Korrespondenzen sehr langwierig, teuer und unzuverlässig ist. Ein kleines Startup braucht es einfach nicht. Zumindest vorerst. Wenn es jedoch in Zukunft Pläne gibt, ein Einhorn wie Akronis zu werden, helfen Ihnen statische Überprüfungen und die Richtlinien-API.