multierr para Go: cómo combinar y manejar múltiples errores

En Go, el manejo de errores es una parte explícita y fundamental del desarrollo. Sin embargo, a menudo surge la situación en la que, durante la ejecución de una sola operación, pueden ocurrir no uno, sino varios errores. Por ejemplo, al procesar archivos por lotes, validar una estructura de datos compleja o ejecutar tareas en paralelo. El paquete estándar errors solo permite trabajar con un error a la vez, lo que dificulta la recopilación y el análisis de todas las fallas ocurridas.

La librería multierr de la empresa Uber (sí, la misma que creó zap y fx) resuelve este problema de forma elegante y eficiente. Proporciona una API simple para combinar varios errores independientes en un solo error compuesto. Esto permite conservar el contexto de todas las fallas sin perder información y manejarlas en un solo lugar. A diferencia de crear manualmente slices de errores, multierr ofrece funciones convenientes para combinar, verificar la existencia de errores e iterar sobre ellos.

La filosofía principal de la librería es la simplicidad y el rendimiento. No realiza asignaciones innecesarias en el heap si no es necesario y se esfuerza por minimizar la sobrecarga. multierr es ideal para casos en los que necesitas recopilar errores de diferentes fuentes (por ejemplo, de gorutinas) y devolverlos como un único resultado que se pueda verificar con el estándar if err != nil.

Instalación

La instalación de la librería se realiza con el comando estándar go get. Asegúrate de tener instalado Go versión 1.13 o superior (para soportar errors.Is y errors.As).

go get go.uber.org/multierr

Después de ejecutar el comando, la librería se agregará a tu archivo go.mod. Se importa de la siguiente manera:

import "go.uber.org/multierr"

Inicio rápido: ejemplo mínimo

Veamos el caso más simple: tenemos dos funciones que pueden devolver un error. Queremos ejecutar ambas y, si al menos una falla, devolver un error combinado.

package main

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

func hacerAlgo() error {
    return errors.New("primer error")
}

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

func main() {
    var err error
    
    // Ejecutamos la primera operación
    err = multierr.Append(err, hacerAlgo())
    // Ejecutamos la segunda operación
    err = multierr.Append(err, hacerOtraCosa())
    
    if err != nil {
        fmt.Println("Ocurrieron errores:")
        // Mostramos todos los errores, separados por salto de línea
        for _, e := range multierr.Errors(err) {
            fmt.Println("-", e)
        }
    }
}

En este ejemplo, multierr.Append agrega un nuevo error al existente. Si err es nil, la función simplemente devuelve el nuevo error. Como resultado, obtenemos un único error compuesto que se puede desglosar con multierr.Errors.

Funciones y métodos principales

La librería multierr proporciona un conjunto pequeño pero muy potente de funciones. Veamos cada una en detalle.

1. multierr.Append

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

Descripción: Esta es la función principal para combinar dos errores. Si ambos errores son nil, devuelve nil. Si uno de ellos es nil, devuelve el otro. Si ambos no son nil, los combina en un solo error compuesto.

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