Fundamentos de Arquitectura en Go

10 ejemplos para empezar con Arquitectura - 7 básicos y 3 intermedios.

Prerrequisitos

• Go 1.26.x instalado (go version).
• Crea un módulo: mkdir archdemo && cd archdemo && go mod init example.com/archdemo.
• Los ejemplos solo usan la biblioteca estándar a menos que se indique lo contrario.

Ejemplos Básicos

1. Diseño de servicio estándar

Binarios separados, implementación privada y código de biblioteca pública.

archdemo/
  cmd/api/main.go
  internal/service/
  internal/store/
  pkg/api/          # tipos de API compartidos opcionales

• cmd/ contiene paquetes main - una carpeta por binario.
• internal/ oculta la implementación a importadores externos.
• pkg/ es opcional para bibliotecas que deseas que otros módulos importen.

Relacionado: Arquitectura en Go: Interfaces Pequeñas, Dependencias Explícitas - por qué importan los límites

2. Inyección de constructor

Pasa dependencias explícitamente en lugar de globales.

package service
 
type Greeter struct {
    prefix string
}
 
func New(prefix string) *Greeter {
    return &Greeter{prefix: prefix}
}
 
func (g *Greeter) Hello(name string) string {
    return g.prefix + ", " + name
}

• New valida las entradas y devuelve una estructura lista.
• Los llamadores controlan la configuración; las pruebas pasan fakes sin mutar globales.
• Mantén la superficie exportada pequeña - los campos pueden permanecer sin exportar.

Relacionado: Inyección de Dependencias: wire, dig y Cableado Manual - escalando el cableado más allá del main hecho a mano

3. Interfaz del lado del consumidor

Define el contrato donde se utiliza.

package handler
 
import "context"
 
type Lister interface {
    List(ctx context.Context) ([]string, error)
}
 
type HTTP struct {
    svc Lister
}
 
func New(svc Lister) *HTTP {
    return &HTTP{svc: svc}
}

• Lister tiene un método - fácil de simular en pruebas de manejador.
• Los tipos de almacenamiento concretos viven en internal/store sin importar HTTP.
• Las interfaces pertenecen cerca del consumidor, no siempre en el proveedor.

4. Manejador HTTP ligero

Traduce HTTP a llamadas de dominio; sin SQL en manejadores.

package handler
 
import (
    "encoding/json"
    "net/http"
)
 
func (h *HTTP) List(w http.ResponseWriter, r *http.Request) {
    items, err := h.svc.List(r.Context())
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    _ = json.NewEncoder(w).Encode(items)
}

• Usa r.Context() para cancelación y plazos.
• Mapea errores a códigos de estado de manera consistente (envuelve errores de dominio en el borde).
• La codificación JSON permanece en la capa del adaptador.

Relacionado: Capas de Manejador-Servicio-Repositorio - flujo completo de tres capas

5. Capa de servicio con errores de dominio

Las reglas de negocio viven entre HTTP y el almacenamiento.

package service
 
import (
    "context"
    "fmt"
)
 
type Repo interface {
    All(ctx context.Context) ([]string, error)
}
 
type Service struct {
    repo Repo
}
 
func New(repo Repo) *Service {
    return &Service{repo: repo}
}
 
func (s *Service) List(ctx context.Context) ([]string, error) {
    items, err := s.repo.All(ctx)
    if err != nil {
        return nil, fmt.Errorf("list: %w", err)
    }
    return items, nil
}

• Los servicios envuelven errores del repositorio con contexto (%w) para observabilidad.
• List satisface la interfaz Lister del manejador del ejemplo 3.
• Los servicios permanecen ignorantes de los códigos de estado HTTP.

6. Límite del repositorio

Aísla la persistencia detrás de una API pequeña.

package store
 
import "context"
 
type Memory struct {
    data []string
}
 
func (m *Memory) All(ctx context.Context) ([]string, error) {
    return append([]string(nil), m.data...), nil
}

• Cambiar de memoria a Postgres cambia un paquete.
• Se acepta el contexto incluso si este ejemplo ignora la cancelación - la E/S real debería respetarlo.
• Devuelve tipos amigables al dominio, no filas del driver, desde los repositorios.

7. Raíz de composición en main

Conecta tipos concretos solo en cmd/api/main.go.

package main
 
import (
    "log"
    "net/http"
 
    "example.com/archdemo/internal/handler"
    "example.com/archdemo/internal/service"
    "example.com/archdemo/internal/store"
)
 
func main() {
    repo := &store.Memory{data: []string{"alpha", "beta"}}
    svc := service.New(repo)
    h := handler.New(svc)
 
    mux := http.NewServeMux()
    mux.HandleFunc("GET /items", h.List)
    log.Fatal(http.ListenAndServe(":8080", mux))
}

• main es el único lugar que conoce todos los tipos concretos.
• El enrutamiento usa patrones conscientes de métodos de Go 1.22+ en ServeMux.
• Añadir una base de datos significa cambiar el cableado aquí, no los paquetes de negocio.

Ejemplos Intermedios

8. Aplicación de internal/

Los paquetes bajo internal/ no pueden ser importados fuera del árbol padre.

// internal/store/pg.go
package store
 
// Solo example.com/archdemo/... puede importar este paquete.
type PG struct{}

• El compilador rechaza importaciones externas de rutas internal.
• Úsalo para código que no es una promesa semver para otros módulos.
• Las bibliotecas públicas pertenecen a rutas no internas con estabilidad documentada.

Relacionado: Arquitectura Limpia y Hexagonal en Go - puertos en el borde del dominio

9. Paquete de funcionalidad en lugar de carpetas solo de capa

Organiza por capacidad cuando los dominios son claros.

internal/
  billing/
    service.go
    handler.go
    postgres.go
  shipping/
    ...

• Las carpetas de funcionalidad reducen los conflictos de fusión entre equipos.
• Los kernels compartidos (internal/platform/) contienen ayudantes de logging y autenticación.
• Divide en servicios solo cuando los límites de lanzamiento y escala lo justifiquen.

Relacionado: Monolito vs Microservicios en Go - cuándo dividir binarios

10. Plantilla ADR para una decisión de límite

Registra por qué elegiste un diseño antes de que el debate se repita.

# ADR 0003: Capas de manejador-servicio-repositorio
 
## Estado
Aceptado
 
## Contexto
Nueva API HTTP; el equipo quiere lógica de negocio testeable.
 
## Decisión
Usar paquetes de manejador / servicio / repositorio con interfaces del consumidor.
 
## Consecuencias
Más paquetes; cableado explícito en main; pruebas unitarias más fáciles.

• Almacena ADRs en docs/adr/ o .adr/ en la raíz del repositorio.
• Vincula las decisiones a las restricciones específicas de Go (sin contenedor DI en stdlib).
• Revisa cuando la carga, la topología del equipo o los requisitos de cumplimiento cambien.

Relacionado: Registros de Decisiones de Arquitectura para Equipos de Go - decisiones clasificadas para servicios de Go

Enlaces Relacionados Externos

• Tutoriales de Go (Oficial) - Tutoriales oficiales en varias partes.
• Effective Go - Guía oficial para escribir Go claro e idiomático.
• Cursos de Go en Boot.dev - Rutas de aprendizaje interactivas basadas en proyectos de Go.
• Get Programming with Go (Manning) - Nathan Youngman & Roger Peppé.
• Learning Go (2nd Edition) - Jon Bodner.

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