hexarc pact

Pacto Hexarc

O Hexarc Pact fornece uma cadeia de ferramentas para expor e consumir API da Web para projetos baseados em .NET/TypeScript.

Desenvolva seu projeto .NET Web API com Pact para manter uma única fonte de verdade para os metadados da API e consumi -lo no ecossistema .NET (Microservices, Desktop e Mobile Applications) ou na Web via TypeScript.

Pacote	Plataforma	Versão	Downloads
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	TypeScript

O que há no pacto?

• Características
• Sistema de tipo
• Regras de anotação API
  • Atributos adicionais
• API Demo
• Como usar
  • Exponha o esquema de API do PACT (serviço da API da Web .NET)
  • Consuma PACT API Schema (Aplicativo do cliente .NET)
• Agradecimentos
• Licença

Características

• Integrações de API sem complicações em segundos.
• Sem informações de tipo perdido. Consuma API exata conforme projetado.
• Código primeiro. Não há necessidade de descrever seu protocolo de API em IDL/DSL externo.
• Carregado de tipos avançados. Não apenas DTOs simples, mas enumes, genéricos, sindicatos marcados etc.

Sistema de tipo

O sistema de tipo de pacto é baseado nos tipos .NET CLR com alguns sob medida para a melhor experiência de desenvolvimento.

O que está dentro do sistema de tipo de pacto:

• Tipos primitivos (incluindo Guid e DateTime )
• Semântica do tipo de valor/referência
• Coleções e genéricos (não apenas matrizes e dicionários simples)
• Suporte completo para anotações de tipo de referência anulável (NRT)
• Enums (baseado em string e baseado em números)
• Sindicatos marcados (via hexarc.serialization.union)
• Tuplas (via hexarc.serialization.tuple)

Regras de anotação API

O esquema da API do PACT foi projetado para ter uma semântica semelhante a RPC. Ao fazer isso, uma API exposta deve seguir estas regras:

• Os controladores da API devem ser marcados com atributos de ApiController padrão e Route .
• O atributo de rota deve ter apenas um caminho de sequência constante sem modelar (por exemplo [Route("Entities")] ).
• Os métodos da API devem ser marcados com um dos verbos HTTP suportados ( HttpGet ou HttpPost ). Os atributos verbais podem conter um caminho de extremidade. Outros não são apoiados no momento.
  • Os métodos HttpGet podem ter parâmetros de consulta que devem ser vinculados através do atributo FromQuery .
  • Os métodos HttpPost devem ter apenas um parâmetro que é o órgão de solicitação.
• O caminho do método da API pode ser especificado no atributo verbal http ou no atributo Route . Se o caminho do método não for especificado no atributo de verbo http, ele será retirado da Route um ou uma exceção será levantada.

Atributos adicionais

O Pact fornece alguns atributos úteis para anotação de API:

• PactIgnoreAttribute pode ser aplicado aos controladores ou métodos da API a ser excluído de um esquema de API.
• PactScopeAttribute pode ser aplicado aos controladores da API para serem isolados em escopo específico em um esquema de API.

Servidor de api de demonstração

O servidor de Demo API pode ser encontrado em https://hexarc-demo-api.herokuapp.com/.

O esquema da API do PACT é exposto em https://hexarc-demo-api.herokuapp.com/pact/schema.

Para gerar um cliente da API, use a instrução abaixo.

Como usar

Descubra como usar o Pact para expor e consumir uma API da Web típica.

Expor esquema de api de compra

1. Instale o pacote Hexarc.Pact.AspNetCore em um projeto da API .NET Web:

dotnet add package Hexarc.Pact.AspNetCore

2. Adicione a geração de esquema do PACT no método Startup.ConfigureServices :

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

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

3. Ative o middleware do Pact no método 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. Implementar um controlador de API de acordo com as regras de anotação do PACT:

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

5. Inicie o aplicativo e abra o endereço YOUR_API_HOST/pact/schema para garantir que o esquema da API do PACT seja gerado.

Consumir esquema de api de pacto

1. Instale o pacote Hexarc.Pact.Client em um projeto .NET:

dotnet add package Hexarc.Pact.Client

2. Instale a ferramenta Hexarc.Pact.Tool no projeto:

dotnet tool install Hexarc.Pact.Tool

Pode ser necessário configurar um manifesto .NET Tools antes de instalar a ferramenta Hexarc.Pact.Tool :

dotnet new tool-manifest

3. Adicione uma configuração pact.json no projeto com as configurações desejadas de geração de clientes da API:

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

onde

• schemaUri - Link para um esquema de API PACT
• clientClassName - Nome para uma classe de cliente da API gerada
• clientClassNamespace - Namespace onde colocar na classe Gerated API Client
• outputDirectory - Diretório de saída para as fontes geradas

4. Gere o cliente da API através da ferramenta PACT CLI:

dotnet pact

Este comando deve ser executado na mesma pasta com a configuração pact.json .

5. O cliente da API gerado estará disponível para acessar o servidor 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. 

Agradecimentos

Construído com ferramentas JetBrains para projetos de código aberto.

Licença

MIT © Max Koverdyaev