gRPC em Go: Contratos, Streaming e Desempenho
Microsserviços precisam de um contrato que sobreviva a refatorações, um formato de rede que permaneça compacto e um transporte que multiplexe muitas chamadas em uma única conexão.
//
Busque em todas as páginas da documentação
Microsserviços precisam de um contrato que sobreviva a refatorações, um formato de rede que permaneça compacto e um transporte que multiplexe muitas chamadas em uma única conexão.
O gRPC atende a todos os três, combinando esquemas de Protocol Buffers com framing HTTP/2 e um pequeno conjunto de padrões de RPC.
O pacote google.golang.org/grpc do Go é a pilha de servidor e cliente de fato para plataformas internas.
Noções Básicas de gRPC apresenta uma configuração executável; páginas irmãs cobrem design de esquema, streaming, interceptadores, erros, gateways e operações.
.proto definem serviços e mensagens, geradores de código emitem APIs Go tipadas e HTTP/2 carrega frames protobuf com prefixo de comprimento entre processos.curl; balanceadores de carga devem entender streams HTTP/2 de longa duração; regras de evolução de proto restringem alterações de esquema.Pense em gRPC como "funções pela rede".
Você declara um service em um arquivo .proto:
service Inventory {
rpc GetStock(GetStockRequest) returns (GetStockResponse);
}protoc com protoc-gen-go e protoc-gen-go-grpc emite interfaces Go como InventoryServer e stubs de cliente.
O servidor implementa a interface; o cliente chama client.GetStock(ctx, req).
Por baixo dos panos, cada chamada se torna um stream HTTP/2 carregando mensagens protobuf codificadas de requisição e resposta.
Diferente do REST, o caminho e o verbo são fixos pelo nome do RPC - você não projeta URLs por endpoint.
Unary RPCs são requisição-resposta, como uma chamada de função.
Server streaming envia muitas respostas para uma requisição (logs de cauda, resultados de busca).
Client streaming envia muitas requisições antes de uma resposta (ingestão em massa).
Bidirectional streaming mantém ambos os lados abertos (chat, replicação).
Metadados (cabeçalhos chave-valor) viajam fora do corpo da mensagem para tokens de autenticação, IDs de trace e dicas de tenência.
Um servidor Go típico registra implementações em um grpc.Server, escuta em TCP e serve HTTP/2:
Stub do cliente Servidor
│ │
│── stream HTTP/2 ───────►│ cadeia de interceptadores
│ (frames protobuf) │ │
│ │ método handler
│◄── status + mensagem ────│
Prazos viajam em context.Context.
Quando um cliente define context.WithTimeout, o servidor observa ctx.Done() e deve parar o trabalho.
Status retorna como um código gRPC (codes.NotFound, codes.InvalidArgument, …) mais uma mensagem e protobufs de detalhes opcionais para erros estruturados.
A pilha Go usa controle de fluxo HTTP/2 para que um stream massivo não prive outros na mesma conexão.
Configurações de keepalive são importantes para NATs e balanceadores de carga L4 que silenciosamente descartam TCP ocioso.
Ganhos de desempenho em relação ao JSON REST vêm de payloads menores, sem cabeçalhos HTTP repetidos por chamada (HPACK), e compressão gzip opcional para mensagens grandes.
A profilagem ainda importa: reflexão, merges de protobuf com alta alocação e cadeias de interceptadores adicionam sobrecarga.
| Abordagem | Força | Fraqueza | Melhor Ajuste |
|---|---|---|---|
| gRPC + protobuf | Contratos fortes, wire binário rápido | Requer pipeline de codegen | Microsserviços internos |
| REST + JSON | Ferramentas universais, depuração fácil | Tipagem fraca, payloads maiores | APIs HTTP públicas, navegadores |
| gRPC-Gateway | Um proto, clientes JSON | Salto extra, limites de mapeamento | Camadas Mobile/BFF |
| Connect/gRPC-Web | Variantes amigáveis ao navegador | Fragmentação do ecossistema | SPA falando com backends gRPC |
| Filas de mensagens | Assíncrono desacoplado | Latência alta, complexidade de ordenação | Eventos fire-and-forget |
No Kubernetes, Serviços headless ou proxies L7 (Envoy, Linkerd, Istio) roteiam gRPC por autoridade HTTP/2 e :path.
Balanceadores L4 que rotacionam TCP por requisição quebram o streaming, a menos que sejam cientes de gRPC.
mTLS e metadados JWT são padrões comuns; interceptadores centralizam a autenticação antes que os handlers sejam executados.
Handlers de estatísticas gRPC do OpenTelemetry emitem spans por RPC; emparelhe com propagação de metadados (traceparent).
Versionamento de proto (v1, v2 pacotes) permite que frotas migrem sem dias de bandeira.
Alterações que quebram compatibilidade (renumerar campos, alterar tipos) são perigos de implantação - trate .proto como migrações de banco de dados.
Os ecossistemas controller-runtime e de operadores expõem cada vez mais gRPC ao lado de REST para APIs de admissão e extensão.
Para bordas públicas, equipes utilizam grpc-gateway ou camadas BFF que falam JSON enquanto os serviços principais permanecem nativos de protobuf.
Monitore GOMAXPROCS, dimensionamento do pool de conexões e streams concorrentes máximos quando um cliente se expande para milhares de backends.
io.EOF e trailers de erro.Contratos de API fortes via protobuf, streaming de primeira classe e multiplexação eficiente HTTP/2.
REST continua sendo melhor para cache HTTP ad hoc e APIs públicas focadas em navegador.
Handlers gRPC implementam interfaces geradas, não http.HandlerFunc.
Você pode montar gRPC e REST em portas diferentes ou usar gateways para expor ambos.
Adicione campos com novos números; nunca reutilize números.
Publique novos pacotes (v2) para alterações incompatíveis e execute ambos durante a migração.
Em context.Context criado pelo cliente.
Servidores devem respeitar ctx.Done() e retornar codes.Canceled ou codes.DeadlineExceeded.
O IDL canônico do gRPC é protobuf.
Outros serializadores existem em outros ecossistemas; pilhas de produção Go assumem protobuf.
Registre códigos de status, habilite o log de depuração gRPC e use grpcurl ou BloomRPC contra servidores habilitados para reflexão.
Detalhes de erro estruturados superam mensagens de texto simples.
Quando o servidor produz uma sequência ilimitada, o cliente envia chunks, ou ambos os lados precisam de escritas concorrentes.
Unary permanece mais simples para CRUD.
Não - filas desacoplam produtores e consumidores no tempo.
gRPC é adequado para requisição-resposta síncrona e streams controlados entre pares conhecidos.
Conexões HTTP/2 de longa duração e streams bidi exigem roteamento ciente de conexão ou configurações de service mesh sem proxy.
gRPC fica sobre HTTP/2, mas não sobre padrões ServeMux.
Muitas equipes executam chi/gin/echo para HTTP público e gRPC para RPC interno em listeners separados.
Versões da Pilha: Esta página foi escrita para Go 1.26.x (padrão GC Green Tea, modernizadores go fix - verifique o patch na compilação), chi (latest - verifique na compilação), gin (latest - verifique na compilação), echo (latest - verifique na compilação), google.golang.org/grpc (latest - verifique na compilação), sigs.k8s.io/controller-runtime (latest - verifique na compilação), kubebuilder (latest - verifique na compilação), tinygo (latest - verifique os alvos de placa na compilação), wazero (latest - verifique na compilação) e golangci-lint (latest - verifique o conjunto de linters na compilação).
Revisado por Chris St. John·Última atualização: 19 de jul. de 2026