Öffentliche Aufträge, wie ihre Konsistenz sichergestellt werden kann

• Besteht Ihr System aus vielen miteinander verbundenen Diensten?
• Aktualisieren Sie den Service-Code immer noch manuell, wenn Sie die öffentliche API ändern?
• Änderungen in Ihren Diensten untergraben oft die Arbeit anderer, und andere Entwickler hassen Sie dafür?

Bedingungen

Um was geht es in dem Artikel

Wie sieht das Problem aus?

So lösen Sie dieses Problem

Das Lieferantenservice-Team wird alles reparieren

Aktualisieren Sie den Code Ihres Dienstes für das Verbraucherteam

Überlegen Sie, was zu tun ist, um das Auftreten des Problems zu verhindern

So verhindern Sie die Manifestation eines Problems

1. in der Entwurfsphase Verträge deklarativ definieren;
2. Während der Implementierung generieren wir Server- und Client-Code im Rahmen von Verträgen.
3. Beim Testen prüfen wir Verträge und versuchen, die Kundenbedürfnisse (CDC) zu berücksichtigen.

Wie das Problem bei uns aussieht

Vom Problem zur Aufgabe

• serverseitig - Controller sind bereits geschrieben;
• Der Browser ist ein Client des Dienstes.
• Dienste kommunizieren über HTTP.
• Generation muss abgestimmt werden. Zum Beispiel, um JWT zu unterstützen.

Fragen

• welches Werkzeug zu wählen ist;
• wie man Verträge bekommt;
• wo die Verträge zu platzieren sind;
• Wo soll der Client-Code platziert werden?
• an welchem ​​Punkt die Generation zu tun.

Welches Tool soll ich wählen?

Werkzeuge

Tools für die Arbeit mit OpenAPI

Wo kann man Verträge abschließen? So greifen Sie auf Dienste zu Verträgen zu

• Der Provider-Service-Projektordner ist die einfachste Option. Wenn Sie den Ansatz ausführen müssen, wählen Sie ihn aus.
• Ein freigegebener Ordner ist eine gültige Option, wenn sich die gewünschten Projekte im selben Repository befinden. Auf lange Sicht wird es schwierig sein, die Integrität der Verträge im Ordner aufrechtzuerhalten. Dies erfordert möglicherweise ein zusätzliches Tool, um verschiedene Versionen von Verträgen usw. zu berücksichtigen.
• Separates Repository für Spezifikationen - Wenn sich die Projekte in verschiedenen Repositories befinden, sollten die Verträge an einem öffentlichen Ort platziert werden. Die Nachteile sind die gleichen wie beim freigegebenen Ordner.
• über die Service-API (swagger.ui, swaggerhub) - ein separater Service, der sich mit dem Spezifikationsmanagement befasst.

Ab wann generieren Sie

Wo soll der Client-Code platziert werden?

• Der Client-Code ist in der Nähe seines Dienstes und ständig auf dem neuesten Stand.
• Verbraucher können den Link zum Projekt in einem Repository verwenden.

• funktioniert nicht, wenn Sie einen Client in einem anderen Teil des Systems generieren müssen, z. B. in einem anderen Repository. Es wird gelöst, indem mindestens ein freigegebener Ordner für Verträge verwendet wird.
• Verbraucher müssen in derselben Sprache verfasst sein. Wenn Sie einen Client in einer anderen Sprache benötigen, müssen Sie OpenApiTools verwenden.

Wir befestigen NSwag

Controller-Attribute

[Microsoft.AspNetCore.Mvc.Routing.Route("[controller]")]  //  url
[Microsoft.AspNetCore.Mvc.ApiController] //     
public class DescriptionController : ControllerBase {
[NSwag.Annotations.OpenApiOperation("GetDescription")] //    
[Microsoft.AspNetCore.Mvc.ProducesResponseType(typeof(ConversionDescription), 200)] //    200  
[Microsoft.AspNetCore.Mvc.ProducesResponseType(401)] //    401
[Microsoft.AspNetCore.Mvc.ProducesResponseType(403)] //    403
[Microsoft.AspNetCore.Mvc.HttpGet("{pluginName}/{binaryDataId}")] //  url
public ActionResult<ConversionDescription> GetDescription(string pluginName, Guid binaryDataId) { 
 // ... 
}

[Microsoft.AspNetCore.Mvc.Route("[controller]")]
[Microsoft.AspNetCore.Mvc.ApiController]
public class FileController : ControllerBase {
[NSwag.Annotations.OpenApiOperation("SaveFile")]
[Microsoft.AspNetCore.Mvc.ProducesResponseType(401)]
[Microsoft.AspNetCore.Mvc.ProducesResponseType(403)]
[Microsoft.AspNetCore.Mvc.HttpPost("{pluginName}/{binaryDataId}/{fileName}")]
[OurNamespace.FileUploadOperation] //  
public async Task SaveFile() { // ... }

Prozessor zum Generieren von Spezifikationen für Dateivorgänge

• FileUploadOperationAttribute: OpenApiOperationProcessorAttribute
• FileUploadOperationProcessor: IOperationProcessor

NSwag-Konfiguration zur Spezifikations- und Codegenerierung

• Laufzeit - Gibt die .net-Laufzeit an. Zum Beispiel NetCore22;
• documentGenerator - beschreibt, wie eine Spezifikation generiert wird;
• codeGenerators - Definiert, wie Code gemäß der Spezifikation generiert wird.

Wir generieren die Spezifikation und den Client-Code bei der Zusammenstellung des Projekts des Dienstleisters

1. Wir haben ein WebApi-Projekt für den Kunden erstellt.
2. Wir haben eine Konfiguration für Nswag CLI - Nswag.json geschrieben (im vorherigen Abschnitt beschrieben).
3. Wir haben ein PostBuild-Ziel innerhalb des csproj-Dienstanbieterprojekts geschrieben.

• $ (NSwagExe_Core22) nswag.json ausführen - Führen Sie das Dienstprogramm NSwag unter .bet runtine netCore 2.2 mit der Konfiguration nswag.json aus

1. NSwag generiert eine Spezifikation aus einer Vendor Service Assembly.
2. NSwag generiert Client-Code gemäß Spezifikation.

So fügen Sie Unterstützung für JWT hinzu

protected Task<HttpRequestMessage> CreateHttpRequestMessageAsync(CancellationToken cancellationToken) {
      var message = new HttpRequestMessage();

      if (!string.IsNullOrWhiteSpace(this.AuthorizationToken)) {
        message.Headers.Authorization =
          new System.Net.Http.Headers.AuthenticationHeaderValue(BearerScheme, this.AuthorizationToken);
      }

      return Task.FromResult(message);
    }

Fazit

• die Spezifikation ist ausführlich;
• , ;
• ;
• .

• , URL, HTTP ..;
• OpenAPI;
• ;
• ;
• HTTP/2.

Versionierung öffentlicher Aufträge

Warum öffentliche Aufträge versionieren?

Lösungsoptionen

Ohne Versionierung öffentlicher Aufträge

Verwenden Sie die Versionierung öffentlicher Aufträge

• welches Werkzeug zu verwenden ist;
• wann eine neue Version einzuführen ist;
• wie lange alte Versionen zu pflegen.

Welches Tool zu verwenden

Wann soll eine neue Version eingeführt werden?

• Für OpenAPI gibt es ein Azure-Opeanapi-Diff-Tool zum Überprüfen der Kompatibilität zwischen zwei Spezifikationen. github.com/Azure/openapi-diff;
• Für gRPC wurde kein automatisches Tool gefunden. Es gibt nur Versionsrichtlinien.
• allgemein github.com/grpc/grpc/blob/master/doc/versioning.md;
• unter .Net docs.microsoft.com/en-us/aspnet/core/grpc/versioning?view=aspnetcore-3.1 .

Wie lange müssen Versionen gewartet werden?

• Benachrichtigen Sie Kunden, dass die alte Version nicht mehr unterstützt wird. In diesem Fall können wir Kundeneinkommen verlieren;
• unterstützen den gesamten Satz von Versionen. Die Kosten für Software-Support steigen.
• Um diese Frage zu beantworten, müssen Sie das Unternehmen fragen: Übersteigen die Einnahmen alter Kunden die Kosten für die Unterstützung älterer Softwareversionen? Könnte es rentabler sein, Kunden um ein Upgrade zu bitten?

Fazit

Testverträge und CDC

Verbrauchergetriebene Verträge (CDC)

1. Der Verbraucher beschreibt den Vertrag.
2. Der Lieferant setzt diesen Vertrag zu Hause um.
3. Dieser Vertrag wird im CI-Prozess beim Verbraucher und Lieferanten verwendet. Wenn der Prozess verletzt wird, hat jemand den Vertrag nicht mehr eingehalten.

Pakt

1. Der Verbraucher schreibt Tests mit der PACT-Bibliothek.
2. Diese Tests werden in eine Artefakt-Pakt-Datei konvertiert. Es enthält Informationen zu den Verträgen.
3. Der Anbieter und der Verbraucher verwenden die Paktdatei, um die Tests auszuführen.

Nützliche Links zum Pakt

• Pact Broker - Pact File Management-Lösung docs.pact.io/pact_broker
• Pakt unterstützt GRPC noch nicht. Lesen Sie mehr über die Roadmap Pact pact.canny.io .
• Mehr Informationen über PACT auf docs.pact.io .
• Warum sollten Sie PACT docs.pact.io/faq/convinceme verwenden ?

Wie CDC in CI eingebettet werden kann

• Pact + Pact Broker selbst bereitstellen;
• Kaufen Sie eine fertige Pact Flow SaaS-Lösung.

Fazit