Códigos de Error y Mapeo de Estado gRPC

Los errores cruzan los límites del proceso como códigos de estado gRPC, no como cadenas de error de Go.

Los clientes deben inspeccionar los códigos; los servidores deben mapear las fallas del dominio deliberadamente.

Resumen

google.golang.org/grpc/status envuelve un codes.Code, un mensaje y protobufs de detalle opcionales.

Los servidores devuelven status.Error o status.Errorf; los clientes desempaquetan con status.FromError.

Dieciséis códigos estándar cubren la mayoría de los escenarios de sistemas distribuidos.

Los detalles estructurados (google.rpc.ErrorInfo, protos personalizados) permiten que las interfaces de usuario y las reintentos actúen sobre campos legibles por máquina.

Tratar los errores gRPC como cadenas opacas de fmt.Errorf pierde información en cada salto.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

import (
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)
 
func findUser(id string) error {
    if id == "" {
        return status.Error(codes.InvalidArgument, "se requiere id")
    }
    if !exists(id) {
        return status.Error(codes.NotFound, "usuario no encontrado")
    }
    return nil
}

// Cliente
st, ok := status.FromError(err)
if ok && st.Code() == codes.NotFound {
    // manejar recurso faltante
}

Cuándo usar esto:

• Devolver fallos de validación (InvalidArgument) frente a entidades faltantes (NotFound).
• Señalar sobrecarga (ResourceExhausted) o mantenimiento (Unavailable) para la lógica de reintento.
• Adjuntar ErrorInfo con reason y domain para gateways de API.
• Traducir códigos gRPC a estados HTTP en mapeos de grpc-gateway.

Ejemplo de Trabajo

package main
 
import (
    "context"
    "fmt"
    "log"
 
    "google.golang.org/genproto/googleapis/rpc/errdetails"
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
    "google.golang.org/protobuf/types/known/anypb"
)
 
type inventoryServer struct{}
 
func (s *inventoryServer) Reserve(ctx context.Context, sku string, qty int32) error {
    if qty <= 0 {
        st := status.New(codes.InvalidArgument, "la cantidad debe ser positiva")
        br := &errdetails.BadRequest{
            FieldViolations: []*errdetails.BadRequest_FieldViolation{
                {Field: "qty", Description: "debe ser > 0"},
            },
        }
        st, err := st.WithDetails(br)
        if err != nil {
            return status.Error(codes.Internal, "falló la adjunción de detalles")
        }
        return st.Err()
    }
    if !inStock(sku, qty) {
        info := &errdetails.ErrorInfo{
            Reason: "INSUFFICIENT_STOCK",
            Domain: "inventory.example.com",
            Metadata: map[string]string{"sku": sku},
        }
        st, _ := status.New(codes.FailedPrecondition, "no hay suficiente stock").WithDetails(info)
        return st.Err()
    }
    return nil
}
 
func clientHandle(err error) {
    st, ok := status.FromError(err)
    if !ok {
        log.Fatal(err)
    }
    fmt.Println("código:", st.Code(), "msg:", st.Message())
    for _, d := range st.Details() {
        switch info := d.(type) {
        case *errdetails.ErrorInfo:
            fmt.Println("razón:", info.GetReason())
        case *errdetails.BadRequest:
            for _, v := range info.GetFieldViolations() {
                fmt.Println(v.GetField(), v.GetDescription())
            }
        default:
            if any, ok := d.(*anypb.Any); ok {
                fmt.Println("tipo de detalle desconocido:", any.GetTypeUrl())
            }
        }
    }
}
 
func inStock(sku string, qty int32) bool { return false }
 
func main() {
    srv := &inventoryServer{}
    err := srv.Reserve(context.Background(), "ABC", 0)
    clientHandle(err)
}

Lo que esto demuestra:

• status.New más WithDetails adjunta mensajes de detalle estándar.
• Los clientes iteran st.Details() con cambios de tipo.
• FailedPrecondition señala violaciones de reglas de negocio distintas de NotFound.
• La validación a nivel de campo usa detalles de BadRequest familiares para los clientes JSON de grpc-gateway.

Análisis Profundo

Cómo Funciona

En caso de fallo, gRPC envía un protobuf de estado en los trailers (cabeceras HTTP/2).

Go lo expone como un error que satisface status.FromError.

El envoltorio con %w preserva el estado si la cadena de envoltorio aún expone un estado gRPC.

Un simple errors.New se convierte en codes.Unknown a menos que se convierta.

Mapeo de Códigos Comunes

Notas de Go

// Preservar el estado a través de capas auxiliares
func wrap(err error, msg string) error {
    if err == nil {
        return nil
    }
    if _, ok := status.FromError(err); ok {
        return fmt.Errorf("%s: %w", msg, err)
    }
    return status.Errorf(codes.Internal, "%s: %v", msg, err)
}

• No devuelvas codes.Internal para errores de validación predecibles; los clientes no pueden remediarlos.
• Registra trazas de pila en el lado del servidor; devuelve mensajes seguros en la red.
• Usa status.Convert al conectar APIs heredadas.

Trampas Comunes

• Coincidencia de cadenas de mensajes de error - Rompe la localización y las refactorizaciones. Solución: compara status.Code(err).
• Devolver panics crudos - Se convierten en oscuros errores Internal. Solución: interceptor de recuperación más mapeo explícito de estado.
• Mapear todo a Unknown - Tormentas de reintentos y alertas incorrectas. Solución: elige el código estándar más cercano.
• Cargas útiles de detalles enormes - Los trailers exceden los límites. Solución: devuelve IDs que hagan referencia a un punto final de búsqueda.
• Pérdida de detalles a través de gateways - El mapeo JSON puede omitir tipos desconocidos. Solución: registra los tipos google.rpc en la configuración del gateway.
• context.Canceled vs codes.Canceled - La desconexión del cliente puede aparecer de manera diferente. Solución: normalizar en las bibliotecas del cliente.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de gRPC - primeras devoluciones de estado
• Middleware, Interceptores y Metadatos de gRPC - mapeo de errores de autenticación
• gRPC Gateway y Transcodificación JSON - mapeo de estado HTTP
• Envoltorio de Errores con %w y errors.As - errores dentro del proceso
• Guía de Compensación de REST vs gRPC - compensación de la ergonomía de errores

Enlaces Externos Relacionados

• Especificación del Lenguaje Go - La referencia formal del lenguaje.
• Stack Overflow – Etiqueta Go - Preguntas y respuestas para programación en Go.
• Effective Go - Guía oficial para escribir Go claro e idiomático.
• Concurrencia en Go - Katherine Cox-Buday.
• Learning Go (2nd Edition) - Jon Bodner.

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