Les marchés publics, comment assurer leur cohérence

• Votre système comprend-il de nombreux services interconnectés?
• mettre à jour manuellement le code de service lors du changement de l'API publique?
• les changements dans vos services sapent souvent le travail des autres, et les autres développeurs vous détestent pour cela?

termes

Quel est le sujet de cet article

À quoi ressemble le problème

Comment résoudre ce problème

L'équipe du service fournisseur réparera tout

Mettre à jour le code de votre service auprès de l'équipe consommateur

Pensez à quoi faire pour éviter que le problème n'apparaisse

Comment prévenir la manifestation d'un problème

1. au stade de la conception, définir de manière déclarative les contrats;
2. lors de la mise en œuvre, nous générons le code serveur et client sous contrat;
3. lors des tests, nous vérifions les contrats et essayons de prendre en compte les besoins des clients (CDC).

A quoi ressemble le problème avec nous

Du problème à la tâche

• côté serveur - les contrôleurs sont déjà écrits;
• le navigateur est client du service;
• Les services communiquent via HTTP.
• la génération doit être réglée. Par exemple, pour prendre en charge JWT.

Des questions

• quel outil choisir;
• comment obtenir des contrats;
• où placer les contrats;
• où placer le code client;
• à quel moment faire la génération.

Quel outil choisir

Outils

Outils pour travailler avec OpenAPI

Où organiser les contrats. Comment accéder aux services des contrats

• Le dossier de projet du service fournisseur est l'option la plus simple. Si vous devez exécuter l'approche, choisissez-la.
• un dossier partagé est une option valide si les projets souhaités se trouvent dans le même référentiel. À long terme, il sera difficile de maintenir l'intégrité des contrats dans le dossier. Cela peut nécessiter un outil supplémentaire pour tenir compte des différentes versions des contrats, etc.
• référentiel séparé pour les spécifications - si les projets se trouvent dans différents référentiels, les contrats doivent être placés dans un lieu public. Les inconvénients sont les mêmes que pour le dossier partagé.
• via l'API de service (swagger.ui, swaggerhub) - un service distinct qui traite de la gestion des spécifications.

À quel moment générez-vous

Où placer le code client

• le code client est proche de son service et est constamment à jour;
• les consommateurs peuvent utiliser le lien vers le projet dans un référentiel.

• ne fonctionnera pas si vous devez générer un client dans une autre partie du système, par exemple, un référentiel différent. Il est résolu en utilisant au moins un dossier partagé pour les contrats;
• les consommateurs doivent être rédigés dans la même langue. Si vous avez besoin d'un client dans une autre langue, vous devez utiliser OpenApiTools.

Nous fixons NSwag

Attributs du contrôleur

[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() { // ... }

Processeur pour générer des spécifications pour les opérations sur les fichiers

• FileUploadOperationAttribute: OpenApiOperationProcessorAttribute
• FileUploadOperationProcessor: IOperationProcessor

Configuration de NSwag pour la génération de spécifications et de code

• runtime - Spécifie le runtime .net. Par exemple, NetCore22;
• documentGenerator - décrit comment générer une spécification;
• codeGenerators - définit comment générer du code selon la spécification.

Nous générons la spécification et le code client lors de l'assemblage du projet du prestataire

1. Nous avons créé un projet WebApi pour le client.
2. Nous avons écrit une configuration pour Nswag CLI - Nswag.json (décrite dans la section précédente).
3. Nous avons écrit une cible PostBuild dans le projet de fournisseur de services csproj.

• $ (NSwagExe_Core22) run nswag.json - exécutez l'utilitaire NSwag sous .bet runtine netCore 2.2 avec la configuration nswag.json

1. NSwag génère une spécification à partir d'un assembly de service fournisseur.
2. NSwag génère du code client selon les spécifications.

Comment ajouter la prise en charge de JWT

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);
    }

Conclusion

• la spécification est détaillée;
• , ;
• ;
• .

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

Gestion des versions des contrats publics

Pourquoi versionner les marchés publics?

Options de solution

Sans versionner les marchés publics

Utiliser le versioning des marchés publics

• quel outil utiliser;
• quand introduire une nouvelle version;
• combien de temps pour conserver les anciennes versions.

Quel outil utiliser

Quand introduire une nouvelle version

• pour OpenAPI, il existe un outil Azure opeanapi-diff pour vérifier la compatibilité entre 2 spécifications github.com/Azure/openapi-diff;
• aucun outil automatique n'a été trouvé pour gRPC, il n'y a que des politiques de version;
• general github.com/grpc/grpc/blob/master/doc/versioning.md;
• sous .Net docs.microsoft.com/en-us/aspnet/core/grpc/versioning?view=aspnetcore-3.1 .

Combien de temps pour maintenir les versions

• informer les clients que l'ancienne version ne sera plus prise en charge. Dans ce cas, nous pouvons perdre le revenu de nos clients;
• prendre en charge l'ensemble des versions. Le coût du support logiciel augmente;
• Pour répondre à cette question, vous devez vous poser la question suivante: les revenus des anciens clients dépassent-ils le coût de prise en charge des anciennes versions de logiciels? Serait-il plus rentable de demander aux clients de mettre à niveau?

Conclusion

Contrats de test et CDC

Contrats axés sur le consommateur (CDC)

1. Le consommateur décrit le contrat.
2. Le fournisseur exécute ce contrat à domicile.
3. Ce contrat est utilisé dans le processus CI chez le consommateur et le fournisseur. Si le processus est violé, alors quelqu'un a cessé de se conformer au contrat.

Pacte

1. Le consommateur écrit des tests à l'aide de la bibliothèque PACT.
2. Ces tests sont convertis en fichier d'artefact-pacte. Il contient des informations sur les contrats.
3. Le fournisseur et le consommateur utilisent le fichier pacte pour exécuter les tests.

Liens utiles sur Pacte

• Pact Broker - Solution de gestion de fichiers Pact docs.pact.io/pact_broker
• Pact ne prend pas encore en charge GRPC. En savoir plus sur la feuille de route Pact pact.canny.io .
• Plus d' informations sur PACT sur docs.pact.io .
• Pourquoi utiliser PACT docs.pact.io/faq/convinceme

Comment CDC peut être intégré dans CI

• déployer Pact + Pact Broker vous-même;
• acheter une solution Pact Flow SaaS prête à l'emploi.

Conclusion