Noções Básicas de Tratamento de Erros

10 exemplos para você começar com Tratamento de Erros - 7 básicos e 3 intermediários.

Pré-requisitos

• Instale o Go 1.26.x ou posterior em go.dev/dl.
• Crie um módulo: mkdir errdemo && cd errdemo && go mod init example.com/errdemo.
• Salve os trechos como main.go e execute com go run ..

Exemplos Básicos

1. A interface error e a verificação de nil

Todo caminho de falha começa com a verificação do segundo valor de retorno.

package main
 
import (
	"fmt"
	"os"
)
 
func main() {
	f, err := os.Open("missing.txt")
	if err != nil {
		fmt.Println("falha ao abrir:", err)
		return
	}
	defer f.Close()
}

• Funções que podem falhar retornam (T, error); um error não-nil significa falha.
• Quando err != nil, trate o resultado principal como inválido, a menos que documentado de outra forma.
• Um erro nil significa sucesso.

Relacionado: Erros como Valores: A Filosofia de Erros do Go - por que o Go usa valores, não exceções

2. Retornando erros de suas próprias funções

Propague falhas retornando error para o chamador.

package main
 
import (
	"errors"
	"fmt"
)
 
func parsePort(s string) (int, error) {
	if s == "" {
		return 0, errors.New("porta é obrigatória")
	}
	return 8080, nil // simplificado
}
 
func main() {
	if _, err := parsePort(""); err != nil {
		fmt.Println(err)
	}
}

• Use errors.New para mensagens estáticas sem formatação.
• Retorne o valor zero para T junto com o erro.
• Os chamadores decidem se devem envolver, registrar ou abortar.

Relacionado: Erros Sentinela e errors.Is - variáveis de erro em nível de pacote

3. fmt.Errorf para erros formatados

Adicione detalhes dinâmicos quando a mensagem depende de valores.

package main
 
import (
	"fmt"
)
 
func loadUser(id int) error {
	if id < 1 {
		return fmt.Errorf("id de usuário inválido %d", id)
	}
	return nil
}
 
func main() {
	fmt.Println(loadUser(-1))
}

• fmt.Errorf é como fmt.Sprintf, mas retorna um error.
• Prefira %w ao envolver um erro existente (abordado nos exemplos intermediários).
• Mantenha as mensagens acionáveis: o que falhou e com qual entrada.

Relacionado: Envolvendo Erros com %w & errors.As - %w e cadeias de unwrap

4. Retorno antecipado em caso de erro

Evite aninhamentos profundos retornando imediatamente após uma falha.

package main
 
import (
	"fmt"
	"os"
)
 
func readSize(path string) (int64, error) {
	info, err := os.Stat(path)
	if err != nil {
		return 0, err
	}
	return info.Size(), nil
}
 
func main() {
	size, err := readSize("go.mod")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println("bytes:", size)
}

• Verifique err antes de usar o valor de sucesso.
• Propague com return zero, err dentro de funções auxiliares.
• O fluxo de controle plano é mais fácil de ler do que if err == nil aninhados.

5. Erro sentinela com errors.Is

Compare erros estáveis em nível de pacote através de cadeias de envolvimento.

package main
 
import (
	"errors"
	"fmt"
	"io"
	"os"
)
 
func main() {
	_, err := os.Open("nope.txt")
	if errors.Is(err, os.ErrNotExist) {
		fmt.Println("arquivo não encontrado")
		return
	}
	if errors.Is(err, io.EOF) {
		fmt.Println("EOF inesperado")
	}
}

• errors.Is percorre cadeias de unwrap; err == os.ErrNotExist falha após o envolvimento.
• A biblioteca padrão exporta sentinelas como os.ErrNotExist e io.EOF.
• Defina os seus próprios com var ErrThing = errors.New("coisa").

Relacionado: Erros Sentinela e errors.Is - regras de design de sentinelas

6. defer ainda é executado em caminhos de erro

Limpe recursos mesmo quando você retorna antecipadamente.

package main
 
import (
	"fmt"
	"os"
)
 
func copyMeta(path string) error {
	f, err := os.Open(path)
	if err != nil {
		return err
	}
	defer f.Close()
	// ler metadados...
	return nil
}
 
func main() {
	fmt.Println(copyMeta("go.mod"))
}

• Registre defer f.Close() imediatamente após uma abertura bem-sucedida.
• Chamadas adiadas são executadas quando a função sai, incluindo em retornos de erro.
• Não use defer antes de verificar err da operação que produziu f.

7. Registrar ou retornar, não ambos cegamente

Escolha uma ação principal por camada, a menos que esteja adicionando contexto distinto.

package main
 
import (
	"fmt"
	"log"
	"os"
)
 
func main() {
	data, err := os.ReadFile("config.yaml")
	if err != nil {
		log.Printf("ler configuração: %v", err)
		return
	}
	fmt.Printf("carregado %d bytes\n", len(data))
}

• Bibliotecas retornam erros; main ou handlers geralmente registram e saem ou respondem.
• O registro duplicado em todas as camadas cria linhas de log barulhentas e correlacionadas.
• Envolva antes de retornar quando a camada superior precisar de contexto.

Relacionado: Melhores Práticas de Tratamento de Erros - responsabilidades de bibliotecas vs. aplicações

Exemplos Intermediários

8. Envolvendo erros com %w

Preserve a causa raiz enquanto adiciona contexto em cada camada.

package main
 
import (
	"fmt"
	"os"
)
 
func readConfig(path string) error {
	_, err := os.ReadFile(path)
	if err != nil {
		return fmt.Errorf("ler configuração %q: %w", path, err)
	}
	return nil
}
 
func main() {
	err := readConfig("missing.yaml")
	fmt.Println(err)
	fmt.Println(os.IsNotExist(err)) // true através da cadeia de envolvimento
}

• %w armazena o erro envolvido para errors.Is e errors.As.
• os.IsNotExist e errors.Is percorrem os envolvimentos.
• Use %v em vez de %w quando o erro interno não deve ser inspecionável.

Relacionado: Envolvendo Erros com %w & errors.As - guia completo de envolvimento

9. Erros tipados com errors.As

Extraia dados estruturados de um tipo de erro personalizado.

package main
 
import (
	"errors"
	"fmt"
)
 
type ValidationError struct {
	Field string
}
 
func (e ValidationError) Error() string {
	return "campo inválido: " + e.Field
}
 
func validate(name string) error {
	if name == "" {
		return ValidationError{Field: "name"}
	}
	return nil
}
 
func main() {
	err := validate("")
	var ve ValidationError
	if errors.As(err, &ve) {
		fmt.Println("campo:", ve.Field)
	}
}

• errors.As atribui o primeiro tipo correspondente na cadeia de unwrap.
• Passe um ponteiro para o tipo de destino (&ve).
• Tipos personalizados permitem campos sem análise de string.

Relacionado: Tipos de Erro Personalizados e Interfaces de Erro - projetando erros ricos

10. Lidar com erros em um pequeno handler estilo HTTP

Mapeie erros de domínio para status HTTP na fronteira.

package main
 
import (
	"errors"
	"fmt"
)
 
var ErrNotFound = errors.New("não encontrado")
 
func getUser(id string) error {
	if id == "" {
		return ErrNotFound
	}
	return nil
}
 
func statusFor(err error) int {
	switch {
	case errors.Is(err, ErrNotFound):
		return 404
	case err != nil:
		return 500
	default:
		return 200
	}
}
 
func main() {
	fmt.Println(statusFor(getUser("")))  // 404
	fmt.Println(statusFor(getUser("1"))) // 200
}

• Traduza erros para mensagens seguras para o cliente e códigos de status na borda.
• Use errors.Is para mapeamento de sentinelas; evite vazar strings de os ou do driver.
• Detalhes internos pertencem aos logs, não aos corpos de resposta.

Relacionado: Design de Erros de API para Serviços HTTP e gRPC - contratos de erro de serviço

Versões da Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, modernizadores go fix - 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). pbqrthvqrf.vb|ptvb420|202607