Tratamento de erros em Go: encapsulamento com %w, errors.Is e errors.As

O que é

Em Go, um erro é qualquer valor cujo tipo tenha um método Error() string; as funções o retornam como último resultado e nil significa sucesso. Não há exceções: o FAQ de Go explica o design como retorno de múltiplos valores para falhas comuns, mais panic/recover para condições realmente excepcionais. Desde o Go 1.13, os erros formam uma cadeia. fmt.Errorf("open config: %w", err) retorna um erro que implementa Unwrap() error, e a documentação do pacote errors descreve como errors.Is e errors.As percorrem essa árvore (primeiro o erro, depois seus filhos, em profundidade): Is compara com um valor-alvo, e As encontra o primeiro erro atribuível a um tipo-alvo e o copia para fora. errors.Join (Go 1.20) e fmt.Errorf com vários verbos %w produzem erros cujo Unwrap retorna []error. O Go 1.26 adiciona o genérico errors.AsType[E](err), que retorna o valor tipado e um booleano.

Por que importa

Quem vem de Python ou JavaScript tem o reflexo de usar try/except em volta de um bloco; em Go, cada ponto de chamada decide. Dois hábitos de linguagens dinâmicas deixam de funcionar aqui: comparar as strings de err.Error(), que mudam sempre que uma camada adiciona contexto, e comparar err == ErrNotFound com ==, o que falha assim que o erro é encapsulado. A documentação afirma que errors.Is(err, fs.ErrExist) é preferível a err == fs.ErrExist justamente por esse motivo.

Como aplicar

• Declare erros sentinela como variáveis de pacote (var ErrNotFound = errors.New("not found")) e erros estruturados como tipos com campos; quem chama faz a verificação com errors.Is ou errors.As.
• Encapsule com %w quando o chamador puder razoavelmente inspecionar a causa e use %v quando a causa for um detalhe de implementação; a orientação do blog de Go é encapsular um erro para expô-lo aos chamadores e não encapsular quando isso exporia detalhes de implementação.
• Adicione contexto uma vez por camada, no formato "what was being done: %w", em minúsculas e sem pontuação final, de modo que as mensagens se leiam como uma cadeia do erro mais externo ao mais interno.
• Trate ou retorne o erro, não ambos: registrar um erro em log e também retorná-lo gera linhas de log duplicadas em todos os níveis.
• Dê a um tipo próprio um método Is(error) bool quando ele deve ser considerado igual a uma sentinela existente; a documentação do pacote descreve esse mecanismo.

Armadilhas

%v quebra a cadeia sem aviso. Encapsular um erro nil cria um erro não nil. Uma função que retorna um ponteiro nil tipado como error retorna uma interface não nil (veja o artigo sobre interfaces). Retornar sql.ErrNoRows com %w a partir de um repositório prende os chamadores ao pacote do banco de dados, que é o próprio exemplo do blog. panic não é um mecanismo geral de tratamento de erros; reserve-o para erros de programação e use recover apenas nas fronteiras de goroutines.