Patrones de Diseño para un Manejo de Errores Limpio y Mantenible en Go

A medida que una aplicación de Go crece en complejidad y adopta arquitecturas desacopladas (Clean Architecture, Hexagonal), el manejo de errores simple deja de ser suficiente. Inyectar metadatos de red en el dominio o propagar errores crudos de infraestructura acopla nuestras capas lógicas y degrada la mantenibilidad del código. En esta guía exploraremos los cuatro patrones profesionales más comunes para traducir, unificar, centralizar y categorizar errores en sistemas Go corporativos.

Tabla de Contenidos

• Objetivo
• ¿Por qué evitar metadatos manuales en los errores?
• Los Cuatro Patrones de Manejo de Errores
  • 1. Boundary Error Translation (Traducción de Errores en la Frontera)
  • 2. Unified Application Error (Error de Aplicación Unificada)
  • 3. Centralized Error Mapping (Mapeador Centralizado)
  • 4. Hybrid Unified App Error (Error Aplicativo Unificado Híbrido)
• Tabla Comparativa de los Patrones
• Para no morir en el intento y consejos prácticos
• Conclusiones del Tema

---

Objetivo

Aprender a desacoplar el núcleo de negocio (Dominio) de los detalles de infraestructura (bases de datos, APIs de terceros) y del protocolo de transporte (HTTP, gRPC, CLI) mediante la implementación de patrones estructurados de manejo y mapeo de errores en Go.

¿Por qué evitar metadatos manuales en los errores?

Una mala práctica común en Go es intentar inyectar manualmente metadatos en los mensajes o campos de error de forma ad-hoc (como inyectar tier: "repository", func: "CreateUser", o timestamps). Esto ensucia el código con boilerplate propenso a errores al refactorizar y viola el principio de responsabilidad única.

La buena práctica en Go profesional dicta:

1. Mantener los errores semánticamente limpios (con foco únicamente en el problema de negocio o técnico que ocurrió).
2. Delegar el contexto a la infraestructura adecuada:
   • El contexto de traza y telemetría se captura automáticamente mediante la envoltura de errores (fmt.Errorf con %w) y sistemas distribuidos de APM/Tracing (OpenTelemetry).
   • El origen del error (archivo y línea de código) se delega a la configuración interna de nuestro logger estructurado (como el parámetro AddSource en slog o usando las herramientas nativas de zap o zerolog).
   • La modularidad y consistencia se logran a través de códigos de error jerárquicos (ej: users:not_found) y una traducción limpia entre capas lógicas.

---

Los Cuatro Patrones de Manejo de Errores

A continuación, analizaremos los cuatro patrones de diseño implementados profesionalmente para gestionar flujos de error en arquitecturas multicapa.

1. Boundary Error Translation (Traducción de Errores en la Frontera)

Este patrón consiste en interceptar errores nativos y específicos de la infraestructura (como los errores devueltos por un driver de base de datos SQL o un cliente HTTP externo) en el adaptador correspondiente, traduciéndolos a errores centinela definidos en el Dominio antes de que suban a las capas de negocio.

Cuándo aplicarlo

• Cuando necesitas proteger tus Casos de Uso y Entidades de los detalles de implementación físicos de la infraestructura.
• Cuando deseas mantener un Dominio agnóstico que no se entere de si la persistencia es Postgres, MongoDB o un mock en memoria.

Trade-offs

• Pros: Aísla por completo el dominio de la infraestructura. Cambios en la base de datos no rompen los contratos de negocio.
• Contras: Requiere mapear manualmente los errores en cada adaptador/repositorio, lo que incrementa el código repetitivo (boilerplate).

Código de Ejemplo (1-domain-translation)

Dominio (domain/errors.go)

package domain

import "errors"

// Errores centinela del dominio (agnósticos de la base de datos o red)
var (
    ErrUserNotFound   = errors.New("user not found")
    ErrDuplicateEmail = errors.New("email already exists")
)

Repositorio / Adaptador (repository/user_repo.go)

package repository

import (
    "database/sql"
    "errors"
    "fmt"
    "error-patterns/1-domain-translation/domain"
)

// Simulación de un error de base de datos específico (Postgres unique constraint violation)
var errPostgresUniqueViolation = errors.New("pq: duplicate key value violates unique constraint \"users_email_key\"")

type UserRepository struct{}

func (r *UserRepository) FindByID(id int) (string, error) {
    if id == 999 {
        return "", sql.ErrNoRows // Simula registro no encontrado
    }
    return "Alex Lopez", nil
}

func (r *UserRepository) Create(email string) error {
    if email == "[e-mail]" {
        return errPostgresUniqueViolation // Simula error de unicidad
    }
    return nil
}

// GetUser traduce sql.ErrNoRows a un error semántico de dominio
func (r *UserRepository) GetUser(id int) (string, error) {
    name, err := r.FindByID(id)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            // Envolvemos el error de dominio para no perder la causa raíz interna en depuración
            return "", fmt.Errorf("get user %d: %w", id, domain.ErrUserNotFound)
        }
        return "", fmt.Errorf("unexpected database error: %w", err)
    }
    return name, nil
}

// CreateUser traduce la violación de Postgres a domain.ErrDuplicateEmail
func (r *UserRepository) CreateUser(email string) error {
    err := r.Create(email)
    if err != nil {
        if errors.Is(err, errPostgresUniqueViolation) {
            return fmt.Errorf("create user: %w", domain.ErrDuplicateEmail)
        }
        return fmt.Errorf("unexpected database error: %w", err)
    }
    return nil
}

Presentación (handler/http_handler.go)

package handler

import (
    "errors"
    "fmt"
    "error-patterns/1-domain-translation/domain"
    "error-patterns/1-domain-translation/repository"
)

type HTTPHandler struct {
    Repo *repository.UserRepository
}

func (h *HTTPHandler) HandleGetUser(id int) (int, string) {
    name, err := h.Repo.GetUser(id)
    if err != nil {
        // La capa de red solo compara contra errores semánticos de dominio
        if errors.Is(err, domain.ErrUserNotFound) {
            return 404, fmt.Sprintf("Response JSON: {\"error\": \"usuario no encontrado con ID %d\"}", id)
        }
        return 500, "Response JSON: {\"error\": \"error interno del servidor\"}"
    }
    return 200, fmt.Sprintf("Response JSON: {\"data\": {\"id\": %d, \"name\": \"%s\"}}", id, name)
}

---

2. Unified Application Error (Error de Aplicación Unificada)

Este patrón define una estructura de error personalizada (AppError) global para todo el proyecto. Esta estructura centraliza los metadatos necesarios tanto para el cliente final (mensajes legibles y códigos de estado de red) como para los ingenieros que revisan los logs (error original interno).

Cuándo aplicarlo

• Excelente en microservicios homogéneos expuestos directamente mediante REST API.
• Cuando deseas una manera estandarizada y simple de construir respuestas y serializar errores a JSON sin escribir mapeos repetitivos.

Trade-offs

• Pros: Altamente automatizable; disminuye drásticamente el código de traducción. Ofrece uniformidad absoluta en las respuestas de error de la API.
• Contras: Acopla las capas lógicas internas a conceptos de transporte (como HTTPStatus), violando parcialmente la pureza del Dominio si la aplicación necesita exponerse a múltiples protocolos (ej. gRPC y HTTP).

Código de Ejemplo (2-unified-app-error)

Definición (errors/app_error.go)

package errors

import "fmt"

type AppError struct {
    Code       string // Identificador único legible para el cliente (ej: "INSUFFICIENT_FUNDS")
    Message    string // Mensaje amigable para el usuario final
    HTTPStatus int    // Código de estado de red correspondiente
    Err        error  // Causa raíz original del error (para logs internos)
}

func (e *AppError) Error() string {
    if e.Err != nil {
        return fmt.Sprintf("[%s] %s (Internal: %v)", e.Code, e.Message, e.Err)
    }
    return fmt.Sprintf("[%s] %s", e.Code, e.Message)
}

func (e *AppError) Unwrap() error {
    return e.Err
}

func NewAppError(code string, msg string, status int, original error) *AppError {
    return &AppError{
        Code:       code,
        Message:    msg,
        HTTPStatus: status,
        Err:        original,
    }
}

Servicio (service/account_service.go)

package service

import (
    "errors"
    "fmt"
    appErrors "error-patterns/2-unified-app-error/errors"
    "net/http"
)

var errDatabaseTimeout = errors.New("db query timeout after 5000ms")

type AccountService struct{}

func (s *AccountService) GetBalance(accountID int) (float64, error) {
    if accountID == 500 {
        return 0, appErrors.NewAppError(
            "DATABASE_TIMEOUT",
            "El sistema está experimentando retrasos. Intente más tarde.",
            http.StatusServiceUnavailable,
            errDatabaseTimeout,
        )
    }
    if accountID == 404 {
        return 0, &appErrors.AppError{
            Code:       "ACCOUNT_NOT_FOUND",
            Message:    fmt.Sprintf("La cuenta con ID %d no existe", accountID),
            HTTPStatus: http.StatusNotFound,
        }
    }
    return 1000.50, nil
}

func (s *AccountService) Withdraw(accountID int, amount float64) error {
    balance, err := s.GetBalance(accountID)
    if err != nil {
        return fmt.Errorf("withdraw check: %w", err)
    }

    if balance < amount {
        return &appErrors.AppError{
            Code:       "INSUFFICIENT_FUNDS",
            Message:    "Tu cuenta no dispone del saldo necesario para retirar este monto",
            HTTPStatus: http.StatusUnprocessableEntity,
        }
    }
    return nil
}

Controlador (handler/http_handler.go)

package handler

import (
    "errors"
    "fmt"
    appErrors "error-patterns/2-unified-app-error/errors"
    "error-patterns/2-unified-app-error/service"
)

type HTTPHandler struct {
    Service *service.AccountService
}

func (h *HTTPHandler) HandleWithdraw(accountID int, amount float64) (int, string) {
    err := h.Service.Withdraw(accountID, amount)
    if err != nil {
        var appErr *appErrors.AppError

        // Extraemos el AppError de la cadena de envolturas recursivamente
        if errors.As(err, &appErr) {
            if appErr.Err != nil {
                // Logs internos del sistema con el fallo de bajo nivel
                fmt.Printf("[LOG INTERNO] ROOT ERROR DETECTADO: %v\n", appErr.Err)
            }

            return appErr.HTTPStatus, fmt.Sprintf(
                "Response JSON: {\n  \"code\": \"%s\",\n  \"message\": \"%s\"\n}",
                appErr.Code,
                appErr.Message,
            )
        }

        // Fallback para fallos no previstos
        fmt.Printf("[LOG INTERNO CRÍTICO] Error no controlado: %v\n", err)
        return 500, "Response JSON: {\n  \"code\": \"INTERNAL_SERVER_ERROR\",\n  \"message\": \"Ocurrió un error inesperado\"\n}"
    }

    return 200, "Response JSON: {\n  \"status\": \"success\",\n  \"message\": \"Retiro completado con éxito\"\n}"
}

---

3. Centralized Error Mapping (Mapeador Centralizado)

Para lograr una pureza absoluta en el Dominio, este patrón prohíbe que los errores contengan metadatos de red (como códigos HTTP o gRPC). El Dominio y los Casos de Uso solo retornan errores de negocio semánticos. La lógica de presentación delega la conversión a funciones mapeadoras centralizadas que viven exclusivamente en la capa de transporte (adaptadores externos).

Cuándo aplicarlo

• En arquitecturas estrictas con múltiples canales de entrega simultáneos (una aplicación que expone HTTP REST y gRPC con las mismas reglas de negocio).
• Cuando deseas mantener tus políticas de seguridad/infraestructura de red estrictamente segregadas de tus lógicas algorítmicas de negocio.

Trade-offs

• Pros: Desacoplamiento total y pureza de dominio. Si cambias de HTTP a gRPC, el Dominio permanece intacto, solo desarrollas un nuevo mapeador en la capa de transporte.
• Contras: Requiere mantener mapeadores centralizados que pueden crecer considerablemente de tamaño en aplicaciones extensas.

Código de Ejemplo (3-centralized-mapping)

Dominio (domain/errors.go)

package domain

import "errors"

// Errores de dominio puros (sin acoplamiento a HTTP, gRPC ni base de datos)
var (
    ErrInsufficientStock = errors.New("insufficient stock for order")
    ErrUserSuspended     = errors.New("user account is suspended")
)

Mapeador HTTP (mapper/http_mapper.go)

package mapper

import (
    "errors"
    "error-patterns/3-centralized-mapping/domain"
    "net/http"
)

type HTTPResponse struct {
    Code    string `json:"code"`
    Message string `json:"message"`
}

// MapDomainErrorToHTTP traduce el error de dominio puro al protocolo HTTP
func MapDomainErrorToHTTP(err error) (int, HTTPResponse) {
    if err == nil {
        return http.StatusOK, HTTPResponse{}
    }

    if errors.Is(err, domain.ErrInsufficientStock) {
        return http.StatusBadRequest, HTTPResponse{
            Code:    "OUT_OF_STOCK",
            Message: "No hay suficiente inventario disponible para este artículo",
        }
    }

    if errors.Is(err, domain.ErrUserSuspended) {
        return http.StatusForbidden, HTTPResponse{
            Code:    "USER_SUSPENDED",
            Message: "La cuenta del usuario está inactiva o suspendida",
        }
    }

    return http.StatusInternalServerError, HTTPResponse{
        Code:    "INTERNAL_SERVER_ERROR",
        Message: "Ocurrió un error inesperado",
    }
}

Mapeador gRPC (mapper/grpc_mapper.go)

package mapper

import (
    "errors"
    "error-patterns/3-centralized-mapping/domain"
)

type GRPCCode uint32

const (
    GRPC_OK                  GRPCCode = 0
    GRPC_PERMISSION_DENIED  GRPCCode = 7
    GRPC_FAILED_PRECONDITION GRPCCode = 9
    GRPC_INTERNAL            GRPCCode = 13
)

type GRPCStatus struct {
    Code    GRPCCode
    Message string
}

// MapDomainErrorToGRPC traduce el error de dominio puro al protocolo gRPC
func MapDomainErrorToGRPC(err error) GRPCStatus {
    if err == nil {
        return GRPCStatus{Code: GRPC_OK, Message: ""}
    }

    if errors.Is(err, domain.ErrInsufficientStock) {
        return GRPCStatus{
            Code:    GRPC_FAILED_PRECONDITION,
            Message: "Fallo de condición: stock insuficiente para completar la petición",
        }
    }

    if errors.Is(err, domain.ErrUserSuspended) {
        return GRPCStatus{
            Code:    GRPC_PERMISSION_DENIED,
            Message: "Permiso denegado: cuenta de usuario suspendida",
        }
    }

    return GRPCStatus{
        Code:    GRPC_INTERNAL,
        Message: "Error interno del servidor",
    }
}

---

4. Hybrid Unified App Error (Error Aplicativo Unificado Híbrido)

Este patrón combina la facilidad del Error Aplicativo Unificado con la modularidad y el desacoplamiento del Mapeador Centralizado. En lugar de inyectar códigos de red como HTTPStatus dentro de la estructura de error, define un alias de categorización lógico (ErrorType) independiente del protocolo.

La conversión a códigos específicos de red (HTTP 404, HTTP 422 o códigos gRPC equivalentes) se delega a un mapeador genérico en la capa de transporte que evalúa los tipos (ErrorType) de forma abstracta.

Cuándo aplicarlo

• La mejor opción para microservicios medianos a grandes con múltiples transportes que quieren evitar mapear a mano cada error de recurso individual en el controlador.
• Cuando deseas mantener la pureza del Dominio desacoplado de HTTP/gRPC, pero requieres de un manejo uniforme, dinámico y escalable.

Trade-offs

• Pros: El Dominio se mantiene libre de detalles de red. El mapeador en la capa de transporte es extremadamente compacto (solo mapea 4 o 5 categorías genéricas de ErrorType, no recursos individuales). El cliente sigue recibiendo JSON estructurado y códigos específicos.
• Contras: Requiere la rigurosidad de clasificar cada error bajo un conjunto de constantes predefinido de categorías.

Código de Ejemplo (4-hybrid-app-error-unified)

Estructura y Categorías (errors/app_error.go)

package errors

import "fmt"

// ErrorType define un alias de tipo para categorización lógica de errores
type ErrorType string

// Categorías abstractas de error
const (
    TypeNotFound        ErrorType = "NOT_FOUND"
    TypeValidationError ErrorType = "VALIDATION"
    TypeUnauthorized    ErrorType = "UNAUTHORIZED"
    TypeInternal        ErrorType = "INTERNAL"
)

// AppError es el error estructurado y unificado, desacoplado del protocolo de red
type AppError struct {
    Type    ErrorType // Categoría evaluada por el mapeador de transporte
    Code    string    // Código de negocio específico para clientes (ej. "ACCOUNT_NOT_FOUND")
    Message string    // Mensaje legible para el usuario
    Err     error     // Causa original para depuración interna
}

func (e *AppError) Error() string {
    if e.Err != nil {
        return fmt.Sprintf("[%s] %s (Internal: %v)", e.Code, e.Message, e.Err)
    }
    return fmt.Sprintf("[%s] %s", e.Code, e.Message)
}

func (e *AppError) Unwrap() error {
    return e.Err
}

func NewAppError(errType ErrorType, code string, msg string, original error) *AppError {
    return &AppError{
        Type:    errType,
        Code:    code,
        Message: msg,
        Err:     original,
    }
}

Servicio (service/account_service.go)

package service

import (
    "errors"
    "fmt"
    appErrors "error-patterns/4-hybrid-app-error-unified/errors"
)

var errDatabaseTimeout = errors.New("db query timeout after 5000ms")

type AccountService struct{}

func (s *AccountService) GetBalance(accountID int) (float64, error) {
    if accountID == 500 {
        // Error de infraestructura mapeado a la categoría abstracta TypeInternal
        return 0, appErrors.NewAppError(
            appErrors.TypeInternal,
            "DATABASE_TIMEOUT",
            "The system is experiencing delays. Please try again later.",
            errDatabaseTimeout,
        )
    }
    if accountID == 404 {
        // Error de negocio mapeado a la categoría abstracta TypeNotFound
        return 0, &appErrors.AppError{
            Type:    appErrors.TypeNotFound,
            Code:    "ACCOUNT_NOT_FOUND",
            Message: fmt.Sprintf("Account with ID %d does not exist", accountID),
        }
    }
    return 1000.50, nil
}

func (s *AccountService) Withdraw(accountID int, amount float64) error {
    balance, err := s.GetBalance(accountID)
    if err != nil {
        return fmt.Errorf("withdraw check: %w", err)
    }

    if balance < amount {
        // Error de validación mapeado a la categoría abstracta TypeValidationError
        return &appErrors.AppError{
            Type:    appErrors.TypeValidationError,
            Code:    "INSUFFICIENT_FUNDS",
            Message: "Your account does not have enough balance for this withdrawal",
        }
    }
    return nil
}

Mapeador HTTP Genérico (mapper/http_mapper.go)

package mapper

import (
    "errors"
    appErrors "error-patterns/4-hybrid-app-error-unified/errors"
    "net/http"
)

type HTTPResponse struct {
    Code    string `json:"code"`
    Message string `json:"message"`
}

// MapToHTTP mapea la categoría de error abstracta al código HTTP correspondiente
func MapToHTTP(err error) (int, HTTPResponse) {
    if err == nil {
        return http.StatusOK, HTTPResponse{}
    }

    var appErr *appErrors.AppError
    if errors.As(err, &appErr) {
        var status int
        switch appErr.Type {
        case appErrors.TypeNotFound:
            status = http.StatusNotFound
        case appErrors.TypeValidationError:
            status = http.StatusUnprocessableEntity
        case appErrors.TypeUnauthorized:
            status = http.StatusUnauthorized
        default:
            status = http.StatusInternalServerError
        }

        return status, HTTPResponse{
            Code:    appErr.Code,
            Message: appErr.Message,
        }
    }

    // Fallback para errores de red no controlados
    return http.StatusInternalServerError, HTTPResponse{
        Code:    "INTERNAL_SERVER_ERROR",
        Message: "An unexpected error occurred",
    }
}

Controlador (handler/http_handler.go)

package handler

import (
    "errors"
    "fmt"
    appErrors "error-patterns/4-hybrid-app-error-unified/errors"
    "error-patterns/4-hybrid-app-error-unified/mapper"
    "error-patterns/4-hybrid-app-error-unified/service"
)

type HTTPHandler struct {
    Service *service.AccountService
}

func (h *HTTPHandler) HandleWithdraw(accountID int, amount float64) (int, string) {
    err := h.Service.Withdraw(accountID, amount)
    if err != nil {
        var appErr *appErrors.AppError
        if errors.As(err, &appErr) && appErr.Err != nil {
            fmt.Printf("[INTERNAL LOG] ROOT CAUSE DETECTED: %v\n", appErr.Err)
        }

        // Delegamos la traducción al mapeador genérico en la capa de transporte
        status, response := mapper.MapToHTTP(err)
        return status, fmt.Sprintf(
            "Response JSON: {\n  \"code\": \"%s\",\n  \"message\": \"%s\"\n}",
            response.Code,
            response.Message,
        )
    }

    return 200, "Response JSON: {\n  \"status\": \"success\",\n  \"message\": \"Withdrawal completed successfully\"\n}"
}

Tabla Comparativa de los Patrones

Criterio	1. Boundary Translation	2. Unified App Error	3. Centralized Mapping	4. Hybrid Unified Error
Acoplamiento de Red	Nulo	Alto (HTTP Status en dominio)	Nulo	Nulo
Complejidad de Código	Media (Mapeo repetitivo)	Baja (Automatizado)	Alta (Mapeador extenso)	Media (Mapeador genérico)
Múltiples Protocolos	Excelente	Dificultoso	Excelente	Excelente
Mantenibilidad	Localizada por Repositorio	Directa	Centralizada	Centralizada y Genérica
Ideal para...	Proteger el dominio de DBs	Microservicios HTTP REST	Arquitecturas estrictas	Microservicios multi-canal

Para no morir en el intento y consejos prácticos

• Cuidado con las dependencias circulares: Al estructurar mappers y manejadores centralizados en Go, ten cuidado de no importar el paquete de transporte dentro del dominio o viceversa. El flujo de importaciones siempre debe ir hacia adentro: Transporte -> Casos de Uso -> Dominio. Los errores siempre deben ser propagados y evaluados en la frontera.
• Riesgo de mutación de errores centinela: Dado que las variables globales en Go son mutables, un paquete de terceros o un error en el código podría modificar un error centinela global (ej. domain.ErrUserNotFound = nil). Si necesitas total inmutabilidad, considera definir tus errores semánticos como constantes mediante tipos personalizados de string:

  type MyError string
  func (e MyError) Error() string { return string(e) }
  const ErrConstNotFound MyError = "not found"

• Fuga de Abstracciones: Evita envolver con %w errores internos nativos de la base de datos (como sql.ErrNoRows) y exponerlos en los paquetes públicos de tu API de cara al cliente. Si un cliente empieza a depender de errors.Is(err, sql.ErrNoRows) y luego migras a MongoDB, romperás la compatibilidad hacia atrás de tu librería. Traduce los errores en las fronteras y envuelve únicamente los errores que formen parte de tu contrato de negocio público.

Conclusiones del Tema

El manejo de errores en Go, lejos de ser rígido, ofrece una flexibilidad extraordinaria para adaptarse a patrones arquitectónicos profesionales. Mientras que en scripts sencillos la traducción manual en la frontera es suficiente, los microservicios corporativos de gran escala obtienen un valor enorme al aplicar el patrón de Error Aplicativo Unificado Híbrido, manteniendo la pureza de sus dominios intacta a la vez que automatizan la salida HTTP/gRPC.