1. O que é e para que serve

A biblioteca errors é o pacote padrão da linguagem Go que fornece funções básicas para criar, formatar e tratar erros. Diferente de muitas outras linguagens, onde exceções (exceptions) são o mecanismo principal, Go utiliza o retorno explícito de valores de erro pelas funções. Isso torna o fluxo de execução do programa mais previsível e controlável.

O principal objetivo da biblioteca é oferecer uma maneira simples e eficiente de criar novos erros, comparar seus tipos e adicionar informações contextuais (como "empacotar" erros). Em Go, um erro é simplesmente a interface error, que qualquer tipo com o método Error() string pode implementar. Isso proporciona enorme flexibilidade: você pode criar seus próprios tipos de erro com campos adicionais (código de erro, dados da requisição, etc.).

Para que serve? Sem ela, é impossível escrever uma aplicação Go confiável. Sempre que uma função pode falhar (ao trabalhar com arquivos, rede, banco de dados), ela retorna um erro. Ignorar erros (atribuí-los à variável _) é considerada uma má prática. A biblioteca errors permite não apenas informar o que deu errado, mas também construir uma cadeia de erros para saber exatamente em qual etapa ocorreu a falha durante a depuração.

2. Instalação

O pacote errors faz parte da biblioteca padrão do Go. Isso significa que nenhuma instalação adicional é necessária. Ele está disponível "de fábrica" ao instalar qualquer Go SDK. Para usá-lo, basta importá-lo no seu código:

import "errors"

Se você usa Go Modules (padrão desde Go 1.11+), o pacote estará automaticamente disponível. Nenhum comando go get é necessário para a biblioteca padrão.

Importante: Existe também a biblioteca de terceiros github.com/pkg/errors, que oferece funcionalidades avançadas (stack traces, formatação). No entanto, este artigo foca exclusivamente no pacote padrão errors, que é a base para qualquer tratamento de erros em Go.

3. Início rápido

Exemplo mínimo funcional de criação e tratamento de erro:

package main

import (
    "errors"
    "fmt"
)

// Função que divide dois números. Se o divisor for zero, retorna um erro.
func divide(a, b float64) (float64, error) {
    if b == 0 {
        return 0, errors.New("divisão por zero não é permitida")
    }
    return a / b, nil
}

func main() {
    result, err := divide(10, 2)
    if err != nil {
        fmt.Println("Erro:", err)
    } else {
        fmt.Println("Resultado:", result)
    }

    // Tentando com erro
    result2, err2 := divide(10, 0)
    if err2 != nil {
        fmt.Println("Erro:", err2) // Saída: Erro: divisão por zero não é permitida
    } else {
        fmt.Println("Resultado:", result2)
    }
}

Neste exemplo, criamos um erro simples com errors.New() e verificamos sua presença da forma padrão: if err != nil.

4. Principais funções e métodos

Abaixo estão 8 funções/métodos principais do pacote errors com descrição detalhada e exemplos.