Layering Handler-Servicio-Repositorio

El patrón handler-service-repository divide los adaptadores HTTP (o gRPC), la lógica de negocio y la persistencia en tres capas testeables.

Es la arquitectura por defecto para APIs en Go que superan main.go con SQL en línea.

Resumen

Los handlers traducen formatos de red y códigos de estado.

Los services aplican reglas y orquestan flujos de trabajo.

Los repositories se comunican con bases de datos, cachés y APIs externas.

Las dependencias fluyen handler → service → interfaz de repository, nunca al revés.

Cuándo usar esto: Al construir servicios REST o gRPC, al incorporar desarrolladores backend, o al extraer lógica de handlers "gordos".

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

// puerto del repositorio
type UserRepo interface {
    ByEmail(ctx context.Context, email string) (User, error)
    Insert(ctx context.Context, u User) error
}
 
// servicio
func (s *Service) Register(ctx context.Context, email string) error { /* reglas */ }
 
// handler
func (h *Handler) Register(w http.ResponseWriter, r *http.Request) { /* decodificar, llamar al servicio, responder */ }

Cuándo usar esto:

• Los handlers contienen cadenas SQL o cadenas if de lógica de negocio más largas que una pantalla.
• Necesitas pruebas unitarias para precios, autenticación o validación sin httptest y Postgres.
• Múltiples transportes (HTTP + gRPC + CLI) compartirán los mismos flujos de trabajo.

Ejemplo de Trabajo

// internal/user/repo.go
package user
 
import (
    "context"
    "time"
)
 
type User struct {
    ID        int64
    Email     string
    CreatedAt time.Time
}
 
type Repository interface {
    FindByEmail(ctx context.Context, email string) (User, error)
    Create(ctx context.Context, u User) error
}

// internal/user/service.go
package user
 
import (
    "context"
    "errors"
    "fmt"
    "strings"
    "time"
)
 
var (
    ErrInvalidEmail = errors.New("user: invalid email")
    ErrExists       = errors.New("user: email already registered")
)
 
type Service struct {
    repo Repository
    now  func() time.Time
}
 
func NewService(repo Repository) *Service {
    return &Service{repo: repo, now: time.Now}
}
 
func (s *Service) Register(ctx context.Context, email string) error {
    email = strings.TrimSpace(strings.ToLower(email))
    if !strings.Contains(email, "@") {
        return ErrInvalidEmail
    }
    if _, err := s.repo.FindByEmail(ctx, email); err == nil {
        return ErrExists
    }
    u := User{Email: email, CreatedAt: s.now()}
    if err := s.repo.Create(ctx, u); err != nil {
        return fmt.Errorf("register: %w", err)
    }
    return nil
}

// internal/user/postgres.go
package user
 
import (
    "context"
    "database/sql"
    "errors"
)
 
type PG struct {
    db *sql.DB
}
 
func (p *PG) FindByEmail(ctx context.Context, email string) (User, error) {
    var u User
    err := p.db.QueryRowContext(ctx,
        `SELECT id, email, created_at FROM users WHERE email=$1`, email,
    ).Scan(&u.ID, &u.Email, &u.CreatedAt)
    if errors.Is(err, sql.ErrNoRows) {
        return User{}, err
    }
    return u, err
}
 
func (p *PG) Create(ctx context.Context, u User) error {
    _, err := p.db.ExecContext(ctx,
        `INSERT INTO users (email, created_at) VALUES ($1,$2)`, u.Email, u.CreatedAt,
    )
    return err
}

// internal/user/http.go
package user
 
import (
    "encoding/json"
    "errors"
    "net/http"
)
 
type Handler struct {
    svc *Service
}
 
func NewHandler(svc *Service) *Handler {
    return &Handler{svc: svc}
}
 
func (h *Handler) Register(w http.ResponseWriter, r *http.Request) {
    var in struct {
        Email string `json:"email"`
    }
    if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
        http.Error(w, "invalid json", http.StatusBadRequest)
        return
    }
    err := h.svc.Register(r.Context(), in.Email)
    if err != nil {
        switch {
        case errors.Is(err, ErrInvalidEmail):
            http.Error(w, err.Error(), http.StatusBadRequest)
        case errors.Is(err, ErrExists):
            http.Error(w, err.Error(), http.StatusConflict)
        default:
            http.Error(w, "server error", http.StatusInternalServerError)
        }
        return
    }
    w.WriteHeader(http.StatusCreated)
}

// cmd/api/main.go
package main
 
import (
    "database/sql"
    "log"
    "net/http"
 
    _ "github.com/jackc/pgx/v5/stdlib"
 
    "example.com/app/internal/user"
)
 
func main() {
    db, err := sql.Open("pgx", "postgres://localhost/app?sslmode=disable")
    if err != nil {
        log.Fatal(err)
    }
    repo := &user.PG{db: db}
    svc := user.NewService(repo)
    h := user.NewHandler(svc)
 
    mux := http.NewServeMux()
    mux.HandleFunc("POST /users", h.Register)
    log.Fatal(http.ListenAndServe(":8080", mux))
}

Lo que esto demuestra:

• Las pruebas de Service usan un Repository falso sin HTTP ni SQL.
• Handler mapea errores de dominio a códigos de estado HTTP en un solo lugar.
• PG es la única capa que conoce los nombres de las columnas SQL.

Inmersión Profunda

Cómo Funciona

• Handler (adaptador): Análisis de peticiones, integración de middleware de autenticación, codificación de respuestas, códigos de estado.
• Service (aplicación): Validación, comprobaciones de autorización, transacciones que abarcan repositorios, claves de idempotencia.
• Repository (infraestructura): CRUD y consultas; devuelve structs de dominio o mapea tipos de drivers.

Flujo de Peticiones

Cliente -> Handler -> Service -> Repository -> Base de Datos
                <-          <-              <-

El contexto se propaga para la cancelación.

Las transacciones generalmente comienzan en el servicio (o en un puerto UnitOfWork) y pasan *sql.Tx a los repositorios cuando es necesario.

Variante gRPC

Mantén los services idénticos; solo cambian los adaptadores de entrada.

Notas de Go

// Repositorio falso para pruebas de servicio
type memRepo struct {
    byEmail map[string]User
}
 
func (m *memRepo) FindByEmail(ctx context.Context, email string) (User, error) {
    u, ok := m.byEmail[email]
    if !ok {
        return User{}, errors.New("not found")
    }
    return u, nil
}

• Prefiere un paquete por característica (user) con tipos Handler, Service y PG en lugar de tres paquetes para APIs pequeñas.
• Divide los paquetes cuando los archivos crecen más allá de la comodidad del equipo o aparecen ciclos de importación.

Trampas Comunes

• Fugas de sql.Rows a los handlers - Expone la lógica de escaneo en la capa HTTP. Solución: Los repositories devuelven structs o slices tipados.
• El servicio devuelve enteros de estado HTTP - Acopla el núcleo al transporte. Solución: Devuelve errores centinela; los handlers traducen.
• Servicio "Dios" - Una única struct Service con cuarenta métodos. Solución: Divide por agregado (UserService, BillingService).
• El repositorio devuelve DTOs con etiquetas JSON - Confunde la persistencia con los contratos de la API. Solución: Separa structs de API en el paquete handler si las formas difieren.
• Contexto faltante en los métodos del repositorio - No se pueden cancelar consultas lentas. Solución: Primer parámetro ctx context.Context en todas las I/O.
• El handler llama a dos services sin transacción - Actualizaciones parciales en caso de fallo. Solución: Orquestar en un método de servicio con un puerto de transacción explícito.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Arquitectura en Go - Ejemplos de diseño y conexión.
• Arquitectura en Go: Interfaces Pequeñas, Dependencias Explícitas - Ubicación de interfaces.
• Arquitectura Limpia y Hexagonal en Go - Puertos y adaptadores formales.
• Patrones de Capa de Repositorio y Servicio - Catálogo de patrones en Go Patterns.
• Mejores Prácticas de Arquitectura y Diseño - Hábitos de equipo para capas en evolución.

Enlaces Externos Relacionados

• Documentación del Framework Web Gin - Documentación del popular framework web de alto rendimiento.
• Documentación de la Biblioteca Estándar de Go - Referencia completa de la biblioteca estándar.
• Effective Go - Guía oficial para escribir Go claro e idiomático.
• Learning Go (2ª Edición, O'Reilly) - Jon Bodner en O'Reilly.
• Concurrency in Go (O'Reilly) - Mismo libro en O'Reilly.

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