multierr para Go: combinando e trabalhando com múltiplos erros

Em Go, o tratamento de erros é uma parte explícita e essencial do desenvolvimento. No entanto, frequentemente surge a situação em que, durante a execução de uma operação, podem ocorrer não apenas um, mas vários erros ao mesmo tempo. Por exemplo, ao processar arquivos em lote, validar uma estrutura de dados complexa ou executar tarefas paralelas. O pacote padrão errors permite trabalhar apenas com um erro por vez, o que dificulta a coleta e análise de todas as falhas ocorridas.

A biblioteca multierr da empresa Uber (sim, a mesma que criou o zap e o fx) resolve esse problema de forma elegante e eficiente. Ela fornece uma API simples para combinar vários erros independentes em um único erro composto (composite error). Isso permite preservar o contexto de todas as falhas sem perder informações e tratá-las em um único local. Ao contrário da criação manual de slices de erros, o multierr oferece funções convenientes para combinar, verificar a existência de erros e iterar sobre eles.

A filosofia principal da biblioteca é simplicidade e desempenho. Ela não cria alocações desnecessárias no heap se não for necessário e se esforça para minimizar a sobrecarga. O multierr é ideal para casos em que você precisa coletar erros de diferentes fontes (por exemplo, de goroutines) e retorná-los como um único resultado que pode ser verificado quanto à presença de erros usando o padrão if err != nil.

Instalação

A instalação da biblioteca é feita com o comando padrão go get. Certifique-se de ter o Go versão 1.13 ou superior instalado (para suporte a errors.Is e errors.As).

go get go.uber.org/multierr

Após executar o comando, a biblioteca será adicionada ao seu arquivo go.mod. A importação é feita da seguinte forma:

import "go.uber.org/multierr"

Início rápido: exemplo mínimo

Vamos considerar o caso mais simples: temos duas funções que podem retornar um erro. Queremos executar ambas e, se pelo menos uma delas falhar, retornar um erro geral.

package main

import (
    "errors"
    "fmt"
    "go.uber.org/multierr"
)

func fazerAlgo() error {
    return errors.New("primeiro erro")
}

func fazerOutraCoisa() error {
    return errors.New("segundo erro")
}

func main() {
    var err error
    
    // Executa a primeira operação
    err = multierr.Append(err, fazerAlgo())
    // Executa a segunda operação
    err = multierr.Append(err, fazerOutraCoisa())
    
    if err != nil {
        fmt.Println("Ocorreram erros:")
        // Exibe todos os erros separados por quebra de linha
        for _, e := range multierr.Errors(err) {
            fmt.Println("-", e)
        }
    }
}

Neste exemplo, multierr.Append adiciona um novo erro a um erro existente. Se err for igual a nil, a função simplesmente retorna o novo erro. Como resultado, obtemos um único erro composto que pode ser decomposto usando multierr.Errors.

Funções e métodos principais

A biblioteca multierr fornece um conjunto pequeno, mas muito poderoso de funções. Vamos detalhar cada uma delas.

1. multierr.Append

Assinatura: func Append(left error, right error) error

Descrição: Esta é a função principal para combinar dois erros. Se ambos os erros forem nil, retorna nil. Se um deles for nil, retorna o outro. Se ambos não forem nil, eles são combinados em um único erro composto.

err1 := errors.New("erro 1")
err2 := e