Códigos de Erro gRPC e Mapeamento de Status

Erros cruzam limites de processo como códigos de status gRPC, não strings de erro Go.

Clientes devem inspecionar códigos; servidores devem mapear falhas de domínio deliberadamente.

Resumo

google.golang.org/grpc/status envolve um codes.Code, mensagem e protobufs de detalhe opcionais.

Servidores retornam status.Error ou status.Errorf; clientes desempacotam com status.FromError.

Dezesseis códigos padrão cobrem a maioria dos cenários de sistemas distribuídos.

Detalhes estruturados (google.rpc.ErrorInfo, protos personalizados) permitem que UIs e retentativas ajam sobre campos legíveis por máquina.

Tratar erros gRPC como cadeias opacas de fmt.Errorf perde informações em cada salto.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import (
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)
 
func findUser(id string) error {
    if id == "" {
        return status.Error(codes.InvalidArgument, "id required")
    }
    if !exists(id) {
        return status.Error(codes.NotFound, "user not found")
    }
    return nil
}

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

Quando usar isso:

• Retornar falhas de validação (InvalidArgument) versus entidades ausentes (NotFound).
• Sinalizar sobrecarga (ResourceExhausted) ou manutenção (Unavailable) para lógica de retentativa.
• Anexar ErrorInfo com reason e domain para gateways de API.
• Traduzir códigos gRPC para status HTTP em mapeamentos grpc-gateway.

Exemplo de Trabalho

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, "quantity must be positive")
        br := &errdetails.BadRequest{
            FieldViolations: []*errdetails.BadRequest_FieldViolation{
                {Field: "qty", Description: "must be > 0"},
            },
        }
        st, err := st.WithDetails(br)
        if err != nil {
            return status.Error(codes.Internal, "detail attach failed")
        }
        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, "not enough stock").WithDetails(info)
        return st.Err()
    }
    return nil
}
 
func clientHandle(err error) {
    st, ok := status.FromError(err)
    if !ok {
        log.Fatal(err)
    }
    fmt.Println("code:", st.Code(), "msg:", st.Message())
    for _, d := range st.Details() {
        switch info := d.(type) {
        case *errdetails.ErrorInfo:
            fmt.Println("reason:", 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("unknown detail type:", any.GetTypeUrl())
            }
        }
    }
}
 
func inStock(sku string, qty int32) bool { return false }
 
func main() {
    srv := &inventoryServer{}
    err := srv.Reserve(context.Background(), "ABC", 0)
    clientHandle(err)
}

O que isso demonstra:

• status.New mais WithDetails anexa mensagens de detalhe padrão.
• Clientes iteram st.Details() com switch de tipo.
• FailedPrecondition sinaliza violações de regras de negócios distintas de NotFound.
• Validação em nível de campo usa detalhes BadRequest familiares aos clientes JSON grpc-gateway.

Mergulho Profundo

Como Funciona

Em caso de falha, o gRPC envia um protobuf de status nos trailers (cabeçalhos HTTP/2).

Go o expõe como error que satisfaz status.FromError.

Envolver com %w preserva o status se a cadeia de envolvimento ainda expuser um status gRPC.

errors.New simples se torna codes.Unknown a menos que seja convertido.

Mapeamento de Código Comum

Notas Go

// Preserva o status através de camadas 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)
}

• Não retorne codes.Internal para erros de validação previsíveis - clientes não podem remediar.
• Registre traces de pilha no lado do servidor; retorne mensagens genéricas na rede.
• Use status.Convert ao interligar APIs legadas.

Armadilhas

• Correspondência de strings de mensagens de erro - Quebra a localização e refatorações. Correção: compare status.Code(err).
• Retornar panics brutos - Torna-se obscuros erros Internal. Correção: interceptor de recuperação mais mapeamento explícito de status.
• Mapear tudo para Unknown - Tempestades de retentativas e alertas ruins. Correção: escolha o código padrão mais próximo.
• Cargas úteis de detalhes enormes - Trailers excedem limites. Correção: retorne IDs referenciando um endpoint de consulta.
• Perda de detalhes através de gateways - O mapeamento JSON pode descartar tipos desconhecidos. Correção: registre tipos google.rpc na configuração do gateway.
• context.Canceled vs codes.Canceled - Desconexão do cliente pode aparecer de forma diferente. Correção: normalize em bibliotecas de cliente.

Alternativas

FAQs

Relacionados

• Noções Básicas de gRPC - primeiros retornos de status
• Middleware, Interceptores e Metadados gRPC - mapeamento de erros de autenticação
• gRPC Gateway e Transcodificação JSON - mapeamento de status HTTP
• Envolvimento de Erros com %w e errors.As - erros no processo
• Guia de Comparação REST vs gRPC - trade-off de ergonomia de erro

Links Externos Relacionados

• Especificação da Linguagem Go - A referência formal da linguagem.
• Stack Overflow – Tag Go - Perguntas e respostas para programação Go.
• Effective Go - Guia oficial para escrever Go claro e idiomático.
• Concurrency in Go - Katherine Cox-Buday.
• Learning Go (2nd Edition) - Jon Bodner.

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