Envolvimento de Erros com %w & errors.As

O envolvimento adiciona contexto a falhas, preservando a causa original para inspeção.

fmt.Errorf com %w constrói uma cadeia de unwrap; errors.Is e errors.As percorrem essa cadeia para que os chamadores reconheçam sentinelas e tipos personalizados através de camadas intermediárias.

Resumo

O Go 1.13 padronizou o envolvimento de erros: cada camada adiciona contexto de operação (ler configuração, conectar ao banco) sem destruir o os.ErrNotExist raiz ou seu tipo de domínio.

errors.As extrai dados tipados quando uma sentinela é muito genérica.

Use %v quando o erro interno não deve participar de Is/As.

Receita

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

if err != nil {
    return fmt.Errorf("buscar usuário %q: %w", id, err)
}
 
var pathErr *os.PathError
if errors.As(err, &pathErr) {
    log.Println("caminho:", pathErr.Path)
}
 
if errors.Is(err, os.ErrNotExist) {
    return ErrNotFound
}

Quando usar isso:

• Cada camada entre I/O e o manipulador adiciona contexto distinto
• Chamadores precisam distinguir timeout de não encontrado através de envolvimentos
• Você precisa de campos de um tipo de erro personalizado no meio da cadeia
• Etapas paralelas produzem múltiplos erros para agregar com errors.Join

Exemplo de Trabalho

package main
 
import (
	"errors"
	"fmt"
	"net"
	"os"
)
 
type OpError struct {
	Op string
}
 
func (e OpError) Error() string {
	return fmt.Sprintf("%s falhou", e.Op)
}
 
func readDB(path string) error {
	_, err := os.ReadFile(path)
	if err != nil {
		return OpError{Op: "leitura"}
	}
	return nil
}
 
func loadUser(path string) error {
	if err := readDB(path); err != nil {
		return fmt.Errorf("carregar usuário de %q: %w", path, err)
	}
	return nil
}
 
func main() {
	err := loadUser("missing.db")
	var op OpError
	if errors.As(err, &op) {
		fmt.Println("operação:", op.Op)
	}
	fmt.Println("não existe:", errors.Is(err, os.ErrNotExist))
	fmt.Println("timeout de rede:", errors.Is(err, net.ErrClosed))
}

O que isso demonstra:

• O tipo personalizado OpError é alcançável através de um envolvimento fmt.Errorf
• errors.As requer um ponteiro para o tipo de destino
• errors.Is ainda encontra os.ErrNotExist sob OpError se a cadeia o incluir
• Mensagens de string são para humanos; Is/As são para lógica de programa

Mergulho Profundo

Como Funciona

• %w cria um invólucro que implementa Unwrap() error.
• errors.Unwrap(err) retorna um nível; Is/As iteram até encontrar uma correspondência ou nil.
• Apenas um %w por chamada fmt.Errorf é permitido.
• errors.Join(errs...) (Go 1.20+) retorna um erro que pode ser desenvovido para múltiplos valores; Is/As verificam cada um.

%w vs %v

Regras do errors.As

• O segundo argumento deve ser um ponteiro para um tipo que implementa error ou um ponteiro para um campo de struct.
• Retorna true e atribui o primeiro valor correspondente na cadeia.
• Prefira receptores de valor em tipos de erro, a menos que você precise de comportamento específico de ponteiro.

Notas do Go

// Extração tipada
var pe *os.PathError
if errors.As(err, &pe) {
    _ = pe.Path
}
 
// Unwrap manual de um nível (raro)
inner := errors.Unwrap(err)

Armadilhas

• Múltiplos %w em um Errorf - Erro de compilação. Correção: Envolva uma vez por chamada; encadeie com fmt.Errorf aninhado.
• Passar não-ponteiro para errors.As - Sempre falha. Correção: var target MyErr; errors.As(err, &target).
• Receptor de ponteiro vs valor em tipos de erro - errors.As para *MyErr vs MyErr deve corresponder ao que você retorna. Correção: Seja consistente; documente o tipo de retorno do construtor.
• Usar As para sentinelas - errors.Is é mais simples para var ErrX. Correção: Reserve As para tipos com campos.
• Vazamento de segredos em mensagens de envolvimento - %w mais logs verbosos podem expor tokens. Correção: Limpe mensagens; use %v em fronteiras públicas.
• Assumir que o texto de Error() é estável - Chamadores não devem analisar strings. Correção: Exporte sentinelas ou tipos para verificações programáticas.

Alternativas

FAQs

Relacionados

• Erros Sentinela & errors.Is - comparação de sentinelas através de cadeias
• Tipos de Erro Personalizados & Interfaces de Erro - projetando tipos para As
• Rastros de Pilha com runtime/debug - anexa diagnósticos a erros envolvidos
• Tratamento de Erros em Código Concorrente - juntando erros de goroutines
• Melhores Práticas de Tratamento de Erros - política de envolvimento para equipes

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