hexarc pact

Pacte hexarc

Hexarc PACT fournit une chaîne d'outils pour exposer et consommer une API Web pour les projets basés sur .NET / TypeScript.

Développez votre projet API Web .NET avec PACT pour conserver une seule source de vérité pour les métadonnées de l'API et le consommer à travers l'écosystème .NET (microservices, applications de bureau et mobile) ou sur le Web via TypeScript.

Emballer	Plate-forme	Version	Téléchargements
Hexarch.Pact.Protocol	.NET 7.0+
Hexarch.Pact.AspNetCore	.NET 7.0+
Hexarch.Pact.Client	.NET 7.0+
Hexarch.Pact.Tool	.NET 7.0+
@hexarc/pact-tool	Manuscrit

Qu'y a-t-il dans Pacte?

• Caractéristiques
• Système de type
• Règles d'annotation de l'API
  • Attributs supplémentaires
• API de démonstration
• Comment utiliser
  • Exposer le schéma API PACT (.NET Web API Service)
  • Consommer le schéma API PACT (application client .NET)
• Remerciements
• Licence

Caractéristiques

• Intégrations d'API sans tracas en secondes.
• Aucune information de type ne perdant. Consommez l'API exacte telle qu'elle est conçue.
• Code d'abord. Pas besoin de décrire votre protocole API dans IDL / DSL externe.
• Chargé de types avancés. Non seulement des DTO simples mais aussi des énumériques, des génériques, des syndicats tagués, etc.

Système de type

Le système de type PACT est basé sur les types de CLR .NET avec certains sur mesure pour la meilleure expérience de développement.

Qu'y a-t-il à l'intérieur du système de type pacte:

• Types primitifs (y compris Guid et DateTime )
• Sémantique de la valeur / type de référence
• Collections et génériques (non seulement des tableaux et dictionnaires simples)
• Prise en charge complète des annotations de type de référence (NRT)
• Enum (basés sur une chaîne et basés sur des nombres)
• Tagged Unions (via hexarc.serialization.union)
• Tuples (via hexarc.serialization.tuple)

Règles d'annotation de l'API

Le schéma API PACT est conçu pour avoir un sémantique de type RPC. Ce faisant, une API exposée doit suivre ces règles:

• Les contrôleurs API doivent être marqués avec des attributs standard ApiController et Route .
• L'attribut Route ne doit avoir qu'un chemin de chaîne constant sans modèles (par exemple [Route("Entities")] ).
• Les méthodes API doivent être marquées avec l'un des verbes HTTP pris en charge ( HttpGet ou HttpPost ). Les attributs du verbe peuvent contenir un chemin de point final. D'autres ne sont pas soutenus pour le moment.
  • Les méthodes HttpGet peuvent avoir des paramètres de requête qui doivent être liés via l'attribut FromQuery .
  • Les méthodes HttpPost ne doivent avoir qu'un seul paramètre qui est le corps de demande.
• Le chemin de méthode de l'API peut être spécifié dans l'attribut verb HTTP ou l'attribut Route . Si le chemin de méthode n'est pas spécifié dans l'attribut Verbe HTTP, il sera prélevé sur la Route un ou une exception sera soulevée.

Attributs supplémentaires

PACT fournit quelques attributs utiles pour l'annotation de l'API:

• PactIgnoreAttribute peut être appliqué aux contrôleurs API ou à des méthodes à exclure d'un schéma API.
• PactScopeAttribute peut être appliqué aux contrôleurs d'API pour être isolés en portée spécifique dans un schéma API.

Serveur API de démonstration

Le serveur API de démonstration peut être trouvé sur https://hexarc-demo-api.herokuapp.com/.

Le schéma API PACT est exposé sur https://hexarc-deno-api.herokuapp.com/pact/schema.

Pour générer un client API, utilisez l'instruction ci-dessous.

Comment utiliser

Découvrez comment utiliser PACT pour exposer et consommer une API Web typique.

Exposer le schéma API PACT

1. Installez le package Hexarc.Pact.AspNetCore dans un projet API Web .net:

dotnet add package Hexarc.Pact.AspNetCore

2. Ajoutez la génération de schéma PACT dans la méthode Startup.ConfigureServices :

 public void ConfigureServices ( IServiceCollection services )
{
    services . AddControllers ( ) ;

    // Register the Pact schema generation.
    services . AddPactGeneration ( ) ;
}

3. Activer le middleware PACT dans la méthode Startup.Configure :

 public void Configure ( IApplicationBuilder app )
{
    // Enable the Pact middleware to expose the generated API schema.
    app . UsePact ( ) ;

    app . UseRouting ( ) ;
    app . UseEndpoints ( endpoints => endpoints . MapControllers ( ) ) ;
}

4. Implémentez un contrôleur API selon les règles d'annotation du PACT:

 [ ApiController , Route ( "Misc" ) ]
public sealed class MiscController : ControllerBase
{
    [ HttpGet ( nameof ( Ping ) ) ]
    public String Ping ( [ FromQuery ] String message ) => $ "Hello, { message } " ;
}

5. Démarrez l'application et ouvrez l'adresse de YOUR_API_HOST/pact/schema pour vous assurer que le schéma API PACT est généré.

Consommer le schéma API PACT

1. Installez le package Hexarc.Pact.Client dans un projet .NET:

dotnet add package Hexarc.Pact.Client

2. Installez l'outil Hexarc.Pact.Tool dans le projet:

dotnet tool install Hexarc.Pact.Tool

Vous devrez peut-être configurer un manifeste d'outils .NET avant d'installer l'outil Hexarc.Pact.Tool :

dotnet new tool-manifest

3. Ajoutez une configuration pact.json dans le projet avec les paramètres de génération de clients API souhaités:

{
   "schemaUri" : " YOUR_API_HOST/pact/schema " ,
   "clientClassName" : " DemoClient " ,
   "clientClassNamespace" : " DemoNamespace " ,
   "outputDirectory" : " Generated "
}

où

• schemaUri - Lien vers un schéma API PACT
• clientClassName - Nom d'une classe client API générée
• clientClassNamespace - Espace de noms où mettre dans la classe client API générée
• outputDirectory - Répertoire de sortie pour les sources générées

4. Générez le client API via l'outil PACT CLI:

dotnet pact

Cette commande doit être effectuée dans le même dossier avec la configuration pact.json .

5. Le client API généré sera disponible pour accéder au serveur API:

 var client = new DemoClient ( new HttpClient { BaseAddress = new Uri ( "YOUR_API_HOST" ) } ) ;
var pong = await client . Misc . Ping ( "World" ) ;
Console . WriteLine ( pong ) ; // Prints "Hello, World" to the output. 

Remerciements

Construit avec des outils JetBrains pour les projets open source.

Licence

MIT © Max Koverdyaev