Se você é um desenvolvedor que trabalha com APIs, provavelmente sabe quão importante é testá-las e depurá-las antes de implantá-las em produção. Você quer garantir que suas APIs sejam confiáveis, seguras e performáticas, e que atendam às expectativas de seus clientes e usuários.
Mas como você testa e depura suas APIs, especialmente se elas usam gRPC, um protocolo moderno e eficiente para comunicação entre microsserviços? É aí que entra o grpc-curl. grpc-curl é uma ferramenta de linha de comando que permite interagir com servidores gRPC de maneira simples e intuitiva.
Neste post do blog, vou mostrar como usar o grpc-curl para testar e depurar suas APIs, e por que você deve considerar usá-lo para seus projetos gRPC.
O que é o grpc-curl?
grpc-curl é uma ferramenta de linha de comando que permite invocar métodos RPC em um servidor gRPC a partir da linha de comando. Ele suporta vários métodos RPC, incluindo unário, streaming do servidor, streaming do cliente e streaming bidirecional. Você também pode navegar pelo esquema dos serviços gRPC, seja consultando um servidor que suporte reflexão do servidor ou carregando arquivos protoset compilados.
grpc-curl é escrito em .NET, e tem algumas vantagens sobre gRPCurl, como:
- Suporta tanto .NET Core quanto .NET Framework, e pode rodar em Windows, Linux e Mac OS.
- Possui uma sintaxe mais concisa e expressiva, e pode inferir os nomes dos serviços e métodos a partir da URL.
- Pode formatar automaticamente a saída JSON com cores e recuo, e também pode gerar saída em XML ou texto simples.
- Consegue manipular mensagens aninhadas e campos repetidos melhor, e também pode aceitar entrada de arquivos ou entrada padrão.
- Pode usar variáveis de ambiente para opções comuns, como a URL do servidor, os cabeçalhos e as configurações TLS.
- Pode gerar trechos de código para C#, Java, Python e Go, para ajudar você a escrever seu próprio código cliente.
grpc-curl está disponível como um pacote NuGet, e você pode instalá-lo com o seguinte comando:
dotnet tool install -g grpc-curl
Como usar o grpc-curl?
Para usar o grpc-curl, você precisa ter um servidor gRPC em execução, e precisa saber sua URL e os nomes dos serviços e métodos que deseja chamar. Você também precisa ter o esquema para os serviços gRPC, seja usando reflexão de servidor ou carregando arquivos protoset.
Para este exemplo, vou usar um servidor gRPC simples que implementa um serviço de calculadora, com quatro métodos: Adicionar, Subtrair, Multiplicar e Dividir. O servidor é escrito em C#, e suporta reflexão do servidor.
Para iniciar o servidor, execute o seguinte comando a partir da pasta do projeto:
dotnet run
O servidor irá escutar na porta 5000 por padrão. Você pode alterar o número da porta no arquivo appsettings.json.
Para chamar o método Adicionar no servidor, execute o seguinte comando de outro terminal:
grpc-curl http://localhost:5000 Calculator/Add -d '{"x": 3, "y": 5}'
A saída deve ser algo assim:
{
"result": 8
}
Como você pode ver, grpc-curl infere automaticamente os nomes do serviço e do método a partir da URL, e formata a saída JSON com cores e recuo. Você também pode usar a opção -o para especificar um formato de saída diferente, como XML ou texto.
Para chamar o método Subtrair, execute o seguinte comando:
grpc-curl http://localhost:5000 Calculator/Subtract -d '{"x": 10, "y": 4}'
A saída deve ser algo assim:
{
"result": 6
}
Para chamar o método Multiplicar, execute o seguinte comando:
grpc-curl http://localhost:5000 Calculator/Multiply -d '{"x": 2, "y": 7}'
A saída deve ser algo assim:
{
"result": 14
}
Para chamar o método Dividir, execute o seguinte comando:
grpc-curl http://localhost:5000 Calculator/Divide -d '{"x": 15, "y": 3}'
A saída deve ser algo assim:
{
"result": 5
}
Se você tentar dividir por zero, receberá uma mensagem de erro, como esta:
grpc-curl http://localhost:5000 Calculator/Divide -d '{"x": 15, "y": 0}'
{
"error": "Não é possível dividir por zero."
}
grpc-curl também suporta métodos de streaming, que podem enviar ou receber várias mensagens em uma única chamada. Por exemplo, digamos que temos um método de streaming do servidor chamado Fibonacci, que leva um número n como entrada e retorna os primeiros n números de Fibonacci como um fluxo de mensagens. O código do servidor para este método parece algo assim:
public override async Task Fibonacci(Number request, IServerStreamWriter<Number> responseStream, ServerCallContext context)
{
int n = request.Value;
int a = 0;
int b = 1;
for (int i = 0; i < n; i++)
{
await responseStream.WriteAsync(new Number { Value = a });
int temp = a;
a = b;
b = temp + b;
}
}
Para chamar este método com grpc-curl, execute o seguinte comando:
grpc-curl http://localhost:5000 Calculator/Fibonacci -d '{"value": 10}'
A saída deve ser algo assim:
{
"value": 0
}
{
"value": 1
}
{
"value": 1
}
{
"value": 2
}
{
"value": 3
}
{
"value": 5
}
{
"value": 8
}
{
"value": 13
}
{
"value": 21
}
{
"value": 34
}
Como você pode ver, grpc-curl imprime cada mensagem à medida que a recebe do servidor, e fecha a conexão quando o fluxo está completo.
grpc-curl também suporta métodos de streaming do cliente, que podem enviar várias mensagens para o servidor e receber uma única resposta. Por exemplo, digamos que temos um método de streaming do cliente chamado Soma, que recebe um fluxo de números como entrada e retorna sua soma como resposta. O código do servidor para este método parece algo assim:
public override async Task<Number> Sum(IAsyncStreamReader<Number> requestStream, ServerCallContext context)
{
int sum = 0;
await foreach (var number in requestStream.ReadAllAsync())
{
sum += number.Value;
}
return new Number { Value = sum };
}
Para chamar este método com grpc-curl, precisamos fornecer as mensagens de entrada a partir de um arquivo ou da entrada padrão. Por exemplo, podemos criar um arquivo chamado numbers.json com o seguinte conteúdo:
{"value": 1}
{"value": 2}
{"value": 3}
{"value": 4}
{"value": 5}
Então, podemos executar o seguinte comando:
grpc-curl http://localhost:5000 Calculator/Sum -d @numbers.json
A saída deve ser algo assim:
{
"value": 15
}
Alternativamente, podemos usar o símbolo - para indicar que as mensagens de entrada estão vindo da entrada padrão, e então digitar ou colar as mensagens no terminal, seguidas por Ctrl+D para encerrar a entrada. Por exemplo:
grpc-curl http://localhost:5000 Calculator/Sum -d -
{"value": 1}
{"value": 2}
{"value": 3}
{"value": 4}
{"value": 5}
^D
A saída deve ser a mesma que antes.
grpc-curl também suporta métodos de streaming bidirecional, que podem enviar e receber várias mensagens em ambas as direções. Por exemplo, digamos que temos um método de streaming bidirecional chamado Chat, que recebe um fluxo de mensagens como entrada e retorna um fluxo de mensagens como saída. O código do servidor para este método parece algo assim:
public override async Task Chat(IAsyncStreamReader<Message> requestStream, IServerStreamWriter<Message> responseStream, ServerCallContext context)
{
await foreach (var message in requestStream.ReadAllAsync())
{
Console.WriteLine($"Recebido: {message.Text}");
var reply = new Message { Text = $"Eco: {message.Text}" };
await responseStream.WriteAsync(reply);
Console.WriteLine($"Enviado: {reply.Text}");
}
}
Para chamar este método com grpc-curl, precisamos fornecer as mensagens de entrada a partir de um arquivo ou da entrada padrão, e precisamos usar a opção -s para indicar que queremos receber as mensagens de saída como um fluxo. Por exemplo, podemos criar um arquivo chamado chat.json com o seguinte conteúdo:
{"text": "Olá"}
{"text": "Como você está?"}
{"text": "Adeus"}
Então, podemos executar o seguinte comando:
grpc-curl http://localhost:5000 Calculator/Chat -d @chat.json -s
A saída deve ser algo assim:
{
"text": "Eco: Olá"
}
{
"text": "Eco: Como você está?"
}
{
"text": "Eco: Adeus"
}
Como você pode ver, grpc-curl envia cada mensagem para o servidor e imprime cada resposta do servidor, até que o fluxo de entrada se esgote.
Por que usar o grpc-curl?
grpc-curl é uma ferramenta útil para testar e depurar suas APIs gRPC, porque permite:
- Invocar qualquer tipo de método RPC, incluindo métodos de streaming, a partir da linha de comando, sem precisar escrever nenhum código cliente.
- Navegar pelo esquema dos serviços gRPC, seja consultando um servidor que suporte reflexão do servidor, ou carregando arquivos protoset.
- Formatar a saída de diferentes maneiras, como JSON, XML ou texto simples, com cores e recuo.
- Manipular mensagens aninhadas e campos repetidos melhor do que gRPCurl, e aceitar entrada de arquivos ou entrada padrão.
- Usar variáveis de ambiente para opções comuns, como a URL do servidor, os cabeçalhos e as configurações TLS.
- Gerar trechos de código para C#, Java, Python e Go, para ajudar você a escrever seu próprio código cliente.
grpc-curl também é fácil de instalar e usar, e funciona em várias plataformas, como Windows, Linux e Mac OS. É compatível com .NET Core e .NET Framework, e suporta os protocolos HTTP/1.1 e HTTP/2.
grpc-curl não é útil apenas para desenvolvedores, mas também para testadores, engenheiros de QA, engenheiros de DevOps e qualquer pessoa que precise interagir com servidores gRPC. Ele pode ajudar você a verificar a funcionalidade, desempenho, segurança e confiabilidade de suas APIs, e identificar e corrigir quaisquer problemas ou bugs.
Como usar o grpc-curl com Apidog?
Se você quiser levar seus testes e depuração de gRPC para o próximo nível, talvez queira usar o grpc-curl com o Apidog, uma ferramenta poderosa e flexível para documentação e teste de APIs.
Apidog é uma ferramenta que permite criar, gerenciar e compartilhar documentação e testes de API, usando uma interface simples e intuitiva. Você pode usar o Apidog para documentar e testar qualquer tipo de API, incluindo REST, SOAP, GraphQL e gRPC.
Com o Apidog, você pode:
- Importar seu esquema de API de várias fontes, como OpenAPI, Swagger, WSDL, GraphQL ou arquivos protoset.
- Criar e organizar seus endpoints de API, métodos, parâmetros, cabeçalhos e respostas, usando um editor gráfico ou um editor de código.
- Adicionar descrições, exemplos, validações e anotações aos seus elementos de API, usando Markdown ou HTML.
- Gerar documentação de API interativa e bonita, com exemplos ao vivo, trechos de código e diagramas.
- Criar e executar testes de API, usando um executor de testes integrado ou uma ferramenta de linha de comando.
- Monitorar e depurar suas chamadas de API, usando um proxy integrado ou uma extensão de navegador.
- Colaborar e compartilhar seus projetos de API com sua equipe ou seus clientes, usando uma plataforma baseada em nuvem ou uma solução auto-hospedada.
Streaming do Servidor
O Streaming do Servidor, como o nome implica, envolve o envio de múltiplos dados de resposta em uma única solicitação. Por exemplo, pode envolver a assinatura de todos os dados de preços de transações de ações dentro de um período de um minuto.
Streaming do Cliente
Neste modo, o cliente pode enviar continuamente várias mensagens de solicitação para o servidor sem esperar respostas imediatas. Após processar todas as solicitações, o servidor envia uma única mensagem de resposta de volta ao cliente. Essa abordagem é adequada para transmitir grandes quantidades de dados de maneira eficiente em streaming, o que ajuda a reduzir a latência e otimizar a troca de dados.
Streaming Bidirecional
O Streaming Bidirecional permite que clientes e servidores estabeleçam uma comunicação bidirecional persistente e transmitam várias mensagens simultaneamente. É comumente utilizado em jogos online e software de chamadas de vídeo em tempo real, e é bem adequado para comunicação em tempo real e cenários de transmissão de dados em larga escala. Após iniciar a chamada, o cliente e o servidor mantêm uma sessão entre eles e recebem respostas em tempo real após enviar diferentes conteúdos de solicitação.
Colaborando em APIs gRPC
O Apidog pode gerar documentos de interface gRPC legíveis para humanos a partir de arquivos .proto, facilitando a colaboração da equipe em interfaces. Clique no botão de menu no lado direito da interface para obter o link de colaboração e compartilhá-lo com outros membros da equipe para alinhar a abordagem de depuração da interface.
- Criar uma conta no Apidog e fazer login no aplicativo web do Apidog.
- Criar um novo projeto de API e dar um nome e uma descrição a ele.
- Impor seu esquema gRPC a partir de um arquivo protoset, ou criá-lo manualmente usando o editor gráfico ou o editor de código.
- Adicionar seus endpoints gRPC, métodos, parâmetros, cabeçalhos e respostas, e preencher os detalhes e exemplos.
- Gerar sua documentação de API e visualizá-la no navegador ou exportá-la como um arquivo PDF ou HTML.
- Criar seus testes de API e executá-los usando o executor de testes integrado ou a ferramenta de linha de comando.
- Monitorar e depurar suas chamadas de API, usando o proxy integrado ou a extensão de navegador.
- Compartilhar seu projeto de API com sua equipe ou seus clientes, usando a plataforma baseada em nuvem ou a solução auto-hospedada.
Para saber mais sobre o Apidog, e como usá-lo com o grpc-curl, você pode visitar o site do Apidog, ou conferir a documentação do Apidog.
Conclusão
grpc-curl é uma ferramenta de linha de comando que permite interagir com servidores gRPC de maneira simples e intuitiva. É baseada no gRPCurl, mas adiciona alguns recursos e melhorias que a tornam mais amigável e poderosa. Você pode usar grpc-curl para testar e depurar suas APIs gRPC e para gerar trechos de código para seu próprio código cliente.
grpc-curl também é compatível com o Apidog, uma ferramenta baseada na web para documentação e teste de APIs. Você pode usar o Apidog para criar, gerenciar e compartilhar seus projetos de API e para executar e monitorar seus testes de API.
Se você é um desenvolvedor que trabalha com gRPC, ou se está interessado em aprender mais sobre gRPC, definitivamente deveria experimentar o grpc-curl e o Apidog. Eles podem ajudar você a melhorar a qualidade e a usabilidade de suas APIs, e facilitar e acelerar seu processo de desenvolvimento.
