gRPC Golang (gRPC-Go)

Visão Geral

Guia completo para projetar e implementar serviços gRPC de nível de produção em Go. Abrange padronização de contratos com Buf, segurança de camada de transporte via mTLS e observabilidade profunda com interceptores OpenTelemetry.

Use esta habilidade quando

• Projetando comunicação de microsserviços com gRPC em Go.
• Construindo APIs internas de alta performance usando Protobuf.
• Implementando cargas de trabalho de streaming (unidirecional ou bidirecional).
• Padronizando contratos de API usando Protobuf e Buf.
• Configurando mTLS para autenticação de serviço a serviço.

Não use esta habilidade quando

• Construindo APIs públicas puramente REST/HTTP sem requisitos de gRPC.
• Modificando arquivos .proto legados sem a capacidade de introduzir uma nova versão de API (por exemplo, api.v2) ou garantir compatibilidade retroativa.
• Gerenciando roteamento de tráfego de malha de serviço (por exemplo, Istio/Linkerd), que está fora do escopo do código da aplicação.

Guia Passo a Passo

1. Confirmar Contexto Técnico: Identifique a versão do Go, a versão do gRPC-Go e se o projeto usa Buf ou protoc puro.
2. Confirmar Requisitos: Identifique necessidades de mTLS, padrões de carga (unário/streaming), SLOs e limites de tamanho de mensagem.
3. Planejar Esquema: Defina versionamento de pacotes (por exemplo, api.v1), tipos de recursos e mapeamento de erros.
4. Projeto de Segurança: Implemente mTLS para autenticação de serviço a serviço.
5. Observabilidade: Configure interceptores para rastreamento, métricas e logging estruturado.
6. Verificação: Sempre execute verificações de buf lint e de alterações que quebram compatibilidade antes de finalizar a geração de código.

Consulte resources/implementation-playbook.md para padrões detalhados, exemplos de código e anti-padrões.

Exemplos

Exemplo 1: Definindo um Serviço e Mensagem (API v1)

syntax = "proto3";
package api.v1;
option go_package = "github.com/org/repo/gen/api/v1;apiv1";

service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
}

message User {
  string id = 1;
  string name = 2;
}

message GetUserRequest {
  string id = 1;
}

message GetUserResponse {
  User user = 1;
}

Melhores Práticas

• ✅ Faça: Use Buf para padronizar sua toolchain e linting com buf.yaml e buf.gen.yaml.
• ✅ Faça: Sempre use versionamento semântico em caminhos de pacotes (por exemplo, package api.v1).
• ✅ Faça: Imponha mTLS para toda a comunicação interna de serviço a serviço.
• ✅ Faça: Trate ctx.Done() em todos os manipuladores de streaming para evitar vazamentos de recursos.
• ✅ Faça: Mapeie erros de domínio para códigos de status gRPC padrão (por exemplo, codes.NotFound).
• ❌ Não faça: Retorne strings de erro internas brutas ou traces de pilha para clientes gRPC.
• ❌ Não faça: Crie uma nova grpc.ClientConn por requisição; sempre reutilize conexões.

Solução de Problemas

• Erro: Gen Inconsistente: Se o código gerado não corresponder ao esquema, execute buf generate e verifique a opção go_package.
• Erro: Prazo do Contexto: Verifique os timeouts do cliente e certifique-se de que o servidor não está bloqueando infinitamente em manipuladores de streaming.
• Erro: Handshake mTLS: Certifique-se de que o certificado CA está corretamente adicionado ao x509.CertPool em ambos os lados, cliente e servidor.

Limitações

• Não cobre roteamento de tráfego de malha de serviço (configuração Istio/Linkerd).
• Não cobre gRPC-Web ou integração gRPC baseada em navegador.
• Assume Go 1.21+ e gRPC-Go v1.60+; versões mais antigas podem ter APIs diferentes (por exemplo, grpc.Dial vs grpc.NewClient).
• Não cobre configuração de balanceador de carga ciente de gRPC L7 (por exemplo, Envoy, NGINX).
• Não aborda registro de esquema Protobuf ou governança de esquema em larga escala além do lint do Buf.

Recursos

• resources/implementation-playbook.md para padrões detalhados, exemplos de código e anti-padrões.
• Guia de Design de API do Google
• Documentação Buf
• Documentação gRPC-Go
• Instrumentação OpenTelemetry Go

Habilidades Relacionadas

• @golang-pro - Padrões gerais de Go e otimização de performance fora da camada gRPC.
• @go-concurrency-patterns - Gerenciamento avançado do ciclo de vida de goroutines para manipuladores de streaming.
• @api-design-principles - Estratégia de nomenclatura e versionamento de recursos antes de escrever arquivos .proto.
• @docker-expert - Containerização de serviços gRPC e configuração de injeção de certificados TLS via segredos do Docker.