Tipos de Erro Personalizados e Interfaces de Erro

Tipos de erro personalizados anexam dados estruturados a falhas: dicas de status HTTP, nomes de campo, sinalizadores de retentativa e códigos de erro opacos.

Projete-os para que os chamadores usem errors.As sem importar seus internos e para que você possa adicionar campos posteriormente sem quebrar o contrato de error.

Resumo

A interface error requer apenas Error() string.

Tudo além disso é convenção: tipos exportados, interfaces de comportamento opcionais e wrappers não exportados que mantêm sua implementação flexível.

Erros ricos potencializam o mapeamento de API e a observabilidade; hierarquias excessivamente projetadas prejudicam a simplicidade que Go favorece.

Receita

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

type APIError struct {
    Code    string
    Status  int
    Retry   bool
}
 
func (e APIError) Error() string {
    return e.Code
}
 
var err error = APIError{Code: "USER_MISSING", Status: 404}
var api APIError
if errors.As(err, &api) {
    _ = api.Status
}

Quando usar isso:

• Os chamadores precisam de mais do que um booleano sentinela
• Camadas HTTP/gRPC mapeiam erros para status e JSON de problema
• Métricas precisam de rótulos Code estáveis sem analisar strings
• Você deseja interfaces opcionais como Timeout() bool para retentativas

Exemplo de Trabalho

package main
 
import (
	"errors"
	"fmt"
)
 
type ValidationError struct {
	Field   string
	Message string
}
 
func (e ValidationError) Error() string {
	return fmt.Sprintf("validation: %s %s", e.Field, e.Message)
}
 
func (e ValidationError) HTTPStatus() int { return 422 }
 
func validateEmail(email string) error {
	if email == "" {
		return ValidationError{Field: "email", Message: "required"}
	}
	return nil
}
 
type statusCoder interface {
	HTTPStatus() int
}
 
func writeResponse(err error) {
	if err == nil {
		fmt.Println("200 ok")
		return
	}
	var sc statusCoder
	if errors.As(err, &sc) {
		fmt.Printf("%d %v\n", sc.HTTPStatus(), err)
		return
	}
	fmt.Printf("500 %v\n", err)
}
 
func main() {
	writeResponse(validateEmail(""))
}

O que isso demonstra:

• ValidationError é um tipo de valor com campos e uma string Error() estável
• A interface opcional HTTPStatus() permite que os manipuladores mapeiem sem um type switch em cada variante
• errors.As extrai o tipo concreto de cadeias encapsuladas quando você adiciona %w upstream
• Interfaces de comportamento permanecem pequenas (um método) de acordo com os idiomas do Go

Mergulho Profundo

Como Funciona

• Qualquer tipo com Error() string satisfaz error.
• Os chamadores usam errors.As(err, &target) para vincular o primeiro tipo correspondente.
• Encapsular com %w mantém os tipos descobertos através das camadas.
• Struct não exportada + funções construtoras exportadas ocultam campos que você pode alterar.

Diretrizes de Design

Interfaces de Comportamento Opcionais

Bibliotecas e a biblioteca padrão usam pequenas interfaces opcionais verificadas com type assertions ou errors.As:

• interface{ Timeout() bool } - decisões de retentativa
• interface{ Temporary() bool } - obsoleto, mas ainda visto em código mais antigo
• interface{ Unwrap() error } - encapsulamento (também satisfeito por erros fmt %w)

Defina os seus próprios quando vários tipos de erro compartilham comportamento sem uma struct comum.

Notas Go

// Construtor evita vazar o layout da struct
func NewRateLimitError(retryAfter int) error {
    return rateLimitError{retryAfter: retryAfter}
}
 
// Ruim: ponteiro nil tipado como interface de erro
func bad() error {
    var p *APIError
    return p // interface não nil!
}

Armadilhas

• Retornar ponteiro nil tipado - var e *MyErr; return e resulta em error não nil. Correção: Retorne nil ou use tipos de valor.
• Alterar texto de Error() como API - Chamadores podem registrá-lo; não confie na correspondência de subcadeias. Correção: Exporte campos Code para lógica.
• Hierarquias de erro exportadas enormes - Espelha árvores de exceção que Go evita. Correção: Poucos tipos, interfaces opcionais, sentinelas para casos simples.
• Falta de Unwrap em wrappers personalizados - Quebra Is/As através do seu tipo. Correção: Implemente Unwrap() error ou incorpore o erro encapsulado.
• Tags JSON em erros retornados a clientes - Vaza campos internos. Correção: Mapeie para um DTO separado na camada HTTP.
• Receptores de ponteiro inconsistentes - As para MyErr vs *MyErr devem corresponder às devoluções. Correção: Escolha um estilo por família de tipos.

Alternativas

FAQs

Relacionados

• Erros Sentinela e errors.Is - quando a identidade sem campos é suficiente
• Encapsulamento de Erro com %w e errors.As - cadeias em tipos personalizados
• Design de Erro de API para Serviços HTTP e gRPC - corpos de erro voltados para o cliente
• Rastreamentos de Pilha com runtime/debug - pilhas em tipos de erro de diagnóstico
• Melhores Práticas de Tratamento de Erros - regras de exportação e estabilidade

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 (ú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).

Y29kZWd1aWRlcy5pb3xjZ2lvNDUyfDIwMjYwNw==