Resumo dos Destaques do gRPC & Protobuf

Cada item destacado das 9 páginas desta seção, reunido em uma página e agrupado pela página de origem.

gRPC em Go: Contratos, Streaming e Performance

• Esquemas Protobuf são o contrato; tipos Go gerados os impõem em tempo de compilação
• Multiplexação HTTP/2 e framing binário reduzem a latência em comparação com JSON REST
• Streaming unário, do servidor, do cliente e bidirecional mapeiam para quatro formas de RPC
• Prazos e códigos de status propagam falhas através dos limites do serviço
• gRPC brilha no tráfego interno (east-west); navegadores e APIs públicas frequentemente precisam de um gateway

Noções Básicas de gRPC

• Nunca reutilize números de campo proto após atribuídos para evitar quebrar a compatibilidade
• A diretiva go_package controla o caminho de importação e o nome do pacote Go para o código gerado
• Use --go_out e --go-grpc_out separadamente para gerar mensagens e stubs de serviço
• Incorpore Unimplemented em servidores para evitar falhas de compilação ao adicionar novas RPCs
• Use acessadores GetName() para tratamento seguro de mensagens nulas em implementações de servidor
• Chame Close() nas conexões do cliente ao desligar para liberar recursos da conexão HTTP/2

Design de Esquema Protocol Buffers

• Números de campo são permanentes; reutilizar tags antigas em novos contextos quebra a compatibilidade retroativa
• Adicione campos opcionais com novos números; alterar tipos em tags existentes é sempre quebra de compatibilidade
• Renomeie campos com segurança mantendo o número inalterado; o formato de wire depende apenas da tag e do tipo
• Reserve números e nomes de campos excluídos para evitar reutilização acidental em versões futuras
• Decodificadores ignoram campos desconhecidos, tornando a compatibilidade retroativa automática sem atualizações do cliente
• Valores zero de enum devem ser UNSPECIFIED; nunca trate zero como um estado de negócio significativo

RPCs Unárias, de Streaming e Bidirecionais

• Quatro formas de RPC: unária (1-1), stream do servidor (1-N), stream do cliente (N-1), bidirecional (N-N)
• Go modela streams com métodos Send/Recv nos tipos gerados do cliente e do servidor
• O streaming do cliente termina quando Recv retorna io.EOF, o servidor responde com SendAndClose
• Em streaming bidirecional, ambos os lados intercalam Send e Recv, a ordem importa
• Retorne um erro não nulo para abortar a RPC com o trailer de status gRPC
• Passe stream.Context() para downstream para que o desconectamento do cliente cancele o trabalho do produtor

Middleware, Interceptors e Metadados gRPC

• Interceptors centralizam autenticação, logging, tracing e retries antes da execução do handler
• Leia metadados de entrada usando metadata.FromIncomingContext em interceptors de servidor
• Encadeie múltiplos interceptors via grpc.ChainUnaryInterceptor; o primeiro listado é o mais externo
• Rejeite cedo com codes.Unauthenticated antes que os handlers sejam executados para falhar rapidamente
• Anexe metadados de saída no contexto do cliente com metadata.AppendToOutgoingContext
• Metadados binários usam chaves com sufixo -bin, codificados em base64 no wire em algumas ferramentas

Códigos de Erro gRPC e Mapeamento de Status

• Erros cruzam limites como códigos de status, não strings de erro Go; clientes inspecionam códigos
• Servidores retornam status.Error; clientes desempacotam com status.FromError
• Dezesseis códigos padrão cobrem a maioria dos cenários de sistemas distribuídos
• Anexe detalhes estruturados via status.New e WithDetails para campos legíveis por máquina
• Use FailedPrecondition para violações de regras de negócio; NotFound para recursos ausentes
• errors.New simples se torna codes.Unknown, a menos que seja explicitamente convertido para status gRPC

Guia de Comparação REST vs gRPC

• Serviços internos usam gRPC para obter verificações em tempo de compilação e evitar sobrecarga de serialização
• REST nos gateways de borda para tráfego público enquanto os serviços internos permanecem em protobuf
• Exponha REST com OpenAPI para webhooks de parceiros para evitar atrito de compilação de .proto
• Streaming gRPC com multiplexação HTTP/2 supera REST por requisição para telemetria
• Construa um MVP com REST primeiro para validar o encaixe do produto antes de otimizar a eficiência
• Use gRPC mais protobuf para frotas poliglota para habilitar stubs tipados entre linguagens

gRPC Gateway e Transcodificação JSON

• Anote arquivos .proto com google.api.http para gerar automaticamente rotas REST JSON
• O Gateway desserializa JSON para protobuf, invoca o método gRPC, e serializa a resposta de volta
• Um proto gera servidores gRPC Go, rotas REST e documentação OpenAPI
• Habilite credenciais TLS tanto nas conexões gateway-para-backend quanto cliente-para-gateway
• Limitações de streaming do Gateway e cabeçalhos de autenticação personalizados complementam, não substituem, o gRPC nativo
• Modelos de caminho como {name} vinculam-se a campos de mensagem protobuf em requisições transcodificadas

Melhores Práticas de gRPC

• Trate arquivos .proto como migrações de banco de dados com verificações de quebra do buf
• Defina prazos do cliente em cada RPC de saída
• Use interceptors para autenticação, logging e recuperação - não para copiar e colar no handler
• Registre verificações de saúde gRPC para sondas do Kubernetes
• Planeje balanceamento de carga ciente de conexão para streams HTTP/2