Fundamentos del Manejo de Errores

10 ejemplos para empezar con el Manejo de Errores - 7 básicos y 3 intermedios.

Prerrequisitos

• Instala Go 1.26.x o posterior desde go.dev/dl.
• Crea un módulo: mkdir errdemo && cd errdemo && go mod init example.com/errdemo.
• Guarda los fragmentos como main.go y ejecútalos con go run ..

Ejemplos Básicos

1. La interfaz error y la comprobación nil

Cada ruta de fallo comienza comprobando el segundo valor de retorno.

package main
 
import (
	"fmt"
	"os"
)
 
func main() {
	f, err := os.Open("missing.txt")
	if err != nil {
		fmt.Println("la apertura falló:", err)
		return
	}
	defer f.Close()
}

• Las funciones que pueden fallar devuelven (T, error); un error no nil significa fallo.
• Cuando err != nil, trata el resultado principal como inválido a menos que se documente lo contrario.
• Un error nil significa éxito.

Relacionado: Errores como Valores: La Filosofía de Errores de Go - por qué Go usa valores, no excepciones

2. Devolver errores desde tus propias funciones

Propaga fallos devolviendo error al llamador.

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

• Usa errors.New para mensajes estáticos sin formato.
• Devuelve el valor cero para T junto con el error.
• Los llamadores deciden si envolver, registrar o abortar.

Relacionado: Errores Centinela y errors.Is - variables de error a nivel de paquete

3. fmt.Errorf para errores formateados

Añade detalles dinámicos cuando el mensaje depende de valores.

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

• fmt.Errorf es como fmt.Sprintf pero devuelve un error.
• Prefiere %w al envolver un error existente (cubierto en ejemplos intermedios).
• Mantén los mensajes accionables: qué falló y con qué entrada.

Relacionado: Envoltura de Errores con %w y errors.As - %w y cadenas de desempaquetado

4. Retorno temprano ante error

Evita anidaciones profundas devolviendo inmediatamente después de un fallo.

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)
}

• Comprueba err antes de usar el valor de éxito.
• Propaga con return zero, err dentro de las funciones auxiliares.
• El flujo de control plano es más fácil de leer que los if err == nil anidados.

5. Error centinela con errors.Is

Compara errores estables a nivel de paquete a través de cadenas de envoltura.

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

• errors.Is recorre las cadenas de desempaquetado; err == os.ErrNotExist falla después de envolver.
• La biblioteca estándar exporta centinelas como os.ErrNotExist y io.EOF.
• Define los tuyos propios con var ErrThing = errors.New("cosa").

Relacionado: Errores Centinela y errors.Is - reglas de diseño de centinelas

6. Defer todavía se ejecuta en rutas de error

Limpia recursos incluso cuando retornas temprano.

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

• Registra defer f.Close() inmediatamente después de una apertura exitosa.
• Las llamadas diferidas se ejecutan cuando la función sale, incluyendo los retornos de error.
• No uses defer antes de comprobar err de la operación que produjo f.

7. Registrar o devolver, no ambos ciegamente

Elige una acción principal por capa a menos que añadas contexto distinto.

package main
 
import (
	"fmt"
	"log"
	"os"
)
 
func main() {
	data, err := os.ReadFile("config.yaml")
	if err != nil {
		log.Printf("leer configuración: %v", err)
		return
	}
	fmt.Printf("cargados %d bytes\n", len(data))
}

• Las bibliotecas devuelven errores; main o los manejadores a menudo registran y salen o responden.
• El registro duplicado en cada capa crea líneas de registro ruidosas y correlacionadas.
• Envuelve antes de devolver cuando la capa superior necesita contexto.

Relacionado: Mejores Prácticas de Manejo de Errores - responsabilidades de bibliotecas vs aplicaciones

Ejemplos Intermedios

8. Envolver errores con %w

Preserva la causa raíz mientras añades contexto en cada capa.

package main
 
import (
	"fmt"
	"os"
)
 
func readConfig(path string) error {
	_, err := os.ReadFile(path)
	if err != nil {
		return fmt.Errorf("leer configuración %q: %w", path, err)
	}
	return nil
}
 
func main() {
	err := readConfig("missing.yaml")
	fmt.Println(err)
	fmt.Println(os.IsNotExist(err)) // true a través de la cadena de envoltura
}

• %w almacena el error envuelto para errors.Is y errors.As.
• os.IsNotExist y errors.Is recorren las envolturas.
• Usa %v en lugar de %w cuando el error interno no deba ser inspeccionable.

Relacionado: Envoltura de Errores con %w y errors.As - guía completa de envoltura

9. Errores tipados con errors.As

Extrae datos estructurados de un tipo de error 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 asigna el primer tipo coincidente en la cadena de desempaquetado.
• Pasa un puntero al tipo objetivo (&ve).
• Los tipos personalizados permiten campos sin análisis de cadenas.

Relacionado: Tipos de Error Personalizados e Interfaces de Error - diseño de errores enriquecidos

10. Manejar errores en un pequeño manejador estilo HTTP

Mapea errores de dominio a códigos de estado HTTP en el límite.

package main
 
import (
	"errors"
	"fmt"
)
 
var ErrNotFound = errors.New("no 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
}

• Traduce errores a mensajes seguros para el cliente y códigos de estado en el borde.
• Usa errors.Is para mapeo centinela; evita filtrar cadenas de os o del driver.
• Los detalles internos pertenecen a los logs, no a los cuerpos de respuesta.

Relacionado: Diseño de Errores de API para Servicios HTTP y gRPC - contratos de error de servicio

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado GC de Green Tea, modernizadores de go fix - verificar parche en la compilación), chi (última versión - verificar en la compilación), gin (última versión - verificar en la compilación), echo (última versión - verificar en la compilación), google.golang.org/grpc (última versión - verificar en la compilación), sigs.k8s.io/controller-runtime (última versión - verificar en la compilación), kubebuilder (última versión - verificar en la compilación), tinygo (última versión - verificar objetivos de placa en la compilación), wazero (última versión - verificar en la compilación) y golangci-lint (última versión - verificar conjunto de linters en la compilación). pbqrthvqrf.vb|ptvb420|202607