Contratos públicos, como garantir sua consistência

• Seu sistema consiste em muitos serviços interconectados?
• ainda atualiza manualmente o código de serviço ao alterar a API pública?
• as mudanças em seus serviços geralmente prejudicam o trabalho de outras pessoas, e outros desenvolvedores o odeiam por isso?

Termos e Condições

Sobre o que é o artigo

Como é o problema

Como resolver este problema

A equipe de serviço do fornecedor corrigirá tudo

Atualize o código do seu serviço para a equipe do consumidor

Pense no que fazer para impedir que o problema apareça

Como evitar a manifestação de um problema

1. na fase de projeto, defina declarativamente os contratos;
2. durante a implementação, geramos código de servidor e cliente sob contratos;
3. durante o teste, verificamos contratos e tentamos levar em consideração as necessidades do cliente (CDC).

Como o problema parece conosco

Do problema à tarefa

• lado do servidor - os controladores já estão gravados;
• o navegador é um cliente do serviço;
• Os serviços se comunicam por HTTP.
• a geração deve ser ajustada. Por exemplo, para suportar o JWT.

Questões

• qual ferramenta escolher;
• como conseguir contratos;
• onde colocar os contratos;
• onde colocar o código do cliente;
• em que ponto fazer a geração.

Qual ferramenta escolher

Ferramentas

Ferramentas para trabalhar com OpenAPI

Onde organizar contratos. Como acessar serviços para contratos

• A pasta do projeto de serviço do provedor é a opção mais fácil. Se você precisar executar a abordagem, escolha-a.
• uma pasta compartilhada é uma opção válida se os projetos desejados estiverem no mesmo repositório. A longo prazo, será difícil manter a integridade dos contratos na pasta. Isso pode exigir uma ferramenta adicional para explicar diferentes versões de contratos, etc.
• repositório separado para especificações - se os projetos estiverem em repositórios diferentes, os contratos deverão ser colocados em um local público. As desvantagens são as mesmas da pasta compartilhada.
• através da API de serviço (swagger.ui, swaggerhub) - um serviço separado que lida com o gerenciamento de especificações.

Em que ponto você gera

Onde colocar o código do cliente

• o código do cliente está próximo ao seu serviço e está constantemente atualizado;
• os consumidores podem usar o link para o projeto em um repositório.

• não funcionará se você precisar gerar um cliente em outra parte do sistema, por exemplo, um repositório diferente. É resolvido usando pelo menos uma pasta compartilhada para contratos;
• os consumidores devem ser escritos no mesmo idioma. Se você precisar de um cliente em outro idioma, precisará usar o OpenApiTools.

Prendemos NSwag

Atributos do Controlador

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

Processador para gerar especificações para operações de arquivo

• FileUploadOperationAttribute: OpenApiOperationProcessorAttribute
• FileUploadOperationProcessor: IOperationProcessor

Configuração do NSwag para geração de especificações e códigos

• tempo de execução - Especifica o tempo de execução .net. Por exemplo, NetCore22;
• documentGenerator - descreve como gerar uma especificação;
• codeGenerators - define como gerar código de acordo com a especificação.

Geramos a especificação e o código do cliente ao montar o projeto do provedor de serviços

1. Criamos um projeto WebApi para o cliente.
2. Escrevemos uma configuração para o Nswag CLI - Nswag.json (descrito na seção anterior).
3. Escrevemos um destino PostBuild dentro do projeto do provedor de serviços csproj.

• $ (NSwagExe_Core22) execute nswag.json - execute o utilitário NSwag em .bet runtine netCore 2.2 com a configuração nswag.json

1. O NSwag gera uma especificação de um assembly de serviço do fornecedor.
2. O NSwag gera o código do cliente conforme a especificação.

Como adicionar suporte ao 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);
    }

Conclusão

• a especificação é detalhada;
• , ;
• ;
• .

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

Controle de versão de contratos públicos

Por que versionar contratos públicos?

Opções de solução

Sem controle de versão de contratos públicos

Usar controle de versão de contratos públicos

• qual ferramenta usar;
• quando introduzir uma nova versão;
• quanto tempo manter versões antigas.

Qual ferramenta usar

Quando introduzir uma nova versão

• para OpenAPI, existe uma ferramenta opeanapi-diff do Azure para verificar a compatibilidade entre duas especificações github.com/Azure/openapi-diff;
• nenhuma ferramenta automática foi encontrada para o gRPC, existem apenas políticas de versão;
• general github.com/grpc/grpc/blob/master/doc/versioning.md;
• em .Net docs.microsoft.com/en-us/aspnet/core/grpc/versioning?view=aspnetcore-3.1 .

Quanto tempo manter as versões

• notifique os clientes que a versão antiga não será mais suportada. Nesse caso, podemos perder a receita do cliente;
• suporta todo o conjunto de versões. O custo do suporte de software está aumentando;
• Para responder a essa pergunta, você precisa perguntar à empresa - a receita de clientes antigos excede o custo de suporte a versões antigas de software? Poderia ser mais rentável pedir aos clientes para atualizar?

Conclusão

Testando contratos e CDC

Contratos orientados ao consumidor (CDC)

1. O consumidor descreve o contrato.
2. O fornecedor implementa este contrato em casa.
3. Este contrato é usado no processo de IC no consumidor e fornecedor. Se o processo for violado, alguém deixou de cumprir o contrato.

Pacto

1. O consumidor grava testes usando a biblioteca PACT.
2. Esses testes são convertidos em um arquivo de artefato-pacto. Ele contém informações sobre os contratos.
3. O provedor e o consumidor usam o arquivo pacto para executar os testes.

Links úteis sobre o Pacto

• Pact broker - solução de gerenciamento de arquivos pact docs.pact.io/pact_broker
• O Pacto ainda não suporta GRPC. Leia mais sobre o roteiro Pacto pact.canny.io .
• Mais informações sobre PACT em docs.pact.io .
• Por que você deve usar o PACT docs.pact.io/faq/convinceme

Como o CDC pode ser incorporado no IC

• implantar o Pact + Pact broker;
• adquira uma solução SaaS Pact Flow pronta para uso.

Conclusão