Melhores Práticas de gRPC

Versionamento de protos, deadlines e balanceamento de carga gRPC em K8s.

Estas regras mantêm contratos estáveis, RPCs observáveis e rollouts seguros, do laptop aos clusters de produção.

Como Usar Esta Lista

• Aplique durante alterações de schema, scaffolding de serviço e revisões de plataforma.
• Execute buf breaking (ou equivalente) em CI antes de mesclar edições de .proto.
• Emparelhe com golangci-lint e testes de integração que se conectam a servidores reais via bufconn.
• Revise quando as plataformas de ingress, mesh ou cliente mudarem.

A - Schema e versionamento

• Nunca reutilize ou renumerem campos protobuf. Reserve tags e nomes excluídos em arquivos .proto.
• Versionem pacotes (v1, v2) para alterações incompatíveis na API. Execute servidores duplos ou RPCs duplos durante janelas de migração.
• Execute a detecção de quebra de alterações em CI contra o branch principal. Bloqueie merges que alteram tipos de campo ou números de wire.
• Mantenha as opções go_package e java_package estáveis. Mover caminhos de importação gerados quebra módulos downstream silenciosamente.
• Use optional ou FieldMask para atualizações parciais. Distinga campos não definidos de valores zero intencionais.

B - Implementação do servidor

• Incorpore Unimplemented<Service>Server em cada struct de serviço. Compatibilidade com versões futuras quando RPCs são adicionados.
• Retorne status.Error com o código padrão mais próximo. Reserve Internal para bugs reais, não falhas de validação.
• Anexe detalhes estruturados (ErrorInfo, BadRequest) para erros legíveis por máquina. Gateways e clientes podem ramificar sem análise de string.
• Respeite o cancelamento do context em handlers longos e loops de stream. Pare o trabalho quando os clientes desconectarem.
• Habilite a reflexão apenas em ambientes de depuração não-produção ou autenticados. A reflexão expõe toda a sua superfície de API.

C - Chamadas de cliente e resiliência

• Defina um deadline ou timeout em cada contexto de cliente. O padrão "sem deadline" fica pendurado para sempre atrás de backends lentos.
• Tente novamente apenas RPCs unários idempotentes em Unavailable com backoff e jitter. Evite tempestades de retentativas durante interrupções.
• Reutilize grpc.ClientConn entre requisições. Conectar por RPC desperdiça handshakes TCP e TLS.
• Feche conexões ao desligar o processo. Libere recursos HTTP/2 de forma limpa junto com GracefulStop em servidores.
• Mapeie códigos retentáveis vs. fatais explicitamente em bibliotecas de cliente. Documente o comportamento para equipes de aplicação.

D - Interceptors, metadados e segurança

• Centralize a validação JWT/mTLS em interceptors unários e de stream. Handlers assumem que a identidade já foi verificada.
• Propague o contexto de trace via metadados (traceparent ou carriers OTel). Emparelhe com handlers otelgrpc para spans.
• Mantenha segredos em metadados ou TLS, não em campos de log protobuf. Redija cabeçalhos de autorização em interceptors de logging.
• Use credenciais TLS em produção para clientes e servidores. Credenciais insecure são apenas para desenvolvimento local.
• Registre interceptors de recuperação de pânico no limite do servidor. Pânicos se tornam Internal com traces de pilha registrados.

E - Streaming e performance

• Use RPCs unários por padrão até que o streaming seja comprovadamente necessário. Operações e balanceadores de carga mais simples.
• Trate io.EOF como fim normal do stream, não sempre como erro. Retorne o status apropriado apenas em caminhos de falha.
• Limite o buffer em memória em streams de cliente e servidor. Processe ou descarte chunks em vez de slices ilimitados.
• Ajuste os tamanhos máximos de mensagem consistentemente em clientes, servidores e gateways. Alinhe os limites de ponta a ponta.
• Configure keepalive para NATs e balanceadores de carga L4 ociosos. Evite quedas silenciosas de TCP em conexões HTTP/2 de longa duração.

F - Kubernetes e operações

• Registre grpc.health.v1 e conecte probes de liveness/readiness. Defina NOT_SERVING até que as dependências estejam aquecidas.
• Use balanceamento ciente de conexão (Serviço headless, mesh ou xDS). Rotação L4 ingênua quebra streams HTTP/2.
• Chame GracefulStop em SIGTERM com um fallback Stop limitado. Corresponda ao terminationGracePeriodSeconds do pod.
• Exponha grpc-gateway ou BFF para clientes JSON em vez de expor gRPC cegamente através de ingress público.
• Documente os passos de depuração do grpcurl para plantão. Inclua cabeçalhos de metadados necessários e endpoints de staging.

FAQs

Relacionados

• gRPC em Go: Contratos, Streaming e Performance - visão geral da seção
• Noções Básicas de gRPC - padrões de configuração
• Design de Schema de Protocol Buffers - regras de evolução
• Middleware, Interceptors e Metadados gRPC - preocupações transversais
• Guia de Trade-off REST vs gRPC - decisões de transporte

Links Externos Relacionados

• pkg.go.dev - Site oficial de documentação e descoberta de pacotes.
• Effective Go - Guia oficial para escrever Go claro e idiomático.
• Go Blog (Oficial) - Anúncios oficiais, mergulhos profundos e notas de release.
• Learning Go (2nd Edition) - Jon Bodner.
• The Go Programming Language (ebook) - Donovan & Kernighan.

Versões da Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - 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).