Conceptos básicos de gRPC

10 ejemplos para empezar con gRPC y Protobuf - 7 básicos y 3 intermedios.

Prerrequisitos

• Instala Go 1.26.x desde go.dev/dl.
• Instala protoc (compilador de Protocol Buffers) desde protobuf releases.
• Instala los plugins de Go:

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

• Asegúrate de que $GOPATH/bin o $(go env GOPATH)/bin esté en tu PATH.
• Crea un módulo: mkdir greet && cd greet && go mod init example.com/greet.
• Añade gRPC: go get google.golang.org/grpc@latest.

Ejemplos básicos

1. Archivo proto mínimo

Define un servicio y mensajes en 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 es la sintaxis predeterminada para las nuevas API de gRPC.
• Los números de campo son identificadores permanentes; nunca los reutilices.
• go_package establece la ruta de importación y el nombre del paquete de Go para el código generado.

Relacionado: Diseño de esquemas de Protocol Buffers - reglas de campos

2. Genera stubs de Go

Ejecuta protoc desde la raíz del 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 las estructuras de mensajes (greet.pb.go).
• --go-grpc_out emite las interfaces de servicio (greet_grpc.pb.go).
• paths=source_relative mantiene los archivos generados junto al .proto.

Relacionado: gRPC en Go: Contratos, Streaming y Rendimiento - modelo de contrato

3. Implementa la interfaz del servidor

Incrusta UnimplementedGreeterServer para compatibilidad 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: "hola, " + req.GetName()}, nil
}

• Los servidores generados requieren incrustar Unimplemented… para que las nuevas RPC no rompan las compilaciones.
• Usa los accesores GetName() - manejan mensajes nulos de forma segura.
• Devuelve (nil, err) para fallos; gRPC mapea los errores a códigos de estado.

Relacionado: Códigos de error y mapeo de estado de gRPC - devuelve errores

4. Inicia un listener de gRPC

Registra el servicio y bloquea en 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("escuchando en :50051")
    log.Fatal(s.Serve(lis))
}

• El puerto predeterminado 50051 es convencional para ejemplos; usa configuración en producción.
• grpc.NewServer() acepta opciones de servidor (TLS, interceptores) cubiertas en páginas avanzadas.
• Serve se bloquea hasta que el proceso sale o se ejecuta GracefulStop.

5. Marca una conexión de cliente

Crea un cliente inseguro para desarrollo 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 en el próximo ejemplo
}

• grpc.NewClient es la API de marcado moderna (reemplaza patrones Dial obsoletos).
• Siempre llama a Close() en las conexiones al apagar para liberar recursos HTTP/2.
• La producción usa credenciales TLS, no insecure.

6. Llamada RPC unaria con contexto

Pasa un contexto para plazos y cancelación.

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())
}

• El contexto propaga los plazos al servidor automáticamente.
• Los errores del lado del cliente envuelven códigos de estado gRPC que se pueden inspeccionar con status.FromError.
• Los tiempos de espera evitan llamadas colgadas cuando los backends se bloquean.

Relacionado: Middleware, Interceptores y Metadatos de gRPC - metadatos e interceptores

7. Devuelve un error de estado gRPC

Usa status.Error para fallos tipificados.

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

• codes.InvalidArgument señala errores del cliente; usa codes.Internal para errores del servidor.
• fmt.Errorf simple se convierte en Unknown a menos que adjuntes el estado con status.Errorf.
• Los clientes deben ramificarse según status.Code(err), no por coincidencia de cadenas.

Relacionado: Códigos de error y mapeo de estado de gRPC - mapeo de códigos

Ejemplos intermedios

8. Reflexión del servidor para grpcurl

Habilita la reflexión para introspeccionar servicios sin archivos proto en 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 descubre servicios en tiempo de ejecución.
• Deshabilita la reflexión en producción a menos que la política lo permita; expone la superficie de tu API.
• Útil para depuración en staging y pruebas de contrato.

9. Apagado elegante

Deja de aceptar RPCs nuevas mientras terminas el trabajo en curso.

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 las RPCs activas; Stop fuerza la finalización inmediata.
• Empareja con hooks preStop de Kubernetes y terminationGracePeriodSeconds acortados.
• Los clientes deben reintentar Unavailable durante despliegues continuos.

10. Servicio de verificación de estado

Registra el protocolo de salud estándar de gRPC para sondeos.

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)
}

• Los sondeos de salud gRPC de Kubernetes llaman a grpc.health.v1.Health/Check.
• Establece NOT_SERVING durante la inicialización de dependencias antes de marcar el pod como listo.
• El nombre del servicio debe coincidir con lo que espera la configuración de tu sondeo.

Relacionado: Mejores prácticas de gRPC - plazos, versionado, K8s

Enlaces externos relacionados

• Sitio web oficial de Go / Documentación - Centro de documentación principal.
• Go by Example - Ejemplos de código prácticos anotados.
• pkg.go.dev - Sitio oficial de documentación y descubrimiento de paquetes.
• Learning Go (2ª Edición, O'Reilly) - Jon Bodner en O'Reilly.
• The Go Programming Language (Tapa blanda) - Donovan & Kernighan en tapa blanda.

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, modernizadores go fix - verifica el parche en la compilación), chi (última versión - verifica en la compilación), gin (última versión - verifica en la compilación), echo (última versión - verifica en la compilación), google.golang.org/grpc (última versión - verifica en la compilación), sigs.k8s.io/controller-runtime (última versión - verifica en la compilación), kubebuilder (última versión - verifica en la compilación), tinygo (última versión - verifica los objetivos de la placa en la compilación), wazero (última versión - verifica en la compilación) y golangci-lint (última versión - verifica el conjunto de linters en la compilación).