Sentinel Errors & errors.Is

Erros sentinela são variáveis em nível de pacote que representam uma identidade de falha fixa.

Os chamadores os reconhecem com errors.Is em vez de correspondência de strings ou verificações == frágeis que falham assim que os erros são encapsulados.

Resumo

Erros sentinela dão à sua API um pequeno vocabulário de resultados estáveis: não encontrado, já existe, cancelado, entrada inválida.

O Go 1.13 adicionou errors.Is para que essas identidades sobrevivam às cadeias de encapsulamento fmt.Errorf("...: %w", err).

Use sentinelas para contratos entre pacotes; opte por tipos customizados quando os chamadores precisarem de campos estruturados.

Receita

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

var ErrNotFound = errors.New("not found")
 
func Find(id string) (Item, error) {
    if id == "" {
        return Item{}, ErrNotFound
    }
    return Item{}, nil
}
 
if errors.Is(err, ErrNotFound) {
    // lida com recurso ausente
}

Quando usar isso:

• Um modo de falha faz parte do seu contrato de API público
• Os chamadores precisam de um branch booleano sem analisar strings
• O erro não tem campos extras além de sua identidade
• Padrões da biblioteca padrão (io.EOF, os.ErrNotExist) se aplicam ao seu domínio

Exemplo de Trabalho

package main
 
import (
	"errors"
	"fmt"
	"os"
)
 
var ErrUserNotFound = errors.New("user not found")
 
func loadUser(path string) error {
	_, err := os.ReadFile(path)
	if err != nil {
		if os.IsNotExist(err) {
			return fmt.Errorf("load user %q: %w", path, ErrUserNotFound)
		}
		return fmt.Errorf("load user %q: %w", path, err)
	}
	return nil
}
 
func main() {
	err := loadUser("alice.json")
	switch {
	case errors.Is(err, ErrUserNotFound):
		fmt.Println("client: 404 user missing")
	case err != nil:
		fmt.Println("client: 500", err)
	default:
		fmt.Println("ok")
	}
}

O que isso demonstra:

• Um sentinela de domínio (ErrUserNotFound) é mapeado para um resultado do cliente
• fmt.Errorf com %w preserva sentinelas os e de domínio na cadeia
• errors.Is encontra ErrUserNotFound através dos wraps
• os.IsNotExist é um wrapper de conveniência em torno de errors.Is(err, os.ErrNotExist)

Mergulho Profundo

Como Funciona

• errors.New retorna um valor de erro opaco com uma identidade fixa.
• Encapsular com %w implementa Unwrap() error, ligando erros externos e internos.
• errors.Is(err, target) retorna true se err == target ou qualquer etapa de unwrap corresponder.
• err == ErrX direto falha quando um wrapper está entre o chamador e o sentinela.

Nomenclatura e Posicionamento de Sentinelas

io.EOF e Fluxo de Controle

io.EOF sinaliza o fim do stream durante Read, não necessariamente uma falha catastrófica.

Faça um loop até errors.Is(err, io.EOF) após processar o último chunk.

Notas Go

// Ruim: falha após o wrap
if err == ErrNotFound { ... }
 
// Bom
if errors.Is(err, ErrNotFound) { ... }
 
// Também bom para helpers da stdlib
if os.IsNotExist(err) { ... }

Armadilhas

• Usar == após encapsular - Erros encapsulados nunca são iguais ao sentinela. Correção: Use errors.Is.
• Muitos sentinelas - Dezenas de variáveis ErrX se tornam difíceis de documentar. Correção: Agrupe falhas relacionadas em um tipo customizado ou enum de código de erro.
• Exportar sentinelas internos - Chamadores dependem de valores que você não pode evoluir. Correção: Exporte apenas erros de contrato estáveis; mantenha helpers não exportados.
• Correspondência de strings com strings.Contains - Frágil através de wraps e mudanças de redação. Correção: errors.Is ou errors.As.
• Retornar ponteiros nil tipados - return (*MyError)(nil) faz err != nil ser true. Correção: return nil ou var err error = nil.
• Tratar todo EOF como falha - Loops de leitura esperam EOF. Correção: Ramifique em errors.Is(err, io.EOF) separadamente de erros reais.

Alternativas

FAQs

Relacionados

• Errors as Values: Go's Error Philosophy - por que erros explícitos existem
• Error Wrapping with %w & errors.As - cadeias e inspeção tipada
• Custom Error Types & Error Interfaces - quando sentinelas não são suficientes
• API Error Design for HTTP and gRPC Services - mapeamento para códigos de status
• Error Handling Best Practices - convenções da equipe

Versões da 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 (latest - verifique na compilação), gin (latest - verifique na compilação), echo (latest - verifique na compilação), google.golang.org/grpc (latest - verifique na compilação), sigs.k8s.io/controller-runtime (latest - verifique na compilação), kubebuilder (latest - verifique na compilação), tinygo (latest - verifique os alvos de placa na compilação), wazero (latest - verifique na compilação) e golangci-lint (latest - verifique o conjunto de linters na compilação).