Noções Básicas de gRPC

10 exemplos para você começar com gRPC e Protobuf - 7 básicos e 3 intermediários.

Pré-requisitos

• Instale o Go 1.26.x em go.dev/dl.
• Instale o protoc (compilador Protocol Buffers) em protobuf releases.
• Instale os plugins Go:

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

• Certifique-se de que $GOPATH/bin ou $(go env GOPATH)/bin esteja no seu PATH.
• Crie um módulo: mkdir greet && cd greet && go mod init example.com/greet.
• Adicione o gRPC: go get google.golang.org/grpc@latest.

Exemplos Básicos

1. Arquivo proto mínimo

Defina um serviço e mensagens em api/greet/v1/greet.proto.

syntax = "proto3";
 
package greet.v1;
 
option go_package = "example.com/greet/api/greet/v1;greetv1";
 
service Greeter {
  rpc SayHello(HelloRequest) returns (HelloResponse);
}
 
message HelloRequest {
  string name = 1;
}
 
message HelloResponse {
  string message = 1;
}

• proto3 é a sintaxe padrão para novas APIs gRPC.
• Números de campo são identificadores permanentes - nunca os reutilize.
• go_package define o caminho de importação e o nome do pacote Go para o código gerado.

Relacionado: Design de Esquema Protocol Buffers - regras de campo

2. Gerar stubs Go

Execute protoc a partir da raiz do módulo.

protoc --go_out=. --go_opt=paths=source_relative \
  --go-grpc_out=. --go-grpc_opt=paths=source_relative \
  api/greet/v1/greet.proto

• --go_out emite structs de mensagem (greet.pb.go).
• --go-grpc_out emite interfaces de serviço (greet_grpc.pb.go).
• paths=source_relative mantém os arquivos gerados ao lado do .proto.

Relacionado: gRPC em Go: Contratos, Streaming e Performance - modelo de contrato

3. Implementar a interface do servidor

Incorpore UnimplementedGreeterServer para compatibilidade futura.

package main
 
import (
    "context"
 
    greetv1 "example.com/greet/api/greet/v1"
)
 
type greeterServer struct {
    greetv1.UnimplementedGreeterServer
}
 
func (s *greeterServer) SayHello(ctx context.Context, req *greetv1.HelloRequest) (*greetv1.HelloResponse, error) {
    return &greetv1.HelloResponse{Message: "hello, " + req.GetName()}, nil
}

• Servidores gerados exigem a incorporação de Unimplemented… para que novas RPCs não causem falhas de compilação.
• Use acessadores GetName() - eles tratam mensagens nil com segurança.
• Retorne (nil, err) para falhas; gRPC mapeia erros para códigos de status.

Relacionado: Códigos de Erro gRPC e Mapeamento de Status - retornar erros

4. Iniciar um listener gRPC

Registre o serviço e bloqueie em Serve.

package main
 
import (
    "log"
    "net"
 
    greetv1 "example.com/greet/api/greet/v1"
    "google.golang.org/grpc"
)
 
func main() {
    lis, err := net.Listen("tcp", ":50051")
    if err != nil {
        log.Fatal(err)
    }
    s := grpc.NewServer()
    greetv1.RegisterGreeterServer(s, &greeterServer{})
    log.Println("listening on :50051")
    log.Fatal(s.Serve(lis))
}

• A porta padrão 50051 é convencional para exemplos; use configuração em produção.
• grpc.NewServer() aceita opções de servidor (TLS, interceptadores) abordadas em páginas avançadas.
• Serve bloqueia até que o processo seja encerrado ou GracefulStop seja executado.

5. Estabelecer conexão de cliente

Crie um cliente inseguro para desenvolvimento local.

package main
 
import (
    "log"
 
    greetv1 "example.com/greet/api/greet/v1"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)
 
func main() {
    conn, err := grpc.NewClient("localhost:50051",
        grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()
 
    client := greetv1.NewGreeterClient(conn)
    _ = client // usar no próximo exemplo
}

• grpc.NewClient é a API de dial moderna (substitui padrões Dial obsoletos).
• Sempre Close() as conexões ao desligar para liberar recursos HTTP/2.
• Produção usa credenciais TLS, não insecure.

6. Chamada RPC unária com contexto

Passe um contexto para prazos e cancelamento.

package main
 
import (
    "context"
    "fmt"
    "log"
    "time"
 
    greetv1 "example.com/greet/api/greet/v1"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)
 
func main() {
    conn, err := grpc.NewClient("localhost:50051",
        grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()
 
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
    defer cancel()
 
    client := greetv1.NewGreeterClient(conn)
    resp, err := client.SayHello(ctx, &greetv1.HelloRequest{Name: "world"})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(resp.GetMessage())
}

• O contexto propaga prazos para o servidor automaticamente.
• Erros do lado do cliente envolvem códigos de status gRPC que podem ser inspecionados com status.FromError.
• Timeouts evitam chamadas travadas quando os backends param.

Relacionado: Middleware, Interceptadores e Metadados gRPC - metadados e interceptadores

7. Retornar um erro de status gRPC

Use status.Error para falhas tipadas.

import (
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)
 
func validateName(name string) error {
    if name == "" {
        return status.Error(codes.InvalidArgument, "name is required")
    }
    return nil
}

• codes.InvalidArgument sinaliza erros do cliente; use codes.Internal para bugs do servidor.
• fmt.Errorf simples se torna Unknown, a menos que você anexe o status com status.Errorf.
• Clientes devem ramificar em status.Code(err), não em correspondência de strings.

Relacionado: Códigos de Erro gRPC e Mapeamento de Status - mapeamento de código

Exemplos Intermediários

8. Reflexão do servidor para grpcurl

Habilite a reflexão para introspectar serviços sem arquivos proto no disco.

import "google.golang.org/grpc/reflection"
 
func main() {
    lis, _ := net.Listen("tcp", ":50051")
    s := grpc.NewServer()
    greetv1.RegisterGreeterServer(s, &greeterServer{})
    reflection.Register(s)
    s.Serve(lis)
}

• grpcurl -plaintext localhost:50051 list descobre serviços em tempo de execução.
• Desabilite a reflexão em produção, a menos que a política permita - ela expõe a superfície da sua API.
• Útil para depuração em staging e testes de fumaça de contrato.

9. Desligamento gracioso

Pare de aceitar novas RPCs enquanto finaliza o trabalho em andamento.

import (
    "os"
    "os/signal"
    "syscall"
    "time"
)
 
func serveWithGracefulStop(s *grpc.Server, lis net.Listener) {
    go func() {
        if err := s.Serve(lis); err != nil {
            log.Fatal(err)
        }
    }()
 
    quit := make(chan os.Signal, 1)
    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
    <-quit
 
    stopped := make(chan struct{})
    go func() {
        s.GracefulStop()
        close(stopped)
    }()
 
    select {
    case <-stopped:
    case <-time.After(10 * time.Second):
        s.Stop()
    }
}

• GracefulStop espera por RPCs ativas; Stop força o encerramento imediato.
• Emparelhe com hooks preStop do Kubernetes e terminationGracePeriodSeconds encurtados.
• Clientes devem tentar novamente Unavailable durante implantações contínuas.

10. Serviço de verificação de saúde

Registre o protocolo de saúde gRPC padrão para sondas.

import (
    "google.golang.org/grpc/health"
    healthpb "google.golang.org/grpc/health/grpc_health_v1"
)
 
func main() {
    s := grpc.NewServer()
    greetv1.RegisterGreeterServer(s, &greeterServer{})
 
    healthServer := health.NewServer()
    healthpb.RegisterHealthServer(s, healthServer)
    healthServer.SetServingStatus("greet.v1.Greeter", healthpb.HealthCheckResponse_SERVING)
 
    // ... Serve(lis)
}

• Sondas de saúde gRPC do Kubernetes chamam grpc.health.v1.Health/Check.
• Defina NOT_SERVING durante o aquecimento de dependências antes de marcar o pod como pronto.
• O nome do serviço deve corresponder ao que sua configuração de sonda espera.

Relacionado: Melhores Práticas gRPC - prazos, versionamento, K8s

Links Relacionados Externos

• Site Oficial do Go / Documentação - Hub principal de documentação.
• Go by Example - Exemplos de código práticos anotados.
• pkg.go.dev - Site oficial de documentação e descoberta de pacotes.
• Learning Go (2ª Edição, O'Reilly) - Jon Bodner na O'Reilly.
• The Go Programming Language (Brochura) - Donovan & Kernighan em brochura.

Versões de Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, modernizadores go fix - verifique o patch na compilação), chi (última - verifique na compilação), gin (última - verifique na compilação), echo (última - verifique na compilação), google.golang.org/grpc (última - verifique na compilação), sigs.k8s.io/controller-runtime (última - verifique na compilação), kubebuilder (última - verifique na compilação), tinygo (última - verifique os alvos de placa na compilação), wazero (última - verifique na compilação) e golangci-lint (última - verifique o conjunto de linters na compilação).