Patrones de Capa de Repositorio y Servicio

Las capas de repositorio y servicio separan el acceso a datos de la lógica de negocio para que los servicios Go permanezcan testeables sin necesidad de levantar Postgres en cada prueba unitaria.

Los manejadores traducen HTTP o gRPC a llamadas de servicio; los repositorios traducen las necesidades del servicio a operaciones SQL, RPC o de caché.

Resumen

Un repositorio oculta cómo se cargan y guardan las filas.

Un servicio orquesta reglas: validación, comprobaciones de autorización, idempotencia y flujos de trabajo de varios pasos.

La capa de manejador se ocupa de las preocupaciones de transporte: códigos de estado, encabezados y análisis de solicitudes.

Las interfaces se definen donde se consumen (típicamente el paquete de servicio) y son satisfechas por implementaciones concretas de repositorio en internal/storage o similar.

Receta

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

type UserRepo interface {
    Get(ctx context.Context, id string) (User, error)
}
 
type UserService struct {
    repo UserRepo
}
 
func (s *UserService) DisplayName(ctx context.Context, id string) (string, error) {
    u, err := s.repo.Get(ctx, id)
    if err != nil { return "", err }
    return strings.TrimSpace(u.First + " " + u.Last), nil
}

Cuándo usar esto:

• Reglas de negocio que sobreviven a las elecciones de tecnología de almacenamiento
• Servicios que necesitan pruebas unitarias rápidas sin Docker
• Equipos donde los manejadores HTTP estaban acumulando cadenas SQL

Ejemplo de Trabajo

package app
 
import (
    "context"
    "errors"
    "fmt"
)
 
type Order struct {
    ID     string
    UserID string
    Total  int64
    Status string
}
 
var ErrNotFound = errors.New("not found")
 
type OrderRepo interface {
    Get(ctx context.Context, id string) (Order, error)
    Save(ctx context.Context, o Order) error
}
 
type OrderService struct {
    repo OrderRepo
}
 
func NewOrderService(repo OrderRepo) *OrderService {
    return &OrderService{repo: repo}
}
 
func (s *OrderService) Cancel(ctx context.Context, id string) error {
    o, err := s.repo.Get(ctx, id)
    if err != nil {
        return err
    }
    if o.Status == "shipped" {
        return fmt.Errorf("cannot cancel shipped order")
    }
    o.Status = "cancelled"
    return s.repo.Save(ctx, o)
}
 
// PostgresRepo vive en internal/storage; las pruebas usan memRepo.
type memRepo struct {
    data map[string]Order
}
 
func (m *memRepo) Get(_ context.Context, id string) (Order, error) {
    o, ok := m.data[id]
    if !ok { return Order{}, ErrNotFound }
    return o, nil
}
 
func (m *memRepo) Save(_ context.Context, o Order) error {
    m.data[o.ID] = o
    return nil
}
 
func Example() {
    svc := NewOrderService(&memRepo{data: map[string]Order{
        "1": {ID: "1", Status: "pending"},
    }})
    _ = svc.Cancel(context.Background(), "1")
}

Lo que esto demuestra:

• OrderService codifica la regla de cancelación
• OrderRepo es una interfaz estrecha con dos métodos
• El fake en memoria implementa el mismo contrato que Postgres
• Los errores de dominio permanecen en el servicio; el mapeo HTTP ocurre en otro lugar

Inmersión Profunda

Cómo Funciona

Manejador HTTP  -->  Servicio  -->  Repositorio  -->  base de datos/driver
     |                |               |
 transporte       negocio         persistencia

• Los manejadores analizan la entrada, llaman a un método de servicio, mapean errores a códigos de estado
• Los servicios componen repositorios y otros clientes (correo electrónico, facturación)
• Los repositorios mapean tipos de dominio a filas SQL o cargas útiles de API
• main une repositorios concretos en servicios y servicios en manejadores

Granularidad de la Interfaz

Manejo de Errores

• Los repositorios devuelven ErrNotFound o errores de driver envueltos
• Los servicios añaden significado de negocio (cannot cancel shipped order)
• Los manejadores mapean a 404, 409, 500 usando errors.Is / errors.As

Notas de Go

// Se integra en cmd/api/main.go
repo := postgres.NewOrderRepo(pool)
svc := app.NewOrderService(repo)
handler := httpapi.NewOrdersHandler(svc)

• Mantenga SQL fuera de los manejadores y servicios
• Pase context.Context a través de cada capa para cancelación y rastreo
• Evite devolver *sql.Rows de los repositorios - devuelva structs de dominio

Trampas

• Fuga de sql.DB a los servicios - El paquete de negocio importa database/sql y se vuelve in-testable. Solución: interfaz de repositorio en el paquete de servicio; SQL en internal/storage.
• El repositorio devuelve enteros de estado HTTP - Las preocupaciones de transporte infectan la capa de persistencia. Solución: devuelva errores; mapee en el manejador.
• Struct de servicio "dios" - Un tipo Service con 40 métodos refleja un paquete "dios". Solución: dividir por contexto delimitado (OrderService, BillingService).
• Interfaces con una sola implementación "para mocks" - Abstracción prematura sin un segundo backend. Solución: comience con un repositorio concreto; extraiga la interfaz cuando las pruebas o una segunda tienda lo necesiten.
• Contexto omitido en los métodos del repositorio - La cancelación y el rastreo se detienen en el límite del servicio. Solución: ctx como primer parámetro en cualquier lugar donde la E/S pueda bloquearse.
• Explosión de DTOs - Estructuras de API, DB y de dominio separadas para cada campo. Solución: comience con una sola estructura de dominio; agregue DTOs cuando las formas diverjan.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Patrones Go - fragmento de interfaz de repositorio
• Funciones Constructoras y APIs de Paquetes - integración en main
• Middleware y Patrones Decoradores - manejadores delgados
• Idiomas de Go: Composición Sobre Herencia - composición de interfaces

Versiones de Stack: Esta página fue escrita para Go 1.26.x (GC por defecto Green Tea, go fix modernizers - 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 en la compilación). cGJxcnRodnFyZi52YnxwdHZiNDQ2fDIwMjYwNw==