Arquitectura hexagonal (sin complicarla)

api-pedidos funciona, pero sus reglas de negocio están mezcladas con HTTP y con los nombres de los roles de Keycloak. En esta lección la reorganizas en arquitectura hexagonal: un dominio que no sabe nada de tokens, y Keycloak como un adaptador más. Desde fuera, nada cambia.

1. Por qué ahora

Mira internal/api/api.go del paso 12. Cada handler hace tres cosas a la vez: leer HTTP, decidir quién puede (con nombres de roles de Keycloak) y aplicar reglas de la tienda. Funciona, pero tiene costes concretos:

• Para comprobar la regla «un cliente solo ve sus pedidos» necesitas un JWT firmado y un servidor HTTP.
• Si el equipo de identidad renombra admin a tienda-admin, o los permisos pasan a venir de Entra ID (lección 12), tocas handlers repartidos por la API.
• Cambiar el almacén en memoria por PostgreSQL obliga a reescribir código que también decide permisos.

La arquitectura hexagonal (también llamada puertos y adaptadores) separa esas tres cosas. Aquí la aplicamos solo a api-pedidos, que es donde viven las reglas de negocio, y con el mínimo de piezas.

2. La idea en un dibujo

3. El dominio: permisos de la tienda, no roles de Keycloak

El paso clave es dejar de preguntar «¿tiene el rol admin?» dentro de la lógica, y preguntar «¿puede gestionar pedidos?». Los permisos son palabras de la tienda; quién los recibe lo decide el adaptador de identidad.

package pedidos

import "slices"

// Permission es algo que el dominio permite hacer. Son conceptos de la
// tienda, no de Keycloak: el adaptador de identidad decide qué roles o
// claims del token dan cada permiso.
type Permission string

const (
	PermBuy     Permission = "comprar"   // ver y crear pedidos propios
	PermManage  Permission = "gestionar" // ver todos los pedidos y cambiar su estado
	PermInvoice Permission = "facturar"  // listar pedidos de todos para facturarlos
)

// Actor es quien pide algo al dominio: una persona o un servicio.
type Actor struct {
	ID          string // identificador estable (el «sub»)
	Name        string
	Permissions []Permission
}

// Can indica si el actor tiene el permiso p.
func (a Actor) Can(p Permission) bool { return slices.Contains(a.Permissions, p) }

El almacenamiento es un puerto: una interfaz pequeña que el dominio necesita y que otro implementa.

package pedidos

import "context"

// Repository es el puerto de salida donde se guardan los pedidos. El dominio
// solo conoce esta interfaz; la implementación (en memoria, PostgreSQL…)
// vive en internal/adaptadores.
type Repository interface {
	// Get devuelve un pedido o ErrNotFound.
	Get(ctx context.Context, id int) (Order, error)
	// List devuelve los pedidos que cumplen el filtro, ordenados por número.
	List(ctx context.Context, f Filter) ([]Order, error)
	// Add guarda un pedido nuevo y le asigna número.
	Add(ctx context.Context, o Order) (Order, error)
	// Update guarda los cambios de un pedido existente (o ErrNotFound).
	Update(ctx context.Context, o Order) error
}

// Filter elige pedidos. Un campo vacío no filtra.
type Filter struct {
	Owner  string
	Status string
}

Los casos de uso reciben al Actor y aplican todas las reglas. Compara Get con el handler del paso 12: la regla «si es de otro, di que no existe» es la misma, pero ahora vive donde se puede probar sin HTTP ni tokens (lección 14).

// Get devuelve un pedido si es del actor o si el actor gestiona pedidos. Si
// es de otra persona, responde ErrNotFound, no ErrForbidden: así no revela
// qué pedidos existen.
func (s *Service) Get(ctx context.Context, a Actor, id int) (Order, error) {
	if !a.Can(PermBuy) && !a.Can(PermManage) {
		return Order{}, ErrForbidden
	}
	o, err := s.repo.Get(ctx, id)
	if err != nil {
		return Order{}, err
	}
	if o.Owner != a.ID && !a.Can(PermManage) {
		return Order{}, ErrNotFound
	}
	return o, nil
}

// Create registra un pedido a nombre del actor. El precio sale del catálogo:
// nunca lo decide quien compra.
func (s *Service) Create(ctx context.Context, a Actor, productID string, qty int) (Order, error) {
	if !a.Can(PermBuy) {
		return Order{}, ErrForbidden
	}
	p, ok := FindProduct(productID)
	if !ok {
		return Order{}, fmt.Errorf("%w: producto desconocido %q", ErrInvalid, productID)
	}
	if qty < 1 || qty > 10 {
		return Order{}, fmt.Errorf("%w: la cantidad debe estar entre 1 y 10", ErrInvalid)
	}
	return s.repo.Add(ctx, Order{
		Owner:     a.ID,
		Items:     fmt.Sprintf("%s ×%d", p.Name, qty),
		Total:     p.Price * float64(qty),
		Status:    "Pendiente",
		CreatedAt: s.now(),
	})
}

Los errores también son del dominio (ErrNotFound, ErrForbidden, ErrInvalid). El dominio no sabe que existen el 404 o el 403.

4. Keycloak como adaptador

Todo lo que sabe api-pedidos de Keycloak cabe ahora en un archivo. Valida el token con el apiauth de la lección 5 (no cambia) y traduce roles a permisos:

// Package keycloak es el adaptador de identidad de api-pedidos: valida el
// access token (con apiauth) y traduce lo que dice Keycloak (roles de realm,
// roles de client, scopes) a lo que entiende el dominio (pedidos.Actor).
//
// Es el único sitio de api-pedidos que conoce los nombres de los roles. Si
// mañana el rol «admin» se llama «tienda-admin», o los permisos vienen de
// otro proveedor, solo cambia este archivo.
package keycloak

import (
	"net/http"

	"tienda/internal/apiauth"
	"tienda/internal/pedidos"
)

// Identity implementa rest.Identity con access tokens de Keycloak.
type Identity struct {
	Verifier *apiauth.Verifier
}

// Middleware exige un access token válido (401 si no lo hay).
func (i Identity) Middleware(next http.Handler) http.Handler { return i.Verifier.Middleware(next) }

// RequireScope exige un scope en el token (403 insufficient_scope si falta).
func (Identity) RequireScope(scope string) func(http.Handler) http.Handler {
	return apiauth.RequireScope(scope)
}

// Actor devuelve quién llama, ya en términos del dominio.
func (Identity) Actor(r *http.Request) pedidos.Actor {
	p := apiauth.FromContext(r.Context())
	if p == nil {
		return pedidos.Actor{}
	}
	return ActorFrom(p)
}

// ActorFrom traduce un token verificado a un Actor del dominio.
func ActorFrom(p *apiauth.Principal) pedidos.Actor {
	a := pedidos.Actor{ID: p.Subject, Name: p.Username}
	if p.HasRole("cliente") || p.HasRole("admin") {
		a.Permissions = append(a.Permissions, pedidos.PermBuy)
	}
	if p.HasRole("admin") {
		a.Permissions = append(a.Permissions, pedidos.PermManage)
	}
	for _, r := range p.APIRoles { // roles de client de api-pedidos (servicios)
		if r == "facturar" {
			a.Permissions = append(a.Permissions, pedidos.PermInvoice)
		}
	}
	return a
}

5. El adaptador REST

REST define qué necesita saber de quien llama (su puerto Identity), registra las rutas y traduce errores del dominio a HTTP:

// Register añade las rutas de la API. Aquí solo se exige un token válido y,
// donde toca, el scope (lo que la APLICACIÓN puede hacer en nombre del
// usuario). Lo que la PERSONA puede hacer lo decide el dominio.
func Register(mux *http.ServeMux, svc *pedidos.Service, id Identity) {
	h := &handlers{svc: svc, id: id}
	escribir := id.RequireScope("pedidos:escribir")
	auth := func(f http.HandlerFunc) http.Handler { return id.Middleware(f) }

	mux.Handle("GET /pedidos", auth(h.list))
	mux.Handle("GET /pedidos/{id}", auth(h.get))
	mux.Handle("POST /pedidos", id.Middleware(escribir(http.HandlerFunc(h.create))))
	mux.Handle("GET /admin/pedidos", auth(h.listAll))
	mux.Handle("PATCH /admin/pedidos/{id}", id.Middleware(escribir(http.HandlerFunc(h.setStatus))))
	mux.Handle("GET /facturacion/pedidos", auth(h.listByStatus))
}

// writeError traduce los errores del dominio a respuestas HTTP.
func writeError(w http.ResponseWriter, err error) {
	switch {
	case errors.Is(err, pedidos.ErrNotFound):
		jsonhttp.Error(w, http.StatusNotFound, "not_found", "pedido no encontrado")
	case errors.Is(err, pedidos.ErrForbidden):
		jsonhttp.Error(w, http.StatusForbidden, "forbidden", "no tienes permiso para esto")
	case errors.Is(err, pedidos.ErrInvalid):
		jsonhttp.Error(w, http.StatusBadRequest, "invalid_request", err.Error())
	default:
		jsonhttp.Error(w, http.StatusInternalServerError, "server_error", "error interno")
	}
}

El dominio ya no lleva etiquetas JSON: el formato de la respuesta (orderJSON) es del adaptador. Es el mismo que antes, campo por campo, porque tienda-web y facturacion dependen de él.

Dónde va cada comprobación

¿Por qué el scope no entra en el dominio? Porque no habla de la persona sino de la aplicación que actúa en su nombre (lección 6): es un asunto del protocolo OAuth, y su respuesta correcta (WWW-Authenticate con insufficient_scope) también. Se queda en el borde.

6. main conecta las piezas

func main() {
	issuer := env("OIDC_ISSUER", "http://localhost:8080/realms/tienda")
	audience := env("API_AUDIENCE", "api-pedidos") // client ID de la API en Keycloak
	addr := env("ADDR", ":8081")

	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	verifier, err := apiauth.NewVerifier(ctx, issuer, audience)
	if err != nil {
		log.Fatal(err) // ¿Keycloak está arrancado?
	}

	// Conectar las piezas: repositorio (salida) → dominio → REST (entrada),
	// con Keycloak como adaptador de identidad.
	svc := pedidos.NewService(memoria.NewWithSamples())
	mux := http.NewServeMux()
	rest.Register(mux, svc, keycloak.Identity{Verifier: verifier})

	srv := &http.Server{
		Addr:              addr,
		Handler:           logRequests(mux),
		ReadHeaderTimeout: 5 * time.Second,
	}
	log.Printf("api-pedidos escuchando en http://%s (issuer %s, audiencia %s)", listenHost(addr), issuer, audience)
	log.Fatal(srv.ListenAndServe())
}

Cambiar el almacén por PostgreSQL sería escribir adaptadores/postgres (que implemente Repository) y cambiar una línea aquí. Ni el dominio ni REST se enteran.

7. Probarlo: desde fuera, nada cambia

Es un refactor: el comportamiento debe ser idéntico. Arranca todo como en el paso 12 (desde tienda/pasos/paso-13) y ejecuta el comprobador: debe dar lo mismo que antes.

go -C tools/comprobar run . -paso 13 -servicios

Las dos diferencias visibles son mensajes: un cliente que entra en /admin/pedidos recibe "no tienes permiso para esto" en lugar de "hace falta uno de estos roles: [admin]", y ya no le contamos qué rol falta. Los códigos de estado son los mismos.

8. Lo que no hicimos (a propósito)

La arquitectura hexagonal se puede llevar mucho más lejos. Aquí no lo hacemos, y conviene saber por qué:

• No hay interfaz para el servicio. REST usa *pedidos.Service directamente. Una interfaz solo haría falta si hubiera dos implementaciones; para los tests basta con un repositorio en memoria (lección 14).
• tienda-web y facturacion siguen como estaban. Son casi solo adaptadores (pantallas y llamadas a otros servicios): tienen poca lógica que proteger.
• Sin capas «application», «infrastructure», DTO por caso de uso… Tres carpetas de adaptadores y un paquete de dominio bastan para este tamaño. Si el dominio crece mucho, ya habrá tiempo de dividirlo.

Ejercicios

// internal/pedidos/actor.go
PermReport Permission = "informar" // ver todos los pedidos, sin cambiarlos

// internal/pedidos/servicio.go — All
if !a.Can(PermManage) && !a.Can(PermReport) {
	return nil, ErrForbidden
}

// internal/adaptadores/keycloak/keycloak.go — ActorFrom, dentro del bucle de APIRoles
if r == "informar" {
	a.Permissions = append(a.Permissions, pedidos.PermReport)
}

Errores comunes