DEV Community: Mauricio Redmerski André

gRPC: um panorama do contexto histórico às aplicações práticas!

Mauricio Redmerski André — Sun, 20 Oct 2024 18:36:29 +0000

Olá, pessoal. Tudo bem?

Há algum tempo, desenvolvi um conteúdo sobre gRPC para criar um bootcamp e disseminar este conhecimento entre os times de software da Becomex. Embora o modelo de bootcamp não tenha sido implementado na prática, o material ficou excelente. Por isso, decidi transformar a parte teórica em um post e compartilhar esse conteúdo com a comunidade.

Para aprender qualquer coisa na vida, começar pelo básico é sempre uma ótima ideia. Antes de mergulharmos no gRPC, vamos entender o que é RPC e o caminho que nos trouxe até aqui. Neste artigo, você terá uma breve introdução aos conceitos de RPC, a diferença básica entre RPC e REST, e entenderá por que o gRPC é tão rápido e uma excelente alternativa para a transição de grandes volumes de dados. Além disso, vamos apresentar exemplos de implementação para facilitar o entendimento.
Então, ajeite-se na cadeira e prepare sua garrafa d'água, porque vem muita informação boa por aí!

A origem

O RPC ou Remote Procedure Call (chamada de processo remoto em português) é uma técnica que permite realizar a chamada de uma função de forma remota. Com o RPC, o recurso A solicita a execução de uma função ao recurso B, estes podem ser componentes distintos que compõem um grande circuito, ou computadores conectados em rede, mostrando que esse modelo de comunicação não está vinculado somente ao protocolo HTTP, mas também se aplicando facilmente a outros protocolos de comunicação.

As proposições teóricas de modelos de chamadas remotas em redes de computadores começaram a ser feitas na década de 70, tendo como marco importante a publicação da RFC 707 no final do ano de 1975 e no começo do ano de 1976 sob o título A High-Level Framework for Network-Based Resource Sharing. Esse documento, dentre outras coisas, enfatizou a necessidade de padronização dos protocolos de comunicação entre sistemas.

O primeiro uso comercial do modelo de comunicação RPC ocorreu em um projeto desenvolvido pela Xerox PARC em 1981. Foi durante esse período que o termo RPC teria sido cunhado por Bruce Jay Nelson, um dos cientistas da computação da empresa.

Anos mais tarde, o Google criou sua própria arquitetura RPC. Essa infraestrutura de propósito geral chamada Stubby foi utilizada por mais de uma década para conectar o vasto número de microsserviços operando dentro e entre seus data centers. Como afirmado pela própria Google, o Stubby possuía vários recursos excelentes, mas estava altamente acoplado à sua infraestrutura interna para ser considerado adequado para o lançamento ao público. Em 2015, a Google publica então o gRPC, um projeto de código aberto que nasce como a evolução do Stubby.

Ao contrário do que muitas pessoas podem pensar, o "g" em gRPC não significa Google. Na realidade, a cada nova versão lançada do gRPC, o "g" é ressignificado. Clique aqui e confira a lista de nomes atribuídos ao “g”. Para todos os efeitos, podemos entender o termo gRPC como high performance Remote Procedure Call ou chamada de processo remoto de alta performance no nosso bom português.

Diferença entre RPC e REST

O modelo REST Representational State Transfer é potencialmente o mais popular atualmente, e a maioria das APIs web com que trabalhamos são REST ou pseudo REST. Por isso, parece ser uma boa ideia explicar como o RPC funciona comparando-o a um modelo mais conhecido.

Fundamentalmente, o REST expõe os recursos ou entidades de sua aplicação e usa os métodos HTTP para fornecer significado semântico às ações realizadas. Já o RPC expõe as operações que a aplicação pode realizar e, em geral, usa apenas dois diferentes métodos HTTP (quando a comunicação se dá por esse protocolo).

Em uma API REST, se você desejar expor dados sobre usuários, você provavelmente teria o seguinte cenário:

GET api/v1/users
GET api/v1/users/:id
POST api/v1/users
PUT api/v1/users/:id
DELETE api/v1/users/:id

Em uma API RPC, ao invés de expor uma rota de usuários e usar os métodos HTTP para atribuir significado às operações, cada rota se parecerá como uma função específica. Veja o exemplo:

GET api/v1/getUserList
GET api/v1/getUserById
POST api/v1/createUser
POST api/v1/updateUser
POST api/v1/deleteUser

Cada modelo de comunicação oferece diferentes níveis de facilidade para representar as operações de uma aplicação. O REST, por exemplo, é ideal para operações de CRUD (criar, ler, atualizar, deletar), enquanto o RPC é mais eficiente para executar ações da sua aplicação, como enviar e-mails ou realizar cálculos. No entanto, nada impede que o RPC seja usado para operações de CRUD, assim como o REST pode ser aplicado para executar funções em uma API.

De onde vem o high performance do gRPC?

A essa altura, você já deve ter percebido que o gRPC nada mais é do que a implementação de um modelo de API RPC, construído de modo a fornecer um alto desempenho em suas execuções. Mas como esse alto desempenho é construído? A primeira coisa que precisamos entender é que o gRPC não é uma tecnologia em si, mas uma junção de várias técnicas e tecnologias. Bora explorar cada uma delas?

Execução sob o protocolo de comunicação HTTP/2

Implementar uma API gRPC significa utilizar o protocolo HTTP/2 para estabelecer a conexão e a troca de informação entre o cliente e o servidor. O HTTP/2 que também foi criado pelo Google oferece vários recursos de melhoria de desempenho em relação ao seu antecessor. Aqui, vamos explorar duas de suas principais características, mas você pode ter uma leitura completa consultando a RFC 7540.

Stream e Multiplexação

Uma das principais limitações do HTTP/1.1 é a sua restrição no envio e recebimento de dados. Nesta versão, não é possível enviar ou receber mais de uma mensagem por conexão, o que significa que, se você precisar enviar duas mensagens ao servidor, terá que abrir duas conexões separadas. Isso torna o processo mais lento, já que a cada requisição é necessário refazer o handshake com o servidor e reenviar eventuais informações repetitivas entre as requisições. Além disso, por questões de desempenho, o número de conexões simultâneas que um browser pode fazer com um servidor é limitado. Para entender melhor essa limitação, recomendo o artigo Why does your browser limit the number of concurrent network calls?.

O protocolo HTTP/2, por outro lado, permite algo chamado multiplexação, o que significa que é possível enviar mais de uma requisição ao servidor por meio de uma única conexão. Isso resolve as limitações de conexões simultâneas e os tempos de handshake que a versão anterior impunha. A imagem abaixo, retirada do livro HTTP/2 in Action, ilustra de forma simples esse funcionamento.

Compressão e redução dos headers

Outra característica interessante do HTTP/2 é a compressão dos headers das mensagens. Em alguns casos, os headers de uma requisição podem ser maiores que o próprio payload, e o HTTP/2 faz uma compressão eficiente dessas informações. Além disso, como essa versão mantém uma única conexão para várias solicitações, não é necessário reenviar todos os headers em cada requisição. O HTTP/2 apenas retransmite os headers que foram alterados e, para os que permanecem iguais, envia apenas um índice de referência.

Protocol Buffers

O Protocol Buffers (ou Protobuf, para os íntimos) é um método muito eficiente de serialização de dados. O Protobuf usa uma linguagem de definição de interface (IDL) para descrever arquivos agnósticos de plataformas e linguagens de programação. Esses arquivos contêm as especificações dos contratos e funções que o servidor pode fornecer e tanto o cliente quanto o servidor mantêm uma cópia desses arquivos, o que garante a coesão na troca de informações. Além disso, isso separa o contexto das mensagens trocadas na rede do seu conteúdo, diferentemente de contratos em JSON, onde contexto e conteúdo são enviados necessariamente juntos.

Veja o exemplo abaixo, que utiliza a IDL do Protobuf para descrever um contrato de um objeto que representa um produto, com as propriedades partnumber, que significam o código e a quantidade de um produto:

syntax = "proto3";

message Produto {
  string partnumber = 1;
  int32 quantidade = 2;
}

Na primeira linha, definimos a sintaxe "proto3". Na terceira, declaramos uma mensagem (ou objeto) chamada "Produto", que pode ser usada tanto como entrada quanto saída de uma função. As linhas quatro e cinco definem as propriedades desse objeto, indicando o tipo, nome e índice de cada uma. E aqui está o interessante: nós definimos índices que determinam a posição das propriedades, o que significa que a mensagem enviada via gRPC não precisa carregar o nome da propriedade, apenas seu índice.

Para ilustrar de forma mais clara, veja o exemplo em JSON que seria necessário para representar essa mensagem:

{
  "partnumber": "Boinas",
  "quantidade": 150
}

Cada caractere da mensagem acima precisa ser transmitido pela rede por meio físico do servidor até o cliente. Quanto maior a mensagem, mais tempo levará para ser transmitida. O Protobuf codifica essa mesma mensagem em um conjunto muito menor de dados, o que acelera a transmissão pela rede. A codificação dessa mensagem pelo Protobuf seria a seguinte: 0A06426F696E6173109601. Não se preocupe, vou explicar como chegamos a esse valor em breve 😉. E ainda, graças ao HTTP/2, esses dados serão comprimidos antes de serem transmitidos.

O Protobuf, que também foi criado pelo Google, pode ser usado de forma independente, sem estar necessariamente no contexto do gRPC. Se salvarmos o exemplo anterior em um arquivo chamado Produto.proto, podemos rodar o seguinte comando no terminal: echo 'partnumber: "boinas"; quantidade: 150' | protoc --encode=Produto produto.proto > produto.bin (você precisará instalar o protoc para isso). O comando echo indica que queremos imprimir um conteúdo, o texto entre aspas simples é o conteúdo que queremos imprimir, concatenamos essa impressão com a chamada do protoc indicando que queremos fazer o encode do objeto "Produto" --encode=Produto especificado dentro do arquivo produto.proto, por fim definimos que o resultado deve ser salvo dentro do arquivo produto.bin. Para visualizar arquivos com essa codificação, gosto de usar o VS Code com a extensão Hex Editor. É assim que você verá a sequência de caracteres 0A06426F696E6173109601 mencionada anteriormente.

O resultado gerado por essa operação é uma sequência hexadecimal, onde cada par de caracteres representa um conjunto de 8 bits. Vamos dar uma olhada mais detalhada nessa estrutura.

O primeiro bit de cada par é o most significant bit (MSB), ou continuation bit. Essa é uma estratégia inteligente de codificação para indicar se o próximo par faz parte da mesma representação de dado ou se é um dado separado. Quando o valor é 0, o par contém toda a informação. Se for 1, é necessário combinar os bits com o próximo par para interpretar o dado.

Os pares 0A e 10, destacados em vermelho na imagem, representam as definições das propriedades enviadas. Após o primeiro bit (MSB), os próximos 4 bits indicam o índice da propriedade (lembrando que no arquivo .proto definimos índices representados aqui), e os três bits seguintes destacados em negrito indicam o tipo da mensagem.

O par 06, destacado em azul, indica o comprimento da mensagem de texto (neste caso, 6 conjuntos), sempre que o tipo do dado for uma string, o dado será precedido por um ou mais conjuntos que definem o comprimento do texto transmitido na propriedade. Em seguida, destacado em cinza, temos a mensagem "Boinas", codificada.

Os últimos dois conjuntos, 96 e 01, representam o valor da propriedade "quantidade". Sabemos que devemos interpretar os dois pares juntos porque o primeiro par, 96, possui o valor 1 no MSB. Para interpretar um valor numérico serializado pelo Protobuf, removemos o MSB da sequência e aplicamos a técnica little-endian, ordenando os bits menos significativos à frente. Isso resulta na sequência 10010110, que representa o valor 150 que informamos em nossa mensagem de teste.

Se quiser entender mais sobre o processo de codificação do Protobuf, você pode consultar as especificações aqui.

Sintaxe e tipos padrões

Já vimos um pouco da sintaxe da IDL do Protobuf nos exemplos anteriores, mas vamos nos aprofundar em alguns conceitos básicos.

syntax = "proto3";

service DocumentoService {
  rpc List(ListDocumentoRequest) returns (stream ListDocumentoResponse);
}

message ListDocumentoRequest {
  reserved 3;
  int64 analise_id = 1;
  optional int32 tipo_documento = 2;
  optional string cnpj_participante = 4
}

message ListDocumentoResponse {
  Documento documento = 1;
}

message Documento {
  int64 documentoId = 1;
  string chave_eletronica = 2;
  bool valido = 3;
  string cnpj_emitente = 4;
  repeated Produto = 5;
}

message Produto {
  string partnumber = 1;
  doubel valor = 2;
}

No exemplo acima, usamos o termo service para indicar que estamos descrevendo as funções de um serviço chamado DocumentoService. Em seguida, usamos o termo rpc para descrever as funções que esse serviço suporta. Definimos uma função chamada List, que recebe um objeto ListDocumentoRequest e retorna um stream de dados chamado ListDocumentoResponse. O uso de stream indica que o volume de dados pode ser alto, permitindo que o cliente processe os dados de forma parcial conforme o servidor os envia.

Nosso exemplo continua com a definição da estrutura do objeto ListDocumentoRequest. Nele, especificamos que a posição de índice 3 é reserved, o que significa que nenhuma propriedade pode ocupar essa posição. A posição 3 não tem nada de especial, foi apenas uma escolha para demonstrar essa possibilidade. Também definimos uma propriedade chamada analise_id como int64, e as duas propriedades seguintes são marcadas com o termo optional. Isso significa que, ao transmitir a mensagem, podemos omitir esses dois parâmetros.

Um ponto importante a se observar ao definir propriedades como optional no Protobuf é que, ao fazer isso, habilitamos uma propriedade chamada Has{MinhaVariável} no objeto convertido para a nossa linguagem de programação. Antes de acessar a propriedade optional, é essencial verificar se essa propriedade está marcada como true ou false. Se tentarmos recuperar a propriedade diretamente, sem essa verificação, receberemos o valor padrão do tipo de dado em questão (0 para inteiros e vazio para strings por exemplo).

Veja um exemplo em C# de como recuperar esses dados:

private DocumentoFilter MapToFilter(ListDocumentoRequest request)
{
  return new DocumentoFilter()
  {
    AnaliseId = request.Query.AnaliseId,
    TipoDocumento = request.Query.HasTipoDocumento
      ? request.Query.TipoDocumento
      : null,
    CnpjParticipante = request.Query.CnpjParticipante
  };
}

Antes de acessar o parâmetro TipoDocumento, foi necessário verificar o estado da propriedade HasTipoDocumento. Se tivéssemos acessado TipoDocumento diretamente, o valor retornado seria zero. No caso de CnpjParticipante, podemos recuperar o valor diretamente, mesmo que seja opcional. Fazer isso não causará erro, o retorno será apenas uma string vazia. Se você precisar diferenciar entre strings vazias e valores nulos (quando o usuário não fornecer esse dado), deverá usar a propriedade HasCnpjParticipante, da mesma forma como fizemos com TipoDocumento.

Seguindo com a análise da sintaxe do arquivo .proto, temos a definição do objeto ListDocumentoResponse. Nesse objeto, há uma propriedade do tipo Documento, que é um objeto personalizado. No Protobuf, podemos encadear objetos livremente, e Documento possui uma propriedade do tipo Produto como exemplo. O termo repeated que precede o tipo Produto indica que essa propriedade é, na verdade, uma lista de produtos. Você pode consultar os tipos padrões e termos reservados da IDL do Protobuf aqui.

Um ponto importante a se observar quando estiver criando seus objetos. Caso sua entidade possua uma propriedade repeat que pode receber uma lista muito grande dados, convêm não inclui-la no retorno de sua entidade, ao invés disso, crie uma outra função que retorne essa lista e permita que seu cliente chame simultaneamente as rotas da entidade pai e de sua lista de propriedades, dessa forma o desempenho na operação dos serviços do gRPC será muito superior.

Também é possível criar enumeradores no Protobuf e passar parâmetros que aceitam valores nulos, o que elimina a necessidade do termo optional. Se quiser saber mais sobre isso, você pode consultar a documentação. Um conselho: se usar propriedades complexas que podem transmitir valores nulos, não use o termo optional, já que não faz sentido declarar optional em propriedades com tipos nullables.

Criando serviços gRPC

Finalmente chegamos à parte mais esperada: colocar a mão na massa! Para iniciar um projeto de servidor gRPC em C#, você pode usar o seguinte comando: dotnet new grpc -o NomeDoProjeto.

O resultado será um Program semelhante ao seguinte:

using GrpcDocumento.Services;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddGrpc();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();

A função MapGrpcService inclui os arquivos de Services que você criar, fornecendo os endpoints definidos nos arquivos .proto. Para começar, basta criar seus próprios arquivos .proto e compilar o projeto. O .NET gerará as classes e tipos necessários para que seu serviço herde a classe base gerada pela compilação do arquivo .proto. Um exemplo disso pode ser visto no template, onde o serviço GreeterService herda as implementações de Greeter.GreeterBase e implementa os métodos definidos para o RPC.

Com o conteúdo que vimos até agora, você já deve ser capaz de criar APIs gRPC simples. Então, vou pular para algo mais avançado e divertido: a criação de métodos que recebem e enviam streams de dados. Se você precisar de um passo a passo mais detalhado para a criação de servidores gRPC, pode acessar o tutorial: Criar um cliente e um servidor gRPC no ASP.NET Core disponibilizado pela Microsoft.

Vamos supor que você precise criar uma função que receba e envie um stream de dados. Um exemplo de implementação seria o seguinte:

public async override Task List(
  IAsyncStreamReader<ListDocumentoRequest> requestStream,
  IServerStreamWriter<ListDocumentoResponse> responseStream,
  ServerCallContext context)
{
  while (await requestStream.MoveNext())
  {
    var filter = MapToFilter(requestStream.Current);
    var documentoList = _documentoService.GetDocumentoList(filter);
    await foreach (var documento in documentoList)
    {
      await responseStream.WriteAsync(documento);
    }
  }
}

Quando o arquivo .proto define a entrada de dados como stream, o tipo recebido na função será IAsyncStreamReader<T>, onde T é o tipo de dado de entrada. Se o retorno da função for definido como stream, o tipo retornado será IServerStreamWriter<T>. No requestStream, você pode usar a função MoveNext para aguardar o próximo pacote de dados enviado pelo cliente ou processar o pacote já recebido. No responseStream, você pode usar a função WriteAsync para enviar pacotes de resposta ao cliente.

Se você está lidando com streams, provavelmente trabalhará com grandes volumes de dados. Nesse caso, é interessante realizar consultas paginadas no banco de dados, para otimizar a eficiência e reduzir o volume de dados em trânsito. Confira abaixo um exemplo de implementação para a função GetDocumentoList usada no exemplo anterior:

public async IAsyncEnumerable<DocumentoResponse> GetDocumentoList(DocumentoFilter)
{
  var documentoQuery = _repository.GetDocumentoQueryByFilter(filter).AsNoTracking();
  var skip = 0;
  var count = 0;

  do
  {
    count = 0;
    foreach (var documento in documentoQuery.Skip(skip).Take(1000))
    {
      count++;
      yield return MapToResponse(documento);
    }
    skip += 1000
  } while (count == 1000);
}

O código acima realiza consultas paginadas de 1000 em 1000 registros e processa os dados sob demanda, usando IAsyncEnumerable e yield return até que todos os dados compatíveis filtrados sejam retornados.

Um destaque importante ao criar servidores gRPC que retornam streams de dados é que os dados enviados para o client são armazenados em um buffer. Como esse buffer não é infinito, se você enviar dados mais rápido do que o client pode consumir, poderão ocorrer erros de estouro de buffer. Você pode ignorar esse problema e deixar que o client lide com o processamento, ou pode ser uma pessoa legal e implementar técnicas que evitem isso, como aguardar um sinal do client para enviar dados paginados sob demanda, de acordo com sua capacidade de processamento.

Consumindo uma API gRPC

Agora, suponha que você já tenha um projeto e deseja consumir uma API gRPC. O processo é bem simples. Primeiro, instale as seguintes bibliotecas:

Grpc.Net.Client
Google.Protobuf
Grpc.Tools

Em seguida, adicione o código necessário no arquivo csproj para mapear os arquivos .proto desejados:

<ItemGroup>
  <Protobut Includ="Protos\documento.proto" GrpcServices="Client" />
</ItemGroup>

Para saber mais sobre as estruturas e relacionamentos entre os nugets do gRPC e sua arquitetura, consulte o blog gRPC.

Agora vamos implementar a função que cria a conexão com o servidor e chama o endpoint RPC

public async Task CallDocumentoServiceAsync(IEnumerable<string> analiseIdList)
{
  using var channel = GrpcChannel.ForAddress("endereco_grpc");
  var client = new DocumentoServiceClient(channel);
  var duplexStream = client.List();

  await SendRequestMessageAsync(analiseIdList, duplexStream);
  await ReceiveResponseMessageAsync(duplexStream);
}

public async Task SendRequestMessage(
  IEnumerable<string> analiseIdList,
  AsyncDuplexStreamingCall<ListDocumentoRequest, ListDocumentoResponse> duplexStream)
{
  foreach (var analiseId in analiseIdList)
  {
    var grpcRequest = new ListDocumentoRequest
    {
      AnaliseId = analiseId
    };

    await duplexStream.RequestStream.WriteAsync(grpcRequest);
  }

  await duplexStream.RequestStream.CompleteAsync();
}

public async ReceiveResponseMessageAsync(
  AsyncDuplexStreamingCall<ListDocumentoRequest, ListDocumentoResponse> duplexStream)
{
  while (await duplexStream.ResponseStream.Move())
  {
    // TODO: Sua implementação
  }
}

A função acima cria um canal gRPC com o endereço do servidor especificado e usa o tipo DocumentoServiceClient gerado a partir da compilação do arquivo .proto para definir o serviço que será chamado. Em seguida, chamamos a função RPC List, que recebe e envia um stream de dados. O retorno da função é um duplexStream.

Em seguida, na função SendRequestMessage, fazemos o stream das requisições, escrevendo cada solicitação com await duplexStream.RequestStream.WriteAsync(grpcRequest);. Depois de enviar todos os pacotes, necessários, é importante informar ao servidor que finalizamos as requisições, chamando a função await duplexStream.RequestStream.CompleteAsync();.

Por fim, a função ReceiveResponseMessageAsync lida com o stream de retorno do servidor, percorrendo cada um dos retornos com duplexStream.ResponseStream.MoveNext() para processar os objetos retornados.

No exemplo fornecido, estamos enviando todas as requisições e, em seguida, recebendo todos os retornos. No entanto, a conexão gRPC é bidirecional, permitindo enviar e receber dados simultaneamente. Isso significa que poderíamos colocar cada função em uma thread separada, otimizando ainda mais o desempenho do envio e recebimento de dados entre cliente e servidor.

Caso você queira construir um servidor gRPC mas não queira criar um cliente apenas para testes, é possível usar o postman para consumir APIs gRPC, facilitando o teste das suas funções.

Conclusão e referências adicionais

O gRPC é uma ferramenta incrível para trafegar grandes volumes de dados, e há muitos cenários onde ele pode ser aplicado. Tenho certeza de que você poderá tirar grande proveito desse conhecimento.

Abaixo estão alguns links adicionais que você pode gostar:

https://blog.lsantos.dev/guia-grpc-1/

https://www.hipsters.tech/http2-magia-com-o-novo-protocolo/

Sua lógica, sua história: O que seu código diz sobre você

Mauricio Redmerski André — Mon, 08 Jan 2024 13:42:44 +0000

Olá, pessoal! Espero encontrar todos bem. Hoje você aprenderá que tipo de programador você é, qual é a história que os códigos que você escreve contam sobre você, e em qual gênero literário você seria encaixado se estivesse escrevendo um livro.

Escrever códigos de computadores é como escrever um livro, algumas estórias nos prendem, nos fazem querer saber mais sobre aquilo que está sendo contato, outras estórias nos repelem, e o único motivo para seguirmos lendo é a obrigação de saber o que acontece no final do livro, digo, final do código. Assim como escritores famosos, nós programadores temos cada um o seu próprio estilo, os seus próprios vícios, e marcamos nossas obras com nossa impressão digital ainda que não percebamos, e ainda que sigamos algum style guide.

As impressões digitais que deixamos para trás ao escrever um código de computador contam muito sobre nós mesmos, e mais ainda, a depender do nosso estilo, diria que nos permitem ser encaixados como produtores literários de livros que vão desde gêneros de romance, até gêneros de terror....

Há algum tempo, eu tive contato com um vídeo sobre React e ficção (link nas referências), no qual a palestrante traça um paralelo entre a escrita criativa de estórias de ficção, e a escrita de códigos de computadores. Inspirado por esse conteúdo, resolvi escrever esse artigo, e nele trato de forma ilusória as minhas próprias percepções sobre os códigos que leio, comparando-os com os sentimentos que se buscam despertar os diferentes gêneros literários.

**O autor adverte, qualquer semelhança com eventos reais, pessoas vivas ou mortas é mera coincidência 😁

Feito o preâmbulo, você está ansioso para saber o que o seu código conta sobre você? E qual é o gênero literário que você seria encaixado se o seu código fosse um livro?

Os gêneros literários dos programadores

Comecemos por definir alguns gêneros e algumas características nos códigos normalmente atribuíveis àqueles.

Terror

Todos nós em algum momento da vida já tivemos que lidar com algum código que nos assustou quando estávamos lendo, e que nos rendeu alguns pesadelos a noite. De fato, existem algumas coisas que são o terror dos programadores, confere só essa pequena lista e me diga se isso não te dá um frio na espinha:

Arquivos com o número de linhas intermináveis;
Linhas de código que poderiam dar a volta no planeta Terra;
O mesmo nome de variável sendo usada para várias coisas diferentes;
Todos os arquivos do projeto na pasta raiz do repositório;
Funções que passam como parâmetro a chamada de outras funções, que passam como parâmetros a chamada de outras funções, que passam como parâmetro a chamada de outras funções, que passam como parâmetro a chamada de outras funções.... Só para deixar claro, essa crítica não se aplica em linguagens funcionais 😁.

E por fim, e mais assustador, alguns programadores adoram esquartejar suas variáveis, muitas vezes, tudo que sobra para trás para contar história é um X marcando o local onde o ataque aconteceu.

lst.forEach(x => x.SOCORRO);

Suspense

Alguns códigos, quando precisamos debugá-los, nos dão a mesma experiência de ler um bom livro de suspense.

Os códigos que estou classificando aqui como suspense são aqueles que todas as vezes que executamos, não sabemos o que esperar, às vezes funciona, às vezes gera um erro, às vezes retorna um resultado, às vezes outro.

Isso costuma acontecer quando uma função faz várias coisas e possui vários efeitos colaterais, além de não deixar claro o que a mesma pretendia fazer.

function funcao1(objeto) {
  if ("o dia está ensolarado")
    console.log("bora curtir uma praia");
  if ("o vento está para o norte")
    objeto.propriedade = 1;
  if ("está chovendo")
    throw new Exception("O Dev pira");
}

Ficção

Ficção definitivamente é um gênero muito popular, pelo menos quando se trata de livros, quem nunca viu uma obra de Isaac Asimov? Quando falamos de algoritmos de computadores, esse gênero não é tão popular assim, é raro, mas acontece com frequência 😁.

Obras de ficção costumam brincar com a realidade, e desafiam o nosso conhecimento ou extrapolam teorias, nos algoritmos de computadores isso costuma ser visto quando o autor escreve uma função cujo objetivo do que se busca e do que se faz só pode ser ficcional.

function somarNumeros(int left, int right) {
  return left - right;
}

Romance

O amor é lindo, e mais lindo que o amor é um código escrito com paixão. Programadores experientes conseguem ver através do código e dizer com quanto carinho o código foi escrito pelo autor.

Poucas coisas são tão satisfatórias quanto trabalhar com um código que foi escrito com esmero, é possível sentir quando o programador se esforçou em tornar o seu trabalho entendível e lapidado. Ainda que não seja o melhor código possível, e não se trata disso! Um programador que escreve romances toma o cuidado de deixar as coisas onde se espera que elas estejam, e conduzem o leitor de seus códigos em uma valsa de funções e variáveis imitando o mais belo dos sonetos.

Escritores deste gênero tomam o cuidado de indentar seus códigos com um padrão bem estabelecido, ainda que o leitor prefira outras formatações, é notável que o autor se esforçou para manter tudo com a mesma estética, e não jogou simplesmente os elementos na tela como quem bate com a cabeça no teclado.

As revelações que os códigos fazem sobre seus autores

Tendo visto alguns gêneros literários usados para falar de características gerais dos desenvolvedores, daremos sequência observando algumas características mais pontuais, itens que os códigos revelam sobre os autores.

Programador Ultrawide Screen

Alguns programadores usam todo o espaço disponível de seus monitores para escrever seus códigos, pode ser muito fácil descobrir o tamanho do monitor de alguns desenvolvedores, basta contar quantas vezes você precisa rolar o código horizontalmente para descobrir se o desenvolvedor que o fez possui um monitor Ultrawide Screen.

Programador Shakespeariano

Esses programadores normalmente escrevem códigos que se encaixam no gênero de romance, suas obras são em geral muito belas, o único problema é que poucas pessoas são capazes de entendê-las.

Programadores que amam e odeiam espaço em branco

Alguns programadores amam usar a tecla de espaço, adicionam vários espaços entre seus códigos, seja verticalmente deixando um vasto espaço vazio entre funções, ou horizontalmente iniciando uma linha na metade da tela.

Por outro lado, há aqueles que a detestam, não incluem espaços entre elementos de uma linha, e muito menos entre blocos de funções, tudo se torna uma grande sequência de caracteres concatenados.

Conclusão

Ler e interpretar códigos compõem a maior parte do trabalho de um desenvolvedor, seja para integrar uma nova feature à um código já existente, corrigir um bug, ou refatorar algum trecho de código. Estamos sempre lendo códigos e tentando entender o que raios ele está fazendo, seja esse escrito por alguém da nossa equipe ou por nós mesmos há alguns meses. Por esse motivo, escrever de forma consistente e aplicar corretamente os padrões de desenvolvimento são tão importantes, isso nos ajuda a comunicar a intenção do código para as outras pessoas, e para nós mesmos no futuro.

O objetivo deste texto foi chamar a atenção de forma divertida para alguns anti-patterns e vícios negativos que temos no desenvolvimento de código, de forma que quando estejamos escrevendo algum código, nos perguntemos: que tipo de estória eu estou contando? Quem está lendo meu código se sentirá lendo um romance ou uma estória de terror?

É sempre mais agradável lidar com código claros e bem escritos, ainda que o código não seja o melhor, é possível notar quando o desenvolvedor se importava com o que estava fazendo, e queria entregar o melhor que podia naquele momento.

Dicas do autor

Quer deixar de escrever estórias de terror e começar a escrever verdadeiros romances? Que tal começar aplicando algumas estratégias de clean code básicas?

Preparei uma pequena lista de tópicos pensando no que vimos dentro dos gêneros literários deste artigo:

Nem todos os desenvolvedores possuem um super monitor, controle o comprimento das linhas do seu código, 80 caracteres é excelente, 120 é aceitável;
Se o arquivo está muito grande, separe o código em arquivos menores de acordo com as responsabilidades do código;
Separou o código em vários arquivos? Ótimo, agora os organize em pastas no seu projeto, não deixe tudo na pasta raiz;
Use nomes reveladores nas variáveis e funções, abreviaturas e usar apenas uma letra como variável dificulta muito a manutenção do código;
Certifique-se de que a função escrita faz o que o nome dela expressa;
Use o espaço vertical e horizontal, mas também não exagere, os elementos não precisam estar unidos, mas também não precisam estar em quarentena um longe do outro;
Siga apenas uma indentação, mesmo que não seja a melhor de todas ela demonstra consistência, poucas coisas mostram mais desleixo do que cada parte de um código escrito e indentado de formas completamente diferentes.

Lembre-se: escritores de livros não publicam a primeira versão de seus manuscritos, eles leem e releem suas obras e as lapidam, do mesmo jeito, você não deveria publicar a primeira versão do seu código, uma revisão ainda que rápida não fará mal a ninguém.

Agora, me conta: que tipo de gênero literário você tem escrito atualmente?

Referências

React e ficção: https://www.youtube.com/watch?v=kqh4lz2Lkzs
Livro: Código limpo: habilidades práticas do Agile software

Executando funções personalizadas no banco de dados usando SqlExpression no .Net

Mauricio Redmerski André — Sat, 06 May 2023 20:26:24 +0000

Olá, pessoal! Espero encontrar todos bem. Hoje teremos um material "mão na massa", demonstrando como fazer o EF Core (Entity Framework Core) ser capaz de traduzir funções personalizadas no banco de dados em expressões construídas com Linq (Consulta Integrada à Linguagem), que normalmente, não seria possível traduzi-las.

Se você trabalha com a linguagem de programação C#, certamente já escreveu alguma query com Linq que executa perfeitamente quando a lista de dados da operação envolvida já está carregada em memória, mas teve uma triste surpresa ao tentar aplicar o mesmo código acessando dados que estavam no banco, recebendo algum erro similar a este:

 The LINQ expression could not be translated

Isso ocorre porque há um limite acerca do que o EF Core é capaz de traduzir para linguagem nativa do banco de dados configurado em seu projeto, restringindo assim as possibilidades de uso do que pode ser feito diretamente no banco, em ralação ao que pode ser feito quando os dados já estão em memória. Mas há uma luz no fim do túnel, e não se preocupe, não é um trem vindo em sua direção... Podemos usar o recurso SqlExpression para ensinar o EF Core a traduzir comandos que ele nativamente não consegue, sendo essas operações nativas do seu banco de dados, ou funções criadas por você dentro do banco de dados.

Antes de começarmos efetivamente, vamos dar uma olhada nas versões de pacotes e programas que estou usando, sabemos que o modo como os recursos são implementados podem variar de acordo com suas versões, então para não haver mal-entendidos, estou usando o .Net 5 e o banco de dados SQL Server 2016, um pouco datado, eu sei.

Vamos começar com um problema simples. Imagine que você precise realizar uma consulta em uma massa de dados de Players, e retornar às seguintes propriedades: Name, Score, e a posição do player no ranking, que claro, é calculado a partir do Score. Para atender a essa demanda, um simples código como o seguinte pode ser usado

var playerList = new List<Player>()
{
    new Player() { Name = "Mauricio", Score = 10 },
    new Player() { Name = "André", Score = 6 },
    new Player() { Name = "Redmerski", Score = 8 },
};

var playerDtoList = playerList
    .OrderByDescending(player => player.Score)
    .Select((player, index) => new PlayerDto()
    {
        Name = player.Name,
        Score = player.Score,
        Position = index + 1,
    })
    .ToList();

Esse código funciona perfeitamente porque os dados que esse algoritmo manipula estão carregados em memória, se você trocar a variável playerList de modo a apontar para uma base de dados, usando dbContext.PlayersDbSet por exemplo, descobrirá que isso não pode ser traduzido para um comando SQL. O parâmetro index contido no Select representa a posição do item percorrido dentro da lista carregada em memória, logo se os dados não estão em memória, essa informação não existe. Poderíamos esperar que essa posição fosse substituída pela função do banco de dados que determina a linha da consulta, chamado de ROW_NUMBE no SQL Server, mas o EF Core não tem uma forma simples de executar essa operação para retornar o número da linha do registro em uma consulta ao banco de dados.

PS: Eu sei que você está com vontade de comentar que esse código não prevê a possibilidade de dois ou mais jogadores estarem empatados, mas quero manter as coisas simples, então segura essa vontade 😁.

Certo, então como podemos tornar essa operação traduzível ao banco de dados? Muito simples meu caro leitor, basta seguirmos os passos abaixo. Ah, os nomes e estruturas que mostro abaixo são uma representação de como eu acredito que essas funções devem ser organizadas, fique à vontade para alterá-las.

Começamos criando um diretório dentro do seu projeto responsável por lidar com a infraestrutura, especificamente o banco de dados, chamo essa pasta de Functions, dentro dessa pasta crio um arquivo chamado EfCoreCustomFunctions, dentro desse crio uma função chamada RowNumber que recebe três parâmetros, um parâmetro do tipo long que representará a coluna do banco de dados também do mesmo tipo que será usada para particionar a enumeração, um segundo parâmetro do tipo long que representará a coluna pela qual a ordenação deve ser aplicada para a enumeração, e um parâmetro booleano que indica a direção de ordenação, quando verdadeiro a ordem é ascendente. Observe que o conteúdo dessa função não é importante, então podemos simplesmente lançar uma exceção.

using System;

namespace MyProject.EntityFrameworkCore
{
    public static class EfCoreCustomFunctions
    {
        public static double RowNumber(long? partition, long ordering, bool ascending)
            => throw new NotSupportedException();
    }
}

Em seguida crio um arquivo na mesma pasta chamado RowNumberFunction, é dentro desse arquivo que a função realmente será criada. Nesse arquivo crio uma função de extensão para a classe ModelBuilder.

namespace MyProject.EntityFrameworkCore
{
    public static class RowNumberFunction
    {
        public static ModelBuilder AddRowNumberFunction(this ModelBuilder modelBuilder)
        {
            return modelBuilder;
        }
    }
}

A primeira coisa a ser feita é recuperar o tipo da classe que criamos para manter as assinaturas dos nossos métodos, e usar a função GetMethod para capturar a assinatura do método específico desejado. Eu gosto de especificar explicitamente os tipos dos parâmetros da função em questão, passando-os como segundo parâmetro da função GetMethod, mas se houver apenas uma função com o nome especificado, essa etapa é opcional.

var method = typeof(EfCoreCustomFunctions)
    .GetMethod(
        nameof(EfCoreCustomFunctions.RowNumber),
        new[] { typeof(long?), typeof(long), typeof(bool) });

Em seguida vem o passo mais importante: instruir o EF Core de fato a como traduzir esse comando, e podemos fazer isso de algumas formas

Depois de usar o modelMuilder para chamar a função HasDbFunction passando como parâmetro a variável method criada na etapa anterior, podemos usar a função HasName e passar o nome de uma função personalizada que nós criamos diretamente no banco.

modelBuilder.HasDbFunction(method).HasName("MinhaFuncaoJaCriadaNaBase");

Eu particularmente não gosto de criar funções diretamente no banco de dados, entendo como a melhor opção usarmos o método HasTranslation após a função HasDbFunction, esse método nos permite instruir o EF Core a como a operação precisa ser criada, sem que a função exista previamente na base, assim mantemos todas as regras de operação dentro do nosso programa. É claro que esse é um posicionamento particular, a função HasName existe para ser usada, então fique à vontade para fazer uso da mesma caso ela atenda ao seu cenário.

A função HasTranslation recebe uma function que contém uma lista de SqlExpression, essa lista é uma representação dos parâmetros que foram enviados para a função, e retorna um SqlExpression que será a função a ser executada. Sim, os tipos de entrada e saídas são iguais, isso porque o parâmetro da sua função pode ser o resultado de uma outra função traduzida para o banco.

A operação RowNumber em que estamos trabalhando possui a classe RowNumberExpression que facilita sua implementação e é herdeira de SqlExpression. Essa classe recebe como parâmetro uma lista opcional com os campos da base a serem usados como partição de agrupamento para a enumeração das linhas, uma lista obrigatória da classe OrderingExpression que contém o nome da coluna a ser usada na ordenação e a direção de ordenação, e o tipo de retorno esperado.

modelBuilder.HasDbFunction(method)
    .HasTranslation(args =>
        new RowNumberExpression(
            null,
            new List<OrderingExpression>()
            {
            },
            new LongTypeMapping("long", DbType.Int64)));

Os parâmetros da função RowNumber que criamos em nossa classe EfCoreCustomFunctions são um pouco diferentes do que é esperado, então vamos manipulá-los um pouco. Primeiro vamos verificar se o primeiro parâmetro que enviamos é do tipo SqlConstantExpression, qualquer constante enviada geraria o mesmo resultado, então eu prefiro testar essa condição, e caso ela seja verdadeira, passar o valor null como parâmetro.

modelBuilder.HasDbFunction(method)
    .HasTranslation(args =>
        new RowNumberExpression(
            args.First() is SqlConstantExpression
                ? null
                : args.Take(1).ToList(),
            new List<OrderingExpression>()
            {
            },
            new LongTypeMapping("long", DbType.Int64)));

Em seguida vamos criar um item na lista passada como segundo parâmetro, esse item vai ter os outros dois campos que recebemos em nossa função de ordenação personalizada. Observe que dada a natureza do tipo do objeto args, precisamos primeiro converter o terceiro parâmetro recebido para SqlConstantExpression para só então conseguir convertê-lo para booleano.

modelBuilder.HasDbFunction(method)
    .HasTranslation(args =>
        new RowNumberExpression(
            args.First() is SqlConstantExpression
                ? null
                : args.Take(1).ToList(),
            new List<OrderingExpression>()
            {
                new OrderingExpression(
                    args.Skip(1).First(),
                    ((bool)((SqlConstantExpression)args.Skip(2).First()).Value))
            },
            new LongTypeMapping("long", DbType.Int64)));

O código final dessa classe deve se parecer com o seguinte:

using System.Collections.Generic;
using System.Data;
using System.Linq;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Query.SqlExpressions;
using Microsoft.EntityFrameworkCore.Storage;

namespace MyProject.EntityFrameworkCore
{
    public static class RowNumberFunction
    {
        public static ModelBuilder AddRowNumberFunction(this ModelBuilder modelBuilder)
        {
            var method = typeof(EfCoreCustomFunctions)
                .GetMethod(
                    nameof(EfCoreCustomFunctions.RowNumber),
                    new[] { typeof(long?), typeof(long), typeof(bool) });

            modelBuilder.HasDbFunction(method)
                .HasTranslation(args =>
                    new RowNumberExpression(
                        args.First() is SqlConstantExpression
                            ? null
                            : args.Take(1).ToList(),
                        new List<OrderingExpression>()
                        {
                            new OrderingExpression(
                                args.Skip(1).First(),
                                ((bool)((SqlConstantExpression)args.Skip(2).First()).Value))
                        },
                        new LongTypeMapping("long", DbType.Int64))
                    );

            return modelBuilder;
        }
    }
}

Agora tudo que temos que fazer é chamar a construção desse método dentro do ModelBuilder, para que quando tentarmos usá-lo, ele saiba exatamente o que fazer. Para isso, vamos criar uma classe chamada ModelFunctionsExtensions dentro da pasta Functions, vamos usar esse arquivo para chamar todas as funções customizadas que criaremos no futuro.

using Microsoft.EntityFrameworkCore;

namespace MyProject.EntityFrameworkCore
{
    public static class ModelFunctionsExtensions
    {
        public static ModelBuilder AddCustomFunctions(this ModelBuilder modelBuilder)
        {
            modelBuilder.AddRowNumberFunction();

            return modelBuilder;
        }
    }
}

Agora no local onde você cria o seu contexto, tudo que você tem a fazer é incluir a seguinte linha builder.AddCustomFunctions(); e todas as configurações estarão prontas. É claro que a variável builder é uma instância de ModelBuilder.

Agora vamos ver como podemos alterar o nosso código de exemplo para usar a função que acabamos de criar. Primeiro vamos acessar os dados diretamente do contexto, e na atribuição da propriedade Position, vamos chamar nossa função RowNumber.

var playerDtoList = playerList
    .OrderByDescending(player => player.Score)
    .Select(player => new PlayerDto()
    {
        Name = player.Name,
        Score = player.Score,
        Position = EfCoreCustomFunctions.RowNumber(null, player.Score, false)
    })
    .ToList();

Pronto! Esse código será capaz de ser traduzido pelo EF Core, e a posição do player será calculada diretamente no banco de dados. Veja um exemplo de como essa query se parecerá quando for executada no banco de dados.

SELECT Name, Score, ROW_NUMBER() OVER(ORDER BY Score DESC) as Position
FROM Playes
ORDER BY Score DESC

Que tal olharmos rapidamente mais um exemplo de função, mas dessa vez um exemplo que use a classe SqlFunctionExpression? Essa classe recebe como primeiro parâmetro o nome da função a ser executado, os argumentos a serem transmitidos, um indicador se o retorno pode ser nulo, e uma lista com o mesmo número de argumentos passados que representa a possibilidade de os parâmetros enviados serem nulos, um parâmetro do tipo System.Type e outro RelationalTypeMapping respectivamente, ambos indicando o tipo de retorno da função.

Vamos criar um método que chama a função Replicate do banco de dados, começamos incluindo a função Replicate à nossa classe EfCoreCustomFunctions.

using System;

namespace MyProject.EntityFrameworkCore
{
    public static class EfCoreCustomFunctions
    {
        public static double RowNumber(long? partition, long ordering, bool ascending)
            => throw new NotSupportedException();

        public static string Replicate(string replicate, int length)
            => throw new NotSupportedException();
    }
}

Agora criamos o nosso arquivo ReplicateFunction e criamos um conteúdo muito semelhante ao exemplo anterior, mas agora usando SqlFunctionExpression.

using System.Collections.Generic;
using System.Data;
using System.Linq;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Query.SqlExpressions;
using Microsoft.EntityFrameworkCore.Storage;

namespace MyProject.EntityFrameworkCore
{
    public static class ReplicateFunction
    {
        public static ModelBuilder AddReplicateFunction(this ModelBuilder modelBuilder)
        {
            var method = typeof(EfCoreCustomFunctions)
                .GetMethod(
                    nameof(EfCoreCustomFunctions.Replicate),
                    new[] { typeof(string), typeof(int) });

            modelBuilder.HasDbFunction(method)
                .HasTranslation(args =>
                    new SqlFunctionExpression(
                        "REPLICATE",
                        args,
                        false,
                        args.Select(x => false),
                        typeof(string),
                        new StringTypeMapping("string", DbType.String))
                    );

            return modelBuilder;
        }
    }
}

Agora basta incluir a linha modelBuilder.AddReplicateFunction(); na função AddCustomFunctions do arquivo ModelFunctionsExtensions e nossa função já está pronta para ser usada.

Nota do autor

Conhecer recursos como esses a respeito da ferramenta com a qual trabalhamos é muito importante, e nos permite fazer coisas incríveis em nossas aplicações. Espero que esse artigo o tenha ajudado a resolver o que você precisava, ou ao menos incluído mais uma ferramenta em sua caixa de ferramentas para lidar com o complexo e maravilhoso mundo da programação.

Abraço!

Fontes e leituras complementares

https://learn.microsoft.com/en-us/ef/core/querying/user-defined-function-mapping

https://www.allhandsontech.com/data-professional/entityframework/entity-framework-core-advanced-mapping/

https://khalidabuhakmeh.com/add-custom-database-functions-for-entity-framework-core

https://stackoverflow.com/questions/56261258/mixing-ef-core-convensions-and-dbfunction-for-a-jobject-property

https://medium.com/@pawel.gerr/entity-framework-core-custom-functions-using-hasdbfunction-191dd57e4967

https://medium.com/@pawel.gerr/entity-framework-core-custom-functions-using-imethodcalltranslator-f8209ae6f95b

Conversando com alienígenas, uma breve introdução ao Gherkin

Mauricio Redmerski André — Thu, 16 Feb 2023 19:55:34 +0000

Olá, pessoal! Espero encontrar todos bem. Hoje vocês aprenderão a se comunicar com uma espécie muito curiosa e intrigante que vive sobre a superfície do nosso pálido ponto azul - ou planeta Terra se você não for tão íntimo.

Mas, antes de começarmos, preciso esclarecer uma coisa: se você começou a ler esse artigo esperando aprender a conversar com alienígenas de verdade, e talvez pensou que Gherkin fosse alguma máquina maluca de tradução de linguagens intergalácticas, detesto te desapontar, mas esse artigo não é bem sobre isso. Mas não desista de ler ele agora, prometo que esse material pode ser útil para você (mesmo se você realmente estiver querendo falar com aliens).

Certo, então qual é a espécie intrigante a qual eu me referi no começo do artigo? E sobre o que é esse material afinal?

No contexto deste artigo, quando falo em alienígenas, faço uma brincadeira com as pessoas da categoria a qual pertenço, me refiro a programadores e programadoras (devs) que em geral tem uma forma muito peculiar de interpretar o que as pessoas falam - darei exemplos e deixarei a analogia mais clara adiante. Esse artigo faz uma introdução a uma sintaxe, um modo de escrever determinado contexto, que elimina termos que possam não ser conhecidos por todos os interlocutores fazendo-o de uma forma declarativa, deste modo todos são capazes de compreender o contexto e qual é a mensagem a ser transmitida, aumentando assim a eficiência da comunicação entre os membros de um time em um ambiente de desenvolvimento de software, e claro, tornando mais fácil para nós desenvolvedores entender o que precisa ser feito. E o nome dessa estrutura mágica é Gherkin.

Problemática

Vamos fazer o seguinte experimento mental: imagine que uma nave alienígena pouse na sua frente, dela sai um homenzinho verde com clara capacidade de manter uma comunicação complexa, mas você não entende um único som que esse visitante espacial emite, e ele também não possui nenhum conhecimento prévio sobre sua língua e cultura. O que você faria para tentar compreender o que nosso visitante está dizendo e como você ensinaria a ele nossa língua para que ele pudesse nos entender?

A ideia de trazer esse experimento é causar a reflexão sobre como podemos nos comunicar com pessoas que não possuem o mesmo background que nós, que possuem outras ideias, onde aquilo que é óbvio para nós não é óbvio para nossos ouvintes. Nessa analogia, o homenzinho verde são os devs, e a questão é como um analista de negócio, gerente de produto ou qualquer outro estabelece contato conosco e nos solicita o desenvolvimento de uma nova funcionalidade. É claro que os papéis de marciano e terrestre podem ser facilmente invertidos, e que essa reflexão não vale apenas para comunicações onde devs estão envolvidos, mas também com qualquer pessoa, lembre-se que não é porque você fala a mesma linguagem que alguém, que não existirão ruídos na comunicação.

Mais uma historinha

Talvez você já tenha ouvido a piada onde alguém pede para um dev ir ao mercado com a seguinte instrução "Compre uma caixa de leite, e se tiver ovos traga dois" e assim o dev compra duas caixas de leite ao invés de uma caixa de leite e dois ovos como o solicitante queria. A piada pode ser engraçada, mas não é nada divertido quando essas confusões acontecem durante o desenvolvimento de um software, e a feature implementada não faz o que o solicitante esperava.

Por essa razão, o modo como uma funcionalidade deve ser descrita é muito importante, não só para o programador, mas para que todos os envolvidos no processo de construção de um software tenham o mesmo entendimento do que deve ser feito.

Só para constar, acho totalmente aceitável comprar duas caixas de leite considerando a instrução fornecida.

Falando sobre Gherkin

Gherkin é um dos elementos presentes no BDD (Behavior Driven Development) e basicamente consiste em escrever cenários de forma padronizadas, baseadas nas regras de negócio e usando palavras-chave para compor os passos que devem ser seguidos até uma conclusão, sendo sempre escritas na terceira pessoa.
Apesar de descrever as regras de negócio, o uso de palavras e termos que pertencem ao negócio deve ser evitado, é ideal que qualquer pessoa consiga ler e interpretar o que deve ser feito, mesmo que não possuam conhecimento de negócio. Em igual medida, termos técnicos e exemplo de codificação devem ser omitidos, essa especificação é o ponto onde todos os envolvidos na construção do software se encontram, sendo assim não pode haver termos que só um dos lados entenda.

Além do motivo supracitado para não acrescentar códigos na solicitação de uma demanda, existe outra boa razão para não fazer isso, o maior valor que um desenvolvedor entrega não é quanto código ele escreve, mas os problemas que ele resolve, somos bons em resolver problemas e gostamos disso, entregar o problema resolvido para "apenas" escrever o código elimina a maior entrega de valor que podemos dar, além de nos matar vagarosamente.

Os arquivos com a estrutura Gherkin são normalmente salvos com a extensão feature e possuem notações iniciadas com cerquilha # para indicar por exemplo a linguagem das palavras-chave usadas naquele arquivo, a indentação do conteúdo é estruturado com espaços e quebra de linha, deste modo o aninhamento do conteúdo e as palavras-chave são identificadas. Essas especificações são especialmente importantes se você for manter esses conteúdos escritos em arquivos, mas nada o impede de usar a caixa de texto de algum sistema para manter esse conteúdo, a fim de usar a ideia e as palavras-chave do Gherkin nas definições de suas demandas no software de gerenciamento de projetos que sua empresa já usa.

Palavras-chave

A lista abaixo apresenta as palavras-chave do Gherkin com uma breve descrição sobre seu objetivo

Feature: Descreve em níveis mais altos o propósito da funcionalidade e agrupa os diferentes cenários que podem existir;
Background: É o contexto, um conjunto inicial de steps que se repetem em todos os cenários da feature;
Scenario ou Example: Descreve um exemplo concreto sobre a regra de negócio e é ou não seguido por steps, é possível incluir quantos steps desejar;
Scenario Outline: Usado para descrever um cenário que se repete alterando as entradas e saídas;
Examples: Usado para construir um conjunto de exemplos de entrada e saída para usar dentro do Scenario Outline;
Step Given: Descreve a condição inicial do cenário;
Step When: Descreve um evento que normalmente causa uma mudança;
Step Then: Descreve o resultado esperado após o evento;
Step And: Pode ser usado para concatenar de forma positiva sentenças dos steps anteriores;
Step But: Pode ser usado para acrescentar uma negativa de forma subsequente a um dos steps superiores;

Casos de testes escritos com Gherkin

Para entendermos melhor a diferença entre simplesmente escrever a funcionalidade e escrevê-la usando Gherkin, que tal observamos um exemplo simples de login de usuário escritos das duas maneiras?

Simplesmente descrevendo:
Quando eu acessar o site e ir até a página de login e preencher o login a senha e clicar no botão de iniciar sessão, uma requisição a api do site deve ser feita transmitindo os dados preenchidos, se o resultado enviado pela api for positivo, uma mensagem de login efetuado com sucesso deve ser apresentada e o site deve me redirecionar para a página inicial do site mantendo minha sessão na memória do navegador.

Usando o Gherkin:

Feature: Login de usuário

  Scenario: Login de usuário válido
    Given que o usuário possua uma conta no site
    And acesse a página de login
    And preencha corretamente os dados de acesso
    When ele acionar o botão de entrar no sistema
    Then uma mensagem de sucesso deve ser apresentada
    And ele deve ser direcionado logado a página inicial do site

Como se pode observar, o modelo escrito com Gherkin é muito mais claro e omite qualquer detalhe técnico do desenvolvimento. Que tal darmos uma olhada em outro exemplo, agora usando as palavras-chave faltantes?

Feature: Café da tarde

Background:
  Given que os escritores de artigos sentem fome

Scenario Outline: Comendo fatias de bolo
  Given que existe <inicial> fatias de bolo
  When for comido <comido> fatias de bolo
  Then deve restar <restante> fatias de bolo

  Examples:
    | inicial | comido | restante |
    |    10   |    3   |     7    |
    |     5   |    5   |     0    |

Apesar dos exemplos modestos, acredito que seja possível compreender a ideia geral. Alguém poderia dizer que esse modelo adiciona mais trabalho na escrita dos cenários, ou mesmo que essa divisão parece infantil e que um texto corrido teria o mesmo efeito. Qualquer quantia de tempo acrescido na criação das descrições das atividades seria recuperada, uma vez que seria poupando tempo de manutenção e correções por conta do desentendimento quanto ao objetivo da função. Quanto a divisão parecer infantil, pense que você está escrevendo cenários para pessoas que não tem o mesmo conhecimento de negócio que você, imagine aquele marciano na sua frente e tente explicar para ele o que precisa ser feito...

Conclusão

Escrever os cenários com Gherkin é incrivelmente simples, o fato de ter poucas palavras-chave torna o modelo muito fácil de ser aprendido, e após escrever poucos cenários não é mais necessário pesquisar exemplos para se basear.

Além de ser fácil, esse modelo fornece uma estrutura de escrita que quando é bem usada, diminui consideravelmente os ruídos e mal-entendidos entre o que o solicitante precisar e o que é implementado de fato.

Por hoje é tudo pessoal, espero que tenham se divertido com a leitura e tenham se interessado por aprender um pouco mais sobre Gherkin, não deixe de conferir as fontes deste material.

Ah, e se encontrar um alien por aí, diga que eu mandei um "Oi!".

Fontes:

https://cucumber.io/docs/gherkin/reference/

https://medium.com/revista-tspi/gherkin-o-dia-em-que-entendi-que-estava-escrevendo-errado-220a84520819