Se você já tentou chamar um serviço gRPC de um navegador, já conhece a fricção. Navegadores não conseguem falar gRPC puro porque não podem controlar os "trailers" HTTP, então você acaba instalando um proxy como o Envoy apenas para traduzir o tráfego. O ConnectRPC remove essa etapa. Ele permite que você construa APIs baseadas em Protobuf que um navegador pode chamar diretamente, que respondem a um comando curl simples e que ainda interoperam com o ecossistema gRPC mais amplo.
Este guia explica o que é o ConnectRPC, o problema que o protocolo Connect resolve, como o Connect se compara a gRPC, gRPC-Web e REST, e como uma requisição Connect se parece via HTTP. Você também verá como testar e depurar endpoints Connect e gRPC com um cliente de API padrão.
O Que É o ConnectRPC
ConnectRPC é uma família de bibliotecas para construir APIs HTTP compatíveis com navegadores e gRPC a partir de Protocol Buffers. Você define seu serviço em um arquivo .proto, gera o código e implementa seus "handlers". O Connect cuida do roteamento, serialização, compressão e geração de clientes.
O projeto foi criado pela Buf, a empresa por trás das ferramentas de construção buf para Protobuf, e agora é um projeto sandbox da Cloud Native Computing Foundation (CNCF). Essa linhagem é importante: o Connect é projetado para se ajustar ao mesmo fluxo de trabalho "schema-first" que as equipes já usam com buf e Protobuf.
Um servidor ConnectRPC suporta três protocolos de uma vez:
- gRPC: compatibilidade total, incluindo streaming e "trailers".
- gRPC-Web: suporte direto, sem a necessidade de um proxy separado.
- Connect: seu próprio protocolo baseado em HTTP, otimizado para a web.
Como um único servidor "fala" os três, um cliente gRPC pode chamar um servidor Connect, e um cliente Connect pode chamar qualquer servidor gRPC. Você escolhe o protocolo por cliente, muitas vezes com uma única alteração de configuração e sem reescrever o código.
O Problema Que o Connect Resolve
gRPC é rápido e fortemente tipado, mas faz suposições que a web não honra. Ele depende de HTTP/2 e de "trailers" HTTP para transportar informações de status. Navegadores não expõem "trailers" ao JavaScript, então um navegador não pode atuar como um cliente gRPC nativo. A solução usual é gRPC-Web mais um proxy de tradução, como o Envoy, que fica entre o navegador e o seu backend gRPC.
Isso funciona, mas adiciona peças móveis. Agora você executa e configura um proxy, e depura um salto extra. Para equipes que desejam APIs tipadas e acesso por navegador sem essa sobrecarga, a configuração parece mais pesada do que deveria.
O Connect adota uma rota diferente. Seu próprio protocolo roda sobre HTTP padrão, então um navegador pode chamá-lo diretamente e você não precisa de um proxy para o tráfego do navegador. Se você também precisar servir clientes gRPC existentes, o mesmo servidor Connect os atende. Você obtém um único backend que responde a navegadores, ferramentas de linha de comando e serviços gRPC igualmente.
Connect vs gRPC vs gRPC-Web vs REST
Essas quatro abordagens se sobrepõem, então é útil compará-las.
gRPC usa Protobuf sobre HTTP/2 com "framing" binário e "trailers". É eficiente e suporta todos os quatro modos de streaming, mas é difícil de chamar de um navegador ou com um shell. Se você quiser uma revisão da camada de transporte, veja como gRPC e HTTP/2 funcionam juntos.
gRPC-Web é uma variante de gRPC amigável ao navegador. Ainda se concentra em Protobuf e geralmente precisa de um proxy para fazer a ponte para um backend gRPC real. Nosso guia sobre o que é gRPC-Web cobre onde ele se encaixa.
Connect mantém o esquema Protobuf e o modelo de método estilo gRPC, mas seu protocolo roda de forma limpa sobre HTTP/1.1, HTTP/2 e HTTP/3. Chamadas unárias carregam um corpo JSON ou Protobuf simples sem "framing" binário gRPC, e as respostas usam códigos de status HTTP reais. Essa combinação é o que torna uma chamada Connect tão acessível quanto qualquer chamada REST.
REST é orientado a recursos e opcionalmente baseado em esquema. É o estilo mais universalmente suportado, mas carece da geração de código e da tipagem estrita que o Protobuf oferece. Se você está avaliando as compensações, gRPC vs REST detalha as diferenças.
A versão curta: o Connect visa oferecer a tipagem e as ferramentas do gRPC com o alcance e a capacidade de depuração do REST. Ele se baseia no modelo de método do Protobuf e do gRPC, ao mesmo tempo em que descarta as partes que navegadores e shells não conseguem lidar.
Uma Requisição Connect Via HTTP
É isso que torna o Connect acessível. Uma chamada unária Connect é um HTTP POST comum. O caminho da URL vem diretamente do seu esquema Protobuf, e o corpo é JSON ou Protobuf binário sem "framing" extra.
O formato do caminho é /<pacote>.<Serviço>/<Método>. Assim, um método Greet em um GreetService no pacote greet.v1 reside em /greet.v1.GreetService/Greet.
Você pode chamá-lo com curl:
curl \
--header "Content-Type: application/json" \
--data '{"name": "Jane"}' \
http://localhost:8080/greet.v1.GreetService/Greet
A resposta é JSON simples:
{"greeting": "Hello, Jane!"}
Sem cliente personalizado, sem proxy, sem decodificação binária. Essa é a requisição completa. Como o corpo é JSON real e o status é um código de status HTTP real, toda ferramenta que "fala" HTTP pode inspecionar a chamada. Essa é a propriedade que separa o protocolo Connect do gRPC puro, onde a mesma requisição seria encapsulada em "framing" binário e transportaria seu status em um "trailer".
O Connect suporta dois tipos de conteúdo para requisições unárias:
application/jsonpara payloads JSON legíveis por humanos.application/protopara Protobuf binário compacto.
Você envia Protobuf binário quando deseja um tamanho de "wire" menor e JSON quando deseja legibilidade durante o desenvolvimento. Para enviar binário, troque o cabeçalho e passe um corpo codificado:
curl \
--header "Content-Type: application/proto" \
--data-binary @request.bin \
http://localhost:8080/greet.v1.GreetService/Greet
Chamadas de streaming usam um tipo de conteúdo diferente (application/connect+proto ou application/connect+json) e encapsulam cada mensagem em um "envelope": um byte de sinalização, um comprimento de quatro bytes em "big-endian", e então a mensagem. Chamadas unárias pulam esse "envelope" inteiramente, o que é o motivo de se mapearem tão claramente para uma requisição HTTP normal. Se você está escolhendo entre formatos de "wire" para seus payloads, Protobuf vs JSON cobre as compensações de tamanho e legibilidade.
Suporte a Linguagens e Ferramentas buf
O ConnectRPC oferece implementações em várias linguagens. Go e TypeScript (para navegador e Node.js) são estáveis e prontas para produção. Swift está disponível para plataformas Apple, com Kotlin para JVM e Android, e Python em beta. Essa amplitude permite compartilhar um contrato Protobuf entre um backend Go e um frontend TypeScript sem escrever clientes manualmente.
A geração de código é feita pela cadeia de ferramentas buf. Você descreve seu serviço em um arquivo .proto e então usa plugins buf para gerar mensagens e "handlers" Connect. Um projeto Go usa dois plugins: protoc-gen-go para as mensagens Protobuf e protoc-gen-connect-go para os "handlers" e clientes Connect.
Os plugins são listados em um arquivo buf.gen.yaml, e você executa a geração com um comando:
buf generate
Isso produz estruturas de mensagem tipadas, além do código de servidor e cliente para o seu serviço. A partir daí, você implementa os métodos do "handler" e os registra em um servidor HTTP. Como o código gerado visa o net/http da biblioteca padrão em Go, você não precisa de um tempo de execução de servidor separado; um "handler" Connect é um "handler" HTTP normal que você pode montar junto com suas rotas existentes.
Testando e Depurando Endpoints Connect e gRPC
Como as chamadas unárias Connect são HTTP simples com um corpo JSON, você pode testá-las da mesma forma que testa qualquer endpoint REST. Isso é uma vantagem prática: nenhum cliente especial é necessário para interagir com seu serviço durante o desenvolvimento.
No Apidog, você envia uma requisição unária Connect como uma requisição HTTP. Defina o método como POST, use a URL derivada do esquema, como http://localhost:8080/greet.v1.GreetService/Greet, adicione o cabeçalho Content-Type: application/json e coloque sua mensagem no corpo JSON:
{"name": "Jane"}
Você recebe a resposta JSON e um código de status HTTP real, que você pode verificar diretamente. O Apidog não é um cliente Connect dedicado, mas não precisa ser; você está exercitando a superfície HTTP que o protocolo Connect expõe, exatamente como o curl faz, com uma interface de usuário, requisições salvas e histórico. Para uma introdução rápida aos "verbos" envolvidos, veja o que são métodos HTTP.
Como um servidor Connect também "fala" gRPC, o lado gRPC do seu serviço também é testável. O Apidog suporta endpoints gRPC, então você pode importar o mesmo arquivo .proto, navegar pelos métodos do serviço e chamá-los com uma requisição tipada. Isso significa que uma única ferramenta cobre ambas as faces do servidor: o protocolo Connect, amigável ao HTTP, e o protocolo gRPC nativo. Se gRPC é sua principal preocupação, como testar APIs gRPC de forma eficiente descreve o fluxo de trabalho.
Uma vez que suas requisições se comportam, você pode movê-las para verificações automatizadas. Salve suas chamadas Connect e gRPC como cenários de teste, depois execute-os em CI com o Apidog CLI. Instale-o com Node:
npm install -g apidog-cli
Em seguida, execute um cenário ou suíte salvo, apontando para um ambiente e escolhendo formatos de relatório:
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t <scenarioOrSuiteId> \
-e <environmentId> \
-r cli,html,junit
O CLI é "headless" (sem interface gráfica), então ele se encaixa em qualquer etapa de CI que possa executar Node. Ele executa cenários e suítes de teste salvos em vez de enviar requisições ad hoc, o que o torna adequado para verificações de regressão em seus endpoints Connect e gRPC. Para um passo a passo completo, veja o tutorial do Apidog CLI para testar uma API pela linha de comando.
Perguntas Frequentes
ConnectRPC é o mesmo que gRPC? Não. ConnectRPC é um framework que implementa três protocolos: gRPC, gRPC-Web e seu próprio protocolo Connect. Um servidor Connect interopera com clientes e servidores gRPC, então ele se encaixa no ecossistema gRPC, mas o protocolo Connect em si é um design separado baseado em HTTP que navegadores e shells podem chamar diretamente.
Ainda preciso de um proxy como o Envoy para alcançar um navegador? Não para o protocolo Connect. O Connect funciona sobre HTTP padrão, então um navegador pode chamar um servidor Connect sem um proxy de tradução. Você só precisaria de um proxy como o Envoy quando precisar fazer a ponte do tráfego do navegador para um backend que "fala" gRPC nativo e nada mais.
Quais linguagens o ConnectRPC suporta? Go e TypeScript (navegador e Node.js) são as implementações estáveis e prontas para produção. Swift, Kotlin e Python também estão disponíveis, com Python em beta. Todas elas geram a partir do mesmo esquema Protobuf.
Qual é a relação entre Connect e buf? ConnectRPC foi criado pela Buf e usa a cadeia de ferramentas buf para geração de código. Você executa buf generate com plugins como protoc-gen-connect-go para produzir "handlers" e clientes a partir dos seus arquivos .proto.
Posso testar um endpoint Connect com um cliente de API normal? Sim. As chamadas unárias Connect são requisições HTTP POST com um corpo JSON ou Protobuf e um código de status HTTP real. Qualquer cliente HTTP, incluindo curl e Apidog, pode enviar uma. O Apidog também pode chamar o lado gRPC do mesmo servidor importando o arquivo .proto.