Resumo dos Destaques de Tratamento de Erros

Cada item destacado das 9 páginas desta seção, reunido em uma única página e agrupado pela página de origem.

Erros como Valores: A Filosofia de Erros do Go

• Erros são valores comuns retornados junto com os resultados
• Chamadores lidam com falhas no ponto de uso, não em blocos catch distantes
• O wrapping preserva cadeias de causa sem desenrolamento de pilha oculto
• Bibliotecas expõem contratos de erro mínimos; aplicativos adicionam contexto nas fronteiras
• panic é para bugs de programador, não para falhas esperadas de I/O ou validação

Noções Básicas de Tratamento de Erros

• Funções retornam (T, error) onde um erro nil sinaliza sucesso
• Use fmt.Errorf com %w para encapsular erros preservando cadeias
• Verifique os erros imediatamente e retorne cedo, evitando ifs aninhados
• Use errors.Is para corresponder a erros sentinela através de cadeias de unwrap
• A limpeza adiada é executada em todos os caminhos de código, mesmo com retornos de erro
• Escreva mensagens de erro acionáveis descrevendo o que falhou e por quê

Erros Sentinela e errors.Is

• Sentinelas são valores estáveis var ErrX = errors.New(...)
• errors.Is percorre cadeias de unwrap; == falha após o wrapping
• Exporte apenas erros que fazem parte do seu contrato público
• Prefira poucos sentinelas; use tipos personalizados quando precisar de campos
• io.EOF é fluxo de controle, nem sempre uma falha grave

Encapsulamento de Erros com %w e errors.As

• %w em fmt.Errorf preserva cadeias de unwrap para Is e As
• errors.As encontra o primeiro tipo atribuível na cadeia
• Use %v nas fronteiras quando erros internos devem permanecer ocultos
• errors.Unwrap expõe um nível; Is/As percorrem a cadeia completa
• errors.Join agrega múltiplas falhas de trabalho paralelo

Tipos de Erro Personalizados e Interfaces de Erro

• Tipos struct carregam campos que os chamadores extraem com errors.As
• Mantenha superfícies de erro exportadas pequenas e estáveis
• Interfaces opcionais (Timeout, Temporary) permitem verificações de comportamento
• Receptores de valor evitam bugs de interface nil tipada
• Strings Error() são para humanos; campos são para lógica

Rastros de Pilha com runtime/debug

• debug.Stack captura a pilha da goroutine atual na criação do erro
• Anexe pilhas em camadas de aplicativo, não em bibliotecas de baixo nível
• Pilhas são para operadores, não para clientes de API
• Emparelhe com slog ou logging estruturado na fronteira
• runtime/debug é leve em comparação com rastros de panic completos

Tratamento de Erros em Código Concorrente

• Goroutines não podem retornar erros para seus pais; use canais ou errgroup
• errgroup cancela o trabalho dos irmãos na primeira falha
• Use select em errCh e ctx.Done() para desligamento limpo
• errors.Join agrega múltiplas falhas de validação
• Nunca ignore erros de goroutines sem um plano de entrega

Design de Erros de API para Serviços HTTP e gRPC

• Erros de domínio permanecem agnósticos ao transporte até o manipulador ou interceptador
• HTTP usa JSON de problema estável; gRPC usa códigos de status e detalhes
• Mapeie com errors.Is e errors.As, não com correspondência de strings
• Nunca vaze detalhes do driver ou da pilha para clientes
• Registre o contexto interno no lado do servidor com IDs de solicitação

Melhores Práticas de Tratamento de Erros

• Bibliotecas retornam erros; aplicativos registram e mapeiam nas fronteiras
• Envolva com %w para contexto; use Is/As para lógica
• Exporte contratos de erro pequenos e estáveis
• Nunca vaze detalhes internos em respostas HTTP ou gRPC
• Teste caminhos de erro com errors.Is e errors.As

Y29kZWd1aWRlcy5pb3xjZ2lvNDg0fDIwMjYwNw==