Has estado ahí. Tu microservicio recibe la respuesta de un servicio externo y no es un error técnico: no hay stack trace, no hay excepción que capturar, no hay un HTTP 500. Es algo más sutil, un estado de negocio que dice ahora no. CANCELADO. NO DISPONIBLE. El servicio está vivo, responde, simplemente no puede atender tu solicitud en este momento.

Poco después llega la instrucción del negocio: inténtalo más tarde. Y ahí empieza el problema real.

«Más tarde» suena razonable hasta que se traduce a un sistema distribuido. ¿Cuánto es más tarde? ¿Quién guarda esa intención mientras transcurre? ¿Qué ocurre si el proceso que debía esperar se reinicia a mitad de camino, o si el mismo mensaje se entrega dos veces y el reintento se duplica? ¿Y si llegan mil respuestas CANCELADO en el mismo minuto y todas deben esperar a la vez sin que nadie gaste recursos esperando?

Lo que parecía un detalle de implementación es un problema de diseño con nombre, con componentes y con varias formas de salir mal si se improvisa. Este artículo recorre ese diseño completo: por qué la espera debe ser un dato y no un proceso, qué piezas la sostienen, cómo se evita que un fallo en cualquier punto produzca duplicados o transacciones atascadas, y cómo se concreta todo en AWS, sin olvidar que el patrón es más importante que cualquier servicio.

Por qué no basta con dormir el proceso

El primer instinto suele ser retener el proceso. Un Thread.sleep, un hilo bloqueado, o un mensaje que no se confirma para que el broker lo reentregue pasado un rato. Es tentador porque funciona en local, con poco volumen y en las demostraciones donde los casos borde son teóricos.

El costo, sin embargo, crece en silencio: un proceso que espera sigue siendo un proceso. Con diez esperas simultáneas el impacto es marginal. Con mil, cifra que cualquier sistema bajo carga real alcanza sin esfuerzo, la infraestructura paga por tiempo en el que no trabaja. Escalar horizontalmente no ayuda, porque solo multiplica los procesos igualmente bloqueados.

La raíz del problema es conceptual. Se está modelando la espera como una actividad, cuando en realidad es un estado. Un proceso dormido consume memoria, hilos y conexiones, mientras que un registro en una base de datos no consume nada mientras espera: existe, y el sistema lo consulta cuando necesita saber qué hacer.

De esa distinción nace el patrón de reintento diferido duradero. Consiste en convertir la intención de «volver a intentarlo en el instante T» en información persistente, en lugar de mantenerla como tiempo de ejecución.

Tres preguntas, tres responsabilidades

Para que la espera viva en el sistema sin ocupar procesos hay que responder tres preguntas distintas, y conviene que cada una tenga un dueño distinto. La primera es cuándo debe ocurrir el reintento: alguien tiene que conservar la intención «actúa en este instante» y cumplirla aunque pasen horas. La segunda es si el reintento todavía tiene sentido cuando el momento llegue, porque la transacción pudo resolverse por otra vía mientras esperaba. La tercera es cómo garantizar que el reintento se ejecute una sola vez, aunque el sistema falle en el medio.

El diseño reparte esas responsabilidades entre unas pocas piezas. Tres colas desacoplan a los participantes: una recibe las respuestas del servicio externo, otra entrega los eventos de reintento cuando el planificador los dispara, y una tercera lleva las solicitudes hacia el servicio externo. Un almacén de estado funciona como fuente de verdad: guarda el estado de cada transacción, el intento en curso y el instante previsto del próximo disparo, y solo acepta cambios condicionales. Un planificador diferido conserva la intención de «entregar este evento en el instante T» sin mantener ningún proceso ocupado. Dos manejadores ejecutan la lógica de negocio: el manejador de respuestas (lo llamaré A) interpreta lo que dice el servicio externo y decide si hay que planificar un reintento, y el manejador de reintentos (B) recibe el evento del planificador, comprueba que siga siendo válido y publica la nueva solicitud. Por último, las colas de mensajes fallidos (DLQ, por dead-letter queue) aíslan lo que no se pudo procesar o entregar y levantan alertas.

Lo que hace correcto al conjunto no es la sofisticación de cada pieza, sino que cada una resuelve exactamente una cosa y desconoce las demás. El planificador no sabe nada de negocio, el almacén no sabe cuándo disparar y los manejadores no se conocen entre sí. Esa ignorancia mutua permite que el sistema se recupere de un fallo sin que ninguna pieza tenga que coordinarse con otra.

Hay además una decisión que protege el modelo existente: el planificador nunca habla directamente con el servicio externo. Publica en la cola de reintento y es B quien decide qué hacer con ese evento. Así no se abren nuevos endpoints ni se introducen caminos de ejecución paralelos. El planificador responde al cuándo y la lógica de negocio sigue viviendo donde siempre vivió.

El siguiente diagrama sigue el recorrido de un mensaje desde que el servicio externo responde CANCELADO hasta que se publica una nueva solicitud, o se descarta si ya no hace falta. Las líneas punteadas marcan rutas de fallo.

flowchart TD
    EXT["Servicio externo"] --> QR[["Cola de respuesta"]]
    QR --> A["Manejador de respuestas (A)"]
    QR -.->|mensajes fallidos| DLQ0[["DLQ de respuesta"]]
    A <--> DB[("Almacén de estado")]

    A -->|EXITOSO| OK["Flujo habitual"]
    A -->|CANCELADO, intentos agotados| FAIL["Marcar FALLIDA<br/>+ alerta"]
    A -->|"CANCELADO, intentos disponibles<br/>(1. PLANIFICANDO + proximo_disparo<br/>2. crear planificación)"| PL["Planificador diferido<br/>(espera creciente)"]

    PL --> QRE[["Cola de reintento"]]
    PL -.->|falla de entrega| DLQ1[["DLQ del planificador"]]
    QRE -.->|mensajes fallidos| DLQ2[["DLQ de reintento"]]

    QRE --> B["Manejador de reintentos (B)"]
    B <--> DB
    B -->|obsoleto o ya procesado| DROP["Descartar"]
    B -->|sigue pendiente| QS[["Cola de solicitud"]]
    QS --> EXT

Una convención pequeña que evita errores grandes

Antes de hablar de estados hay que fijar un detalle de numeración que parece trivial y, sin embargo, es responsable de errores muy difíciles de rastrear. El intento = 1 es la solicitud original, la primera vez que el microservicio contacta al servicio externo. El primer reintento es el intento = 2, el segundo es el intento = 3, y así sucesivamente. El campo max_intentos cuenta la solicitud original, no solo los reintentos: con max_intentos = 4 hay una solicitud original y hasta tres reintentos.

Si esto no queda escrito, el error de off-by-one aparece tarde y en producción. Una transacción hace un reintento de más porque alguien contó desde cero, o se detiene antes de tiempo porque otro incluyó el original en el conteo de reintentos. Son bugs silenciosos: el sistema funciona, pero no se comporta como el negocio espera.

El almacén de estado y las reglas del juego

Con la numeración clara, el siguiente paso es definir qué guarda el almacén para cada transacción. Son pocos campos, pero cada uno tiene una razón de ser.

La razón de modelar así es que la corrección de un flujo distribuido no está en el orden de los pasos. La trampa más común al diseñar reintentos es suponer que, si cada paso se ejecuta en el orden correcto, el resultado será correcto. Pero los mensajes se reentregan, se duplican, llegan tarde, o el proceso se cae a mitad de una operación y reaparece con el mismo mensaje en la cola. En esas condiciones, la única forma de mantener la consistencia es trabajar con estados explícitos y permitir cada transición solo si el estado actual es exactamente el esperado. Si no coincide, el mensaje es obsoleto o duplicado, y se descarta sin ejecutar nada. En DynamoDB esto se logra con una ConditionExpression, y en una base relacional con un UPDATE ... WHERE estado = :esperado AND intento_actual = :n.

La vida de una transacción discurre así. Nace en EN_CURSO cuando se envía la solicitud original. Si la respuesta es exitosa, termina en EXITOSA. Si llega un CANCELADO y los intentos están agotados, termina en FALLIDA. Pero si todavía quedan intentos, pasa primero a PLANIFICANDO, un estado intermedio que significa «se decidió reintentar, aunque la planificación puede no existir aún», y luego a PLANIFICADO cuando la planificación queda confirmada. Cuando llega el evento, la transacción pasa a ENVIANDO mientras se publica la nueva solicitud y vuelve a EN_CURSO, ya con el intento incrementado, cuando la solicitud sale. Si mientras espera la transacción se resuelve por otra vía (un proceso manual, una corrección externa), puede pasar directamente a EXITOSA.

stateDiagram-v2
    [*] --> EN_CURSO: solicitud enviada (intento n)
    EN_CURSO --> EXITOSA: respuesta EXITOSO
    EN_CURSO --> FALLIDA: CANCELADO y n = max_intentos
    EN_CURSO --> PLANIFICANDO: CANCELADO y n < max_intentos<br/>(guarda intento_siguiente y proximo_disparo)
    PLANIFICANDO --> PLANIFICADO: planificación confirmada
    PLANIFICANDO --> ENVIANDO: evento llega antes de confirmar
    PLANIFICADO --> ENVIANDO: llega el evento (intento n+1)
    ENVIANDO --> ENVIANDO: reentrega retoma la publicación
    ENVIANDO --> EN_CURSO: solicitud publicada (intento_actual = n+1)
    PLANIFICANDO --> EXITOSA: resuelta por otra vía
    PLANIFICADO --> EXITOSA: resuelta por otra vía
    EXITOSA --> [*]
    FALLIDA --> [*]

Cada flecha del diagrama es, en realidad, una condición: «pasa a este estado solo si el estado actual es aquel y el número de intento es este». Si cualquiera de las dos cosas falla, la operación no se ejecuta, y esa regla aplicada sin excepciones es lo que hace correcto al sistema aunque los mensajes lleguen duplicados o desordenados.

Conviene decir que la regla de «resuelta por otra vía» es una decisión, no una verdad universal. Aquí se permite desde PLANIFICANDO y PLANIFICADO, pero no desde ENVIANDO: en ese punto la solicitud ya está en vuelo y será la respuesta del servicio externo la que decida el destino. Otros equipos podrían optar por permitirla también desde ENVIANDO e intentar cancelar la solicitud. Lo importante es elegir y dejarlo documentado.

Tres escrituras que no son atómicas

Cuando A recibe un CANCELADO y decide planificar un reintento, tiene que hacer tres cosas: actualizar el almacén de estado, crear la planificación y confirmar el mensaje de la cola. Ninguna de las tres está conectada a las otras por una transacción. Si el proceso cae entre dos de ellas, el mensaje se reentregará y A deberá poder retomar desde donde quedó, sin duplicar ni perder nada.

La primera versión intuitiva de este flujo calculaba la fecha del reintento en el momento de crear la planificación. Funciona hasta que el proceso cae justo después de crearla y antes de anotar nada: la reentrega vuelve a calcular, y como la espera incluye una variación aleatoria, obtiene un instante distinto y crea una segunda planificación para el mismo intento. El negocio terminaba viendo reintentos duplicados sin que ningún componente hubiera «fallado» en sentido estricto.

La solución es cuestión de orden. Cuando A detecta un CANCELADO con intentos disponibles, lo primero que hace es una transición condicional de EN_CURSO(n) a PLANIFICANDO, y en esa misma escritura guarda intento_siguiente = n+1 y el proximo_disparo, el instante exacto del reintento. Solo después crea la planificación, usando ese instante ya persistido. Si el proceso cae entre ambos pasos, la reentrega encuentra la transacción en PLANIFICANDO, lee el proximo_disparo guardado e intenta crear la planificación de nuevo. Si ya existía, el planificador responde con un error de conflicto que A trata como éxito, porque la planificación está creada con el instante correcto. El resultado es el mismo: un único reintento programado.

El flujo completo de A queda así. Primero descarta las respuestas tardías: si el número de intento de la respuesta no coincide con intento_actual, pertenece a un intento viejo y se confirma sin más. Si es EXITOSO y la transacción está EN_CURSO, pasa a EXITOSA. Si es CANCELADO y n = max_intentos, pasa a FALLIDA y se emite una alerta de negocio. Y si es CANCELADO con intentos disponibles, ejecuta la secuencia descrita: guardar el instante, crear la planificación, marcar PLANIFICADO y confirmar el mensaje. Si en cualquier reentrega la transacción ya está más adelante, en PLANIFICADO o ENVIANDO, significa que otra ejecución ya hizo el trabajo: A confirma el mensaje y termina. Del mismo modo, si la transición final a PLANIFICADO falla porque el estado ya avanzó, es un éxito, no un error.

sequenceDiagram
    participant Q as Cola de respuesta
    participant A as Manejador A
    participant DB as Almacén de estado
    participant PL as Planificador
    Q->>A: CANCELADO (intento n)
    A->>DB: EN_CURSO(n) → PLANIFICANDO + proximo_disparo
    Note over A,DB: Punto de fallo 1
    A->>PL: Crear planificación (nombre determinista)
    Note over A,PL: Punto de fallo 2
    PL-->>A: OK o conflicto (= éxito)
    A->>DB: PLANIFICANDO → PLANIFICADO
    Note over A,DB: Punto de fallo 3
    A->>Q: confirmar mensaje

Cuando el evento llega: ejecutar una sola vez

Horas después, el planificador dispara el evento y este aterriza en la cola de reintento, donde B lo recoge. Tanto el planificador como la cola ofrecen entrega al menos una vez, lo cual significa que el mismo evento puede llegar dos veces. B tiene que producir el mismo resultado en ambos casos, y para ello usa las mismas transiciones condicionales que A.

Al recibir el evento, B lee la transacción. Si el intento del evento no coincide con intento_siguiente, el evento es obsoleto y se descarta. Si coincide, mira el estado: desde PLANIFICADO o PLANIFICANDO intenta la transición a ENVIANDO; si ya está en EN_CURSO, EXITOSA o FALLIDA, el mensaje es un duplicado de un procesamiento terminado y se descarta. Una vez en ENVIANDO, publica la nueva solicitud en la cola del servicio externo con una clave de idempotencia que combina el identificador de la transacción con el número de intento (por ejemplo, TX-100200#2). Por último, la transición de ENVIANDO a EN_CURSO fija intento_actual = n+1, limpia intento_siguiente y cierra el ciclo.

Aquí aparecieron dos dificultades.

La primera es una carrera. Si el evento llega mientras la transacción sigue en PLANIFICANDO, porque A fue lento, cayó o su reentrega se demoró, un B que exigiera PLANIFICADO descartaría el evento, y después A marcaría PLANIFICADO sin que nadie volviera a disparar el reintento. La transacción quedaría esperando un evento que ya pasó. La salida es que B acepte también PLANIFICANDO como estado de partida, y que A trate como éxito el fallo condicional que encontrará después.

La segunda es más sutil. Si B cae después de pasar a ENVIANDO y antes de publicar, la reentrega encuentra la transacción en ENVIANDO. Con una regla ingenua de «si el estado no es el esperado, descartar», ese mensaje se tiraría y la transacción quedaría atascada para siempre, sin solicitud y sin nadie que la reintente. Por eso, cuando B encuentra ENVIANDO con el intento correcto, no descarta: retoma. Vuelve a publicar con la misma clave de idempotencia y completa la transición a EN_CURSO.

Esa decisión tiene un precio que hay que aceptar con los ojos abiertos. Si dos entregas del mismo evento llegan en paralelo, ambas pueden publicar la solicitud. Es inocuo únicamente porque el servicio externo descarta el duplicado gracias a la clave de idempotencia. Esa es una precondición del patrón, no un detalle: si el servicio externo no respeta la clave, el diseño necesita el patrón outbox. En él, la solicitud a publicar se guarda en el almacén junto con la transición de estado, y un publicador independiente se encarga de enviarla de forma fiable. Es más costoso de construir, pero elimina del todo la ventana entre publicar y confirmar.

sequenceDiagram
    participant PL as Planificador
    participant Q as Cola de reintento
    participant B as Manejador B
    participant DB as Almacén de estado
    participant QS as Cola de solicitud
    PL->>Q: evento (intento n+1)
    Q->>B: entrega del evento
    B->>DB: PLANIFICADO o PLANIFICANDO → ENVIANDO
    Note over B,DB: Punto de fallo 1
    B->>QS: publicar (clave transaccion_id#n+1)
    Note over B,QS: Punto de fallo 2
    B->>DB: ENVIANDO → EN_CURSO (intento_actual = n+1)
    Note over B,DB: Punto de fallo 3
    B->>Q: confirmar mensaje

Una espera que crece para no presionar siempre igual

Hay una pregunta que todavía no hemos contestado: cuánto hay que esperar. Si la causa del CANCELADO persiste, porque el servicio externo tiene un problema que tarda en resolverse, reintentar con el mismo intervalo cada vez aplica la misma presión sin darle tiempo real de recuperarse. La espera debería crecer. La fórmula, configurable, es la siguiente:

espera(k) = min( base × factor^(k-1) , tope ) × (1 + u),   u ∈ [-jitter, +jitter]

Aquí k es el número de reintento (tras fallar el intento n, se usa k = n), base es la espera antes del primer reintento, factor es cuánto crece en cada paso, tope es el máximo de la espera nominal y jitter es la variación aleatoria relativa. Con valores típicos (base = 2 h, factor = 2, tope = 24 h, jitter = ±10 %), una transacción con max_intentos = 4 queda así:

Un matiz que suele pasarse por alto: en la fórmula, la variación se aplica después del tope, de modo que la espera real puede llegar a tope × 1,1, es decir, 26,4 horas con estos valores. Si el negocio necesita un máximo estricto, hay que recortar de nuevo tras aplicar la variación. Cualquiera de las dos opciones es válida, siempre que esté documentada.

El jitter merece su propio párrafo porque no es un adorno. Imagina que llegan mil respuestas CANCELADO en el mismo minuto, por una caída momentánea del servicio externo. Si todas calculan exactamente la misma espera, sus reintentos se disparan al mismo instante horas después y golpean al servicio en ráfaga, justo cuando intentaba recuperarse. La variación aleatoria dispersa esa ráfaga a lo largo de un intervalo, y reparte la carga de forma natural.

Hay, además, una decisión con impacto directo en la corrección: el jitter se calcula en la aplicación, no se delega al planificador. Así el proximo_disparo, con su variación ya incorporada, queda registrado en el almacén. Si el proceso falla y el mensaje se reentrega, la planificación se recrea con exactamente el mismo instante, y el comportamiento es determinista aunque el proceso se haya reiniciado.

Esta política tampoco tiene por qué ser uniforme. No todo CANCELADO representa la misma situación de negocio: algunos justifican esperas cortas y otros largas, y el criterio puede depender del tipo de transacción, del cliente o del motivo concreto del rechazo.

Proteger al servicio que se quiere recuperar

El jitter ayuda, pero no es suficiente si el volumen es muy alto o si el servicio externo está en un estado delicado. B debería incorporar tres controles adicionales.

El primero es limitar su propia concurrencia al publicar en la cola de solicitud. Si B puede procesar cien eventos por segundo pero el servicio externo solo absorbe diez, el límite debe vivir en B y no depender de que el servicio resista.

El segundo es un cortacircuitos (circuit breaker). Si el servicio está claramente degradado, porque responde lento, con errores o directamente no responde, tiene más sentido pausar o reprogramar los reintentos que seguir gastando el presupuesto de max_intentos. Un fallo por indisponibilidad técnica no equivale a un CANCELADO de negocio, y tratarlos igual acorta artificialmente la vida de una transacción que aún podría resolverse. Conviene advertir que la máquina de estados que hemos descrito no modela esta transición; hacerlo implicaría permitir, por ejemplo, volver de PLANIFICADO o ENVIANDO a PLANIFICANDO conservando intento_siguiente y fijando un nuevo proximo_disparo, con un nombre de planificación que incluya un sufijo de secuencia para evitar conflictos con el anterior.

El tercero es la cancelación proactiva de planificaciones. Si una transacción se resuelve por otra vía y todavía tiene una planificación pendiente, el sistema es correcto de todas formas: cuando el planificador dispare, B encontrará un estado distinto de los esperados y descartará el evento. Pero eliminar la planificación en cuanto la transacción se resuelve es una buena práctica, porque reduce ruido, eventos inútiles y costo.

Qué pasa cuando algo falla en el camino

La prueba real de un diseño así no es el flujo feliz, sino lo que ocurre cuando algo se rompe entre dos operaciones que no son atómicas. Recorrer los fallos relevantes es la mejor manera de comprobar que las reglas anteriores se sostienen.

El patrón se repite en todas las filas: el almacén de estado, con sus transiciones condicionales, actúa como árbitro. Cualquier operación que llegue cuando el estado no es el esperado simplemente no tiene efecto.

Hay un caso que esta tabla deja fuera a propósito, y es el de los mensajes que terminan en una DLQ. Un mensaje que cae allí significa que la transacción quedó detenida en un estado intermedio, y cada cola cuenta una historia diferente. La DLQ de respuesta indica que A falló repetidamente con una respuesta, y la transacción quedó en EN_CURSO o PLANIFICANDO. La DLQ del planificador indica que el planificador no pudo entregar el evento a la cola, y la transacción espera en PLANIFICADO. La DLQ de reintento indica que B falló repetidamente con un evento que sí llegó, y la transacción puede estar en PLANIFICANDO, PLANIFICADO o ENVIANDO. En los tres casos, el procedimiento es el mismo: diagnosticar la causa, corregirla y reenviar el mensaje a su cola de origen. Como los manejadores son idempotentes, reprocesar es seguro. Toda DLQ debería tener una alarma que salte con el primer mensaje, porque cualquiera de ellos es una incidencia.

Aun así, un diseño serio no debería depender únicamente de que alguien mire las DLQ. Por eso conviene sumar un reconciliador, un proceso periódico que busca transacciones detenidas en un estado intermedio durante más de un umbral razonable (por ejemplo, el doble de la latencia máxima esperada). Si encuentra una en PLANIFICANDO, reintenta la creación de la planificación con el proximo_disparo guardado. Si encuentra una en PLANIFICADO con el instante muy pasado, publica directamente el evento en la cola de reintento. Si la encuentra en ENVIANDO, republica el evento para que B retome. Como todas esas acciones pasan por los mismos manejadores idempotentes, el reconciliador no introduce riesgos nuevos. Para ejecutarlo de forma eficiente en DynamoDB hace falta un índice secundario por estado y actualizado_en.

Llevarlo a AWS

Con los conceptos claros, el mapeo a servicios de AWS es casi directo, porque cada componente lógico tiene un equivalente natural. Las colas de solicitud, respuesta y reintento son colas Amazon SQS de tipo Standard. El planificador diferido es Amazon EventBridge Scheduler, usando planificaciones de una sola ejecución (one-time schedules). El almacén de estado puede ser Amazon DynamoDB, con ConditionExpression para las transiciones, o una base relacional con UPDATE ... WHERE si ya forma parte del stack. Las DLQ son colas SQS adicionales, y la plataforma de ejecución es Amazon EKS, con pods que obtienen sus permisos mediante IRSA o EKS Pod Identity. Es una combinación razonable, pero no la única posible: lo esencial del patrón sobrevive a cualquier otra elección.

La elección del planificador responde a una limitación concreta. El retraso nativo de SQS tiene un máximo de 15 minutos, suficiente para reintentos rápidos pero insuficiente cuando el negocio pide esperas de horas. EventBridge Scheduler permite registrar un evento para cualquier instante futuro, sean horas o días, sin mantener ningún proceso activo durante la espera. Las planificaciones one-time se disparan una vez y, si se configura ActionAfterCompletion = DELETE, se eliminan solas.

Un detalle que suele confundir al principio: las DLQ de esta arquitectura se configuran de dos maneras distintas. La del planificador se define en el destino de cada planificación, mediante DeadLetterConfig. Las de SQS (respuesta y reintento) se definen en la cola de origen mediante una redrive policy con un maxReceiveCount, y conviene que el visibility timeout de esas colas sea mayor que el tiempo máximo de procesamiento del manejador, para que un mensaje en proceso no reaparezca en otro consumidor.

Cómo configurar cada planificación

Cada reintento se registra como una planificación con una expresión at(yyyy-mm-ddThh:mm:ss) que fija el instante exacto. Hay varios parámetros que es fácil dejar implícitos y que después producen comportamientos inesperados.

El ScheduleExpressionTimezone debe ser explícito. Sin él, la expresión at() se interpreta en UTC, y si alguien del equipo no lo tiene presente puede esperar disparos en otro horario. Lo más sencillo es calcular siempre en UTC y dejarlo escrito. El FlexibleTimeWindow debe estar en OFF: esa propiedad permite al planificador añadir una ventana de flexibilidad para optimizar recursos, pero con ella activa el instante real de disparo deja de ser predecible, y no tiene sentido ceder ese determinismo cuando el proximo_disparo ya incorpora el jitter y está guardado. El ActionAfterCompletion debe ser DELETE, para que las planificaciones ejecutadas desaparezcan en lugar de acumularse y ocupar cuota sin propósito. Conviene, también, usar un grupo de planificaciones dedicado a los reintentos, que permite aislar permisos, etiquetas y cuotas del resto de la cuenta. Y, por último, la RetryPolicy y la DeadLetterConfig del destino garantizan que, si el planificador no logra entregar el evento a SQS, lo reintente y, al agotarse los intentos, lo envíe a la DLQ del planificador para su análisis.

Este es un ejemplo concreto, el de la planificación del segundo intento de la transacción TX-100200:

{
  "Name": "retry-TX-100200-2",
  "GroupName": "reintentos-ms-procesamiento",
  "ScheduleExpression": "at(2026-10-03T16:38:00)",
  "ScheduleExpressionTimezone": "UTC",
  "FlexibleTimeWindow": { "Mode": "OFF" },
  "ActionAfterCompletion": "DELETE",
  "Target": {
    "Arn": "arn:aws:sqs:<region>:<cuenta>:cola-reintento",
    "RoleArn": "arn:aws:iam::<cuenta>:role/scheduler-reintentos",
    "Input": "{\"transaccion_id\":\"TX-100200\",\"origen\":\"PLANIFICADOR_REINTENTO\",\"intento\":2}",
    "RetryPolicy": {
      "MaximumRetryAttempts": 5,
      "MaximumEventAgeInSeconds": 3600
    },
    "DeadLetterConfig": {
      "Arn": "arn:aws:sqs:<region>:<cuenta>:dlq-planificador"
    }
  }
}

Como JSON no admite comentarios, vale la pena leer el ejemplo campo por campo: Name es un nombre determinista (prefijo fijo, identificador de la transacción y número de intento); ScheduleExpression contiene el proximo_disparo en UTC; Target.Arn apunta a la cola de reintento; RoleArn es el rol que el planificador asume para escribir en esa cola; Input es la carga que B recibirá, con el número de intento incluido; y RetryPolicy y DeadLetterConfig gobiernan lo que ocurre si la entrega falla.

Idempotencia al crear la planificación

El nombre retry-TX-100200-2 es determinista a propósito. Si A intenta crear una planificación que ya existe, el planificador responde con un ConflictException, y A debe tratarlo explícitamente como un éxito y no como un error.

Pero hay un matiz importante. Con ActionAfterCompletion = DELETE, la planificación desaparece después de dispararse, y el nombre queda libre de nuevo. Eso significa que la unicidad del nombre no es la barrera definitiva contra los duplicados. Esa barrera sigue siendo el almacén de estado con sus transiciones condicionales: el planificador resuelve el cuándo, pero la corrección la garantiza el almacén. Un último detalle práctico: los nombres de planificación tienen restricciones de longitud y de caracteres, así que si el identificador de la transacción es largo o contiene símbolos especiales conviene codificarlo, y un hash corto funciona bien.

Permisos con el menor privilegio posible

Los pods del microservicio necesitan scheduler:CreateSchedule para crear planificaciones, scheduler:DeleteSchedule si se implementa la cancelación proactiva, e iam:PassRole restringido al rol del planificador, todo acotado al grupo de planificaciones dedicado. El rol del planificador, por su parte, solo necesita sqs:SendMessage sobre la cola de reintento y la DLQ del planificador. Si las colas están cifradas con una clave KMS gestionada por el cliente, ese rol requiere además kms:GenerateDataKey y kms:Decrypt sobre la clave. Y la política de la cola de reintento debería aceptar mensajes únicamente del rol del planificador: esa restricción cierra la posibilidad de que cualquier otro componente inyecte reintentos de forma no autorizada.

Las cuotas que conviene mirar antes de producción

Crear planificaciones es una llamada a una API con límites de tasa, y existe además un máximo de planificaciones activas simultáneamente por cuenta y región. Esos valores cambian con el tiempo, así que la fuente definitiva es Service Quotas en la consola de AWS y no la documentación de terceros.

El volumen que importa estimar no es solo la ráfaga máxima de CANCELADO por segundo, sino también cuántas planificaciones pueden estar activas al mismo tiempo. Con espera creciente, cada planificación vive más, hasta varias horas, y con muchas transacciones en espera el número puede crecer más de lo esperado. Para absorber ráfagas sin perder mensajes hay tres medidas. La primera es limitar la concurrencia del consumidor de la cola de respuesta: SQS aplica contrapresión de forma natural, y si la creación falla por throttling, el mensaje reaparece tras el visibility timeout y se reintenta. La segunda es usar reintentos con backoff y jitter en la propia llamada de creación, para no amplificar el throttling. Y la tercera es solicitar un aumento de cuota con antelación si el análisis de capacidad lo indica.

Si no hay un planificador gestionado

Todo lo anterior es independiente de la tecnología, porque el planificador diferido es un componente lógico y no necesariamente un servicio gestionado. Si el entorno no ofrece uno, la alternativa más directa es una tabla de reintentos pendientes en la base de datos, junto con un proceso periódico (poller) que busque las transacciones cuyo proximo_disparo ya pasó y las envíe a la cola de reintento.

Es más portable y no introduce dependencias externas, pero tiene un costo real: un componente más que operar, una latencia que depende de la frecuencia del sondeo en lugar de ser casi inmediata, y una presión de lectura adicional sobre el almacén proporcional al número de transacciones pendientes. La máquina de estados, la idempotencia y la política de espera creciente no cambian en absoluto; solo cambia quién dispara el evento cuando llega el momento.

La corrección del patrón no depende de tener un planificador diferido gestionado. Depende del diseño: la máquina de estados, las transiciones condicionales y los manejadores idempotentes funcionan igual con cualquier mecanismo de disparo.

Lo que hay que medir para confiar en el sistema

Un flujo con esta complejidad necesita observabilidad proporcional. Sin métricas concretas es imposible saber si el sistema funciona como se diseñó o si acumula problemas que solo aflorarán bajo carga.

En cada cola SQS hay dos métricas esenciales: ApproximateNumberOfMessagesVisible, que indica cuántos mensajes esperan procesamiento, y ApproximateAgeOfOldestMessage, que indica cuánto lleva esperando el más antiguo y suele ser la primera señal de un consumidor atascado o caído. Las DLQ merecen vigilancia aparte, porque significan cosas distintas, como vimos antes, y su alarma debería saltar ante el primer mensaje. EventBridge Scheduler publica en CloudWatch métricas de invocaciones al destino, errores de entrega, entregas enviadas a la DLQ y throttling; un pico de errores de entrega suele delatar un problema de permisos o de disponibilidad de SQS que de otro modo pasaría desapercibido. Los nombres exactos de esas métricas conviene verificarlos en la documentación vigente de AWS antes de definir alarmas.

Las métricas más valiosas para entender el comportamiento de negocio son las del propio microservicio: el porcentaje de respuestas CANCELADO sobre el total, el número de planificaciones creadas y de conflictos recibidos (que mide, indirectamente, la frecuencia de las reentregas), las transacciones que terminan en FALLIDA por intentos agotados, y la distribución de transacciones por estado e intento. Esta última permite detectar, por ejemplo, un acúmulo de transacciones en PLANIFICANDO que no avanzan a PLANIFICADO, señal clara de un problema al crear planificaciones.

Pero lo que más se agradece en un incidente real no es una métrica sino un registro de auditoría: la posibilidad de reconstruir el historial completo de una transacción, con qué intentos ocurrieron, con qué identificador de planificación, cuándo se creó, cuándo se esperaba el disparo y cuál fue el resultado. El almacén de estado solo guarda el estado actual, así que este historial exige una tabla de eventos de solo-añadir, donde cada transición deje una fila. Sin ella, cuando algo sale mal en producción la respuesta es especulación; con ella, el diagnóstico es una consulta.

Lo que el patrón garantiza, y lo que no

Conviene nombrar con claridad las garantías. Una transacción no produce reintentos duplicados. El ciclo es finito, porque cada transacción termina en un estado terminal, sea EXITOSA o FALLIDA. Y el sistema se comporta correctamente ante reentregas y fallos en cualquier punto del flujo, siempre que se cumpla la precondición de idempotencia del servicio externo, o se adopte outbox.

Lo que no garantiza es precisión de reloj. El instante programado es el momento en que el evento queda disponible en la cola, no el momento en que se ejecuta, y entre ambos intervienen la cola, la disponibilidad del consumidor y su concurrencia. La desviación es de segundos en condiciones normales. Es algo distinto del jitter, que es intencional y puede ser de minutos; ambas cosas coexisten y hay que distinguirlas al documentar el comportamiento esperado.

Antes de llevar el patrón a producción, estas garantías deberían convertirse en pruebas formales y no en afirmaciones de diseño. Una ráfaga de N cancelaciones simultáneas no debe perder ni duplicar ningún reintento. La reentrega forzada de cada mensaje, en cada paso del flujo, no debe alterar el resultado final, lo que incluye el caso del evento que llega con la transacción aún en PLANIFICANDO y el de B caído en ENVIANDO. Ninguna transacción debe superar max_intentos. Una respuesta tardía de un intento anterior no debe modificar el estado. Las alertas de DLQ y de intentos agotados deben dispararse, el reconciliador debe reanudar transacciones detenidas en cada estado intermedio, y el servicio externo no debe recibir más de X solicitudes por segundo durante una ráfaga de reintentos. No son criterios opcionales de calidad: son la forma de demostrar que el diseño funciona en condiciones reales y no solo en el camino feliz.

La espera como decisión de diseño

Volvamos al punto de partida. El negocio pide reintentar más tarde, y alguien tiene que decidir cómo se modela ese «más tarde» dentro del sistema.

Como resumen, estos son los puntos que sostienen todo lo anterior. La espera debe ser un estado persistente y no un proceso dormido, porque lo primero no cuesta nada mientras transcurre y lo segundo se paga hora a hora. Cada pieza resuelve una sola responsabilidad (cuándo, si todavía tiene sentido, y una sola vez) y por eso el conjunto se recupera sin coordinación central. La corrección vive en las transiciones condicionales del almacén y no en el orden de los pasos, de modo que cualquier mensaje duplicado, tardío u obsoleto simplemente no tiene efecto. Guardar el instante del reintento antes de crear la planificación, aceptar PLANIFICANDO en B y retomar desde ENVIANDO son las tres decisiones que cierran los huecos que las primeras versiones del diseño dejaban abiertos. Y la espera creciente con jitter calculado en la aplicación protege al servicio externo y mantiene el comportamiento determinista.

La diferencia entre un Thread.sleep y este patrón no es de complejidad superficial, sino de qué tan bien el sistema entiende su propia situación. Un proceso que duerme no sabe que está esperando un reintento, no puede decirlo, no puede auditarse y no puede recuperarse de un fallo sin ayuda externa. Un almacén de estado con transiciones condicionales sí sabe en qué punto está, puede registrarlo, puede responder preguntas sobre su historial y puede retomar exactamente donde lo dejó si algo falla. Eso es lo que hace escalable la solución, y no el hecho de que use servicios concretos: el planificador es intercambiable, mañana puede ser una tabla con un poller o un servicio de otro proveedor, y lo que permanece es la máquina de estados, la idempotencia y la política de espera.

Quedan, además, varias líneas abiertas que merecen exploración. La más inmediata es modelar formalmente el cortacircuitos dentro de la máquina de estados, distinguiendo con claridad las indisponibilidades técnicas de los rechazos de negocio, para que las primeras no consuman el presupuesto de intentos. Otra es refinar la política de espera según el motivo del rechazo, o incluso volverla adaptativa, ajustando la base y el factor a partir de la tasa de éxito observada en reintentos anteriores. También vale la pena estudiar la adopción de outbox de forma sistemática en los casos donde el servicio externo no ofrezca garantías de idempotencia, y evaluar su costo frente al de aceptar un duplicado ocasional. Y, en el plano de la validación, tiene mucho potencial la inyección controlada de fallos (chaos engineering) aplicada a cada uno de los puntos intermedios descritos, para comprobar de forma continua, y no solo antes del lanzamiento, que las garantías se mantienen a medida que el sistema evoluciona.

Darle tiempo al servicio externo para recuperarse no es una concesión ante un fallo. Es reconocer que en sistemas distribuidos los fallos suelen ser temporales, que una segunda oportunidad bien diseñada tiene un valor real, y que esperar bien, sin desperdiciar recursos, sin duplicar y sin perder el hilo, es una forma de resiliencia tan importante como actuar rápido cuando todo va bien.

Te llega la tarea y parece de las fáciles: "agregar paginación al listado de artículos". Añades ?page=0&size=20, Spring te proporciona Pageable, el repositorio hereda findAll(pageable) y, en pocos minutos, tienes un endpoint funcionando.

En desarrollo, con mil registros, todo va bien. En staging, con diez mil, probablemente también. El problema aparece más adelante, cuando la tabla alcanza cientos de miles de filas, los filtros se vuelven más complejos y los tiempos de respuesta empiezan a crecer de una forma que ya no resulta tan fácil de explicar.

Y esa lentitud no aparece porque sí. Tiene una causa concreta, relacionada con la forma en que la base de datos resuelve la consulta internamente.

El costo invisible de OFFSET

La paginación tradicional suele apoyarse en dos cláusulas SQL: LIMIT, que determina cuántos registros devolver, y OFFSET, que indica cuántos registros deben quedar fuera antes de comenzar a devolver resultados.

SELECT * FROM articulos
ORDER BY created_at DESC
LIMIT 20 OFFSET 10000;

La consulta parece directa. Pero lo que ocurre para resolverla no siempre lo es.

Para obtener los veinte registros solicitados, el motor necesita avanzar hasta la posición indicada por el OFFSET. Los registros anteriores no forman parte del resultado final, pero el trabajo necesario para llegar hasta ellos existe.

Por eso, a medida que aumenta la profundidad de la página, puede aumentar también el trabajo que debe realizar el motor. La página 1 con tamaño 20 apenas necesita avanzar. Una página mucho más profunda tiene que recorrer una cantidad considerablemente mayor de registros antes de llegar al conjunto que finalmente devolverá.

La diferencia puede ser especialmente importante en tablas grandes. Los índices ayudan a reducir el trabajo necesario, pero no eliminan por completo la naturaleza del problema: la posición se expresa como una cantidad de registros que deben quedar atrás.

Existe además otro problema, menos visible durante las pruebas: la posición de una página puede cambiar mientras el usuario navega.

Imagina que un cliente solicita la página 3 y, antes de solicitar la página 4, se inserta un nuevo registro que queda al principio del orden.

Ese nuevo registro desplaza las posiciones siguientes. Como consecuencia, el cliente puede recibir un registro que ya había visto o dejar de recibir otro que esperaba encontrar en la siguiente página.

El mismo tipo de desplazamiento puede producirse cuando se eliminan registros o cuando una modificación cambia su posición dentro del orden.

No es necesariamente un error que aparezca durante una prueba funcional. Es un comportamiento que puede hacerse visible cuando varios usuarios navegan mientras el sistema continúa recibiendo escrituras.

Tenemos, entonces, dos problemas diferentes pero relacionados:

• El costo puede aumentar a medida que se profundiza en las páginas.
• Los resultados pueden desplazarse entre una solicitud y la siguiente cuando los datos cambian.

Estos problemas explican por qué una implementación de OFFSET que funcionaba perfectamente con una tabla pequeña puede empezar a presentar dificultades cuando cambian el volumen o la forma de utilizar el endpoint.

Pero todavía no podemos concluir que haya que reemplazar OFFSET.

La pregunta siguiente es otra: ¿qué características tiene el caso de uso que estamos intentando resolver?

Las variables que realmente determinan la solución

No existe una única solución para todos los escenarios de paginación. La estrategia adecuada depende de cómo se navegan los resultados, cómo se filtran, cómo se ordenan y cuánto crecerán los datos.

Antes de comparar alternativas, conviene responder cuatro preguntas.

La primera es probablemente la más importante:

¿El usuario navega secuencialmente o necesita saltar a páginas arbitrarias?

Navegar secuencialmente significa avanzar a partir del resultado anterior: siguiente, anterior, scroll infinito o cualquier otra interfaz en la que el usuario recorre los resultados de forma progresiva.

La navegación aleatoria es diferente. Aquí el usuario puede seleccionar directamente una página concreta, por ejemplo la 53, sin haber recorrido las anteriores.

Esta diferencia es fundamental porque algunas estrategias utilizan precisamente el resultado anterior como punto de referencia. Si el usuario necesita saltar directamente a una posición arbitraria, ese modelo deja de encajar tan bien.

La segunda pregunta aparece cuando entran en juego los filtros:

¿Los filtros utilizan valores discretos o rangos abiertos?

Un filtro discreto trabaja con un conjunto relativamente acotado de posibilidades: estado, categoría, autor o tipo.

Un rango abierto permite prácticamente cualquier combinación dentro de un continuo: una fecha entre X e Y, un precio entre A y B o una búsqueda de texto libre.

Esta diferencia se vuelve especialmente importante cuando se considera una estrategia basada en caché. Si existen pocas combinaciones posibles, una consulta puede reutilizar un resultado previamente calculado. Cuando las combinaciones son prácticamente infinitas, esa reutilización se vuelve mucho menos probable.

La tercera pregunta tiene que ver con el orden:

¿El orden de los resultados es estable o puede cambiar?

Un orden estable puede ser, por ejemplo, created_at DESC, acompañado de un identificador como desempate.

Un orden dinámico permite que el usuario cambie la columna o los criterios de orden durante la navegación. En ese caso, una referencia calculada para el orden anterior deja de representar correctamente la posición dentro del nuevo orden.

Finalmente está el volumen:

¿Cuántos registros existen hoy y cuánto se espera que crezca la tabla?

Una tabla con cincuenta mil registros presenta unas necesidades diferentes a una que puede alcanzar varios millones.

El volumen no determina por sí solo la solución, pero sí cambia el costo de las estrategias. Algo que resulta perfectamente razonable en una tabla pequeña puede dejar de serlo cuando aumentan la profundidad de las páginas, la cantidad de consultas y la concurrencia.

Con estas cuatro variables definidas, ya podemos comparar las alternativas de manera más precisa. Cada una resuelve una combinación diferente de necesidades y, al mismo tiempo, introduce sus propios límites.

Cuando OFFSET sigue siendo suficiente

La primera posibilidad es también la más sencilla: mantener OFFSET, pero controlar las condiciones en las que se utiliza.

Esto tiene sentido cuando el volumen es moderado, las páginas profundas son poco frecuentes y la navegación aleatoria forma parte de los requisitos.

En muchos sistemas, los usuarios rara vez llegan a páginas extremadamente profundas. Si una interfaz obliga a recorrer miles de páginas para encontrar un registro, probablemente el problema de fondo sea que falta una búsqueda o un mecanismo de filtrado más adecuado.

Por eso, establecer un límite máximo de profundidad puede ser una decisión razonable. Por ejemplo, se puede impedir que una API consulte páginas más allá de cierto límite y obligar al consumidor a utilizar filtros o búsqueda para localizar registros concretos.

El segundo elemento importante es el índice.

Supongamos que la consulta utiliza:

ORDER BY estado, created_at, id

Si esas columnas participan habitualmente en el orden y los filtros, un índice compuesto diseñado de acuerdo con el patrón real de consulta puede reducir considerablemente el trabajo necesario.

El costo asociado con la profundidad no desaparece por completo, pero puede disminuir de forma importante.

Aquí aparece una idea importante: no toda paginación necesita una arquitectura sofisticada.

Si el problema es pequeño y los requisitos son sencillos, introducir cursores, Redis o un motor de búsqueda puede añadir mucha más complejidad de la que realmente se necesita.

Cuándo encaja

OFFSET puede seguir siendo una buena opción cuando:

• El volumen es moderado.
• Las páginas profundas son poco frecuentes.
• El usuario necesita saltar a páginas arbitrarias.
• Los filtros y órdenes pueden cambiar dinámicamente.
• Se quiere mantener un contrato de API convencional basado en page y size.
• La simplicidad de implementación es importante.

Qué no resuelve

El costo de las páginas profundas sigue existiendo.

Además, los cambios en los datos entre solicitudes pueden desplazar los resultados de una página a otra.

Cuando esas limitaciones dejan de ser aceptables, aparece una estrategia basada en una idea diferente: dejar de identificar la posición mediante un número y utilizar el propio orden de los datos como referencia.

Cuando la navegación es secuencial: cursor-based pagination

Aquí aparece la paginación basada en cursores, también conocida como keyset pagination.

La diferencia conceptual es sencilla.

Con OFFSET, la consulta pregunta:

"Dame los registros que están después de las primeras N posiciones."

Con un cursor, la consulta pregunta:

"Dame los registros que vienen después de este punto concreto del orden."

Por ejemplo:

SELECT * FROM articulos
WHERE (created_at, id) < (:ultima_fecha, :ultimo_id)
ORDER BY created_at DESC, id ASC
LIMIT 20;

En este caso, el último registro recibido se convierte en el punto de referencia para solicitar el siguiente conjunto.

La base de datos ya no necesita interpretar la página como una posición numérica. Puede utilizar los valores del orden para localizar el punto desde el que debe continuar.

Cuando existe un índice adecuado, esto permite evitar gran parte del trabajo asociado con recorrer posiciones profundas mediante OFFSET.

Por eso, la profundidad de la navegación deja de tener el mismo efecto que tenía en la estrategia anterior.

El cursor que recibe el cliente suele ser un token opaco. Puede contener los valores de las columnas utilizadas para determinar la posición y estar codificado, por ejemplo, mediante Base64URL.

El cliente no necesita conocer su estructura. Solo necesita conservarlo y devolverlo cuando solicite la siguiente página.

Esto permite que el backend cambie la representación interna del cursor sin obligar al cliente a interpretar sus componentes.

El requisito que hace posible un cursor

Para que este modelo funcione correctamente, el orden debe ser determinista.

Si varios registros tienen exactamente el mismo valor para el criterio principal, necesitamos una columna adicional que permita desempatar.

Por ejemplo:

ORDER BY created_at DESC, id ASC

Aquí created_at determina el orden principal y id permite distinguir registros que tienen la misma fecha.

Cuando el orden de negocio tiene varios niveles, todos ellos forman parte de la referencia.

Por ejemplo:

estado → created_at → id

El cursor deberá contener la información necesaria para reproducir esa posición dentro del orden.

El backend recibe el token, recupera esos valores y construye la condición correspondiente.

La contrapartida: la navegación deja de ser aleatoria

Aquí aparece la principal diferencia con OFFSET.

Un cursor representa un punto dentro del orden, no un número de página.

Por eso, si el usuario está recorriendo:

página 1 → página 2 → página 3 → página 4

es natural solicitar la siguiente posición.

Pero si quiere saltar directamente a la página 53, el cursor de esa página no puede calcularse simplemente a partir del número 53.

Esto significa que los cursores son especialmente adecuados cuando la navegación es secuencial.

No son simplemente una optimización de SQL: también representan un cambio en el contrato de la API y, en algunos casos, en la interfaz.

Una tabla tradicional basada en números de página no puede sustituirse por cursores manteniendo exactamente la misma semántica.

Cuándo encaja

La estrategia basada en cursores resulta especialmente apropiada para:

• Feeds.
• Historiales.
• Scroll infinito.
• Exportaciones secuenciales.
• Integraciones entre servicios.
• Tablas de gran volumen.
• Sistemas con escrituras frecuentes.
• Casos en los que el usuario no necesita saltar a una página arbitraria.

Qué no resuelve

No permite una navegación aleatoria equivalente a page=53.

Además, necesita un orden estable y determinista.

Cuando el requisito de navegación aleatoria es obligatorio, debemos buscar otra estrategia.

Cuando necesitas saltar directamente a una página

Supongamos ahora que el volumen es grande y que el usuario sí necesita ir directamente a una página concreta.

En ese caso, un cursor no encaja con el requisito principal de la interfaz.

Una posibilidad consiste en separar dos problemas que hasta ahora estaban mezclados: determinar qué registros ocupan cada posición y recuperar después los datos de esas posiciones.

La idea es construir un índice de navegación que contenga únicamente los identificadores de los registros que cumplen el filtro, en el orden correspondiente.

Por ejemplo:

SELECT id
FROM articulos
WHERE estado = :estado
  AND categoria = :categoria
ORDER BY
    CASE estado
        WHEN 'BORRADOR' THEN 1
        WHEN 'PUBLICADO' THEN 2
        ELSE 3
    END ASC,
    created_at DESC,
    id ASC;

El resultado conceptual sería:

[uuid_1, uuid_2, uuid_3, ..., uuid_N]

No estamos almacenando los artículos completos. Estamos almacenando el mapa que permite saber qué identificadores corresponden a cada posición.

Ese resultado puede guardarse en una caché utilizando como clave una representación de los filtros y del criterio de orden.

Por ejemplo:

hash(filtros + orden) → [id_1, id_2, id_3, ...]

Si la misma combinación se solicita nuevamente mientras el índice sigue siendo válido, puede reutilizarse.

Si el usuario cambia el filtro o el orden, cambia la clave y se genera otro índice.

A partir de ese mapa, solicitar la página 53 significa seleccionar las posiciones correspondientes.

Con un tamaño de página de 20:

página 53 → posiciones 1040 a 1059

Después, el sistema puede recuperar directamente los registros identificados:

SELECT *
FROM articulos
WHERE id = ANY(:ids_pagina);

Finalmente, debe reconstruir el mismo orden utilizado por el índice.

Una consecuencia importante: la consulta representa una fotografía

Esta estrategia introduce una propiedad que conviene hacer explícita.

El índice representa el conjunto de resultados en el momento en que fue construido.

Si se inserta un nuevo registro después de crear el índice, ese registro no tiene por qué aparecer en la navegación actual.

Si se elimina uno de los registros, el índice puede seguir haciendo referencia a un elemento que ya no existe y será necesario decidir cómo gestionar ese caso.

La ventaja es que el comportamiento deja de depender de desplazamientos implícitos entre solicitudes y pasa a formar parte explícita del diseño.

En otras palabras, el sistema está diciendo:

"Esta navegación corresponde a esta fotografía del conjunto de resultados."

Dependiendo del caso de uso, eso puede ser precisamente lo que se necesita.

El papel de los filtros

Aquí las características de los filtros que definimos antes adquieren importancia.

Si existen filtros discretos y relativamente acotados, es posible que diferentes usuarios soliciten repetidamente las mismas combinaciones.

Por ejemplo:

estado=PUBLICADO
categoria=TECNOLOGIA
orden=created_at

Ese tipo de consulta tiene más posibilidades de reutilizar un índice existente.

En cambio, si cada usuario puede especificar una fecha inicial, una fecha final, un precio mínimo, un precio máximo y otros parámetros arbitrarios, el número de combinaciones crece rápidamente.

En ese escenario, la caché puede tener menos oportunidades de reutilización y la generación del índice inicial puede convertirse en un costo importante.

Cuándo encaja

Este enfoque resulta especialmente interesante cuando:

• La navegación aleatoria es necesaria.
• El volumen de datos es elevado.
• Los filtros son relativamente discretos y repetibles.
• El orden de negocio es complejo.
• La misma combinación de filtros se consulta con frecuencia.
• Se dispone de infraestructura de caché.

Qué no resuelve

La generación inicial del índice sigue teniendo un costo proporcional al conjunto de resultados que debe procesar.

Además, mantener la caché introduce complejidad operacional: expiración, invalidación, memoria utilizada y comportamiento ante cambios en los datos.

Cuando los filtros dejan de ser discretos y pasan a incluir texto libre o rangos arbitrarios, puede ser necesario cambiar nuevamente de enfoque.

Cuando el problema ya es de búsqueda

Llegados a este punto, aparece un escenario diferente.

El problema ya no consiste únicamente en decidir cómo recorrer una lista grande.

Supongamos que el endpoint necesita combinar:

• Texto libre.
• Rangos arbitrarios.
• Múltiples dimensiones de filtrado.
• Orden dinámico.
• Millones de registros.
• Consultas frecuentes y concurrentes.
• Navegación sobre grandes conjuntos de resultados.

Aquí puede tener sentido utilizar un motor de búsqueda especializado.

Herramientas como Elasticsearch u OpenSearch utilizan estructuras de indexación diseñadas específicamente para búsquedas y filtrados complejos.

En lugar de depender exclusivamente del modelo de consulta de una tabla relacional, mantienen estructuras especializadas que permiten localizar documentos a partir de los términos y valores buscados.

También ofrecen mecanismos orientados a recorrer grandes conjuntos de resultados, como search_after, que permite continuar una búsqueda a partir de una posición determinada.

Esto cambia la naturaleza del problema.

Ya no estamos intentando hacer que una tabla relacional resuelva eficientemente cualquier combinación imaginable de búsqueda, filtro y orden.

Estamos utilizando una infraestructura especializada para ese patrón de acceso.

Pero esa decisión introduce un costo nuevo: ahora existe una infraestructura adicional que debe mantenerse sincronizada con la base de datos principal.

El flujo puede verse, conceptualmente, así:

Base de datos principal
        ↓
Proceso de sincronización
        ↓
Índice de búsqueda

Esto obliga a resolver preguntas que no existían con una única base de datos:

• ¿Cuándo se actualiza el índice?
• ¿Qué ocurre si la sincronización falla?
• ¿Cuánto retraso puede existir entre ambos sistemas?
• ¿Cuál es la fuente de verdad?
• ¿Cómo se reconstruye el índice?
• ¿Cómo se monitoriza?

Por eso, un motor de búsqueda no debería incorporarse simplemente porque OFFSET sea lento.

Tiene sentido cuando las necesidades de búsqueda y filtrado justifican la infraestructura adicional.

Cuándo encaja

Puede resultar adecuado cuando:

• El texto libre es una parte central del caso de uso.
• Existen rangos y filtros complejos.
• Se combinan múltiples dimensiones de búsqueda.
• El volumen de datos es elevado.
• Las consultas son frecuentes y concurrentes.
• La base de datos principal ya no ofrece una solución eficiente para el patrón de búsqueda requerido.

Qué no resuelve

No elimina la complejidad: la desplaza hacia la arquitectura.

Aparecen nuevos componentes, sincronización, monitorización, gestión de índices y una nueva forma de consultar los datos.

Si una solución más sencilla satisface los requisitos, incorporar otro sistema puede ser innecesario.

El árbol de decisión

A estas alturas, las cuatro estrategias ya no aparecen como alternativas aisladas. Cada una responde a las condiciones que acabamos de analizar.

El recorrido puede resumirse así:

flowchart TD

    A([Necesito paginar una tabla])
        --> B{¿Volumen moderado<br/>y páginas superficiales?}

    B -->|Sí| S1[OFFSET con índices<br/>bien diseñados]

    B -->|No| C{¿El usuario necesita<br/>saltar a páginas arbitrarias?}

    C -->|No — navegación secuencial| D{¿El orden puede ser<br/>determinista?}

    D -->|Sí| S2[Cursor-based pagination<br/>CursorRequest + CursorPage&lt;T&gt;]

    D -->|No| D2[Añadir una columna<br/>de desempate única al orden]

    D2 --> D

    C -->|Sí — acceso aleatorio| E{¿Los filtros son<br/>discretos y acotados?}

    E -->|Sí| S3[Índice de navegación con caché<br/>Hash del filtro → IDs en Redis]

    E -->|No| F{¿La búsqueda y el volumen<br/>justifican infraestructura adicional?}

    F -->|Sí| S4[Motor de búsqueda dedicado<br/>Elasticsearch / OpenSearch]

    F -->|No| S1b[OFFSET con límite<br/>de profundidad]

El árbol no debe interpretarse como una fórmula rígida.

Por ejemplo, el número de registros por sí solo no determina qué estrategia utilizar. Lo que importa es cómo se combina ese volumen con la profundidad de navegación, el patrón de consulta, los filtros, el orden y la frecuencia de acceso.

El objetivo del árbol es obligarnos a formular las preguntas correctas antes de introducir complejidad.

Lo que cada solución no resuelve

Después de recorrer las alternativas, aparece una conclusión importante: ninguna estrategia elimina el costo de la paginación; cada una lo desplaza hacia un lugar diferente.

OFFSET mantiene un contrato sencillo y permite navegar directamente a páginas arbitrarias. Su costo aparece principalmente cuando la profundidad aumenta y los datos son numerosos.

Los cursores reducen el trabajo asociado con posiciones profundas y funcionan especialmente bien para navegación secuencial. A cambio, el cliente deja de trabajar con páginas numéricas y debe conservar un punto de referencia.

El índice de navegación con caché permite recuperar páginas arbitrarias a partir de un mapa previamente construido. A cambio, introduce un costo inicial y una infraestructura adicional para almacenar y gestionar ese mapa.

El motor de búsqueda permite resolver escenarios donde el problema ya no es solamente paginar, sino buscar y filtrar grandes volúmenes de información. A cambio, introduce otra pieza de infraestructura y la necesidad de mantenerla coordinada con la fuente de datos principal.

Por eso, la decisión no consiste en encontrar una solución que no tenga costos.

Consiste en decidir qué costo es aceptable para el contexto concreto del sistema.

Volver al endpoint que "simplemente funcionaba"

Cuando aquel endpoint que inicialmente "simplemente funcionaba" empieza a mostrar tiempos de respuesta cada vez mayores, es tentador concluir que OFFSET fue una mala decisión desde el principio.

Pero esa conclusión sería demasiado simple.

OFFSET puede ser una solución perfectamente válida para determinados escenarios.

El problema aparece cuando cambian las condiciones para las que fue elegido y nadie revisa la decisión.

Una tabla que comenzó con 20.000 registros puede terminar teniendo varios millones.

Una interfaz que inicialmente mostraba cinco páginas puede terminar necesitando búsqueda avanzada.

Un listado que solo se consultaba ocasionalmente puede convertirse en una de las rutas más utilizadas de la aplicación.

Y un criterio de orden sencillo puede terminar acompañado de múltiples filtros y reglas de negocio.

Por eso, la pregunta importante no es si OFFSET es bueno o malo.

La pregunta es si sigue siendo adecuado para las condiciones actuales del endpoint.

Ese cambio de perspectiva también modifica la forma de diseñar la solución desde el principio.

Antes de implementar la paginación, conviene conocer:

• cómo navegará el usuario;
• si necesita saltos arbitrarios;
• qué filtros tendrá disponibles;
• si esos filtros son discretos o abiertos;
• cómo se ordenarán los resultados;
• si ese orden es determinista;
• cuánto volumen existe actualmente;
• cuánto se espera que crezca;
• y cuánto pueden cambiar los datos mientras el usuario navega.

Con esa información, OFFSET, cursores, un índice de navegación o un motor de búsqueda dejan de ser decisiones basadas en preferencias técnicas.

Se convierten en respuestas a requisitos concretos.

Y esa es probablemente la idea más importante de todo el problema: la paginación no debería elegirse por costumbre ni por la tecnología que tenemos disponible, sino por la forma en que el endpoint realmente necesita ser utilizado.

La tarea puede seguir siendo "agregar paginación al listado de artículos".

Lo que cambia es la pregunta que hacemos antes de tocar el código.

No:

"¿Cuál es la mejor técnica de paginación?"

Sino:

"¿Qué tipo de navegación, filtrado, orden y volumen necesita realmente este endpoint?"

A partir de ahí, la implementación deja de ser una decisión aislada y pasa a formar parte del diseño técnico del sistema.

Y cuando el volumen, los filtros o la forma de navegación cambien, la estrategia puede revisarse de nuevo.

Ese punto de revisión es tan importante como la decisión inicial.

El Arte de Filtrar Datos en HTTP: Entre la Elegancia de la URL y la Potencia del Payload

Seguro que alguna vez empezaste con un endpoint de listado que parecía no necesitar demasiado. Un par de filtros simples: nombre, categoría, quizá un estado. Todo cabía cómodamente en una URL como ?categoria=electronica&estado=activo, era fácil de leer y nadie tenía demasiadas razones para cuestionar la decisión.

El problema aparece cuando esa pantalla deja de ser simple.

Alguien de producto pide filtrar por varias categorías al mismo tiempo, añadir un rango de precios, restringir por fecha de publicación y, además, ordenar por relevancia. Nada especialmente extraño: es el tipo de evolución que termina teniendo cualquier sistema de búsqueda que crece un poco. Lo que cambia no es la necesidad funcional, sino la dificultad de representar esa necesidad dentro de HTTP.

Y es ahí donde una decisión que parecía puramente sintáctica empieza a afectar cosas bastante más importantes: la legibilidad de las URLs, su capacidad para compartirse, el caché, la infraestructura que las procesa y, finalmente, la forma en que el propio código del backend tiene que recibirlas.

Cuando los filtros dejan de caber cómodamente en una URL

La primera reacción suele ser intentar mantener el modelo que ya funciona y llevarlo un poco más lejos. Si un parámetro alcanza para un filtro, quizá varios parámetros puedan representar varios filtros.

Pronto aparece algo parecido a esto:

filter[0][field]=categoria&filter[0][op]=in&filter[0][value][]=electronica&filter[0][value][]=hogar&filter[1][field]=precio&filter[1][op]=between&filter[1][value][]=100000&filter[1][value][]=500000

El problema no es que esta representación sea imposible. El problema es que, a medida que aumenta la complejidad, empieza a depender de una sintaxis que la propia API tiene que inventar y documentar. No existe una convención universal que garantice que otro equipo, otro framework o incluso otro endpoint vaya a interpretar exactamente esa estructura de la misma manera.

Con dos condiciones todavía se puede tolerar. Con tres o cuatro, la URL deja de comunicar lo que está ocurriendo y pasa a convertirse en una estructura que hay que descifrar.

La siguiente idea parece más atractiva precisamente porque elimina esa sintaxis inventada: si el filtro es estructurado, ¿por qué no representarlo directamente como JSON?

Por ejemplo:

{
  "and": [
    {
      "field": "categoria",
      "op": "in",
      "value": ["electronica", "hogar"]
    }
  ]
}

Conceptualmente es mucho mejor. La estructura expresa exactamente lo que se quiere consultar y no hace falta inventar una notación propia para representar operadores, campos y valores.

El problema llega cuando ese JSON tiene que viajar dentro de una URL.

Después de aplicar URL encoding, una estructura que originalmente era legible termina convertida en una secuencia como esta:

%7B%22and%22%3A%5B%7B%22field%22%3A%22categoria%22%2C%22op%22%3A%22in%22%2C%22value%22%3A%5B%22electronica%22%2C%22hogar%22%5D%7D%5D%7D

La información sigue estando ahí. El problema es que dejó de ser visible.

Esto parece una molestia estética hasta que aparece un caso real de diagnóstico. Una URL así puede terminar en un mensaje de chat del equipo, en Postman, en un log de producción o en un ticket donde alguien intenta explicar por qué una búsqueda devolvió resultados inesperados. En ninguno de esos escenarios resulta evidente qué filtro representa la cadena.

Hay que decodificarla antes de poder entenderla.

Y entonces aparece una tercera posibilidad, casi inevitable: abandonar la URL y enviar el JSON en el body de un POST.

La solución fácil también cambia el contrato

La propuesta de utilizar POST tiene una ventaja evidente: el filtro vuelve a verse exactamente como lo que es.

POST /productos/search
Content-Type: application/json

{
  "and": [
    {
      "field": "categoria",
      "op": "in",
      "value": ["electronica", "hogar"]
    },
    {
      "field": "precio",
      "op": "between",
      "value": [100000, 500000]
    }
  ]
}

Desde el punto de vista de representación, es probablemente la solución más cómoda. Pero resuelve el problema de legibilidad introduciendo otro: la búsqueda ya no está contenida en una URL que pueda copiarse, pegarse y compartir como un recurso de lectura.

Además, aunque el caché de respuestas POST es posible con configuraciones específicas, no tiene la misma interoperabilidad ni la misma naturalidad que el caché de un GET. Una petición GET encaja directamente con las expectativas de navegadores, proxies, CDN y clientes HTTP para operaciones de lectura.

Esto no significa que POST sea incorrecto. Significa que, al elegirlo, se está renunciando deliberadamente a ciertas propiedades.

Y esa distinción es importante porque permite formular mejor el problema. No se trata de encontrar una opción universalmente correcta entre query params, JSON en la URL y POST. Se trata de decidir qué propiedad del contrato HTTP se necesita conservar.

Si la búsqueda debe poder compartirse como enlace y además interesa mantenerla como GET, todavía quedan alternativas que merece la pena explorar — y antes de comprometerse con una, conviene entender de qué depende cada una.

Dos caminos para conservar el GET, con distinta dependencia

Cuando la meta es mantener la búsqueda como GET compartible sin caer en URLs ilegibles, hay dos familias de solución, y no son intercambiables porque no piden lo mismo al resto del sistema.

Una es codificar el filtro tal cual el frontend lo pensó (un objeto JSON con la forma que el dominio necesite) y transportarlo como un blob opaco en un único parámetro. Esta idea no le exige nada a la capa de persistencia: el servidor recibe una cadena, la decodifica, obtiene un JSON y lo interpreta como quiera. Es agnóstica al motor de datos por completo.

La otra es expresar el filtro directamente como una gramática de texto pensada para mapear campo-operador-valor, apoyándose en que exista una capa de acceso a datos capaz de traducir esa gramática a una consulta ejecutable. Esta idea sí depende de algo externo a la propia idea: solo funciona si hay un traductor gramática→query, típicamente provisto por un ORM con soporte de construcción dinámica de condiciones (Criteria API en el mundo Java, query builders equivalentes en otros stacks).

Esa diferencia — necesitar o no una capa de traducción externa — es la que determina cuál conviene en cada caso, y conviene resolverla antes de escribir una sola línea de código.

El camino agnóstico: JSON opaco vía Base64URL

Cuando el filtro es estructurado pero sigue siendo razonablemente pequeño, una posibilidad es serializarlo como JSON y después codificar ese JSON utilizando Base64URL.

El flujo conceptual es sencillo:

1. Se construye el filtro como un objeto.
2. Se serializa a JSON.
3. Ese JSON se codifica mediante Base64URL.
4. El resultado se envía como un único parámetro de query.
5. El servidor lo decodifica y recupera nuevamente el JSON.

La diferencia importante es que no se intenta hacer legible el contenido del filtro dentro de la URL. Se acepta que sea opaco, pero se consigue que la representación sea mucho más adecuada para convivir con la sintaxis de una URL.

También conviene precisar el nombre. No se trata simplemente de Base64 tradicional.

Base64 utiliza caracteres como +, / y =, que pueden requerir tratamiento adicional cuando aparecen dentro de una URL. Base64URL, definido en la sección 5 del RFC 4648, utiliza - y _ en lugar de esos caracteres y permite omitir el padding cuando el protocolo que lo utiliza lo contempla.

Tomemos el filtro completo:

{
  "and": [
    {
      "field": "categoria",
      "op": "in",
      "value": ["electronica", "hogar"]
    },
    {
      "field": "precio",
      "op": "between",
      "value": [100000, 500000]
    }
  ]
}

Después de codificarlo, la petición puede quedar así:

GET /productos?filter=eyJhbmQiOlt7ImZpZWxkIjoiY2F0ZWdvcmlhIiwib3AiOiJpbiIsInZhbHVlIjpbImVsZWN0cm9uaWNhIiwiaG9nYXIiXX0seyJmaWVsZCI6InByZWNpbyIsIm9wIjoiYmV0d2VlbiIsInZhbHVlIjpbMTAwMDAwLDUwMDAwMF19XX0

La cadena sigue siendo opaca. No pretende ser legible para una persona. Pero ya no está dominada por secuencias %XX, y lo más importante es que la operación continúa siendo un GET.

Eso permite conservar varias propiedades útiles: la búsqueda puede copiarse, guardarse y compartirse como enlace y, cuando la infraestructura está configurada para ello, la respuesta puede aprovechar el caché asociado a una petición GET.

Hay, eso sí, una condición que no conviene esconder: el filtro debe seguir teniendo un tamaño razonable. Si la consulta contiene decenas de condiciones, listas enormes o estructuras profundamente anidadas, el problema deja de ser cómo codificarla y empieza a ser cuánto sentido tiene seguir transportándola dentro de una URL.

Pero para una búsqueda con un conjunto moderado de filtros, Base64URL puede ser un punto intermedio razonable.

Lo que queda pendiente es hacer que el backend pueda consumir esa representación sin convertir cada controlador en responsable de la decodificación.

El camino dependiente de la persistencia: RSQL

Existe otra manera de mantener el GET sin sacrificar legibilidad, pero que parte de una premisa distinta: en lugar de esconder el filtro dentro de un blob opaco, expresarlo directamente como texto legible dentro del propio query param.

RSQL es una extensión de FIQL (Feed Item Query Language) que permite escribir eso: una gramática de comparaciones encadenadas con AND/OR, pensada para mapear uno a uno contra atributos de una entidad. La URL sigue siendo un GET, sigue siendo compartible, y además no pierde legibilidad:

GET /productos?filter=categoria=in=(electronica,hogar);precio=ge=100000;precio=le=500000

El punto y coma es AND, la coma es OR, los paréntesis agrupan. Los paths de relaciones se escriben con notación de punto:

GET /productos?filter=marca.pais==Argentina;estado!=suspendido

Comparado con Base64URL, la ganancia es evidente: no hace falta decodificar nada para entender qué se está pidiendo. La cadena es el filtro.

Pero esa legibilidad no es gratis, y ahí está el punto que conviene no pasar por alto: RSQL no resuelve nada por sí mismo. Es una gramática de texto; alguien tiene que parsearla y, sobre todo, alguien tiene que traducirla a una consulta ejecutable contra el almacenamiento real. A diferencia de Base64URL — donde el servidor simplemente decodifica y deserializa un JSON con sus propias reglas —, RSQL necesita que exista, entre el parser y la base de datos, una capa capaz de convertir cada nodo de comparación en una condición de persistencia. Sin esa capa, RSQL es solo una cadena de texto sin ningún lugar donde ejecutarse.

En el ecosistema Java, esa capa la provee típicamente la Criteria API de JPA a través de una Specification, y existen librerías (no oficiales de Spring, sino de terceros) que hacen ese puente automáticamente. En otros stacks el concepto se mantiene — una gramática campo-operador-valor traducida a un query builder dinámico —, pero el mecanismo concreto cambia según el ORM disponible. Quien quiera ver cómo se ve esa integración en un proyecto Spring Boot real puede saltar directamente al anexo al final del artículo.

Esa dependencia tiene además una consecuencia de seguridad que conviene resolver antes de decidirse por este camino, no después.

El vector de seguridad que ninguna gramática resuelve por defecto

Cualquier mecanismo que traduzca texto libre a una condición de persistencia enfrenta el mismo riesgo, independientemente del lenguaje o el framework: el parser no sabe, por sí solo, qué campos del modelo deberían ser alcanzables desde afuera.

Si una entidad tiene una relación hacia otra entidad con datos sensibles, nada en la gramática impide que un consumidor intente comparar directamente contra esos campos:

GET /productos?filter=usuario.password==algo
GET /productos?filter=usuario.resetToken==abc123

El sistema no devolvería esos valores en el body, pero sí variaría el número de resultados según si la condición se cumple o no. Es suficiente para montar un ataque de oráculo e inferir, comparación a comparación, valores que nunca deberían ser accesibles desde un filtro de listado.

La mitigación es siempre la misma en cualquier stack: recorrer la estructura del filtro ya parseado (su AST) antes de ejecutar la consulta y rechazar cualquier campo que no esté en una allowlist explícita, y componer esa consulta junto con las condiciones base que el usuario nunca debería poder eludir (soft-delete, tenant, permisos).

Esto es exactamente lo que distingue este camino del de Base64URL con un DTO tipado: ahí, los campos filtrables son exactamente los que el desarrollador declaró en la clase. No hay forma de filtrar por usuario.resetToken si ese campo no existe en el tipo — la allowlist es estructural, la garantiza el propio DTO. En el camino de la gramática de texto, en cambio, la allowlist es una responsabilidad operacional: hay que construirla y mantenerla activamente, y es un paso que se puede omitir bajo presión sin que nada lo impida a nivel de compilación.

Cuándo conviene cada camino

La pregunta que separa un camino del otro no es cuál es "mejor", sino qué tan bien el filtro se mapea contra atributos simples de una entidad persistida:

• Si los filtros son AND/OR sobre atributos que existen tal cual en el modelo de datos, y se cuenta con una capa de persistencia capaz de traducir esa gramática (Specification, Criteria API o equivalente), una gramática de texto como RSQL resuelve el problema con muy poco código y conserva la legibilidad de la URL — a cambio de mantener activamente una allowlist.
• Si el contrato del filtro es propio del dominio, con operadores específicos, estructuras anidadas particulares o simplemente no hay (o no se quiere depender de) una capa de traducción gramática→persistencia, Base64URL con un DTO tipado ofrece un contrato explícito, no le pide nada al motor de datos, y su allowlist es estructural en lugar de operacional.

Esta bifurcación es la que después vuelve a aparecer, ya formalizada, en el árbol de decisión al final del artículo.

Llevar la idea de Base64URL a un endpoint real con Spring Boot

En cualquier framework aparece la misma pregunta: alguien tiene que recibir el parámetro, decodificarlo, convertir el JSON en el DTO correspondiente y manejar los errores que puedan producirse durante el proceso.

En Spring Boot, la solución más directa consiste en hacerlo dentro del controlador:

@GetMapping("/productos")
public ResponseEntity<List<ProductoDto>> buscar(
        @RequestParam("filter") String filterBase64,
        ObjectMapper objectMapper) throws IOException {

    byte[] jsonBytes = Base64.getUrlDecoder().decode(filterBase64);

    FiltroProductosDto filtro =
            objectMapper.readValue(jsonBytes, FiltroProductosDto.class);

    return ResponseEntity.ok(productoService.buscar(filtro));
}

Para un solo endpoint, no hay nada especialmente problemático en este enfoque. El inconveniente aparece cuando el sistema crece.

Si existen diez endpoints de búsqueda, probablemente aparezcan diez implementaciones prácticamente iguales. Y entonces la cuestión deja de ser si podemos decodificar Base64URL y pasa a ser si queremos mantener esa lógica repartida por todos los controladores.

En ese punto aparecen problemas de consistencia bastante concretos.

¿Todos los endpoints manejan el padding de la misma forma? ¿Todos distinguen entre un Base64URL inválido y un JSON inválido? ¿Todos responden de la misma manera cuando falta el parámetro? ¿Todos deserializan el contenido con las mismas reglas? ¿Todos aplican las mismas validaciones?

La duplicación empieza a convertir una decisión de transporte en una responsabilidad del código de negocio.

Una solución más limpia consiste en hacer que el controlador reciba directamente el DTO que necesita:

@GetMapping("/productos")
public ResponseEntity<List<ProductoDto>> buscar(
        @Base64Filter @Valid FiltroProductosDto filtro) {

    return ResponseEntity.ok(productoService.buscar(filtro));
}

El controlador ya no necesita saber que el filtro llegó codificado. Esa información pertenece a la capa que transforma la petición HTTP en los argumentos del método.

Spring MVC proporciona precisamente un mecanismo para realizar esa transformación: HandlerMethodArgumentResolver.

Sacar la infraestructura del controlador

El primer paso es definir una anotación que identifique los parámetros que deben resolverse mediante este mecanismo:

import java.lang.annotation.*;

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface Base64Filter {

    String value() default "filter";
}

El valor permite mantener filter como nombre por defecto, pero también utilizar otro parámetro cuando el endpoint lo necesite:

@Base64Filter("criteria")
FiltroProductosDto filtro

La anotación por sí sola no hace la transformación. El trabajo lo realiza el resolver.

Aquí aparece además una cuestión importante que puede pasar desapercibida: cuando Spring construye automáticamente un objeto mediante mecanismos como @RequestBody, el ciclo de validación habitual puede ejecutarse de forma transparente. Cuando el objeto lo construimos manualmente dentro de un HandlerMethodArgumentResolver, esa validación no aparece automáticamente solo porque hayamos escrito @Valid.

Por eso el resolver tiene que encargarse también de esa parte.

Una implementación posible es:

@Component
public class Base64FilterArgumentResolver implements HandlerMethodArgumentResolver {

    private final ObjectMapper objectMapper;
    private final Validator validator;

    public Base64FilterArgumentResolver(ObjectMapper objectMapper, Validator validator) {
        this.objectMapper = objectMapper;
        this.validator = validator;
    }

    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.hasParameterAnnotation(Base64Filter.class);
    }

    @Override
    public Object resolveArgument(
            MethodParameter parameter,
            ModelAndViewContainer mavContainer,
            NativeWebRequest webRequest,
            WebDataBinderFactory binderFactory) throws Exception {

        Base64Filter annotation = parameter.getParameterAnnotation(Base64Filter.class);
        String paramName = annotation.value();
        String rawValue = webRequest.getParameter(paramName);
        Class<?> targetType = parameter.getParameterType();

        Object filtro;

        if (rawValue == null || rawValue.isBlank()) {
            filtro = targetType.getDeclaredConstructor().newInstance();
        } else {
            try {
                byte[] jsonBytes = Base64.getUrlDecoder().decode(rawValue);
                filtro = objectMapper.readValue(jsonBytes, targetType);
            } catch (IllegalArgumentException e) {
                throw new FiltroInvalidoException(
                        "El parámetro '" + paramName + "' no es Base64URL válido");
            } catch (JacksonException e) {
                throw new FiltroInvalidoException(
                        "El parámetro '" + paramName + "' no contiene un JSON de filtro válido");
            }
        }

        if (parameter.hasParameterAnnotation(Valid.class)) {
            Set<ConstraintViolation<Object>> violations = validator.validate(filtro);
            if (!violations.isEmpty()) {
                throw new FiltroInvalidoException(
                        "El filtro no cumple las validaciones: " + violations);
            }
        }

        return filtro;
    }
}

Hay varias decisiones dentro de este código que conviene entender porque son parte del contrato y no simples detalles de implementación.

El método supportsParameter hace que el resolver intervenga únicamente cuando el parámetro tiene la anotación @Base64Filter. Esto mantiene el comportamiento localizado y evita que todos los parámetros de la aplicación intenten pasar por la misma lógica.

Después se obtiene el nombre del parámetro desde la anotación y se recupera su valor desde la petición. Si no existe o está vacío, el ejemplo construye una instancia vacía del DTO. Esa decisión puede ser apropiada cuando la ausencia del filtro significa "sin restricciones", pero no debería convertirse en una regla universal. Si en el dominio la ausencia del parámetro tiene otro significado, ese comportamiento debe reflejarlo.

Cuando sí existe un valor, primero se decodifica Base64URL y después se deserializa el JSON utilizando ObjectMapper.

Las dos operaciones pueden fallar por motivos diferentes, y distinguirlas permite devolver mensajes de error más útiles. Un contenido que no es Base64URL válido no representa el mismo problema que una cadena correctamente codificada que contiene un JSON malformado.

Una vez construido el objeto, el resolver comprueba si el parámetro utiliza @Valid. Solo en ese caso ejecuta explícitamente Bean Validation.

Eso permite mantener en el DTO las reglas habituales:

public class FiltroProductosDto {

    @Size(
        max = 10,
        message = "No se permiten más de 10 categorías"
    )
    private List<String> categorias;

    @Min(0)
    private Long precioMinimo;

    @Min(0)
    private Long precioMaximo;

    // getters y setters
}

De esta manera, colocar @Valid junto con @Base64Filter activa las validaciones sintácticas habituales sin introducir lógica adicional en el controlador.

Es importante, sin embargo, no confundir validación sintáctica con validación de negocio.

Una regla como "no se permiten más de diez categorías" o "el precio mínimo no puede ser negativo" pertenece naturalmente a esta capa. En cambio, comprobar que precioMinimo sea menor que precioMaximo, que una categoría exista realmente o que determinado filtro esté permitido para un usuario concreto puede requerir información que el resolver no debería conocer.

Esas decisiones pertenecen a una capa posterior, normalmente al servicio o a la lógica de dominio.

Registrar el resolver y completar la separación

Una vez creado el resolver, hay que registrarlo en Spring MVC:

@Configuration
public class WebConfig implements WebMvcConfigurer {

    private final Base64FilterArgumentResolver resolver;

    public WebConfig(Base64FilterArgumentResolver resolver) {
        this.resolver = resolver;
    }

    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(resolver);
    }
}

A partir de ahí, el controlador puede mantenerse completamente centrado en su responsabilidad:

@GetMapping("/productos")
public ResponseEntity<List<ProductoDto>> buscar(
        @Base64Filter @Valid FiltroProductosDto filtro) {

    return ResponseEntity.ok(
            productoService.buscar(filtro)
    );
}

El beneficio real de esta arquitectura no es que Spring haya aprendido a decodificar Base64URL. El beneficio es haber separado dos decisiones que no deberían estar mezcladas.

Una decisión responde a cómo viaja el filtro por HTTP.

La otra responde a qué filtro necesita el caso de uso.

El controlador solo debería preocuparse por la segunda.

Cuando llegue el endpoint de búsqueda número once, no será necesario copiar la misma secuencia de decodificación, deserialización y validación. El mecanismo de transporte queda encapsulado en una pieza transversal y los endpoints pueden expresar únicamente el contrato que necesitan.

Pero conseguir que el código quede limpio no significa que el diseño esté terminado. Hay varias cuestiones que el resolver no puede solucionar por sí solo.

Codificar no significa proteger

La primera es seguridad.

Base64URL no cifra el contenido. Tampoco lo convierte en secreto. Cualquier persona que tenga acceso a la cadena puede decodificarla y recuperar el JSON original.

Por eso nunca debe interpretarse la codificación como una medida de protección.

Después de deserializar el filtro siguen siendo necesarias las comprobaciones correspondientes: campos permitidos, operadores válidos, tipos esperados, tamaños máximos y, cuando la estructura lo permita, profundidad máxima de anidamiento.

Esto es especialmente relevante cuando el filtro admite estructuras complejas. Una petición puede ser perfectamente válida desde el punto de vista sintáctico y, aun así, provocar un consumo excesivo de CPU o memoria si el servidor acepta estructuras arbitrariamente grandes o profundas.

La validación, por tanto, no es un accesorio que se añade después de implementar Base64URL. Forma parte del contrato de entrada.

Los errores también forman parte del diseño

El segundo punto es el manejo de errores.

El resolver puede lanzar FiltroInvalidoException, pero eso no significa que cada controlador deba capturarla individualmente. La aplicación puede centralizar la conversión de esa excepción en una respuesta HTTP uniforme:

@RestControllerAdvice
public class FiltroExceptionHandler {

    @ExceptionHandler(FiltroInvalidoException.class)
    public ResponseEntity<ErrorResponse> handleFiltroInvalido(FiltroInvalidoException ex) {
        return ResponseEntity.badRequest().body(new ErrorResponse(ex.getMessage()));
    }
}

Esto elimina otro nivel de duplicación, pero todavía conviene conservar internamente las distintas categorías de fallo.

No es lo mismo recibir un Base64URL inválido que recibir un JSON malformado. Tampoco es lo mismo un JSON válido que no puede convertirse al DTO esperado, un DTO que incumple las validaciones, o un filtro completamente válido que no está permitido para determinado usuario.

No siempre es necesario exponer todas esas diferencias al consumidor. De hecho, en algunos casos sería contraproducente. Pero mantenerlas diferenciadas internamente puede resultar decisivo cuando haya que investigar un comportamiento extraño en producción.

La uniformidad hacia fuera no debería implicar perder información hacia dentro.

Si el consumidor no sabe qué codificar, el contrato está incompleto

Hay todavía otra pieza que suele olvidarse porque no afecta directamente al funcionamiento del endpoint: la documentación.

Una anotación personalizada como @Base64Filter no necesariamente será interpretada automáticamente por herramientas como springdoc-openapi como un parámetro de query convencional. Si el consumidor no recibe una explicación explícita, terminará teniendo que averiguar por su cuenta cómo construir la cadena.

Por ejemplo:

@Operation(
    summary = "Búsqueda de productos con filtro estructurado"
)
@Parameter(
    name = "filter",
    description =
        "Filtro JSON codificado en Base64URL según RFC 4648 §5",
    example =
        "eyJhbmQiOlt7ImZpZWxkIjoiY2F0ZWdvcmlhIn1dfQ",
    schema = @Schema(type = "string")
)
@GetMapping("/productos")
public ResponseEntity<List<ProductoDto>> buscar(
        @Base64Filter @Valid FiltroProductosDto filtro) {

    return ResponseEntity.ok(
            productoService.buscar(filtro)
    );
}

Una buena documentación debería mostrar las dos representaciones.

Por un lado, el JSON conceptual que el consumidor realmente quiere expresar. Por otro, la cadena Base64URL que debe enviar.

La transformación puede ser transparente para el servidor, pero no debe ser un misterio para quien consume la API.

El coste que aparece después: una URL que ya no se puede leer

Hasta este punto, Base64URL parece haber conseguido un equilibrio bastante atractivo: mantiene GET, conserva una URL autocontenida y evita llenar el query string de secuencias de escape.

Pero ese equilibrio tiene un precio evidente.

La URL deja de ser legible.

Un log como este:

GET /productos?filter=eyJhbmQiOlt7ImZpZWxkIjoiY2F0ZWdvcmlhI...

no permite saber inmediatamente qué filtros se utilizaron.

Y eso importa especialmente porque las URLs aparecen en muchos lugares que no están bajo el control directo del desarrollador que diseñó el endpoint: logs de servidores, herramientas de monitoreo, historial del navegador, sistemas de analítica y mecanismos de diagnóstico.

Es exactamente el costo que, como vimos antes, RSQL evita — a cambio de pedir una capa de traducción a persistencia y una allowlist mantenida activamente. Ninguna de las dos alternativas gana en todo; cada una conserva una propiedad distinta.

Cuándo RSQL se queda corto

Incluso en el escenario donde sí conviene la gramática de texto — filtros que mapean bien a atributos y operadores relacionales estándar —, hay límites concretos donde deja de alcanzar.

El primero es semántica propia. Un operador =between= con dos valores puede registrarse como extensión del parser, pero si el dominio necesita expresar algo como un rango con extremos configurables o un operador geoespacial con parámetros propios, la gramática obliga a inventar una notación que ya no es estándar. El DTO tipado puede incluir esos campos con semántica explícita.

El segundo es correlación en colecciones. Si Producto tiene una lista de Variante y la consulta necesita encontrar productos que tengan una variante que sea simultáneamente roja y con stock mayor a cero, una traducción directa campo-operador-valor genera un JOIN que evalúa las condiciones por separado. Puede devolver un producto con una variante roja sin stock y otra variante con stock pero de distinto color. Para expresar esa correlación hace falta un subquery o un EXISTS, que la gramática no modela.

El tercero es contexto de runtime. Un score de relevancia calculado en el momento de la petición, una distancia geoespacial o un ranking de machine learning no tienen representación natural como par campo-operador-valor.

Cuando el filtro cruza alguno de esos límites, Base64URL con DTO tipado vuelve a ser la opción más honesta: el contrato es explícito, los campos posibles están acotados por el tipo y la estructura puede ser tan específica como lo exija el dominio.

Cuando el filtro crece, el problema deja de ser de codificación

Hasta aquí estamos hablando de un escenario bastante concreto: filtros estructurados pero todavía razonablemente pequeños.

La situación cambia cuando la consulta empieza a crecer.

Decenas de condiciones. Listas extensas de identificadores. Estructuras anidadas varios niveles hacia abajo. Combinaciones complejas de operadores.

En ese momento, insistir en mantener todo dentro de una URL deja de ser una cuestión de encontrar una codificación más conveniente.

Se convierte en una decisión de diseño de interfaz.

Y es precisamente ahí donde POST vuelve a tener sentido, pero esta vez por una razón diferente a la del comienzo.

No se utiliza porque no hayamos encontrado una manera suficientemente ingeniosa de meter el filtro en un GET. Se utiliza porque el contrato ha cambiado y ahora el body es un lugar más apropiado para transportar una estructura grande.

POST /productos/search
Content-Type: application/json

{
  "and": [
    {
      "field": "categoria",
      "op": "in",
      "value": ["electronica", "hogar"]
    },
    {
      "field": "precio",
      "op": "between",
      "value": [100000, 500000]
    }
  ]
}

Se gana una representación natural del filtro y se evita someterlo a las limitaciones prácticas de una URL.

A cambio, la búsqueda deja de ser un recurso autocontenido en forma de enlace y pierde la misma naturalidad para el caché que tendría un GET.

Pero si el filtro ya ha alcanzado un tamaño que hace poco razonable mantenerlo en la URL, esa pérdida probablemente sea aceptable.

Una tercera posibilidad: QUERY

Existe además una alternativa más reciente que resulta conceptualmente interesante: el método HTTP QUERY.

La motivación es precisamente separar la semántica de una operación de consulta de la necesidad de transportar una estructura compleja en el body.

En teoría, encaja muy bien con el problema: una consulta segura podría mantener una semántica específica de consulta y, al mismo tiempo, recibir contenido estructurado sin tener que comprimirlo artificialmente dentro de la URL.

El inconveniente está en el ecosistema.

Que un método esté definido mediante un estándar no significa que navegadores, proxies, firewalls, gateways y otras piezas de infraestructura lo soporten con la misma madurez que GET o POST.

Por eso puede ser una opción interesante para mantener en el radar, especialmente cuando se controla de extremo a extremo la infraestructura, pero no necesariamente es la elección más conservadora para una API pública que necesita máxima interoperabilidad.

Cuando ni siquiera el body es suficiente

Hay todavía un escenario más extremo.

Supongamos que la consulta es muy grande, pero además se reutiliza constantemente. Enviar todo el filtro en cada petición puede empezar a resultar innecesario.

En ese caso, quizá el problema ya no consista en decidir cómo transportar el filtro, sino en dejar de transportarlo.

Una alternativa es convertir la búsqueda en un recurso persistente:

POST /saved-searches
Content-Type: application/json

{
  "and": [
    {
      "field": "categoria",
      "op": "in",
      "value": ["electronica", "hogar"]
    }
  ]
}

El servidor puede almacenar esa definición y devolver un identificador:

HTTP/1.1 201 Created

Location: /saved-searches/abc123

A partir de ahí, las peticiones posteriores pueden referirse al identificador en lugar de reenviar toda la estructura.

La decisión es diferente porque también lo es el problema.

Ya no estamos intentando representar una búsqueda compleja dentro de una URL. Estamos modelando la búsqueda como un recurso que puede persistir y reutilizarse.

Del lado del frontend

Todas estas decisiones del backend tienen una contraparte en el cliente que construye la petición.

El problema no es solo cómo codificar el filtro. Es que si el filtro vive únicamente en el estado del componente, el usuario pierde la posibilidad de compartir la búsqueda, usar el botón atrás del navegador o guardarla como favorito. La URL deja de ser el estado de la pantalla.

La solución en Angular es sincronizar el filtro con los query params del Router en ambas direcciones. Cuando el usuario aplica filtros, la URL se actualiza. Cuando alguien llega con una URL que ya tiene filtros, el formulario se rellena y la búsqueda se ejecuta automáticamente.

Para Base64URL el helper de codificación es simple:

encode(filter: object): string {
  const json = JSON.stringify(filter);
  return btoa(unescape(encodeURIComponent(json)))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');
}

Y la sincronización con el router:

// Al cambiar filtros → actualizar la URL
this.router.navigate([], {
  relativeTo: this.route,
  queryParams: { filter: this.encode(filter) },
  queryParamsHandling: 'merge'
});

// Al inicializar → leer filtros de la URL
this.route.queryParams.pipe(
  map(params => params['filter']),
  filter(Boolean),
  map(encoded => this.decode(encoded))
).subscribe(filter => {
  this.applyToForm(filter);
  this.search(filter);
});

Para RSQL la mecánica es idéntica. Solo cambia el formato del string que viaja en el param: en lugar de Base64URL opaco viaja una cadena legible como categoria=in=(electronica,hogar);precio=ge=100000. El router no distingue entre uno y otro.

Volver a aquella URL de 400 caracteres

Aquella URL llena de %7B%22and%22%3A no era realmente un problema de sintaxis.

Era una señal.

La complejidad de la consulta había empezado a superar la comodidad del mecanismo elegido para transportarla, pero todavía no se había tomado una decisión consciente sobre qué propiedad del contrato era importante conservar.

Si los filtros se mapean bien a campos de una entidad persistida y a operadores relacionales estándar, una gramática de texto como RSQL resuelve el problema con muy poco código y conserva la legibilidad de la URL — a costa de depender de una capa de traducción a persistencia y de mantener activamente una allowlist. Si el contrato del filtro es propio del dominio, con operadores específicos o estructuras que no encajan en el modelo relacional directo, Base64URL con DTO tipado ofrece un contrato explícito, no depende de ningún motor de datos particular, y su allowlist es estructural en lugar de operacional.

flowchart TD
    A[¿Qué tipo de filtros necesitás?] --> B
    A --> C
    A --> D
    A --> E

    B["Campos simples\nsin lógica compleja"]
    --> F["QueryDSL Web Bindings\nCero código, nativo Spring Data"]

    C["AND / OR sobre atributos\nde una entidad persistida"]
    --> G{¿Existe una capa que traduzca\ngramática de texto a persistencia?}
    G -->|Sí| H["RSQL / gramática similar\nCon allowlist explícita"]
    G -->|No| D

    D["Operadores custom\nlógica de dominio\ncolecciones correlacionadas"]
    --> I{¿Necesitás URL compartible?}
    I -->|Sí, filtro moderado| J["Base64URL + HandlerMethodArgumentResolver"]
    I -->|No, o filtro grande| K["POST /search\nBody JSON estructurado"]

    E["Filtros enormes\nreutilizados entre sesiones"]
    --> L["saved-searches como recurso\nPOST para crear, GET con ID para reutilizar"]

Cuando el filtro deja de ser razonablemente pequeño, el problema cambia de naturaleza. POST con JSON puede ser un contrato mucho más apropiado. Y si la búsqueda se vuelve grande y reutilizable, puede tener más sentido convertirla en un recurso persistente y referenciarla mediante un identificador.

La decisión correcta no consiste en elegir una tecnología y aplicarla a todas las búsquedas.

Consiste en reconocer que cada representación conserva unas propiedades y sacrifica otras.

Query params simples conservan una URL muy legible, pero se vuelven incómodos cuando la estructura crece. Una gramática de texto como RSQL mantiene esa legibilidad con más expresividad, pero exige que exista una capa de traducción a persistencia y una allowlist explícita mantenida activamente, o la superficie de ataque crece silenciosamente. Base64URL mantiene la búsqueda como GET y permite un contrato de filtro completamente propio, sin depender de ningún motor de datos particular, aunque sacrifica legibilidad en logs. POST recupera la representación natural del JSON cuando la consulta ya es demasiado grande. Y una búsqueda persistente elimina directamente la necesidad de reenviar una estructura que ya existe en el servidor.

El verdadero cambio, entonces, no está en Base64URL, en RSQL, en Spring Boot ni siquiera en HTTP.

Está en dejar de pedirle al mismo mecanismo que resuelva problemas de tamaños y necesidades diferentes.

Cuando una búsqueda es pequeña, puede viajar como una consulta.

Cuando necesita estructura pero todavía cabe razonablemente en una URL, puede codificarse, con la representación que mejor encaje con el contrato.

Cuando crece demasiado, puede pasar al body.

Y cuando se convierte en algo que se reutiliza como entidad propia, puede dejar de viajar por completo y convertirse en un recurso.

Ese es el criterio que permite que la arquitectura evolucione con la complejidad real del problema, en lugar de obligar a cada nueva necesidad a encajar a la fuerza en la decisión que se tomó cuando el endpoint todavía parecía sencillo.

Anexo: RSQL en el stack Java (Spring Boot + JPA)

Todo lo dicho sobre RSQL en el cuerpo del artículo es válido para cualquier stack que cuente con una capa de traducción gramática→persistencia equivalente. Este anexo muestra cómo se ve concretamente esa integración en el ecosistema Java, donde esa capa la provee la Criteria API de JPA a través de una Specification.

La integración más difundida usa un starter de terceros (no es un proyecto oficial de Spring) que convierte directamente la cadena RSQL en una Specification:

<dependency>
    <groupId>io.github.perplexhub</groupId>
    <artifactId>rsql-jpa-spring-boot-starter</artifactId>
    <version>6.0.18</version>
</dependency>

@GetMapping("/productos")
public Page<Producto> buscar(
        @RequestParam(defaultValue = "") String filter,
        Pageable pageable) {

    return productoRepository.findAll(
        RSQLJPASupport.toSpecification(filter),
        pageable
    );
}

Eso es todo el controlador. Sin anotaciones custom, sin resolver, sin ObjectMapper — la contrapartida es la dependencia externa a un motor de persistencia relacional vía JPA, que es justamente lo que el cuerpo del artículo señala como condición de existencia de este camino.

La allowlist mencionada antes se implementa recorriendo el AST que produce el parser de RSQL, antes de convertirlo en Specification, y rechazando cualquier campo fuera de lo permitido:

private void validarCamposPermitidos(String filter, Set<String> permitidos) {
    if (filter.isBlank()) return;

    new RSQLParser().parse(filter).accept(new RSQLVisitor<Void, Void>() {
        public Void visit(AndNode node, Void p) {
            node.getChildren().forEach(c -> c.accept(this, null)); return null;
        }
        public Void visit(OrNode node, Void p) {
            node.getChildren().forEach(c -> c.accept(this, null)); return null;
        }
        public Void visit(ComparisonNode node, Void p) {
            if (!permitidos.contains(node.getSelector()))
                throw new FiltroInvalidoException(
                    "Campo no permitido: " + node.getSelector());
            return null;
        }
    });
}

Y componer la Specification resultante con los filtros base que el usuario nunca debe poder eludir:

Specification<Producto> spec = RSQLJPASupport.<Producto>toSpecification(filter)
    .and((root, query, cb) -> cb.equal(root.get("eliminado"), false))
    .and((root, query, cb) -> cb.equal(root.get("tenantId"), TenantContext.get()));

En otro stack o con otro ORM, el nombre de las piezas cambia, pero el rol de cada una se mantiene: un parser de la gramática, un traductor hacia el mecanismo de consulta dinámica del ORM disponible, y una allowlist que se aplica sobre el árbol ya parseado antes de ejecutar nada contra la base de datos.

En proyectos donde los microservicios comparten una misma base de datos, hay momentos en los que un cambio que comienza como una tarea rutinaria dentro de un equipo puede terminar en una reunión con tres equipos distintos. Clientes, el servicio responsable de las cuentas de usuario, despliega una limpieza de cuentas inactivas, cambia el tipo de su identificador o renombra una columna que hasta entonces consideraba interna. Sus pruebas pasan y el despliegue parece correcto. Poco después, Pedidos empieza a fallar.

Normalmente, la situación comienza de una forma mucho más sencilla. Pedidos necesita consultar determinada información de Clientes y, como ambos servicios comparten la misma base de datos, acceder directamente a sus tablas parece una solución rápida y práctica. Con el tiempo, esa consulta puede dejar de ser algo puntual y convertirse en parte del funcionamiento habitual de Pedidos. El servicio comienza entonces a asumir que las tablas, columnas y estructuras que consulta estarán disponibles y conservarán el mismo significado.

Lo que inicialmente parecía una integración sencilla puede terminar haciendo que decisiones internas de Clientes tengan consecuencias sobre Pedidos. Clientes puede ser responsable de la identidad, el estado y las reglas de ciclo de vida de una persona, mientras que Pedidos solo necesita conservar una referencia estable al cliente y obtener determinados datos para cumplir con sus propias responsabilidades. Sin embargo, cuando Pedidos resuelve esa necesidad consultando directamente las tablas de Clientes, termina dependiendo no solo de los datos que necesita, sino también de la forma en que Clientes los almacena y organiza.

Este escenario plantea una cuestión que va más allá de una consulta concreta o de una columna que haya cambiado. Si dos microservicios comparten la misma base de datos, ¿cómo pueden relacionarse sin convertir las estructuras internas de un dominio en dependencias del otro? Y, sobre todo, ¿cómo se puede establecer una frontera clara cuando la infraestructura sigue siendo compartida?

El problema real: acoplamiento al esquema ajeno

Supongamos que Clientes es responsable de la identidad, el estado y las reglas de ciclo de vida de una persona. Pedidos, en cambio, es responsable de los pedidos y necesita conservar una referencia estable al cliente asociado.

Pedidos necesita saber quién es el cliente, pero no necesita conocer cómo Clientes organiza internamente esa información. No debería depender de si el nombre se almacena en una columna, en dos columnas, en una tabla normalizada o mediante una relación con otra entidad. Tampoco debería decidir qué significa anonimizar una cuenta ni asumir que todas las columnas existentes en clientes son datos que puede interpretar.

Sin embargo, cuando ambos servicios comparten una base de datos, es fácil terminar con algo como esto:

CREATE TABLE pedidos (
    id UUID PRIMARY KEY,
    cliente_id UUID NOT NULL,
    total NUMERIC(12, 2) NOT NULL,
    creado_en TIMESTAMPTZ NOT NULL DEFAULT NOW(),

    CONSTRAINT fk_pedidos_cliente
        FOREIGN KEY (cliente_id) REFERENCES clientes(id)
);

Al estudiar pedidos, la FOREIGN KEY deja visible una relación con clientes. Esa relación es importante, pero conviene distinguir dos conceptos que suelen mezclarse.

Una clave foránea expresa una garantía de integridad referencial. Le dice al motor que un valor de pedidos.cliente_id debe corresponder a un registro existente en clientes.id, de acuerdo con las reglas de la restricción.

Eso no significa que clientes se haya convertido en una API para Pedidos.

Tampoco significa que Pedidos tenga derecho a consultar cualquier columna de la tabla, ejecutar JOIN arbitrarios o depender de la forma en que Clientes almacena sus datos. La clave foránea hace visible una relación entre estructuras; no define una interfaz de integración entre dominios.

El verdadero acoplamiento aparece cuando Pedidos empieza a hacer algo como esto:

SELECT
    p.id,
    p.total,
    c.nombre,
    c.estado,
    c.tipo_documento
FROM pedidos p
JOIN clientes c ON c.id = p.cliente_id;

La consulta parece inocente. El problema es que convierte clientes en una interfaz accidental.

A partir de ese momento, Clientes no puede modificar libremente nombre, estado o tipo_documento porque Pedidos ha asumido que esas columnas forman parte de su contrato. Si mañana Clientes normaliza el nombre, cambia el modelo de estados o separa la información personal de la comercial, el cambio deja de ser exclusivamente suyo.

flowchart LR
    Clientes[(Clientes)]
    Pedidos[(Pedidos)]

    Pedidos -->|JOIN y acceso a tablas privadas| Clientes

La frontera se ha roto porque el consumidor depende de la estructura interna del propietario para funcionar.

Por eso, al analizar una base de datos compartida, la pregunta importante no es únicamente «¿existe una FOREIGN KEY?». La pregunta relevante es «¿qué parte de esta estructura está siendo utilizada como interfaz por otro dominio?».

Relación local o contrato entre dominios

Antes de modificar el DDL conviene clasificar la relación.

Cuando la relación protege una invariante dentro del mismo dominio, la FOREIGN KEY sigue siendo una herramienta apropiada. Si dos tablas pertenecen al mismo modelo y la existencia de una fila depende de la existencia de otra, eliminar la restricción únicamente para conseguir una apariencia de autonomía significa renunciar a una garantía que el motor puede proporcionar de forma fiable.

La situación cambia cuando la relación cruza límites de propiedad.

Pedidos puede conservar cliente_id como referencia estable al cliente. Ese identificador expresa una relación entre conceptos, pero no concede a Pedidos permiso para interpretar el modelo interno de Clientes.

Esta distinción es importante porque eliminar una FOREIGN KEY no crea automáticamente autonomía. Solo elimina una garantía de integridad referencial.

La autonomía aparece cuando cada dominio puede modificar su estructura interna sin romper a sus consumidores.

De aquí surge una estrategia especialmente útil para escenarios de transición: Database as an API. La base de datos continúa siendo compartida desde el punto de vista físico, pero sus esquemas dejan de funcionar como una superficie de acceso indiscriminado. Cada dominio mantiene sus estructuras privadas y decide explícitamente qué información publica y qué operaciones permite.

La frontera lógica aparece antes que la frontera física.

Vistas como contratos de lectura

Para las lecturas entre dominios, una de las herramientas más sencillas disponibles en una base relacional es una vista.

Clientes puede mantener sus tablas privadas y publicar únicamente la información que Pedidos necesita:

CREATE VIEW clientes_publicos_para_pedidos AS
SELECT
    id AS cliente_id,
    nombre_comercial,
    estado_comercial
FROM clientes;

Pedidos deja entonces de depender directamente de clientes:

SELECT
    cliente_id,
    nombre_comercial,
    estado_comercial
FROM clientes_publicos_para_pedidos
WHERE cliente_id = :cliente_id;

La diferencia parece pequeña desde el punto de vista de SQL, pero es significativa desde el punto de vista arquitectónico.

La tabla clientes representa el modelo interno del dominio. La vista clientes_publicos_para_pedidos representa una superficie publicada.

La vista puede funcionar conceptualmente como un DTO o como un endpoint GET: expone un conjunto definido de datos y oculta cómo se obtiene internamente.

Clientes podría, por ejemplo, pasar de una tabla monolítica a varias tablas normalizadas:

clientes
    ├── identidades
    ├── perfiles
    └── estados_comerciales

Mientras la vista conserve su contrato:

cliente_id
nombre_comercial
estado_comercial

Pedidos no necesita conocer ese cambio.

La vista, por supuesto, no hace que el contrato desaparezca. Al contrario: lo hace explícito. Cambiar el nombre de una columna publicada, eliminarla o alterar significativamente su semántica debe tratarse como un cambio contractual, aunque no exista HTTP de por medio.

Esta estrategia resulta particularmente útil cuando varios servicios ya utilizan el mismo motor de base de datos. Permite reducir el acoplamiento sin exigir inmediatamente una migración física completa.

También puede tener ventajas operativas. Una lectura que permanece dentro del mismo motor evita llamadas adicionales entre microservicios y puede evitar tráfico de red o costos de egress que aparecerían al sacar la consulta fuera de la infraestructura. Pero conviene no confundir esto con «latencia cero»: la consulta sigue consumiendo CPU, memoria, I/O y capacidad de concurrencia de la base de datos.

Además, una vista no crea independencia física. Los servicios siguen compartiendo disponibilidad, capacidad, credenciales, copias de seguridad, mantenimiento y, potencialmente, una misma condición de fallo.

La vista reduce el acoplamiento al esquema. No elimina el acoplamiento operativo a la infraestructura compartida.

Las lecturas y las escrituras necesitan fronteras diferentes

Aquí aparece una distinción fundamental. No todas las interacciones con una base de datos pueden modelarse de la misma manera.

Una lectura puede exponerse mediante una vista porque, conceptualmente, está proporcionando una representación de información. Una escritura, en cambio, puede modificar el estado del dominio y activar decisiones de negocio.

Por eso conviene distinguir entre una operación técnica y una operación que expresa una decisión de negocio.

Cuando la operación pertenece al negocio

Si una escritura necesita validar reglas, permisos, transiciones de estado, límites, invariantes o efectos secundarios, la autoridad debería permanecer en el servicio propietario.

En ese caso, REST o gRPC son canales adecuados para expresar la operación:

Pedidos
   |
   | POST /clientes/{id}/suspension
   v
Clientes
   |
   +--> valida autorización
   +--> comprueba estado actual
   +--> aplica reglas de negocio
   +--> registra auditoría
   +--> persiste el nuevo estado

Pedidos no debería ejecutar directamente una función SQL equivalente a «suspender cliente» simplemente porque ambos servicios comparten una base de datos.

La suspensión no es solamente un UPDATE. Es una decisión.

Clientes debe determinar si la transición es válida, quién puede ejecutarla, qué auditoría requiere y qué otros efectos deben producirse. Si Pedidos pudiera modificar directamente la fila, el servicio propietario perdería el control de su propio dominio.

Cuando la operación es puramente técnica

Existe otro tipo de operación que sí puede tener sentido encapsular en SQL: una operación técnica, acotada, atómica y sin decisiones de negocio.

Por ejemplo, una función podría eliminar un registro temporal identificado explícitamente:

CREATE FUNCTION purgar_registro_temporal(p_registro_id UUID)
RETURNS VOID
LANGUAGE SQL
AS $$
    DELETE FROM registros_temporales
    WHERE id = p_registro_id;
$$;

La semántica es deliberadamente limitada. Si el registro existe, se elimina; si no existe, la operación no necesita tomar una decisión adicional.

La función no determina quién tiene derecho a suspender una cuenta, qué significa que una cuenta esté inactiva ni qué transición de negocio corresponde.

Este tipo de función puede ser útil como mecanismo de infraestructura, pero existe un riesgo importante: convertir gradualmente la base de datos en una segunda capa de aplicación.

Cuando cada nueva regla termina implementada como un stored procedure, la lógica queda repartida entre el backend y la base de datos. Las pruebas, el versionado, la observabilidad y el razonamiento sobre las reglas se vuelven progresivamente más difíciles.

La regla práctica es sencilla:

La base puede encapsular acceso y operaciones técnicas; el servicio debe conservar las decisiones del dominio.

Una matriz para decidir dónde vive cada operación

Esta separación puede resumirse en una regla operativa:

La matriz no pretende convertir la base de datos en un reemplazo universal de los servicios. Su propósito es asignar cada responsabilidad al canal que puede sostenerla sin volver a abrir el acceso indiscriminado al esquema interno.

El contrato también necesita gobierno

Una vista por sí sola no resuelve el problema. Si cualquier desarrollador puede modificarla sin considerar a sus consumidores, simplemente se habrá sustituido una dependencia implícita por otra.

Cada esquema y cada tabla privada deben tener un propietario claro. Las credenciales de Pedidos no deberían disponer de escritura sobre las tablas de Clientes y, cuando sea posible, tampoco deberían tener lectura directa sobre ellas.

El acceso público debe concederse sobre objetos concretos:

clientes
    ├── tablas privadas
    ├── funciones internas
    └── vistas publicadas
            └── acceso para Pedidos

El principio de mínimo privilegio ayuda a convertir la arquitectura deseada en una restricción técnica. Si Pedidos no tiene permiso para leer clientes, un nuevo JOIN directo deja de ser una tentación que depende exclusivamente de la disciplina del equipo.

Los contratos publicados también necesitan versionado.

Si la vista expone:

cliente_id
nombre_comercial
estado_comercial

y una nueva versión requiere eliminar estado_comercial, no debería tratarse como una modificación trivial. Es un cambio de contrato.

Una estrategia puede ser crear una nueva versión:

clientes_publicos_para_pedidos_v1
clientes_publicos_para_pedidos_v2

y mantener ambas durante un período de transición.

La nomenclatura concreta puede variar. Lo importante es que exista una forma de distinguir entre cambios compatibles y cambios incompatibles y que los consumidores puedan migrar deliberadamente.

El mismo principio aplica a las funciones SQL. Su firma, parámetros, comportamiento y permisos forman parte de una interfaz. No porque exista HTTP, sino porque otro componente depende de ella.

Medir antes de retirar

Una de las dificultades prácticas de estas migraciones es descubrir quién utiliza realmente una tabla.

En sistemas maduros, la documentación rara vez contiene todas las dependencias. Puede haber consultas en servicios antiguos, procesos batch, scripts operativos, herramientas de análisis, trabajos programados o accesos manuales que nadie recuerda.

Por eso la migración debería empezar con un inventario.

No basta con buscar referencias en el código fuente. También conviene revisar permisos, consultas observables en el motor, jobs programados, procesos de integración y consumidores conocidos.

El objetivo es construir un mapa aproximado:

                 ┌── Pedidos
clientes ────────┼── Facturación
                 ├── Reportes
                 └── Batch histórico

A partir de ahí, cada dependencia puede clasificarse.

Algunas serán invariantes legítimas. Otras serán lecturas que deberían convertirse en vistas. Otras serán escrituras que necesitan regresar al servicio propietario. Y algunas serán dependencias históricas que ya pueden eliminarse.

La observabilidad también permite medir el éxito de la transición: número de consumidores, frecuencia de consultas, latencia, errores, volumen de datos y tráfico entre dominios.

El objetivo no es solamente cambiar SQL. Es poder demostrar que la frontera está funcionando.

Una migración gradual sobre la misma infraestructura

Una de las ventajas de este enfoque es que no exige separar físicamente las bases desde el primer día.

La transición puede comenzar con la infraestructura actual.

Primero se construye un inventario de JOIN, consultas directas, procesos batch y permisos entre esquemas. Después se clasifican las relaciones para distinguir invariantes locales de dependencias entre dominios.

A continuación se declara quién es propietario de cada tabla, identificador y regla de ciclo de vida. Esta definición es importante porque una arquitectura no puede establecer fronteras si no está claro quién tiene autoridad sobre aquello que queda dentro de ellas.

Las lecturas necesarias para otros dominios se trasladan a vistas públicas. Las escrituras que expresan reglas de negocio se llevan a REST o gRPC. Las funciones SQL que permanezcan se mantienen deliberadamente pequeñas y técnicas.

Después se versionan los contratos y se empieza a medir su utilización.

Solo cuando los consumidores han dejado de depender de las tablas privadas tiene sentido retirar gradualmente esos permisos y revisar las FOREIGN KEY que atraviesan límites de propiedad.

Este orden importa.

Eliminar primero las restricciones o mover físicamente las bases no resuelve las dependencias semánticas. Es posible tener dos bases de datos completamente separadas y seguir manteniendo un acoplamiento fuerte si un servicio depende de la estructura interna del otro mediante consultas, replicaciones o procesos frágiles.

La frontera lógica debe preceder a la frontera física.

Preparar una futura separación física

Este modelo también puede funcionar como una etapa intermedia hacia una arquitectura con bases independientes.

Mientras ambos dominios comparten el mismo motor, Pedidos puede consumir:

VIEW clientes_publicos_para_pedidos

Más adelante, si Clientes pasa a tener su propia base de datos, esa misma semántica puede representarse mediante:

GET /clientes/{id}

o mediante un contrato equivalente en gRPC.

El cambio de infraestructura no necesita redefinir desde cero qué información necesita Pedidos. La interfaz conceptual ya existía.

Esto permite entender Database as an API no como una arquitectura final obligatoria, sino como una técnica de transición: primero se estabiliza el contrato y después, si es necesario, se separa la infraestructura que lo implementa.

La separación física deja de ser el mecanismo que crea la frontera y pasa a ser una consecuencia posible de una frontera que ya estaba definida.

Conclusión: la frontera que realmente hay que proteger

El desafío de trabajar con microservicios sobre una base de datos compartida no está en la existencia de una relación entre tablas, sino en determinar qué parte del modelo pertenece a cada dominio y qué información puede ser utilizada por los demás. Una relación entre pedidos y clientes puede ser necesaria desde el punto de vista de los datos, pero eso no significa que Pedidos deba conocer o depender de la estructura interna con la que Clientes gestiona sus propias entidades.

La autonomía comienza cuando cada dominio puede evolucionar su modelo interno sin obligar a los demás servicios a conocer esos cambios. Para conseguirlo, la base de datos compartida necesita límites explícitos. Las vistas permiten publicar únicamente los datos que un consumidor necesita; las funciones SQL pueden encapsular operaciones técnicas acotadas; y las decisiones que contienen reglas de negocio deben permanecer bajo la responsabilidad del servicio propietario, mediante REST, gRPC u otro mecanismo de integración apropiado.

Esto convierte la base de datos en algo más que un repositorio común. Puede actuar como una infraestructura compartida que ofrece contratos de acceso definidos y gobernados, en lugar de convertirse en un espacio donde cualquier servicio puede consultar y modificar libremente las estructuras de los demás.

Para que este modelo sea sostenible, los contratos necesitan las mismas garantías que cualquier otra interfaz entre componentes: propietarios claros, permisos restringidos, versionado, compatibilidad entre cambios, observabilidad y un proceso controlado para retirar consumidores. De esta manera, una vista o una función no son simplemente objetos de base de datos, sino parte de una superficie que un dominio decide publicar y mantener.

Este enfoque también permite avanzar de forma gradual. No es necesario separar físicamente las bases de datos para comenzar a establecer límites entre los servicios. Primero pueden definirse los contratos y eliminarse las dependencias directas sobre las tablas privadas. Más adelante, si las necesidades operativas lo requieren, esos mismos contratos pueden trasladarse a una API o a otra forma de comunicación entre servicios.

La separación física, por tanto, no tiene que ser el punto de partida para conseguir autonomía. Puede ser una evolución posterior de una frontera que ya existe a nivel lógico.

La idea central es sencilla:

Compartir una base de datos no obliga a compartir el modelo interno de cada dominio.

La cuestión importante no es cuándo eliminar una relación entre tablas ni cuándo separar físicamente las bases de datos. La cuestión es qué información y qué operaciones está dispuesto a publicar cada dominio, bajo qué condiciones y con qué garantías de estabilidad.

Cuando esa frontera está claramente definida, la base de datos compartida deja de ser una fuente de dependencias accidentales y puede convertirse en una etapa controlada hacia una arquitectura con mayor independencia. El siguiente paso natural consiste en estudiar cómo versionar estos contratos, detectar automáticamente a sus consumidores y establecer mecanismos que permitan evolucionar desde una base unificada hacia servicios con almacenamiento independiente cuando la arquitectura y las necesidades operativas lo justifiquen.

Llevas un tiempo trabajando en equipos que dicen practicar Scrum, y algo no termina de cuadrarte. Los sprints avanzan, la demo sale en tiempo, el tablero se vacía cada dos semanas. Y aun así, al cabo de varios meses, el sistema tiene algo raro: funciona por partes, pero no tiene columna vertebral. Cada módulo fue una decisión tomada en el momento, sin conversación con las anteriores. Se ve ágil desde afuera. Se siente frágil desde adentro.

No es que el equipo sea poco disciplinado. Los rituales se hacen, el backlog está priorizado, el Product Owner participa. El problema es más silencioso que eso: nadie definió, antes de arrancar, qué parte del proyecto no puede improvisarse sprint a sprint. Y esa omisión, que parece menor al principio, se cobra con intereses compuestos.

Lo que nadie dice en la retrospectiva

El síntoma más claro aparece cuando alguien intenta cambiar algo que parecía simple. Un ajuste en el modelo de datos toca cuatro historias ya entregadas. Un nuevo servicio necesita un contrato que nadie documentó porque se asumió. Una integración que "ya estaba resuelta" resulta que cada equipo la resolvió a su manera. Cada uno de esos problemas tiene la misma raíz: una decisión estructural que se tomó con la misma liviandad que una tarea de sprint.

La fragilidad no nace de hacer sprints cortos. Nace de confundir dos tipos de decisiones que tienen costos de reversión completamente distintos, y tratarlas como si fueran iguales.

Hay decisiones de implementación —cómo se resuelve una historia de usuario específica, en qué orden se atacan las funcionalidades dentro de una misma capa, qué tan grande es cada tarea— que son baratas de revertir. Si una no funciona, la corriges en el siguiente sprint sin que nada estructural se rompa. Esas son exactamente las decisiones que se benefician de la flexibilidad ágil: se ajustan con la información más fresca posible, sprint a sprint, sin necesidad de comité.

Y hay decisiones estructurales —el modelo de datos central, los contratos entre servicios, los patrones de comunicación del sistema— que son caras de cambiar una vez que varios equipos ya construyeron sobre ellas. Cada sprint que pasa sin que esas decisiones estén tomadas es un sprint que agrega capas sobre cimientos que nadie inspeccionó. El costo de revertirlas no crece linealmente: crece con cada historia que asumió que esa decisión ya estaba resuelta.

El error que produce proyectos frágiles no es aplicar demasiado ágil. Es aplicar la flexibilidad de la capa barata en la capa cara.

La solución incómoda

La respuesta es que esa capa cara necesita el tratamiento opuesto: rigidez deliberada antes de que comience el primer sprint. Se define una vez, con la misma seriedad que un plano estructural, y cambiarla requiere un proceso formal, no una conversación de pasillo. Es, en ese tramo específico, exactamente lo que hace la cascada.

Decirlo así genera resistencia inmediata. "Eso es cascada" es la objeción más rápida, y es comprensible: el malestar con la rigidez de los proyectos tradicionales es real y justificado. Pero la objeción parte de una confusión sobre qué es lo que realmente distingue cascada de ágil, y vale la pena deshacerla antes de continuar.

Lo que define a la cascada no es tener fases, ni tener diseño antes de construcción, ni tener decisiones tomadas de antemano. Lo que la define es que el mapa completo de trabajo —qué se construye, en qué orden, con qué criterios— se cierra una sola vez al principio y no se vuelve a abrir con lo que se aprende en el camino. Un proyecto en cascada puede tener veinte subproyectos y entregas parciales. Sigue siendo cascada porque el subproyecto quince ya estaba escrito en el mes uno, aunque se ejecute en el mes diez, y lo que se aprendió construyendo el subproyecto tres no tuvo ningún efecto sobre él.

Lo que distingue a ágil es una sola cosa: cuando terminas de ejecutar una unidad de trabajo, lo que aprendiste ahí puede reescribir el contenido, el orden o la existencia de la unidad que sigue. Es un bit de información viajando en dirección contraria al plan. Ese bit es lo que mantiene vivo el aprendizaje. Y ese bit puede existir perfectamente en un proyecto que tiene una arquitectura base cerrada, contratos entre servicios definidos antes del primer sprint, y una Definition of Ready rigurosa. Nada de eso impide que lo aprendido en el sprint tres cambie el alcance del sprint seis. Solo impide que lo aprendido en el sprint tres destruya los cimientos sobre los que ya construyó el resto del equipo.

Aplicar rigidez en la capa cara no es cascada. Es reconocer que no todas las decisiones tienen el mismo costo de reversión, y tratarlas en consecuencia.

Dónde vive esa rigidez dentro de Scrum

Lo interesante es que no necesitas inventar nada por fuera del framework. Ágil ya tiene nombre para cada capa de este sistema de gobernanza, y los tres elementos son igual de obligatorios.

El primero es el walking skeleton: antes de que arranque el primer sprint de construcción, el equipo define un esqueleto funcional y liviano que recorre el sistema de punta a punta. No es el diseño completo — es lo mínimo necesario para que todos los equipos construyan sobre la misma base sin pisarse. Incluye las decisiones que son caras de revertir: el modelo de datos central, los contratos entre servicios, los patrones de comunicación, las convenciones técnicas que el resto del proyecto va a asumir como dadas. Quién lo construye es el equipo técnico completo, antes del sprint uno, con la misma formalidad con que un arquitecto firma un plano estructural. Lo que viene después puede crecer y cambiar libremente — precisamente porque ese esqueleto existe.

El segundo y el tercero viven dentro de cada sprint y protegen ese esqueleto historia por historia: la Definition of Ready es la puerta de entrada —ninguna historia entra a un sprint sin demostrar que respeta los contratos que el walking skeleton estableció—, y la Definition of Done es la puerta de salida —ninguna historia se declara terminada sin haber verificado que sigue encajando con el sistema completo, no solo con el módulo recién construido.

Dicho así suena razonable. El problema es que la mayoría de los equipos tratan esa puerta de entrada como un trámite: "la historia tiene criterios de aceptación, ya está lista". Eso responde apenas una parte de la pregunta. Antes de que una historia entre a un sprint, alguien tiene que haber respondido, con la misma seriedad con que un ingeniero civil revisa un plano antes de excavar, qué depende de qué.

No basta con saber que la historia es viable en abstracto. Hay que identificar explícitamente qué habilitadores necesita para poder construirse: un endpoint que todavía no existe, un cambio en el modelo de datos que otra historia debe entregar primero, un permiso o una integración externa que tarda en aprobarse. Y aquí está el punto que casi siempre se salta: no puedes nombrar esas dependencias con honestidad si nadie diseñó, aunque sea a nivel de solución técnica, cómo se va a construir esa historia en concreto.

Decir "esto depende de X" sin haber bajado al menos un boceto de la solución —qué componentes toca, qué contrato de datos necesita, por dónde entra y por dónde sale la información— no es identificar una dependencia, es adivinarla. Y las dependencias adivinadas son exactamente las que aparecen a mitad del sprint disfrazadas de sorpresa.

Lo que una DoR seria realmente exige

Por eso la rigidez concreta no está en agregar más preguntas a un checklist de planning. Está en aceptar que ninguna historia entra a un sprint sin haber pasado antes por un ejercicio de diseño de solución propio, específico para esa actividad. No el diseño de arquitectura completo del sistema —eso vive en el walking skeleton y rara vez se toca. Es un diseño más modesto pero igual de innegociable: la DoR deja de ser una intención difusa en el momento en que se convierte en un entregable verificable con campos obligatorios.

Ninguna historia entra a Sprint Planning sin esos campos completos, y no admite medias respuestas. Como mínimo:

• El diseño de solución específico de esa actividad: qué componentes toca, por dónde entra y sale la información, qué contratos consume o expone.
• La lista explícita de dependencias y habilitadores identificados a partir de ese diseño, no adivinados desde la descripción funcional.
• La estimación de esfuerzo apoyada en esa lista. Construir algo que necesita tres piezas ajenas no cuesta lo mismo que construir algo autocontenido, aunque la descripción funcional suene igual de simple.
• Los criterios de aceptación funcionales: lo que ve el usuario.
• Los criterios no funcionales: rendimiento, seguridad, manejo de errores, mantenibilidad. Una historia puede cumplir su criterio funcional y aun así ser un desastre para el sistema si nadie exigió que respetara los estándares que el resto del proyecto ya adoptó.
• Dos validaciones distintas: la del dueño de producto, que confirma que resuelve el problema del usuario; y la del responsable técnico, que confirma que la solución respeta la arquitectura y los lineamientos que el walking skeleton estableció.

Si a la historia le falta cualquiera de esos ítems, no está lista, sin importar qué tan urgente parezca meterla al sprint. No es un principio abstracto: es un documento con campos obligatorios que nadie puede saltarse por falta de tiempo, exactamente igual que un plano estructural no se salta porque la obra vaya con retraso.

Esa segunda validación —la del responsable técnico— es la que casi nunca se sienta en la conversación. El usuario final valida si la historia resuelve su problema, pero eso es necesario y no suficiente. Falta quien evalúe si el modo en que se va a construir mantiene viva la coherencia del sistema completo. Puedes tener una historia perfectamente aprobada por el producto y absolutamente inaceptable para quien tiene que mantener esa base de código dentro de un año. Si tu Definition of Ready solo mira la primera validación, ya sembraste el mismo desacople que estás intentando evitar.

La Definition of Done cierra el ciclo: exigir pruebas de integración contra el sistema completo —y no solo contra el módulo recién construido— garantiza que lo que se declara terminado realmente encaja con todo lo demás. Ninguna de estas tres piezas rompe el Scrum Guide. Todas simplemente convierten en obligatorio, para ese proyecto específico, algo que el framework siempre dejó como decisión de cultura de equipo —y que la mayoría, por prisa o por comodidad, nunca llegó a decidir en serio.

De vuelta al tablero

Lo que hace funcionar este sistema no es la cantidad de rigor que aplicas, sino dónde lo aplicas. La mayor parte del proyecto —reglas de negocio, funcionalidades, flujos de usuario— se beneficia de decidirse tarde, con la información más fresca posible. Solo una fracción pequeña necesita el tratamiento opuesto: definirse antes, con formalidad, y no tocarse sin proceso. El walking skeleton, la DoR y la DoD son exactamente los tres puntos donde esa fracción vive.

Cuando vuelves al tablero de ese sprint en el que todo se veía bien —los puntos avanzaban, la demo salía en tiempo, nadie levantaba la mano— y lo comparas con el sistema que quedó meses después, frágil, sin columna vertebral, con cada módulo viviendo en su propia realidad, la distancia entre los dos momentos ya tiene explicación. No fueron los rituales, ni la disciplina del equipo, ni el framework. Fue que nadie definió los tres puntos donde el rigor no es opcional: el walking skeleton que estableciera la base común, la DoR que obligara a diseñar antes de construir, y la DoD que verificara que cada pieza encajaba con el resto.

Eso no es traicionar el manifiesto ágil. Es leerlo con más cuidado.

Las dos primeras partes de esta serie resolvieron un problema bien delimitado: construir un sistema de logging centralizado que operara de forma transversal sobre una arquitectura DDD sin contaminar la lógica de negocio. Al final de ese recorrido, el sistema producía registros estructurados, consistentes y con métricas de tiempo precisas en cada capa, todo sin una sola línea de log escrita manualmente en ninguna clase del dominio o la infraestructura.

Pero quedaba una deuda pendiente, y era visible precisamente porque el sistema funcionaba tan bien. Al serializar los argumentos y resultados de cada método, el aspecto exponía los datos tal como viajan por el sistema: nombres completos, direcciones de correo, identificadores, cualquier dato que el método recibiera o retornara aparecía en texto plano en el log. En un entorno de desarrollo o en una demostración técnica eso es aceptable. En producción, con herramientas de observabilidad accesibles a equipos de soporte, operaciones o incluso a proveedores externos, es un problema real.

La respuesta convencional a este problema es la convención: no logueen datos personales. Ya se exploró en la primera parte por qué las convenciones fallan, y el argumento aplica aquí con la misma fuerza. Una convención requiere que cada desarrollador, en cada momento, recuerde aplicarla. El día que alguien olvida, o que un nuevo integrante del equipo no la conoce, la protección desaparece sin dejar rastro. La única solución que escala es que la privacidad deje de ser responsabilidad de quien escribe el log y pase a ser una propiedad declarada en el modelo. Esta tercera parte documenta cómo se implementa exactamente eso.

El punto de partida: qué tenía el sistema y qué faltaba

Al concluir la segunda parte, el sistema de logs contaba con cinco artefactos: LoggingAopProperties para la configuración de patrones de interceptación, JacksonConfig para el ObjectMapper del aspecto, MethodLoggingAspect como motor de interceptación, la clase principal de la aplicación con @EnableConfigurationProperties, y el archivo application.properties. Cinco piezas que funcionaban como una unidad cohesionada.

El problema que esta iteración viene a resolver surgió de una decisión de diseño inicial que parecía razonable en ese momento: el ObjectMapper que usaba el aspecto para serializar argumentos y resultados era el mismo que Spring MVC usaba para las respuestas HTTP. Esto implicaba que cualquier cambio en la serialización para los logs afectaría también al contrato público de la API. Si se añadía un introspector que enmascarara emails, los emails llegarían enmascarados no solo al log, sino también al cliente que consumía la API. Es exactamente el tipo de acoplamiento involuntario que un diseño cuidadoso debe evitar: dos preocupaciones distintas compartiendo la misma pieza de infraestructura, sin que ninguna de las dos pueda evolucionar independientemente.

La primera tarea, entonces, era separar los dos mappers: uno para las respuestas HTTP, sin ninguna modificación, y otro exclusivo para los logs, que sería el que recibiría toda la lógica de enmascaramiento. Esta separación no es un detalle técnico menor. Es la decisión arquitectónica que hace posible todo lo que viene después.

La separación de los ObjectMapper

La solución es directa. Se crean dos configuraciones de Jackson independientes, cada una produciendo su propio bean con un calificador distinto.

SpringJacksonConfig, en el paquete applications/config, produce el ObjectMapper principal de la aplicación anotado con @Primary. Este mapper no tiene ningún introspector especial ni ninguna lógica de enmascaramiento. Es el que Spring MVC usa por defecto para serializar las respuestas HTTP y para deserializar los cuerpos de los requests, exactamente igual que antes:

@Configuration
public class SpringJacksonConfig {
    @Bean
    @Primary
    public ObjectMapper objectMapper() {
        ObjectMapper mapper = new ObjectMapper();
        mapper.registerModule(new JavaTimeModule());
        mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
        return mapper;
    }
}

JacksonConfig, en el paquete applications/shared/serialization/config, produce un segundo ObjectMapper identificado con el calificador "loggingObjectMapper". Este es el que el aspecto recibe por inyección y el único que conoce la existencia del sistema de enmascaramiento:

@Configuration
public class JacksonConfig {
    @Bean("loggingObjectMapper")
    public ObjectMapper objectMapper(MaskingStrategyRegistry registry, MaskingProperties maskingProperties) {
        ObjectMapper mapper = new ObjectMapper();
        mapper.registerModule(new JavaTimeModule());
        mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
        mapper.setAnnotationIntrospector(new DomainAnnotationIntrospectorConfig(registry, maskingProperties));
        return mapper;
    }
}

La línea que marca la diferencia es mapper.setAnnotationIntrospector(...). Un introspector en Jackson es el componente que decide, campo por campo, cómo debe serializarse cada propiedad de un objeto. Al inyectar un introspector personalizado, se puede interceptar el proceso de serialización en el momento exacto en que Jackson va a escribir un campo y aplicar la lógica de enmascaramiento antes de que el valor llegue al log. El aspecto, por su parte, pasa a inyectar el mapper correcto usando el calificador:

private final @Qualifier("loggingObjectMapper") ObjectMapper objectMapper;

A partir de este punto, los dos mappers evolucionan de forma completamente independiente. Añadir una nueva estrategia de enmascaramiento, modificar el comportamiento de una existente, o cambiar cómo se resuelven las reglas por nombre de campo son operaciones que ocurren en el sistema de logs sin afectar en absoluto las respuestas HTTP de la aplicación.

Las anotaciones del dominio

Con la infraestructura de serialización dividida, el siguiente paso es definir el vocabulario que el modelo de dominio usará para declarar la sensibilidad de sus campos. Ese vocabulario son tres anotaciones que viven en el paquete del dominio, completamente aisladas de cualquier dependencia de infraestructura.

La primera es @Hidden. Cuando un campo está anotado con ella, el introspector le indica a Jackson que lo omita completamente durante la serialización. No aparece como null, no aparece enmascarado: directamente no existe en el JSON producido para el log. El caso de uso más claro es el de campos cuyo tamaño o naturaleza los hace inadecuados para cualquier registro: imágenes en Base64, documentos adjuntos, objetos anidados muy grandes. En el proyecto de ejemplo se aplica sobre el campo fechaRegistro del modelo Usuario, que es un dato técnico interno sin valor para el diagnóstico operacional:

@Hidden
private LocalDateTime fechaRegistro;

La segunda es @Masked. Esta anotación indica que el campo contiene información sensible y que su valor debe transformarse antes de escribirse en el log. A diferencia de @Hidden, el campo sigue apareciendo en el registro, pero con su contenido protegido. La anotación acepta cuatro parámetros que controlan cómo se aplica la transformación: type define la estrategia de enmascaramiento, visibleStart y visibleEnd especifican cuántos caracteres se preservan al inicio y al final del valor original, y maskChar define el carácter de relleno. Cuando no se especifica ningún parámetro, el comportamiento por defecto es enmascaramiento total con asteriscos:

@Masked(type = MaskType.EMAIL)
private String email;

@Masked
private Integer edad;

@Masked(type = MaskType.CUSTOM, visibleStart = 2, visibleEnd = 2, maskChar = '*')
private String username;

La tercera anotación, @NoMask, sirve como escape explícito del sistema. Si un campo pertenece a una clase que tiene reglas globales por nombre aplicadas desde application.properties, pero ese campo en particular no debe enmascararse aunque su nombre coincida con alguna regla, @NoMask garantiza que el introspector lo serialice sin ninguna transformación. Es la forma de decir explícitamente que este campo, en este contexto, es seguro para el log.

Las tres se definen con retención RUNTIME para que estén disponibles mediante reflexión en el momento de la serialización, y con target FIELD porque se aplican sobre los campos del modelo:

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Hidden { }

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Masked {
    MaskType type() default MaskType.FULL;
    int visibleStart() default -1;
    int visibleEnd() default -1;
    char maskChar() default '*';
}

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface NoMask { }

Junto a las anotaciones, el enumerado MaskType define el catálogo de estrategias disponibles. En lugar de pasar strings o constantes al sistema, cada campo declara su tipo de máscara usando un valor tipado:

public enum MaskType {
    EMAIL,
    PHONE,
    CREDIT_CARD,
    DOCUMENT,
    PASSWORD,
    TOKEN,
    IBAN,
    FULL,
    CUSTOM
}

El catálogo incluye tanto tipos genéricos —FULL para enmascaramiento total y CUSTOM para transformaciones configuradas con los parámetros de la anotación— como tipos específicos por categoría de dato. El tipo CUSTOM merece una mención especial: es el que habilita las máscaras de desplazamiento, donde el desarrollador controla exactamente cuántos caracteres quedan visibles y desde dónde, sin necesidad de crear una estrategia nueva para cada variante.

Vale la pena detenerse un momento en dónde viven estas definiciones. Las anotaciones y el enumerado están en el paquete domain/shared/serialization/masking, dentro del dominio. No en infraestructura, no en la capa de aplicación: en el dominio. Esto es deliberado y tiene una implicación directa en el modelo de propiedad: quien define qué es sensible es el modelo de dominio mismo, en el mismo lugar donde se define la estructura del dato. Cuando un desarrollador abre Usuario.java y ve @Masked(type = MaskType.EMAIL) sobre el campo email, la intención es inmediata y no requiere buscar configuración en ningún otro archivo.

Las estrategias de enmascaramiento

Con el vocabulario de declaración definido, se necesita el mecanismo de ejecución: las clases que saben cómo transformar un valor según cada tipo de máscara. El diseño usa el patrón Strategy, con una interfaz común que todas las implementaciones respetan:

public interface MaskingStrategy {
    String mask(String value, Masked annotation);
}

El parámetro annotation no es ceremonial. Algunas estrategias, como CUSTOM, necesitan leer los valores de visibleStart, visibleEnd y maskChar de la anotación para saber cómo operar. Pasarla como argumento en lugar de extraerla en cada implementación hace que la interfaz sea suficientemente expresiva para todos los casos sin requerir que las estrategias simples la utilicen.

Cada implementación se anota con @MaskTypeHandler, una anotación personalizada que actúa como metadato de registro:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Component
public @interface MaskTypeHandler {
    MaskType value();
}

La anotación también incluye @Component, lo que hace que cada estrategia sea automáticamente un bean de Spring. Esto permite que MaskingStrategyRegistry, el componente que centraliza el acceso a las estrategias, las reciba todas por inyección de lista y construya un mapa indexado por tipo en su constructor:

@Component
public class MaskingStrategyRegistry {
    private final Map<MaskType, MaskingStrategy> strategies = new EnumMap<>(MaskType.class);

    public MaskingStrategyRegistry(List<MaskingStrategy> strategiesList) {
        for (MaskingStrategy strategy : strategiesList) {
            MaskTypeHandler annotation = strategy.getClass().getAnnotation(MaskTypeHandler.class);
            if (annotation != null) {
                strategies.put(annotation.value(), strategy);
            }
        }
    }

    public MaskingStrategy get(MaskType type) {
        return strategies.get(type);
    }
}

Este diseño tiene una propiedad muy conveniente: añadir una nueva estrategia de enmascaramiento al sistema se reduce a crear una clase que implemente MaskingStrategy y anotarla con @MaskTypeHandler indicando el tipo. El registry la descubre automáticamente en el siguiente arranque de la aplicación, sin ningún lugar central que modificar.

Las tres estrategias que el proyecto implementa ilustran el rango de transformaciones posibles. FullMaskingStrategy es la más simple: reemplaza cualquier valor con "****" independientemente de su contenido, cuando el dato no debe revelar ninguna información ni siquiera estructural:

@MaskTypeHandler(MaskType.FULL)
public class FullMaskingStrategy implements MaskingStrategy {
    @Override
    public String mask(String value, Masked annotation) {
        if (value == null) return null;
        return "****";
    }
}

EmailMaskingStrategy preserva la estructura del correo electrónico, manteniendo el dominio visible y enmascarando la parte local excepto los primeros dos caracteres. Un correo como [email protected] se convierte en ju***@empresa.com. Esta transformación comunica que el valor era un email y a qué dominio pertenecía, sin revelar la identidad del destinatario:

@MaskTypeHandler(MaskType.EMAIL)
public class EmailMaskingStrategy implements MaskingStrategy {
    @Override
    public String mask(String value, Masked annotation) {
        if (value == null || !value.contains("@")) {
            return value;
        }
        String[] parts = value.split("@", 2);
        String local = parts[0];
        String domain = parts[1];
        if (local.length() <= 2) {
            return "*@" + domain;
        }
        return local.substring(0, 2) + "***@" + domain;
    }
}

CustomMaskingStrategy delega en OffsetMasker, un componente que implementa la lógica de máscara por desplazamiento. Recibe los parámetros visibleStart, visibleEnd y maskChar directamente de la anotación y preserva exactamente esa cantidad de caracteres en cada extremo del valor, reemplazando el centro con el carácter de máscara configurado. Si la suma de los caracteres visibles es mayor o igual a la longitud total del valor, la cadena se retorna sin modificación, evitando transformaciones que no aportarían ningún tipo de protección real:

@RequiredArgsConstructor
@MaskTypeHandler(MaskType.CUSTOM)
public class CustomMaskingStrategy implements MaskingStrategy {
    private final OffsetMasker offsetMasker;

    @Override
    public String mask(String value, Masked annotation) {
        return offsetMasker.mask(value, annotation);
    }
}

@Component
public class OffsetMasker {
    public String mask(String value, Masked annotation) {
        return Optional.ofNullable(value)
                .filter(v -> !v.isBlank())
                .filter(v -> annotation != null)
                .map(v -> {
                    int length = v.length();
                    int visibleStart = annotation.visibleStart();
                    int visibleEnd = annotation.visibleEnd();
                    if (visibleStart + visibleEnd >= length) {
                        return v;
                    }
                    String start = v.substring(0, visibleStart);
                    String end = v.substring(length - visibleEnd);
                    String fixedMask = String.valueOf(annotation.maskChar()).repeat(4);
                    return start + fixedMask + end;
                })
                .orElse(value);
    }
}

Aplicado sobre el campo username con la declaración @Masked(type = MaskType.CUSTOM, visibleStart = 2, visibleEnd = 2, maskChar = '*'), un valor como juanperez se transforma en ju****ez. Los dos primeros y los dos últimos caracteres permanecen visibles; el centro queda reemplazado por cuatro asteriscos, independientemente de cuántos caracteres haya entre los extremos. Esta consistencia en la longitud del bloque de máscara es deliberada: evita que la longitud del valor enmascarado revele indirectamente la longitud del valor original.

El introspector: donde todo se conecta

Las estrategias saben cómo transformar valores, las anotaciones declaran qué campos son sensibles, y el registry mapea tipos a estrategias. La pieza que conecta todos estos elementos durante la serialización es DomainAnnotationIntrospectorConfig, la implementación personalizada del introspector de Jackson.

Esta clase extiende JacksonAnnotationIntrospector, que es el introspector estándar de Jackson. Al extender en lugar de reemplazar, se hereda todo el comportamiento normal de serialización y solo se sobreescriben los dos métodos relevantes para el enmascaramiento: hasIgnoreMarker, que controla si un campo debe omitirse, y findSerializer, que controla qué serializador se aplica sobre un campo.

La lógica de hasIgnoreMarker implementa la precedencia entre @NoMask y @Hidden. Si un campo tiene @NoMask, devuelve false independientemente de cualquier otra condición. Si tiene @Hidden, devuelve true para que Jackson lo excluya del JSON resultante. En cualquier otro caso delega al comportamiento estándar del padre:

@Override
public boolean hasIgnoreMarker(AnnotatedMember m) {
    if (m.hasAnnotation(NoMask.class)) {
        return false;
    }
    return m.hasAnnotation(Hidden.class) || super.hasIgnoreMarker(m);
}

La lógica de findSerializer implementa tres niveles de prioridad. El primer nivel es @NoMask: si el campo tiene esta anotación, el método devuelve el serializador estándar sin ninguna modificación. El segundo nivel es @Masked: si el campo tiene esta anotación, se construye un MaskedSerializer con el tipo y la anotación completa. El tercer nivel son las reglas por nombre de campo definidas en application.properties: si el nombre del campo coincide con alguna de esas reglas, se construye una instancia sintética de @Masked con el tipo resuelto y se aplica el mismo MaskedSerializer:

@Override
public Object findSerializer(Annotated am) {
    if (am.hasAnnotation(NoMask.class)) {
        return super.findSerializer(am);
    }
    Masked masked = am.getAnnotation(Masked.class);
    if (masked != null) {
        return new MaskedSerializer(registry, masked.type(), masked);
    }
    if (!resolvedRules.isEmpty()
            && am instanceof AnnotatedMethod
            && am.getName() != null) {
        String fieldName = am.getName();
        MaskType resolvedType = resolveByFieldName(fieldName);
        if (resolvedType != null) {
            Masked syntheticMasked = buildSyntheticMasked(resolvedType);
            return new MaskedSerializer(registry, syntheticMasked.type(), syntheticMasked);
        }
    }
    return super.findSerializer(am);
}

Este sistema de prioridades tiene una consecuencia operacional importante: las reglas por nombre de campo desde application.properties actúan como una red de seguridad para los datos que todavía no tienen anotación en el modelo. Si el equipo decide que todo campo cuyo nombre contenga email debe enmascararse como EMAIL aunque ningún campo del dominio tenga @Masked, basta con agregar la regla en el archivo de configuración.

La resolución de las reglas por nombre usa coincidencia parcial insensible a mayúsculas. Si más de una regla coincide con el mismo campo, el sistema aplica FULL como estrategia por defecto, eligiendo siempre la opción más conservadora ante la ambigüedad:

private MaskType resolveByFieldName(String fieldName) {
    String fieldNameLower = fieldName.toLowerCase();
    List<MaskType> matches = resolvedRules.entrySet().stream()
            .filter(entry -> fieldNameLower.contains(entry.getKey()))
            .map(Map.Entry::getValue)
            .collect(Collectors.toList());
    if (matches.isEmpty()) return null;
    if (matches.size() > 1) return MaskType.FULL;
    return matches.get(0);
}

Las reglas se pre-procesan en el constructor del introspector, convirtiendo los strings del mapa de propiedades a valores tipados de MaskType una sola vez en el momento de creación del bean. Esto garantiza que la comparación durante la serialización sea siempre una operación de bajo costo:

private Map<String, MaskType> buildResolvedRules(Map<String, String> rawRules) {
    if (rawRules == null || rawRules.isEmpty()) {
        return Map.of();
    }
    return rawRules.entrySet().stream()
            .collect(Collectors.toMap(
                    entry -> entry.getKey().toLowerCase().trim(),
                    entry -> resolveMaskType(entry.getValue())));
}

Si el string del valor en las propiedades no corresponde a ningún valor del enumerado MaskType, el método resolveMaskType devuelve FULL como fallback. Ante una configuración incorrecta o ambigua, el sistema protege más de lo necesario en lugar de exponer datos que deberían estar protegidos.

El serializador contextual

MaskedSerializer es el componente que Jackson invoca directamente cuando necesita escribir el valor de un campo que el introspector ha marcado para enmascarar. Implementa dos interfaces: JsonSerializer<Object>, que es el contrato estándar de serialización, y ContextualSerializer, que permite a Jackson pasar información adicional sobre el contexto del campo en el momento de la serialización.

La implementación de ContextualSerializer a través del método createContextual resuelve un problema sutil. Jackson no siempre invoca directamente el serializador registrado para un campo: a veces lo crea primero y luego le pasa el contexto del campo a través de createContextual. Sin esta interfaz, el serializador puede perder acceso a la anotación @Masked del campo concreto y por tanto a sus parámetros de configuración:

@Override
public JsonSerializer<?> createContextual(SerializerProvider prov, BeanProperty property) {
    if (property != null) {
        Masked masked = property.getAnnotation(Masked.class);
        if (masked != null) {
            return new MaskedSerializer(registry, masked.type(), masked);
        }
    }
    if (maskType != null && maskedAnnotation != null) {
        return this;
    }
    return new MaskedSerializer(registry);
}

La serialización del valor en sí es directa: si el valor es nulo se escribe null, de lo contrario se convierte a string, se consulta la estrategia correspondiente en el registry y se escribe el resultado transformado. Si por alguna razón no hay estrategia disponible para el tipo indicado, el campo se escribe como "****", garantizando que ningún dato sensible llegue al log incluso en casos de configuración incompleta:

@Override
public void serialize(Object value, JsonGenerator gen, SerializerProvider serializers)
        throws IOException {
    if (value == null) {
        gen.writeNull();
        return;
    }
    String strValue = value.toString();
    if (maskType != null && maskedAnnotation != null) {
        MaskingStrategy strategy = registry.get(maskType);
        if (strategy != null) {
            gen.writeString(strategy.mask(strValue, maskedAnnotation));
            return;
        }
    }
    gen.writeString("****");
}

El enmascaramiento de tipos simples en los parámetros de entrada

Las anotaciones sobre los campos del modelo de dominio cubren la serialización de los objetos que el aspecto captura como argumentos o resultados. Pero hay una categoría de casos que ese mecanismo no alcanza: los métodos que reciben tipos simples como parámetros directos, sin que haya un objeto con campos anotados de por medio.

Un ejemplo concreto está en el propio proyecto de ejemplo. El método existeEmail del adapter recibe un String como argumento:

public boolean existeEmail(String email)

Cuando el aspecto intercepta esa llamada y loguea el INPUT, el argumento es directamente el string con el correo electrónico. No hay ningún objeto Usuario que serializar, no hay ninguna anotación @Masked sobre el parámetro —Java no permite aplicar las anotaciones de campo sobre parámetros de método con la misma semántica—, y el ObjectMapper con el introspector no tiene forma de saber que ese string en particular es un email que debe enmascararse.

Para cubrir este caso, el aspecto implementa un mecanismo complementario de enmascaramiento a nivel de parámetro, basado en el nombre del parámetro en lugar de en una anotación sobre el campo. La clase MaskingProperties expone un mapa de reglas configurables desde application.properties:

logging.masking.field-name-rules.email=EMAIL
logging.masking.field-name-rules.phone=PHONE

El aspecto aplica esta lógica en el método maskIfSimpleType, que se invoca sobre cada argumento antes de que llegue a formatArg para la serialización:

private Object maskIfSimpleType(String paramName, Object value) {
    if (value == null) return null;
    if (!LoggingUtils.isSimpleType(value)) return value;

    Map<String, String> rules = maskingProperties.getFieldNameRules();
    if (rules == null || rules.isEmpty()) return value;

    String paramNameLower = paramName.toLowerCase();
    List<MaskType> matches = rules.entrySet().stream()
            .filter(entry -> paramNameLower.contains(
                    entry.getKey().toLowerCase().trim()))
            .map(entry -> LoggingUtils.resolveMaskType(entry.getValue()))
            .collect(Collectors.toList());

    if (matches.isEmpty()) return value;

    MaskType maskType = matches.size() > 1 ? MaskType.FULL : matches.get(0);
    MaskingStrategy strategy = maskingStrategyRegistry.get(maskType);
    if (strategy == null) return "****";

    return strategy.mask(value.toString(), LoggingUtils.buildSyntheticMasked(maskType));
}

El método solo actúa sobre tipos simples: String, Number, Boolean y Character. Para cualquier otro tipo, devuelve el valor sin modificación y deja que el ObjectMapper con el introspector maneje el enmascaramiento a través de las anotaciones del modelo. Esta separación evita la duplicación: los objetos complejos se enmascaran por vía del introspector, los tipos simples por vía del nombre del parámetro.

Cuando la estrategia necesita aplicarse sobre un tipo simple que no tiene una anotación real, se construye una instancia sintética de @Masked con los valores por defecto del tipo correspondiente. LoggingUtils.buildSyntheticMasked centraliza esa construcción:

public static Masked buildSyntheticMasked(MaskType maskType) {
    return new Masked() {
        @Override
        public Class<? extends java.lang.annotation.Annotation> annotationType() {
            return Masked.class;
        }

        @Override
        public MaskType type() {
            return maskType;
        }

        @Override
        public int visibleStart() {
            return -1;
        }

        @Override
        public int visibleEnd() {
            return -1;
        }

        @Override
        public char maskChar() {
            return '*';
        }
    };
}

Los valores negativos en visibleStart y visibleEnd son intencionales. Las estrategias que no usan esos parámetros, como FULL o EMAIL, simplemente los ignoran. La estrategia CUSTOM, que sí los usa, los interpreta como ausencia de configuración y aplica su lógica de fallback. De esta forma, la instancia sintética es válida para cualquier estrategia sin necesidad de crear variantes distintas según el tipo.

El registro de las propiedades en el bootstrap

Con todos los componentes del sistema de enmascaramiento en su lugar, la clase principal de la aplicación necesita registrar tanto LoggingAopProperties como la nueva MaskingProperties para que Spring Boot las enlace con el prefijo correspondiente del archivo de configuración:

@SpringBootApplication
@EnableConfigurationProperties({
    LoggingAopProperties.class,
    MaskingProperties.class
})
public class Id202603212000artApplication {
    public static void main(String[] args) {
        SpringApplication.run(Id202603212000artApplication.class, args);
    }
}

Sin MaskingProperties en esta lista, Spring Boot crea el bean pero no lo enlaza con el prefijo logging.masking. El mapa de reglas permanece vacío, el introspector construye un resolvedRules vacío, y el aspecto devuelve todos los tipos simples sin enmascarar. Es el mismo error silencioso que ocurriría si LoggingAopProperties no estuviera registrada: el sistema arranca sin errores, pero el comportamiento es diferente al esperado y sin ninguna advertencia visible.

La nueva estructura del sistema de logs

Con estas incorporaciones, el sistema de logs pasa de cinco artefactos a diecisiete. La división entre applications/shared/serialization y domain/shared/serialization refleja con precisión el límite de responsabilidades:

src/main/java/com/app_247/blog/id202603212000art/
│
├── Id202603212000artApplication.java
│
├── applications/
│   ├── config/
│   │   └── SpringJacksonConfig.java              ← ObjectMapper principal (@Primary)
│   │
│   └── shared/
│       ├── log/
│       │   ├── aspect/
│       │   │   └── MethodLoggingAspect.java       ← Motor de interceptación
│       │   ├── config/
│       │   │   └── LoggingAopProperties.java      ← Patrones de interceptación
│       │   └── tool/
│       │       ├── LoggingUtils.java              ← Utilidades de formato
│       │       └── PatternMatcher.java            ← Evaluación y cache de patrones
│       │
│       └── serialization/
│           ├── config/
│           │   ├── DomainAnnotationIntrospectorConfig.java  ← Introspector de máscaras
│           │   ├── JacksonConfig.java             ← ObjectMapper de logs
│           │   └── MaskingProperties.java         ← Reglas por nombre de campo
│           ├── strategy/
│           │   ├── MaskedSerializer.java          ← Serializador contextual
│           │   ├── MaskingStrategy.java           ← Interfaz de estrategias
│           │   ├── MaskingStrategyRegistry.java   ← Registro de estrategias
│           │   ├── MaskTypeHandler.java           ← Anotación de registro
│           │   └── strategies/
│           │       ├── CustomMaskingStrategy.java
│           │       ├── EmailMaskingStrategy.java
│           │       └── FullMaskingStrategy.java
│           └── util/
│               └── OffsetMasker.java              ← Lógica de máscara por offset
│
└── domain/
    └── shared/
        └── serialization/
            └── masking/
                ├── annotation/
                │   ├── Hidden.java
                │   ├── Masked.java
                │   └── NoMask.java
                └── vo/
                    └── MaskType.java

El dominio declara la intención: este campo es un email sensible, este campo no debe aparecer en ningún registro. La capa de aplicación ejecuta esa intención: sabe cómo transformar un email, sabe cómo invocar a Jackson con el introspector correcto, sabe cómo resolver los nombres de parámetro contra las reglas de configuración. El dominio no sabe nada de Jackson. La capa de aplicación no necesita saber qué datos son sensibles porque el dominio ya se lo comunicó a través de las anotaciones.

El flujo completo con enmascaramiento activo

Con todos los componentes integrados, vale la pena recorrer la salida real del sistema para el mismo flujo de registro de usuario que se documentó en la segunda parte, esta vez con el enmascaramiento activo.

La solicitud llega al Controller con nombre Juan Perez, email [email protected] y edad 25. El INPUT del Controller serializa el objeto RegistrarUsuarioRequest completo. Si la regla logging.masking.field-name-rules.email=EMAIL está activa, el campo email del request aparece transformado:

INFO : c.a.b.i.i.e.a.registrarusuario.RegistrarUsuarioController#registrar
       >>> [INPUT] | args: {request={"nombre":"Juan Perez","email":"ju***@empresa.com","edad":25}}

El UseCase recibe el RegistrarUsuarioIn y el aspecto loguea su INPUT. Los campos de este DTO tampoco tienen anotaciones directas, pero el email sigue siendo detectado por la regla de nombre de campo:

INFO : c.a.b.i.d.u.registrarusuario.RegistrarUsuarioUseCase#ejecutar
       >>> [INPUT] | args: {command={"nombre":"Juan Perez","email":"ju***@empresa.com","edad":25}}

El adapter consulta si el email existe. Aquí el parámetro es un String directo, y el mecanismo de enmascaramiento de tipos simples entra en acción. El nombre del parámetro es email, coincide con la regla configurada, y la estrategia EMAIL se aplica sobre el string antes de que llegue al log:

DEBUG : c.a.b.i.i.d.j.u.adapter.UsuarioPersistenciaAdapter#existeEmail
        >>> [INPUT] | args: {email="ju***@empresa.com"}

DEBUG : c.a.b.i.i.d.j.u.adapter.UsuarioPersistenciaAdapter#existeEmail
        <<< [OUTPUT] | return: false

WARN  : c.a.b.i.i.d.j.u.adapter.UsuarioPersistenciaAdapter#existeEmail
        *** [TIMING] | start: 15:47:05.750 | end: 15:47:05.870 | elapsed: 120ms ⚠️ superó umbral de 100ms

El UseCase construye el objeto Usuario y llama a gateway.guardar(). Aquí es donde el enmascaramiento basado en anotaciones del modelo muestra su efecto más visible. El objeto Usuario tiene cuatro campos con comportamiento especial: email con @Masked(type = MaskType.EMAIL), edad con @Masked por defecto que aplica FULL, username con @Masked(type = MaskType.CUSTOM, visibleStart = 2, visibleEnd = 2, maskChar = '*'), y fechaRegistro con @Hidden. El introspector lee esas anotaciones en el momento de la serialización y produce un JSON donde cada campo respeta exactamente la declaración del modelo:

DEBUG : c.a.b.i.i.d.j.u.adapter.UsuarioPersistenciaAdapter#guardar
        >>> [INPUT] | args: {usuario={"id":null,"nombre":"Juan Perez",
            "email":"ju***@empresa.com","edad":"****",
            "username":"ju****ez"}}

Tres aspectos de este registro merecen atención. Primero: fechaRegistro no aparece en absoluto, ni como null, ni como "****". La anotación @Hidden le indica al introspector que omita el campo completamente, y Jackson lo excluye sin dejar ninguna huella de su existencia. Segundo: edad es un entero, pero en el log aparece como "****", una cadena; el MaskedSerializer convierte cualquier valor a string antes de aplicar la máscara, porque la representación en el log es siempre texto. Tercero: username muestra "ju****ez", preservando exactamente dos caracteres al inicio y dos al final, con cuatro asteriscos en el centro independientemente de cuántos caracteres tenga el username real.

La persistencia ocurre y el adapter retorna el objeto Usuario con el id ya asignado. El OUTPUT aplica exactamente el mismo enmascaramiento sobre el objeto de retorno:

DEBUG : c.a.b.i.i.d.j.u.adapter.UsuarioPersistenciaAdapter#guardar
        <<< [OUTPUT] | return: {"id":1,"nombre":"Juan Perez",
            "email":"ju***@empresa.com","edad":"****",
            "username":"ju****ez"}

DEBUG : c.a.b.i.i.d.j.u.adapter.UsuarioPersistenciaAdapter#guardar
        *** [TIMING] | start: 15:47:05.877 | end: 15:47:05.939 | elapsed: 62ms

Finalmente, el Controller retorna el response HTTP. El RegistrarUsuarioResponse tampoco tiene anotaciones de enmascaramiento, pero las reglas por nombre de campo del introspector siguen activas:

INFO  : c.a.b.i.i.e.a.registrarusuario.RegistrarUsuarioController#registrar
        <<< [OUTPUT] | return: {"id":1,"nombre":"Juan Perez",
            "email":"ju***@empresa.com","username":"ju****ez",
            "fechaRegistro":"2026-05-18T15:47:05.8756894",
            "mensaje":"Usuario registrado exitosamente"}

INFO  : c.a.b.i.i.e.a.registrarusuario.RegistrarUsuarioController#registrar
        *** [TIMING] | start: 15:47:05.747 | end: 15:47:05.944 | elapsed: 197ms

La respuesta HTTP que el cliente recibe es completamente diferente. El SpringJacksonConfig produce un ObjectMapper sin ningún introspector de enmascaramiento, así que Spring MVC serializa el RegistrarUsuarioResponse tal como está, con todos sus campos en texto plano. El cliente ve el email completo, el username completo y la fecha de registro. El enmascaramiento existe exclusivamente en los logs y no tiene ningún efecto sobre el contrato público de la API.

Dos canales, dos contratos

Recorrer el flujo completo con enmascaramiento activo hace visible algo que conviene nombrar explícitamente porque es la garantía central de todo el diseño: los datos sensibles tienen dos representaciones distintas que nunca se contaminan entre sí.

En el canal de respuesta HTTP, los datos viajan en su forma original. El ObjectMapper principal, marcado con @Primary, es el que Spring Boot usa por defecto para cualquier serialización no calificada. No tiene introspector de enmascaramiento, no conoce la existencia de @Masked ni de @Hidden, y serializa exactamente lo que recibe.

En el canal de logs, los datos viajan en su forma protegida. El ObjectMapper de logs, identificado con el calificador "loggingObjectMapper", es el único que conoce el sistema de enmascaramiento. Solo lo recibe el aspecto, explícitamente a través de @Qualifier. Ningún otro componente del sistema puede confundirlo con el mapper principal porque @Primary garantiza que Spring resuelva cualquier inyección sin calificador hacia el mapper de HTTP.

Esta separación tiene una consecuencia que vale la pena señalar para los equipos que trabajan con múltiples desarrolladores en paralelo: es físicamente imposible introducir un bug donde el enmascaramiento afecte la respuesta HTTP, o donde la ausencia de enmascaramiento exponga datos en el log, siempre que se respeten dos reglas. Primera: cualquier inyección del ObjectMapper que no sea en el aspecto debe hacerse sin calificador, recibiendo siempre el bean @Primary. Segunda: cualquier nueva estrategia de enmascaramiento se registra en el sistema de logs a través de @MaskTypeHandler, nunca modificando el SpringJacksonConfig.

Si alguna vez aparece en una revisión de código un @Qualifier("loggingObjectMapper") en una clase que no sea MethodLoggingAspect, es una señal de alerta clara. La arquitectura hace visible la anomalía antes de que llegue a producción.

Privacidad por configuración, privacidad por declaración

El sistema implementa dos mecanismos de enmascaramiento que son complementarios pero que sirven propósitos distintos, y entender cuándo usar cada uno evita duplicaciones innecesarias y configuraciones contradictorias.

Las reglas por nombre de campo en application.properties son el mecanismo de cobertura amplia. Funcionan sobre cualquier objeto que el aspecto serialice, incluso si ese objeto pertenece a una librería externa o a una capa de la aplicación que no tiene acceso al paquete del dominio para añadir anotaciones. Son también el mecanismo de transición: mientras el equipo va añadiendo las anotaciones correctas al modelo, las reglas por nombre garantizan que los campos sensibles no queden expuestos en el proceso de migración. Su limitación es la precisión: una regla que aplica a cualquier campo cuyo nombre contenga email puede afectar campos que no son correos electrónicos pero que tienen esa cadena en su nombre por coincidencia.

Las anotaciones @Masked y @Hidden en el modelo son el mecanismo de precisión quirúrgica. Se aplican campo a campo, con el tipo exacto de transformación que corresponde a cada dato, y viven donde tienen semántica: en la definición del modelo. Su limitación es que requieren acceso al código fuente del modelo para añadirlas, lo cual no siempre es posible para tipos de terceros.

La convivencia de ambos mecanismos está gestionada por el orden de prioridades del introspector: @NoMask gana sobre todo, @Masked gana sobre las reglas por nombre, y las reglas por nombre actúan cuando no hay ninguna anotación. Un patrón de adopción razonable sería comenzar con reglas por nombre para tener cobertura inmediata en las categorías más sensibles —email, password, token, phone, document—, e ir añadiendo anotaciones al modelo progresivamente. Cuando todos los campos sensibles tienen su anotación, las reglas por nombre pasan a ser una segunda línea de defensa para los casos que se hayan podido olvidar.

Añadir una nueva estrategia de enmascaramiento

Uno de los beneficios del diseño basado en @MaskTypeHandler y MaskingStrategyRegistry es que extender el catálogo de estrategias es un proceso completamente autocontenido. Para ilustrarlo, los pasos para añadir una estrategia de enmascaramiento de números de teléfono que preserve los últimos cuatro dígitos son exactamente tres.

Primero, añadir el valor al enumerado si no existe ya:

public enum MaskType {
    EMAIL,
    PHONE,    // ya existe en el catálogo
    // ...
}

Segundo, crear la clase de estrategia con la anotación @MaskTypeHandler:

@MaskTypeHandler(MaskType.PHONE)
public class PhoneMaskingStrategy implements MaskingStrategy {
    @Override
    public String mask(String value, Masked annotation) {
        if (value == null || value.length() < 4) {
            return "****";
        }
        String lastFour = value.substring(value.length() - 4);
        return "****" + lastFour;
    }
}

Tercero, activar la regla en las propiedades si se quiere que aplique por nombre de campo sin necesidad de anotar cada campo individualmente:

logging.masking.field-name-rules.phone=PHONE

En el siguiente arranque de la aplicación, MaskingStrategyRegistry descubre la nueva clase a través de la inyección de lista y la registra bajo MaskType.PHONE. Ninguna otra clase del sistema necesita ser modificada. El mismo patrón aplica para cualquier necesidad especial: números de identificación nacional, IBANs bancarios, tokens de autenticación con un formato particular. El sistema crece con el proyecto sin acumular complejidad en ningún componente central.

Lo que el sistema no puede hacer solo

Con todo lo documentado hasta aquí, es tentador concluir que el sistema de enmascaramiento cubre la privacidad de los logs de forma completa y automática. Eso sería inexacto, y vale la pena ser preciso sobre los límites.

El sistema protege los datos que el modelo declara como sensibles y los que las reglas por nombre cubren. No puede proteger los datos que nadie declaró como sensibles. Si un desarrollador añade un campo numeroCuentaBancaria al modelo de dominio sin ninguna anotación y sin que ninguna regla por nombre lo cubra, ese campo llegará al log en texto plano.

Tampoco puede actuar sobre el contenido de los mensajes de excepción. Cuando el sistema loguea exception: BusinessException - El email [email protected] ya está registrado, el mensaje de la excepción llega al log tal como fue construido en el código que la lanzó. La única solución es no incluir datos sensibles en el mensaje de la excepción desde el inicio, lo cual es una decisión que ocurre en el momento de escribir el throw, no en el sistema de logs.

El mismo límite aplica para los stacktraces completos. Si en algún punto del sistema se loguea un stacktrace fuera del aspecto, y ese stacktrace incluye representaciones de objetos con datos sensibles en sus métodos toString(), esos datos quedarán expuestos. La regla práctica que complementa al sistema automatizado es la misma que aplica a cualquier mecanismo de privacidad: los datos sensibles no deben aparecer en los mensajes de error, en los métodos toString() de los modelos, ni en ningún otro lugar desde el que puedan filtrarse hacia un log sin pasar por el introspector.

Estas limitaciones no invalidan el diseño, lo contextualizan. El sistema automatizado elimina la categoría más grande y frecuente de exposición accidental. La categoría residual requiere disciplina en el código que construye los mensajes, y esa disciplina es significativamente más fácil de aplicar cuando el desarrollador sabe que el resto del sistema ya está cubierto.

Mirando hacia adelante

El sistema de observabilidad que esta serie ha construido a lo largo de sus tres partes es funcional, extensible y listo para producción. Pero como cualquier sistema bien diseñado, establece una base desde la que hay líneas naturales de evolución.

La integración con OpenTelemetry es la más inmediata. Los registros estructurados que produce el aspecto, con sus campos de capa, duración y firma de método, son compatibles con el modelo de spans de OpenTelemetry. Los mismos puntos de interceptación que hoy emiten registros de texto podrían emitir spans instrumentados que plataformas como Jaeger o Zipkin renderizan como árboles de llamadas con tiempos y metadatos visuales. La transición no requeriría cambios en ninguna clase de negocio: solo en el aspecto, que ya tiene toda la información necesaria para construir esos spans.

La generación de métricas con Micrometer desde los mismos puntos de interceptación eliminaría la duplicación entre el sistema de logs y el sistema de métricas. Hoy, para calcular la latencia promedio de un adapter externo es necesario parsear los registros TIMING. Con Micrometer integrado en el aspecto, ese mismo dato podría alimentar un histograma directamente en el momento de la interceptación, sin ningún procesamiento posterior.

El catálogo de estrategias también puede crecer según las necesidades de cada proyecto. Los tipos CREDIT_CARD, DOCUMENT, IBAN y TOKEN están definidos en el enumerado MaskType pero no tienen implementación en el proyecto de ejemplo. Añadir cada uno es exactamente el proceso de tres pasos que se describió antes. El sistema está diseñado para crecer en esa dirección sin ninguna fricción estructural.

Finalmente, el patrón de aspectos transversales que sostiene todo el sistema de observabilidad puede extenderse a otros dominios de preocupación que comparten la misma naturaleza: la auditoría de cambios de estado, el registro de accesos a datos sensibles para cumplimiento regulatorio, la validación automática de contratos entre capas. La mecánica es idéntica, y el código de negocio permanece completamente ajeno a esas preocupaciones.

Lo que esta serie ha documentado, más allá de los detalles técnicos de cada componente, es un argumento sobre cómo se relacionan la observabilidad y la privacidad cuando se tratan como decisiones arquitectónicas en lugar de como detalles de implementación. Cuando la observabilidad se diseña con los mismos principios que la lógica de negocio —separación de responsabilidades, consistencia y extensibilidad— y cuando la privacidad se declara donde tiene semántica, en el modelo de dominio junto al dato que protege, el resultado no es solo un sistema de logs que funciona. Es un sistema que el equipo puede confiar, extender y razonar, en producción, sin adivinar y sin comprometer la seguridad de los datos de los usuarios.

    # Anexo: Código fuente completo

El código completo del sistema de enmascaramiento se organiza en grupos funcionales que reflejan las responsabilidades de cada componente. Todos los artefactos están disponibles para que puedas reproducir el sistema en tu proyecto.

---

## Grupo 1 — Anotaciones de privacidad en el dominio

Las anotaciones que declaran la privacidad de los datos viven en el paquete de dominio y no tienen dependencias de infraestructura.

**Hidden.java** — Omite completamente un campo de los logs
```java
package com.app_247.blog.id202603212000art.domain.shared.serialization.masking.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Hidden {
}
```

**Masked.java** — Enmascara un campo según el tipo especificado
```java
package com.app_247.blog.id202603212000art.domain.shared.serialization.masking.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.vo.MaskType;

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Masked {
    MaskType type() default MaskType.FULL;
    int visibleStart() default -1;
    int visibleEnd() default -1;
    char maskChar() default '*';
}
```

**NoMask.java** — Excluye explícitamente un campo del enmascaramiento
```java
package com.app_247.blog.id202603212000art.domain.shared.serialization.masking.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface NoMask {
}
```

**MaskType.java** — Enum con los tipos de enmascaramiento disponibles
```java
package com.app_247.blog.id202603212000art.domain.shared.serialization.masking.vo;

public enum MaskType {
    EMAIL,
    PHONE,
    CREDIT_CARD,
    DOCUMENT,
    PASSWORD,
    TOKEN,
    IBAN,
    FULL,
    CUSTOM
}
```

---

## Grupo 2 — Estrategias de enmascaramiento

Cada estrategia implementa una forma específica de ocultar datos sensibles.

**MaskingStrategy.java** — Interfaz que todas las estrategias deben cumplir
```java
package com.app_247.blog.id202603212000art.applications.shared.serialization.strategy;

import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.annotation.Masked;

public interface MaskingStrategy {
    String mask(String value, Masked annotation);
}
```

**MaskTypeHandler.java** — Anotación para registrar estrategias automáticamente
```java
package com.app_247.blog.id202603212000art.applications.shared.serialization.strategy;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import org.springframework.stereotype.Component;

import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.vo.MaskType;

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Component
public @interface MaskTypeHandler {
    MaskType value();
}
```

**EmailMaskingStrategy.java** — Enmascara emails preservando el dominio
```java
package com.app_247.blog.id202603212000art.applications.shared.serialization.strategy.strategies;

import com.app_247.blog.id202603212000art.applications.shared.serialization.strategy.MaskTypeHandler;
import com.app_247.blog.id202603212000art.applications.shared.serialization.strategy.MaskingStrategy;
import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.annotation.Masked;
import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.vo.MaskType;

@MaskTypeHandler(MaskType.EMAIL)
public class EmailMaskingStrategy implements MaskingStrategy {

    @Override
    public String mask(String value, Masked annotation) {
        if (value == null || !value.contains("@")) {
            return value;
        }

        String[] parts = value.split("@", 2);
        String local = parts[0];
        String domain = parts[1];

        if (local.length() <= 2) {
            return "*@" + domain;
        }

        return local.substring(0, 2) + "***@" + domain;
    }
}
```

**FullMaskingStrategy.java** — Reemplaza todo el valor con asteriscos
```java
package com.app_247.blog.id202603212000art.applications.shared.serialization.strategy.strategies;

import com.app_247.blog.id202603212000art.applications.shared.serialization.strategy.MaskTypeHandler;
import com.app_247.blog.id202603212000art.applications.shared.serialization.strategy.MaskingStrategy;
import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.annotation.Masked;
import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.vo.MaskType;

@MaskTypeHandler(MaskType.FULL)
public class FullMaskingStrategy implements MaskingStrategy {

    @Override
    public String mask(String value, Masked annotation) {
        if (value == null) {
            return null;
        }
        return "****";
    }
}
```

**CustomMaskingStrategy.java** — Enmascara con control de caracteres visibles
```java
package com.app_247.blog.id202603212000art.applications.shared.serialization.strategy.strategies;

import com.app_247.blog.id202603212000art.applications.shared.serialization.strategy.MaskTypeHandler;
import com.app_247.blog.id202603212000art.applications.shared.serialization.strategy.MaskingStrategy;
import com.app_247.blog.id202603212000art.applications.shared.serialization.util.OffsetMasker;
import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.annotation.Masked;
import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.vo.MaskType;

import lombok.RequiredArgsConstructor;

@RequiredArgsConstructor
@MaskTypeHandler(MaskType.CUSTOM)
public class CustomMaskingStrategy implements MaskingStrategy {

    private final OffsetMasker offsetMasker;

    @Override
    public String mask(String value, Masked annotation) {
        return offsetMasker.mask(value, annotation);
    }
}
```

**OffsetMasker.java** — Utilidad para enmascarar con offsets configurables
```java
package com.app_247.blog.id202603212000art.applications.shared.serialization.util;

import java.util.Optional;

import org.springframework.stereotype.Component;

import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.annotation.Masked;

@Component
public class OffsetMasker {

    public String mask(String value, Masked annotation) {
        return Optional.ofNullable(value)
                .filter(v -> !v.isBlank())
                .filter(v -> annotation != null)
                .map(v -> {
                    int length = v.length();
                    int visibleStart = annotation.visibleStart();
                    int visibleEnd = annotation.visibleEnd();
                    if (visibleStart + visibleEnd >= length) {
                        return v;
                    }
                    String start = v.substring(0, visibleStart);
                    String end = v.substring(length - visibleEnd);
                    String fixedMask = String.valueOf(annotation.maskChar()).repeat(4);
                    return start + fixedMask + end;
                })
                .orElse(value);
    }
}
```

**MaskingStrategyRegistry.java** — Registro centralizado de estrategias
```java
package com.app_247.blog.id202603212000art.applications.shared.serialization.strategy;

import java.util.EnumMap;
import java.util.List;
import java.util.Map;

import org.springframework.stereotype.Component;

import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.vo.MaskType;

@Component
public class MaskingStrategyRegistry {

    private final Map<MaskType, MaskingStrategy> strategies = new EnumMap<>(MaskType.class);

    public MaskingStrategyRegistry(List<MaskingStrategy> strategiesList) {
        for (MaskingStrategy strategy : strategiesList) {
            MaskTypeHandler annotation = strategy.getClass().getAnnotation(MaskTypeHandler.class);
            if (annotation != null) {
                strategies.put(annotation.value(), strategy);
            }
        }
    }

    public MaskingStrategy get(MaskType type) {
        return strategies.get(type);
    }
}
```

---

## Grupo 3 — Configuración de Jackson para enmascaramiento

Estos componentes configuran Jackson para que aplique el enmascaramiento durante la serialización.

**MaskingProperties.java** — Propiedades de configuración para reglas por nombre
```java
package com.app_247.blog.id202603212000art.applications.shared.serialization.config;

import java.util.Collections;
import java.util.Map;
import org.springframework.boot.context.properties.ConfigurationProperties;
import lombok.Data;

@Data
@ConfigurationProperties(prefix = "logging.masking")
public class MaskingProperties {
    private Map<String, String> fieldNameRules = Collections.emptyMap();
}
```

**DomainAnnotationIntrospectorConfig.java** — Introspector personalizado de Jackson
```java
package com.app_247.blog.id202603212000art.applications.shared.serialization.config;

import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

import com.app_247.blog.id202603212000art.applications.shared.serialization.strategy.MaskedSerializer;
import com.app_247.blog.id202603212000art.applications.shared.serialization.strategy.MaskingStrategyRegistry;
import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.annotation.Hidden;
import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.annotation.Masked;
import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.annotation.NoMask;
import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.vo.MaskType;
import com.fasterxml.jackson.databind.introspect.Annotated;
import com.fasterxml.jackson.databind.introspect.AnnotatedMember;
import com.fasterxml.jackson.databind.introspect.AnnotatedMethod;
import com.fasterxml.jackson.databind.introspect.JacksonAnnotationIntrospector;

public class DomainAnnotationIntrospectorConfig extends JacksonAnnotationIntrospector {

    private final MaskingStrategyRegistry registry;
    private final Map<String, MaskType> resolvedRules;

    public DomainAnnotationIntrospectorConfig(
            MaskingStrategyRegistry registry,
            MaskingProperties maskingProperties) {
        this.registry = registry;
        this.resolvedRules = buildResolvedRules(maskingProperties.getFieldNameRules());
    }

    @Override
    public boolean hasIgnoreMarker(AnnotatedMember m) {
        if (m.hasAnnotation(NoMask.class)) {
            return false;
        }
        return m.hasAnnotation(Hidden.class) || super.hasIgnoreMarker(m);
    }

    @Override
    public Object findSerializer(Annotated am) {
        if (am.hasAnnotation(NoMask.class)) {
            return super.findSerializer(am);
        }
        
        Masked masked = am.getAnnotation(Masked.class);
        if (masked != null) {
            return new MaskedSerializer(registry, masked.type(), masked);
        }
        
        if (!resolvedRules.isEmpty() && am instanceof AnnotatedMethod && am.getName() != null) {
            String fieldName = am.getName();
            MaskType resolvedType = resolveByFieldName(fieldName);
            if (resolvedType != null) {
                Masked syntheticMasked = buildSyntheticMasked(resolvedType);
                return new MaskedSerializer(registry, syntheticMasked.type(), syntheticMasked);
            }
        }
        return super.findSerializer(am);
    }

    private MaskType resolveByFieldName(String fieldName) {
        String fieldNameLower = fieldName.toLowerCase();
        List<MaskType> matches = resolvedRules.entrySet().stream()
                .filter(entry -> fieldNameLower.contains(entry.getKey()))
                .map(Map.Entry::getValue)
                .collect(Collectors.toList());
        if (matches.isEmpty()) {
            return null;
        }
        if (matches.size() > 1) {
            return MaskType.FULL;
        }
        return matches.get(0);
    }

    private Map<String, MaskType> buildResolvedRules(Map<String, String> rawRules) {
        if (rawRules == null || rawRules.isEmpty()) {
            return Map.of();
        }
        return rawRules.entrySet().stream()
                .collect(Collectors.toMap(
                        entry -> entry.getKey().toLowerCase().trim(),
                        entry -> resolveMaskType(entry.getValue())));
    }

    private MaskType resolveMaskType(String value) {
        if (value == null || value.isBlank()) {
            return MaskType.FULL;
        }
        try {
            MaskType type = MaskType.valueOf(value.toUpperCase().trim());
            if (type == MaskType.CUSTOM) {
                return MaskType.FULL;
            }
            return type;
        } catch (IllegalArgumentException e) {
            return MaskType.FULL;
        }
    }

    private Masked buildSyntheticMasked(MaskType maskType) {
        return new Masked() {
            @Override
            public Class<? extends java.lang.annotation.Annotation> annotationType() {
                return Masked.class;
            }

            @Override
            public MaskType type() {
                return maskType;
            }

            @Override
            public int visibleStart() {
                return -1;
            }

            @Override
            public int visibleEnd() {
                return -1;
            }

            @Override
            public char maskChar() {
                return '*';
            }
        };
    }
}
```

**MaskedSerializer.java** — Serializador personalizado que aplica el enmascaramiento
```java
package com.app_247.blog.id202603212000art.applications.shared.serialization.strategy;

import java.io.IOException;

import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.annotation.Masked;
import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.vo.MaskType;
import com.fasterxml.jackson.core.JsonGenerator;
import com.fasterxml.jackson.databind.BeanProperty;
import com.fasterxml.jackson.databind.JsonSerializer;
import com.fasterxml.jackson.databind.SerializerProvider;
import com.fasterxml.jackson.databind.ser.ContextualSerializer;

public class MaskedSerializer extends JsonSerializer<Object> implements ContextualSerializer {

    private final MaskingStrategyRegistry registry;
    private final MaskType maskType;
    private final Masked maskedAnnotation;

    public MaskedSerializer(MaskingStrategyRegistry registry, MaskType maskType, Masked maskedAnnotation) {
        this.registry = registry;
        this.maskType = maskType;
        this.maskedAnnotation = maskedAnnotation;
    }

    public MaskedSerializer(MaskingStrategyRegistry registry) {
        this(registry, null, null);
    }

    @Override
    public void serialize(Object value, JsonGenerator gen, SerializerProvider serializers) throws IOException {
        if (value == null) {
            gen.writeNull();
            return;
        }
        String strValue = value.toString();
        if (maskType != null && maskedAnnotation != null) {
            MaskingStrategy strategy = registry.get(maskType);
            if (strategy != null) {
                gen.writeString(strategy.mask(strValue, maskedAnnotation));
                return;
            }
        }
        gen.writeString("****");
    }

    @Override
    public JsonSerializer<?> createContextual(SerializerProvider prov, BeanProperty property) {
        if (property != null) {
            Masked masked = property.getAnnotation(Masked.class);
            if (masked != null) {
                return new MaskedSerializer(registry, masked.type(), masked);
            }
        }
        if (maskType != null && maskedAnnotation != null) {
            return this;
        }
        return new MaskedSerializer(registry);
    }
}
```

**JacksonConfig.java** — Configuración del ObjectMapper para logging
```java
package com.app_247.blog.id202603212000art.applications.shared.serialization.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.app_247.blog.id202603212000art.applications.shared.serialization.strategy.MaskingStrategyRegistry;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;

@Configuration
public class JacksonConfig {
    @Bean("loggingObjectMapper")
    public ObjectMapper objectMapper(MaskingStrategyRegistry registry, MaskingProperties maskingProperties) {
        ObjectMapper mapper = new ObjectMapper();
        mapper.registerModule(new JavaTimeModule());
        mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
        mapper.setAnnotationIntrospector(new DomainAnnotationIntrospectorConfig(registry, maskingProperties));
        return mapper;
    }
}
```

**SpringJacksonConfig.java** — ObjectMapper principal sin enmascaramiento
```java
package com.app_247.blog.id202603212000art.applications.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;

@Configuration
public class SpringJacksonConfig {
    @Bean
    @Primary
    public ObjectMapper objectMapper() {
        ObjectMapper mapper = new ObjectMapper();
        mapper.registerModule(new JavaTimeModule());
        mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
        return mapper;
    }
}
```

---

## Grupo 4 — Integración con el aspecto de logging

El aspecto de logging se actualiza para usar el enmascaramiento en valores simples.

**Fragmento relevante de MethodLoggingAspect.java** — Método que enmascara valores simples
```java
private Object maskIfSimpleType(String paramName, Object value) {
    if (value == null) {
        return null;
    }
    if (!LoggingUtils.isSimpleType(value)) {
        return value;
    }
    Map<String, String> rules = maskingProperties.getFieldNameRules();
    if (rules == null || rules.isEmpty()) {
        return value;
    }
    String paramNameLower = paramName.toLowerCase();
    List<MaskType> matches = rules.entrySet().stream()
            .filter(entry -> paramNameLower.contains(entry.getKey().toLowerCase().trim()))
            .map(entry -> LoggingUtils.resolveMaskType(entry.getValue()))
            .collect(Collectors.toList());
    if (matches.isEmpty()) {
        return value;
    }
    MaskType maskType = matches.size() > 1 ? MaskType.FULL : matches.get(0);
    MaskingStrategy strategy = maskingStrategyRegistry.get(maskType);
    if (strategy == null) {
        return "****";
    }
    return strategy.mask(value.toString(), LoggingUtils.buildSyntheticMasked(maskType));
}
```

**Fragmento de LoggingUtils.java** — Métodos auxiliares para enmascaramiento
```java
public static boolean isSimpleType(Object value) {
    return value instanceof String
            || value instanceof Number
            || value instanceof Boolean
            || value instanceof Character;
}

public static MaskType resolveMaskType(String value) {
    if (value == null || value.isBlank()) {
        return MaskType.FULL;
    }
    try {
        MaskType type = MaskType.valueOf(value.toUpperCase().trim());
        return type == MaskType.CUSTOM ? MaskType.FULL : type;
    } catch (IllegalArgumentException e) {
        return MaskType.FULL;
    }
}

public static Masked buildSyntheticMasked(MaskType maskType) {
    return new Masked() {
        @Override
        public Class<? extends java.lang.annotation.Annotation> annotationType() {
            return Masked.class;
        }

        @Override
        public MaskType type() {
            return maskType;
        }

        @Override
        public int visibleStart() {
            return -1;
        }

        @Override
        public int visibleEnd() {
            return -1;
        }

        @Override
        public char maskChar() {
            return '*';
        }
    };
}
```

---

## Grupo 5 — Ejemplo de uso en el modelo de dominio

**Usuario.java** — Entidad de dominio con campos anotados
```java
package com.app_247.blog.id202603212000art.domain.model.usuario;

import java.time.LocalDateTime;

import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.annotation.Hidden;
import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.annotation.Masked;
import com.app_247.blog.id202603212000art.domain.shared.serialization.masking.vo.MaskType;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Usuario {
    private Long id;
    private String nombre;
    
    @Masked(type = MaskType.EMAIL)
    private String email;
    
    @Masked
    private Integer edad;
    
    @Masked(type = MaskType.CUSTOM, visibleStart = 2, visibleEnd = 2, maskChar = '*')
    private String username;
    
    @Hidden
    private LocalDateTime fechaRegistro;
}
```

---

## Grupo 6 — Configuración de la aplicación

**application.properties** — Configuración de reglas de enmascaramiento
```properties
# ================================
# AOP LOGGING
# ================================
logging.aop.enabled=true
logging.aop.base-package=com.app_247.blog.id202603212000art

# UseCase
logging.aop.patterns[0].package-regex=com\\.app_247\\.blog\\.id202603212000art\\.domain\\.usecase.*
logging.aop.patterns[0].class-regex=.*UseCase
logging.aop.patterns[0].method-regex=.*
logging.aop.patterns[0].log-level=INFO
logging.aop.patterns[0].warn-threshold-ms=300

# Adapter de persistencia
logging.aop.patterns[1].package-regex=com\\.app_247\\.blog\\.id202603212000art\\.infrastructure\\.drivenadapters.*
logging.aop.patterns[1].class-regex=.*Adapter
logging.aop.patterns[1].method-regex=.*
logging.aop.patterns[1].log-level=DEBUG
logging.aop.patterns[1].warn-threshold-ms=100

# Controller
logging.aop.patterns[2].package-regex=com\\.app_247\\.blog\\.id202603212000art\\.infrastructure\\.entrypoints.*
logging.aop.patterns[2].class-regex=.*Controller
logging.aop.patterns[2].method-regex=.*
logging.aop.patterns[2].log-level=INFO
logging.aop.patterns[2].warn-threshold-ms=500

# ================================
# MASKING — Reglas por nombre de campo
# ================================
logging.masking.field-name-rules.email=EMAIL
logging.masking.field-name-rules.phone=PHONE
logging.masking.field-name-rules.password=FULL
logging.masking.field-name-rules.token=FULL
logging.masking.field-name-rules.identificacion=FULL
```

**Id202603212000artApplication.java** — Clase principal con habilitación de propiedades
```java
package com.app_247.blog.id202603212000art;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;

import com.app_247.blog.id202603212000art.applications.shared.log.config.LoggingAopProperties;
import com.app_247.blog.id202603212000art.applications.shared.serialization.config.MaskingProperties;

@SpringBootApplication
@EnableConfigurationProperties({
    LoggingAopProperties.class,
    MaskingProperties.class
})
public class Id202603212000artApplication {
    public static void main(String[] args) {
        SpringApplication.run(Id202603212000artApplication.class, args);
    }
}
```

---

Con estos componentes tienes todo lo necesario para implementar el sistema completo de enmascaramiento de datos sensibles en logs. El código está organizado siguiendo los principios de arquitectura limpia: las anotaciones viven en el dominio sin dependencias de infraestructura, las estrategias son componentes aislados y extensibles, y la configuración de Jackson se mantiene separada del ObjectMapper principal que usa Spring MVC para las respuestas HTTP.

  

Imagina que llevas meses construyendo un sistema moderno sobre PostgreSQL, desplegado en contenedores sobre una infraestructura en la nube. Los datos están bien estructurados, las relaciones son claras, las consultas son rápidas. Un día descubres que el sistema con el que tienes que integrarte no sabe lo que es una API. Su protocolo de integración es un archivo CSV que aparece en una carpeta a las 2 de la mañana. Si el archivo llega, el sistema funciona. Si no llega, el negocio se detiene.

No es un escenario hipotético. Es la realidad operativa de una cantidad enorme de empresas que modernizaron una parte de su infraestructura sin poder modernizar todo al mismo tiempo. El sistema legado sigue ahí, inamovible, consumiendo archivos como siempre lo hizo, y el sistema nuevo tiene que aprender a hablarle en ese idioma.

La pregunta que surge de inmediato parece simple: ¿cómo tomas los datos que viven en tu base de datos y los conviertes en un archivo CSV que llega a S3 de forma confiable? Pero debajo de esa pregunta hay varias más que definen la complejidad real del problema, y entenderlas bien es lo que separa una integración sólida de una que falla en silencio cuando más importa.

El problema que se esconde detrás del problema

La primera reacción cuando te enfrentas a este reto suele ser optimista. Tienes los datos en la base de datos, sabes el formato que necesita el sistema legado, y S3 es solo una carpeta en la nube. La solución parece obvia: consultas los registros, los transformas y los subes. Tres pasos. Una tarde de trabajo.

Esa imagen se complica en cuanto empiezas a hacerte las preguntas correctas.

¿Cómo sabes qué registros procesar en cada ciclo? El proceso corre periódicamente y cada ejecución debe tomar exactamente los registros que le corresponden, sin repetir los del ciclo anterior ni perderse ninguno del actual. Necesitas algún mecanismo para rastrear qué ya se procesó y qué no. Luego está la pregunta de dónde viven realmente los datos que necesitas exportar: raramente en una sola tabla. Generalmente hay información distribuida en varias tablas relacionadas que hay que unir, transformar y formatear según la estructura exacta que el sistema legado espera, y esa transformación tiene un costo que no siempre es trivial. La más incómoda llega al final: ¿qué pasa si algo sale mal a mitad del proceso? ¿Los registros quedan marcados como procesados aunque el archivo nunca haya llegado a S3? ¿O el archivo llega pero la base de datos queda inconsistente porque el proceso murió antes de confirmar? ¿Y si el volumen crece y un solo proceso ya no alcanza a terminar a tiempo?

Cada una de esas preguntas revela una decisión de arquitectura que no puedes ignorar. Y hay una más que puede o no aplicar a tu caso: ¿el sistema legado espera un solo archivo por ciclo o varios, cada uno con un formato distinto? Si tu integración es simple y homogénea, la respuesta es uno. Pero si los datos que exportas representan entidades distintas con estructuras distintas, el sistema legado puede esperar un archivo por cada tipo. Vale la pena saberlo desde el principio, porque esa variable aparece en ambos enfoques y cambia algunas decisiones de implementación.

El flujo a grandes rasgos

Antes de entrar en los detalles, vale la pena tener clara la imagen completa de lo que estamos construyendo, porque esa imagen es la que le da sentido a cada decisión que viene después.

El sistema legado espera sus archivos a una hora determinada. No los solicita, no los consulta, no tiene una API a la que llamar: simplemente los recoge de una ubicación conocida en el momento que tiene programado. Eso impone una restricción que define toda la arquitectura: el proceso de exportación tiene que ejecutarse de forma programada, en un horario fijo, con suficiente anticipación para que los archivos estén listos cuando el sistema legado los busque.

El flujo general es el siguiente: a la hora programada se activa un proceso que extrae los registros pendientes de la base de datos, los transforma siguiendo el formato exacto que el sistema legado espera, genera los archivos CSV correspondientes y los deposita en S3. A partir de ahí el sistema legado toma esos archivos y los incorpora a su propio flujo de procesamiento.

Hora programada
     ↓
Proceso extrae registros pendientes de PostgreSQL
     ↓
Transforma y formatea según plantilla del sistema legado
     ↓
Deposita archivos CSV en S3
     ↓
Sistema legado recoge los archivos y los procesa

Simple en apariencia. Pero garantizar que ese flujo sea confiable, que cada registro se procese exactamente una vez y que los archivos lleguen siempre en un estado consistente, es donde está el verdadero reto.

Dos caminos, un mismo destino

Para resolver este problema existen dos enfoques que cubren la mayoría de los escenarios reales. Cuál usar depende principalmente del volumen de datos, de si el procesamiento por registro requiere lógica fuera de la base de datos y de qué tan detallada necesitas que sea la trazabilidad cuando algo falla.

El primero delega casi todo el trabajo a la base de datos. PostgreSQL tiene una instrucción llamada COPY TO STDOUT que puede leer registros, aplicar transformaciones y devolver el resultado en formato CSV directamente al proceso que hizo la consulta, todo en una sola operación. Es elegante, directo y eficiente cuando el dataset es acotado y predecible, y cuando un solo proceso tiene el tiempo y la memoria suficientes para manejarlo completo.

El segundo reconoce que hay situaciones donde esa elegancia no alcanza. Cuando el volumen es grande, cuando cada registro requiere procesamiento costoso fuera de la base de datos, o cuando un fallo no puede tirar todo el trabajo sino solo la parte afectada, necesitas un patrón más sofisticado: múltiples procesos trabajando en paralelo, cada uno tomando lotes pequeños, coordinándose a través de la misma base de datos y contribuyendo su parte a un archivo final que S3 ensambla mediante su mecanismo de carga en partes. Este mecanismo, sin embargo, exige que cada fragmento que se sube pese al menos 5MB, lo que convierte ese umbral en una condición técnica que determina si este enfoque es viable o no.

Ninguno de los dos es mejor en abstracto. La elección depende de tu escenario concreto, y para que esa decisión sea más fácil de tomar, aquí está el comparativo completo:

Con la decisión tomada, entremos en los detalles de cada uno.

Enfoque A: dejar que la base de datos haga el trabajo pesado

Hay algo intuitivamente correcto en la idea de que quien tiene los datos es quien mejor puede procesarlos. PostgreSQL no es solo un lugar donde guardar información: es un motor de procesamiento con capacidades que muchos equipos subutilizan, y COPY TO STDOUT es una de esas capacidades.

Cuando ejecutas COPY TO STDOUT con una consulta SQL, PostgreSQL lee los registros, aplica las transformaciones que definas, los marca como procesados dentro de la misma operación y devuelve el resultado en formato CSV directamente al proceso a través de la conexión. El proceso que recibe ese stream solo tiene que subirlo a S3. El trabajo pesado de transformación y formateo ocurre dentro de la base de datos, no en el proceso que la llama.

Al recibir el resultado en un único stream, el archivo completo se sube a S3 en un solo envío sin restricciones de tamaño mínimo. Este enfoque es especialmente adecuado cuando el CSV resultante del ciclo no supera los 5MB, lo que en la práctica cubre la gran mayoría de integraciones con volúmenes diarios moderados. A partir de ese umbral, las opciones de consolidación disponibles cambian y vale la pena evaluar si este enfoque sigue siendo el más apropiado.

Una preparación que vale la pena

Antes de ejecutar esa consulta, hay una decisión de diseño que puede marcar la diferencia entre un proceso ágil y uno que pone la base de datos bajo presión innecesaria. Los registros que necesitas exportar raramente viven en una sola tabla con el formato exacto que necesita el CSV. Generalmente hay que unir varias tablas, transformar algunos campos y ordenar las columnas de cierta manera. Hacer toda esa lógica en el momento de la exportación, sobre todos los registros de un ciclo, puede ser costoso cuando el volumen es considerable.

La alternativa es preparar el terreno antes: mantener una tabla auxiliar cuya estructura sea idéntica al CSV destino. La lógica de transformación ocurre cuando los datos llegan al sistema, no cuando salen. Si el sistema que alimenta la base de datos puede escribir directamente en esa tabla con el formato correcto, perfecto. Si no puede, un disparador en PostgreSQL puede hacer esa transformación automáticamente cada vez que se inserta un registro nuevo, sin que el proceso de exportación tenga que preocuparse por eso.

En cualquier caso el resultado es el mismo: en el momento de exportar tienes una tabla limpia y lista donde la consulta del COPY TO STDOUT es un SELECT simple sin transformaciones costosas. Para este enfoque esa tabla no es una recomendación opcional: es prácticamente un requisito. Una consulta compleja sobre decenas de miles de registros con múltiples uniones puede tardar lo suficiente como para alcanzar los límites de tiempo de la conexión, y el impacto sobre la base de datos durante esa operación puede afectar otros procesos que corren al mismo tiempo.

El flujo completo

Con la tabla de exportación lista, el proceso arranca consultando qué tipos de registros existen con trabajo pendiente. Si solo se tiene un tipo de formato de CSV, este paso es trivial: siempre hay un único archivo que generar. Si tienes varios, cada tipo corresponde a una plantilla distinta y puede haber uno o varios archivos por ciclo. En cualquier caso el proceso abre una transacción por cada tipo, ejecuta el COPY TO STDOUT que lee los registros y los marca como procesados en la misma operación, recibe el stream CSV completo, lo sube a S3 y confirma la transacción si S3 respondió con éxito. Si S3 falla, hace rollback y ese tipo queda pendiente para el siguiente ciclo.

Proceso arranca
     ↓
Consulta qué tipos tienen registros pendientes
     ↓
Por cada tipo:
     Abre transacción
          ↓
     COPY TO STDOUT:
     SELECT sobre tabla de exportación
     + marca registros como procesados
     + devuelve CSV listo
          ↓
     Sube CSV a S3
          ↓
     S3 exitoso → confirma transacción ✅
     S3 falla   → rollback → registros vuelven a pendiente 🔄

Aquí aparece una decisión de diseño que vale la pena tomar conscientemente antes de implementar: ¿el fallo de un tipo debe afectar a los demás o cada uno es independiente?

Cuando cada tipo vive su propia historia

Si los tipos son independientes entre sí, cada uno tiene su propia transacción. El sistema legado puede recibir los archivos de los tipos que funcionaron mientras el tipo fallido se reintenta en el siguiente ciclo. Es la opción más resiliente y la más simple de implementar porque los fallos están contenidos: un problema con un tipo no contamina a los demás.

Tipo A → transacción propia → éxito ✅
Tipo B → transacción propia → falla → rollback → pendiente 🔄
Tipo C → transacción propia → éxito ✅

El siguiente ciclo solo tiene trabajo pendiente del Tipo B. Los demás ya están procesados y no se vuelven a tocar.

Cuando todos los tipos son parte de un todo

Hay casos donde el sistema legado espera todos los archivos juntos o ninguno. Recibir una parte y no la otra puede generar inconsistencias en el proceso de negocio del otro lado. En esos casos necesitas que la subida a S3 sea atómica: o llegan todos los archivos o no llega ninguno.

S3 no ofrece esa atomicidad de forma nativa para múltiples archivos independientes. Pero hay una forma de conseguirla: comprimir todos los CSVs en un único archivo y hacer un solo envío a S3. O el archivo comprimido llega completo o no llega nada. No hay estado intermedio posible.

Abre una sola transacción
     ↓
Por cada tipo ejecuta COPY TO STDOUT
y acumula los CSVs en memoria
     ↓
Comprime todos los CSVs en un único archivo
     ↓
Un solo envío a S3
     ↓
Éxito  → confirma transacción ✅
Falla  → rollback → todos los registros vuelven a pendiente 🔄

Esta variante tiene un requisito adicional del lado del sistema legado: necesita poder descomprimir el archivo antes de procesarlo. Si el sistema legado no tiene esa capacidad —y muchos no la tienen precisamente porque son legados— la solución es una función Lambda en S3 que se dispara automáticamente cuando llega el archivo comprimido, lo descomprime y deja los CSVs individuales en la ubicación que el sistema legado espera. El sistema legado nunca sabe que hubo un archivo comprimido de por medio.

Lo que necesitas para implementarlo

Para que este enfoque funcione, la tabla de exportación debe tener al menos dos elementos además de las columnas del CSV: un campo de estado que indique si el registro está pendiente o ya fue procesado, y la estructura debe estar alimentada por el sistema origen o por un disparador según la capacidad disponible.

Enfoque B: cuando el trabajo es demasiado para uno solo

Hay un punto en el crecimiento de cualquier sistema donde un solo proceso ya no es suficiente. El volumen supera lo que puede procesarse en el tiempo disponible, o simplemente la infraestructura escala horizontalmente y levantar múltiples instancias del mismo proceso es la forma natural de responder a la demanda. Pero este enfoque tiene dos condiciones que deben cumplirse para que tenga sentido aplicarlo.

La primera es que haya procesamiento real y costoso por registro fuera de la base de datos: llamadas a APIs externas, validaciones complejas en código o transformaciones que no pueden vivir en SQL. Si todo el procesamiento puede ocurrir en la base de datos, el Enfoque A resuelve el problema con mucha menos complejidad.

La segunda es que el volumen de datos por ciclo supere los 5MB. Este número no es arbitrario: es el tamaño mínimo que S3 exige por cada parte en su mecanismo de carga en partes, que es el que permite consolidar el trabajo de múltiples pods en un único archivo final. Por debajo de ese umbral, el mecanismo de consolidación no es aplicable y el Enfoque A sigue siendo la opción correcta.

Si ambas condiciones se cumplen, este enfoque ofrece algo que el Enfoque A no puede dar: escala horizontal, trazabilidad por registro y manejo de errores individuales sin detener el ciclo completo.

El problema central: coordinación y consolidación

Cuando múltiples pods consultan la base de datos al mismo tiempo y encuentran los mismos registros pendientes, ambos intentarán procesarlos y terminarás con duplicados. Evitar eso sin introducir un componente externo de coordinación es precisamente lo que hace interesante este enfoque.

La solución para la coordinación está en PostgreSQL mismo. La instrucción SELECT FOR UPDATE SKIP LOCKED permite que un pod tome un conjunto de registros y los bloquee de forma que otros pods que ejecuten la misma consulta simplemente los salten y tomen registros distintos. El bloqueo dura solo el tiempo necesario para que el pod reclame esos registros como suyos, no durante todo el procesamiento. Así múltiples pods pueden trabajar en paralelo sobre el mismo conjunto de datos sin coordinación externa y sin duplicados.

El segundo problema es la consolidación: ¿cómo unen su trabajo múltiples pods en un único archivo final? La respuesta está en una tabla temporal en la misma base de datos. Cada pod, al terminar de procesar un registro, deposita la línea CSV ya formateada junto con su peso en bytes en esa tabla. Cualquier pod puede consultar el peso acumulado en esa tabla y cuando detecta que hay suficiente para una parte válida de 5MB, toma esas líneas y las sube al mecanismo de carga en partes de S3. El peso pre-calculado en bytes permite saber con precisión cuándo se tiene suficiente para una parte válida sin estimaciones ni aproximaciones.

La sesión como punto de coordinación

Para que múltiples pods trabajen sobre el mismo conjunto de registros de forma ordenada, necesitan compartir cierta información: qué registros les corresponde procesar en este ciclo y a qué carga en partes de S3 deben contribuir. Esa información vive en lo que llamamos una sesión de exportación.

Una sesión representa un ciclo completo de exportación. Contiene la ventana de registros que se van a procesar —definida por el identificador mínimo y máximo de los registros pendientes al inicio del ciclo— y los tipos de registro que existen dentro de esa ventana. Todos los pods del ciclo leen esa sesión para saber qué les toca hacer.

La sesión se crea una sola vez al inicio del ciclo y cierra una sola vez al final. Ambas operaciones son bloqueantes: cuando múltiples pods arrancan al mismo tiempo, el primero que llega crea la sesión mientras los demás esperan. El mecanismo que garantiza que solo un pod hace cada una de esas operaciones es el mismo bloqueo pesimista de PostgreSQL: SELECT FOR UPDATE sobre el registro de control de la sesión.

El ciclo de vida completo

El flujo completo tiene tres fases que se ejecutan en orden estricto.

Inicio de la sesión. Cuando el cron dispara los pods, todos intentan iniciar o unirse a una sesión activa. El primero que llega no encuentra sesión activa, bloquea el registro de control y asume la responsabilidad de inicializar el ciclo.

Lo primero que hace ese pod —antes de definir qué registros procesará— es revisar si quedaron registros atascados del ciclo anterior. Un pod puede morir en medio del procesamiento por razones fuera de su control: un fallo de infraestructura, un timeout, una excepción no manejada. Cuando eso ocurre, los registros que ese pod había tomado quedan marcados como en procesamiento pero nunca llegan a completarse. El pod que inicia la sesión los detecta buscando registros que lleven más tiempo del razonable en ese estado y los devuelve a pendiente antes de continuar.

Con los registros huérfanos recuperados, el pod determina la ventana del ciclo: consulta el identificador mínimo y máximo de los registros pendientes y fija esos valores como los límites del ciclo. Ningún registro que llegue después de ese momento entra en este ciclo. Luego consulta qué tipos de registros existen dentro de esa ventana y registra esa información en la sesión sin iniciar aún ninguna carga en S3. El Multipart Upload no se inicia en este momento porque todavía no se sabe si habrá suficiente volumen para justificarlo. Finalmente libera el bloqueo y los demás pods pueden empezar a trabajar.

Primer pod llega
     ↓
No encuentra sesión activa → bloquea registro de control
     ↓
Recupera registros huérfanos del ciclo anterior
     ↓
Determina ventana: min_id y max_id de registros pendientes
     ↓
Consulta tipos distintos dentro de la ventana
     ↓
Por cada tipo registra en DB:
     - el tipo
     - estado OPEN
     - sin uploadId aún
     ↓
Marca sesión como activa y libera bloqueo
     ↓
Los demás pods leen la sesión y empiezan a trabajar

Procesamiento en lotes. Cada pod entra en un ciclo continuo donde toma lotes de registros, los procesa y deposita las líneas resultantes en la tabla temporal, hasta que no queden registros pendientes dentro de la ventana.

Por cada lote, el pod ejecuta SELECT FOR UPDATE SKIP LOCKED sobre los registros pendientes dentro de la ventana. Inmediatamente los marca como en procesamiento y cierra la transacción, liberando el bloqueo para que otros pods puedan seguir tomando registros distintos. Luego procesa cada registro consultando sus tablas relacionadas, validando los datos y formateando la línea CSV según la plantilla del tipo correspondiente.

Al terminar cada registro, el pod deposita en la tabla temporal la línea CSV formateada, su peso en bytes y el tipo al que pertenece, y marca el registro como completado. Si el procesamiento de un registro falla, registra el error en la tabla de auditoría. Si el registro lleva menos de tres intentos, vuelve a pendiente. Si ya acumula tres intentos fallidos, se marca como descartado y no vuelve a procesarse: sigue visible en la tabla de auditoría para revisión manual pero no bloquea el avance del ciclo.

En paralelo al procesamiento, cualquier pod consulta el peso acumulado en la tabla temporal por tipo. Cuando detecta que hay suficiente para una parte válida de 5MB, toma esas líneas mediante SELECT FOR UPDATE SKIP LOCKED, las marca como en subida y ejecuta el siguiente flujo:

Si es la primera parte que se sube para ese tipo, el pod inicia el Multipart Upload en S3, sube los headers del CSV junto con las líneas acumuladas como primera parte, y registra el uploadId en la tabla de partes por tipo. Incluir los headers en la primera parte real de datos es necesario porque S3 Multipart no permite subir una parte vacía o con solo encabezados: la primera parte debe tener contenido suficiente para alcanzar el mínimo de 5MB. Si el Multipart ya fue iniciado por otro pod, simplemente sube las líneas como la siguiente parte disponible.

Pod consulta peso acumulado en tabla temporal por tipo
     ↓
¿Hay 5MB pendientes de subir?
     ├── NO → sigue procesando registros
     └── SÍ → toma líneas via SELECT FOR UPDATE SKIP LOCKED
               marca líneas como en subida
               ↓
               ¿Existe uploadId para este tipo?
               ├── NO → inicia Multipart Upload en S3
                         sube headers + líneas acumuladas
                         como primera parte
                         registra uploadId en DB
               └── SÍ → usa uploadId existente
                         sube líneas como siguiente parte
               ↓
               Marca líneas como subidas
               Registra número de parte en DB

Proceso entra en loop
     ↓
SELECT FOR UPDATE SKIP LOCKED
registros pendientes dentro de la ventana
     ↓
¿Hay registros?
     ├── No → sale del loop
     └── Sí → marca como en procesamiento
               cierra transacción → libera bloqueo
               ↓
               Por cada registro:
               consulta tablas relacionadas
               valida y formatea línea CSV
               deposita en tabla temporal con peso en bytes
               marca registro como completado
               ↓
               Para fallidos:
               registra error en auditoría
               < 3 intentos → vuelve a pendiente
               ≥ 3 intentos → marca como descartado

Cierre de la sesión. Al terminar cada lote, el pod verifica si quedan registros pendientes o con menos de tres intentos dentro de la ventana. Los registros descartados se consideran procesados porque ya superaron el límite de reintentos y no volverán a intentarse.

Si no quedan registros pendientes, el pod verifica si quedan líneas en la tabla temporal que no hayan sido subidas a S3, independientemente de si superan o no los 5MB. Estas son las líneas residuales del ciclo: los últimos registros procesados que no alcanzaron a formar una parte completa. El pod que detecta esta condición intenta ser el que cierra la sesión usando el mismo mecanismo bloqueante del inicio.

Bloquea el registro de control y verifica el estado de la sesión. Si otro pod ya la cerró, simplemente libera el bloqueo y termina. Si la sesión sigue activa, este pod es el responsable del cierre: toma las líneas residuales de la tabla temporal y las sube como última parte del Multipart Upload de cada tipo. S3 permite que la última parte sea menor a 5MB, por lo que no hay restricción de tamaño en este paso. Luego llama a completeMultipartUpload para consolidar todas las partes en el archivo final, marca la sesión como cerrada y libera el bloqueo.

Al terminar cada lote:
     ↓
¿Quedan registros pendientes o con menos de 3 intentos
dentro de la ventana?
     ├── Sí → siguiente lote
     └── No → ¿Quedan líneas sin subir en tabla temporal?
               ↓
               Bloquea registro de control
               ↓
               ¿Sesión ya cerrada?
               ├── Sí → libera bloqueo y termina
               └── No → toma líneas residuales de tabla temporal
                         sube como última parte de cada tipo
                         llama completeMultipartUpload por cada tipo
                         marca sesión como cerrada
                         libera bloqueo

Lo que necesitas para implementarlo

Este enfoque requiere más elementos que el primero, pero cada uno tiene una razón de ser clara.

Lo que ninguno de los dos te dice hasta que fallas en producción

Después de ver los dos enfoques en detalle puede parecer que la decisión está tomada y la implementación es directa. Pero hay un punto que ninguno de los dos resuelve por sí solo y que, si no se atiende, puede hacer que cualquiera de las dos soluciones falle de una manera silenciosa y difícil de detectar.

PostgreSQL y S3 no viven en el mismo mundo transaccional. Cuando haces un cambio en la base de datos dentro de una transacción, puedes deshacerlo si algo falla: eso es precisamente lo que hace una transacción. Pero cuando subes un archivo a S3, esa operación no participa en ninguna transacción de base de datos. Es independiente, definitiva e irreversible desde el punto de vista de PostgreSQL. Si el archivo llega a S3 y luego la transacción de base de datos falla, el archivo ya está ahí y no hay forma de retirarlo automáticamente.

Esto crea una ventana de inconsistencia que puede ser devastadora si no se maneja. Imagina que marcas los registros como procesados, confirmas la transacción y luego intentas subir a S3. Si S3 falla, los registros ya están marcados como procesados en la base de datos pero el archivo nunca llegó. El sistema legado no recibe nada, pero el siguiente ciclo tampoco reintenta porque los registros ya no están pendientes. Los datos simplemente desaparecen del proceso sin que nadie lo detecte fácilmente.

La solución está en el orden de las operaciones, y ese orden debe ser disciplinado y consistente en toda la implementación: primero marcas los registros como procesados dentro de una transacción que aún no has confirmado, luego subes el archivo a S3, y solo si S3 confirma el éxito confirmas la transacción en PostgreSQL. Si S3 falla, haces rollback y los registros vuelven a su estado anterior, listos para reintentarse en el siguiente ciclo.

Marcar registros como procesados en DB (sin confirmar aún)
          ↓
     Subir archivo a S3
          ↓
S3 exitoso → confirmar transacción en PostgreSQL ✅
S3 falla   → rollback → registros vuelven a pendiente 🔄

Este orden no es una preferencia de implementación: es la única secuencia que garantiza consistencia entre los dos sistemas en todos los escenarios posibles. Con él, un fallo en S3 siempre deja la base de datos en un estado coherente y el siguiente ciclo retoma el trabajo sin intervención manual. Sin él, cualquier fallo entre la confirmación de la transacción y la subida a S3 crea un estado inconsistente que requiere corrección manual para detectar y resolver.

El sistema legado no va a cambiar. Pero tu integración sí puede ser confiable.

Volvamos al punto de partida. Tienes un sistema moderno que genera datos y un sistema legado que consume archivos. Entre los dos hay una brecha que no vas a poder cerrar cambiando el sistema legado, porque ese no es el juego. El juego es construir un puente confiable entre los dos mundos, y la complejidad de ese puente debe estar justificada por los problemas que resuelve, no por los que imaginas que podrían aparecer.

Desde aquí hay líneas naturales hacia las que vale la pena mirar. La observabilidad es la más inmediata: métricas de ciclo integradas en una herramienta de monitoreo permiten detectar degradaciones antes de que se conviertan en incidentes. La gestión operativa de registros descartados es la que más se subestima: una interfaz mínima para que un operador los inspeccione, corrija y reintroduzca al flujo es lo que transforma este sistema en algo verdaderamente autónomo. Y para quienes están en el extremo de mayor volumen, vale explorar si COPY TO STDOUT puede coexistir con el patrón distribuido, usando la capacidad de PostgreSQL para exportar directamente incluso en un escenario de múltiples procesos.

Imagina que estás diseñando el flujo de solicitud de productos financieros de un banco. Un cliente puede pedir una tarjeta de crédito o un crédito para comprar un vehículo. Los dos productos son distintos: tienen pasos diferentes, documentos diferentes, validaciones diferentes. Pero también comparten algo que no puede variar: antes de que cualquier producto se evalúe, el banco necesita saber quién es el cliente, confirmar su identidad y consultar su historial crediticio. Eso ocurre siempre, para cualquier producto, sin excepción.

La pregunta que se presenta de inmediato parece técnica pero es en realidad arquitectónica: ¿dónde vive ese comportamiento compartido? ¿Lo repites en cada flujo de producto? ¿Lo centralizas en algún lugar y los flujos de producto lo invocan? ¿Construyes un flujo único con condicionales que bifurcan la lógica según el tipo de producto?

Cualquiera de esas tres respuestas funciona mientras el sistema es pequeño. El problema aparece cuando el banco decide lanzar un tercer producto, luego un cuarto. Cuando un equipo necesita cambiar la validación de identidad sin tocar los flujos de tarjeta ni de vehículo. Cuando hay que agregar un paso transversal nuevo y ese cambio no puede romper nada de lo que ya está operando. Ahí es donde las soluciones aparentemente razonables revelan su costo real.

Si duplicaste la lógica compartida, ahora debes modificarla en tres o cuatro lugares y confiar en que todos los cambios sean consistentes. Si la centralizaste mediante invocaciones directas, los flujos de producto están acoplados a ese componente central y cualquier cambio en él requiere verificar el impacto en todos los consumidores. Si construiste un flujo con condicionales, cada nuevo producto aumenta la complejidad del núcleo hasta que nadie entiende del todo qué hace ese código.

La tensión es real: hay pasos que deben ejecutarse de forma consistente en toda instancia del flujo, pero cada caso de negocio introduce lógica específica que no puede ni debe generalizarse. Y esa tensión no se resuelve eligiendo uno de los dos lados. Se resuelve separándolos con precisión y definiendo el mecanismo exacto por el que conviven.

La separación que sostiene todo lo demás

El problema que tienen las tres soluciones descritas antes es que todas intentan resolver la tensión desde el mismo lugar: deciden quién ejecuta qué. Una duplica la ejecución, otra la centraliza, otra la condiciona. Pero ninguna se hace la pregunta más profunda: ¿quién tiene el gobierno del flujo en cada momento?

Esa distinción importa porque gobernar el flujo no es lo mismo que ejecutar un paso. Gobernar significa saber en qué punto está el proceso, decidir qué viene después y ser responsable de que el flujo llegue a su fin de forma consistente. Cuando esa responsabilidad está dispersa entre varios componentes que ejecutan partes del proceso, nadie la tiene completamente. Y cuando nadie la tiene completamente, el flujo se fragmenta.

La respuesta natural a ese problema es concentrar el gobierno. Que haya un único responsable del flujo completo que sepa en todo momento dónde está el proceso y qué debe ocurrir a continuación. Ese responsable ejecuta lo que es común a todos los casos y, cuando llega el momento en que cada caso tiene su propia lógica, cede el gobierno temporalmente a quien sabe cómo manejarla. No lo invoca, no lo llama como si fuera una función: le transfiere el control de forma explícita, permanece en espera y lo recupera cuando termina.

Eso es exactamente lo que hace el núcleo transversal: concentra el gobierno del flujo completo, ejecuta los pasos que son comunes a todos los casos y cede el control cuando la especificidad de cada caso debe intervenir. Y eso es exactamente lo que hace un módulo de extensión: recibe ese control, ejecuta la lógica propia de su caso y lo devuelve. El módulo no conoce al núcleo, no depende de él y no lo dirige. Solo sabe que en algún momento va a recibir el gobierno y que cuando termine debe devolverlo.

Para que esa cesión y esa devolución ocurran con precisión, ambas partes necesitan saber en todo momento dónde están y qué viene después. Ese mecanismo es una máquina de estados: un registro del punto exacto en que se encuentra el proceso y un conjunto de transiciones válidas desde ahí. El núcleo tiene la suya, que gobierna sus pasos transversales. Cada módulo tiene la propia, completamente independiente, que gobierna sus pasos específicos. Cuando el núcleo cede el gobierno, su máquina de estados transiciona a un estado que reconoce explícitamente esa cesión. Mientras está en ese estado, cualquier solicitud de navegación que llegue al núcleo es redirigida al módulo activo. Cuando el módulo termina, el núcleo recibe el control de vuelta y su máquina de estados avanza hacia el cierre.

El flujo, visto desde afuera, parece continuo. Visto desde adentro, está compuesto por pasos atómicos: unidades independientes que no conocen ni necesitan conocer los pasos anteriores ni los siguientes. Cada paso se ejecuta, produce un resultado, lo persiste y termina. La secuencia no es responsabilidad del paso, es responsabilidad de la máquina de estados que lo gobierna.

Esa independencia entre pasos le da al flujo algo que los modelos continuos no tienen: la capacidad de pausarse sin romperse. Si un paso necesita información del cliente, el flujo persiste su estado completo y se detiene. Cuando el cliente responde, la máquina de estados retoma exactamente desde donde estaba. Y si el cliente quiere corregir algo que ya ingresó, puede retroceder: la máquina activa, sea la del núcleo o la del módulo, hace la transición hacia atrás y el paso anterior vuelve a estar disponible.

Un núcleo que no cambia pero se adapta

La estabilidad del núcleo es una decisión de diseño, no una limitación técnica. Cuando se incorpora un nuevo producto al banco, el núcleo no se modifica. No necesita saber qué pasos tiene el nuevo módulo, qué validaciones aplica ni qué documentos solicita. Lo único que necesita es que el módulo cumpla un contrato: un acuerdo lógico formal que define las reglas mínimas de interacción entre el núcleo y cualquier módulo que quiera participar del flujo. El módulo no tiene referencia al núcleo ni a otros módulos. Su única dependencia es hacia ese contrato.

Ese contrato es deliberadamente mínimo. En el momento de la cesión, el núcleo no le entrega al módulo un paquete de información recopilada durante la parte transversal. Le entrega una sola cosa: el identificador de la transacción en curso, un identificador único que el núcleo genera cuando el flujo se inicia y que lo acompaña hasta el cierre. Con ese identificador, el módulo puede relacionar cada uno de sus pasos con la transacción correcta. Y si en algún punto de su ejecución necesita información que el núcleo recolectó durante la parte transversal, como los datos del cliente o el resultado de la validación de identidad, la solicita activamente a través de los endpoints que el núcleo expone para ese propósito.

Eso resuelve un problema que los modelos con contratos de entrada ricos suelen enfrentar: si el núcleo evoluciona y empieza a recolectar información nueva, no hay necesidad de modificar el contrato de cesión ni de actualizar los módulos existentes. El núcleo simplemente expone un endpoint nuevo. Los módulos que necesitan esa información lo adoptan cuando lo necesitan. Los que no lo necesitan no saben que existe y no se ven afectados.

Pero la estabilidad del núcleo no significa rigidez. Cuando un módulo se registra, puede declarar una configuración que adapta ciertos comportamientos del núcleo para su caso particular: activar o desactivar capacidades transversales, ajustar ciertas acciones según las respuestas esperadas. La distinción es precisa: el núcleo decide desde su diseño qué aspectos son adaptables y los expone de forma explícita. Un módulo solo puede moverse dentro de ese espacio predefinido, nunca ampliarlo ni redefinirlo. Lo que no fue diseñado como configurable permanece invariante sin importar qué módulo se registre.

Cómo se registra un módulo

Antes de que cualquier flujo pueda ejecutarse, cada módulo debe registrarse en el núcleo. Este proceso ocurre una única vez por módulo y es completamente independiente del flujo de ejecución.

El módulo se presenta ante el componente de registro del núcleo, declara su identidad y entrega su configuración. Como parte de esa configuración, declara también el listado completo de sus pasos: cuántos son y cómo se llama cada uno. Esa información queda almacenada en el núcleo como dato estático y se convierte en la fuente de verdad para el indicador de progreso que verá el cliente durante el flujo. El núcleo valida que el módulo cumpla el contrato de extensión y que su configuración sea válida dentro del espacio de adaptación permitido. Si todo es correcto, el módulo queda disponible para ser invocado.

A partir de ese momento el núcleo sabe que ese módulo existe, cómo debe comportarse cuando sea invocado y cuántos pasos lo componen. No sabe nada más. No conoce la lógica interna del módulo, no puede modificarla y no necesita hacerlo.

Cómo se ejecuta el flujo

Cuando el cliente inicia una solicitud e indica qué producto desea, el núcleo busca el módulo correspondiente, carga su configuración y adapta su comportamiento dentro de los límites predefinidos. Su máquina de estados transiciona al primer estado activo.

El primer paso es el preprocesamiento: el núcleo normaliza y construye el contexto inicial del flujo. En el caso del banco, esto incluye los datos básicos del cliente que llegaron con la solicitud. Al completarse, persiste el estado y la máquina de estados avanza al siguiente paso.

El siguiente paso es la validación transversal. El núcleo confirma la identidad del cliente y consulta su historial crediticio. Si alguna de esas validaciones requiere información adicional del cliente, el flujo se pausa, persiste su estado completo y espera. Cuando el cliente responde, la máquina de estados retoma exactamente desde donde estaba y la validación continúa. Al completarse, el estado se persiste y la máquina de estados avanza.

Es en este punto donde el flujo hace algo que ninguno de los tres modelos anteriores podía hacer limpiamente: reconoce que lo que sigue ya no le pertenece. La máquina de estados del núcleo transiciona al estado de control delegado y genera el identificador único de la transacción en curso. Ese identificador es lo único que el núcleo le entrega al módulo en el momento de la cesión. Con él, el módulo sabe a qué transacción pertenece cada uno de sus pasos. Y con él, puede consultar al núcleo cualquier información que necesite de la parte transversal ya completada.

A partir de ese instante, la máquina de estados del módulo toma el gobierno. El núcleo permanece en ese estado de espera activa, sin intervenir. Toda solicitud de navegación que llegue al núcleo durante este período es redirigida al módulo activo.

La máquina de estados del módulo activa sus pasos en la secuencia que ella misma define. Cada paso se ejecuta, produce un resultado y termina. Si un paso requiere interacción con el cliente, el flujo se pausa y espera exactamente igual que en la parte transversal. Después de cada paso, el estado se persiste y la máquina evalúa si hay un paso siguiente o si el módulo ha terminado.

Cuando no hay más pasos, el módulo devuelve el control al núcleo. La máquina de estados del núcleo transiciona desde el estado de control delegado hacia el cierre: registra la trazabilidad del flujo completo, persiste el estado final y notifica al cliente que el proceso ha concluido.

Lo que ve el cliente durante todo este proceso

Desde la perspectiva del cliente, el flujo es una secuencia continua de pantallas con un indicador de progreso que avanza. No hay ninguna señal visible de que en algún punto el gobierno pasó de una máquina de estados a otra. Esa continuidad no es cosmética: es el resultado de dos decisiones de diseño que trabajan juntas.

La primera es que el núcleo actúa como proxy de navegación. Toda instrucción del cliente, avanzar, retroceder, saltar a un paso anterior, cancelar, llega siempre al núcleo. El núcleo evalúa en qué punto del flujo se encuentra y decide si la ejecuta directamente o la redirige al módulo activo. El cliente nunca sabe esa distinción. Para él, siempre está hablando con el mismo interlocutor.

La segunda es que el indicador de progreso funciona sin necesidad de consultar al módulo en cada momento. El núcleo ya sabe cuántos pasos tiene el flujo completo desde el registro: el módulo declaró sus pasos al registrarse y esa información quedó almacenada de forma estática. Durante la ejecución, el núcleo solo necesita consultar al módulo por el paso actual, y únicamente cuando el control está delegado. El total de pasos nunca cambia y nunca necesita preguntarse de nuevo.

Con esas dos piezas en su lugar, cada pantalla puede ser completamente autónoma. No necesita conocer el flujo completo para saber qué mostrar ni con quién hablar. La navegación, avanzar, retroceder, saltar, cancelar, siempre pasa por el núcleo. Pero la interacción propia de cada paso, los datos que el cliente ingresa y las respuestas específicas de ese punto del flujo, van directamente al responsable de ese paso: el núcleo si el paso es transversal, el módulo si el paso le pertenece a él. Esto es posible porque cada pantalla es tan atómica como el paso que representa: desde el diseño se definen sus puntos de comunicación, con quién habla y para qué. No hay lógica en tiempo de ejecución que decida eso. La pantalla ya lo sabe.

Los comandos que el cliente puede dar en cualquier momento del flujo, y quién los resuelve, son los siguientes:

Lo que esta tabla muestra, más allá de los detalles técnicos, es que el cliente siempre tiene el mismo conjunto de comandos disponibles sin importar en qué parte del flujo se encuentra. El hecho de que algunos los resuelva el núcleo y otros el módulo es invisible para él. Y esa invisibilidad es exactamente lo que permite que el caso del banco, con sus dos productos distintos, se sienta como una sola experiencia coherente.

Lo que esta separación realmente cuesta

Sería deshonesto presentar este modelo sin nombrar lo que exige.

El contrato de extensión debe estar bien definido desde el principio. No en términos de la información que se transfiere en la cesión, que es mínima por diseño, sino en términos de las reglas de interacción: cómo se registra un módulo, qué debe declarar, cómo devuelve el control y qué formato tienen las respuestas que el núcleo espera. Si esas reglas están mal definidas o son ambiguas, los módulos las interpretarán de formas distintas y el flujo producirá comportamientos inconsistentes que son difíciles de rastrear porque la causa no está en la lógica de ningún paso sino en el acuerdo que los articula.

La máquina de estados de cada módulo requiere diseño cuidadoso. No es compleja en términos de implementación, pero sí requiere que quien diseña el módulo tenga claridad total sobre la secuencia de sus pasos, las transiciones válidas y los estados de pausa. Un módulo con una máquina de estados mal definida produce comportamientos inconsistentes que son difíciles de rastrear porque la lógica de secuencia está separada de la lógica de cada paso. Cuando algo falla, no es obvio si el problema está en el paso que se ejecutó o en la transición que lo activó.

Los endpoints que el núcleo expone para que los módulos consulten información transversal deben tratarse con la misma disciplina que el contrato de extensión. Son una interfaz pública que los módulos van a consumir, y cualquier cambio en ellos tiene el potencial de romper módulos existentes. Agregar endpoints nuevos es seguro: los módulos que no los necesitan simplemente no los usan. Pero modificar o eliminar endpoints existentes requiere coordinación con todos los módulos que los consumen, y esa coordinación tiene un costo real que crece con la cantidad de módulos operativos.

El modelo de proxy de navegación en el núcleo introduce una dependencia en tiempo de ejecución que debe estar bien resuelta. Cuando el núcleo redirige una solicitud de navegación al módulo activo, necesita tener una referencia válida a ese módulo. Si el módulo no está disponible por cualquier razón, esa solicitud falla. Esto no es diferente a cualquier otra dependencia en tiempo de ejecución, pero debe tenerse en cuenta en el diseño de tolerancia a fallos del sistema.

Finalmente, la disciplina de no modificar el núcleo es una restricción organizacional además de técnica. En la práctica, siempre hay presión para agregar una excepción aquí, un comportamiento especial allá. Cada vez que esa presión cede, el núcleo pierde algo de su estabilidad y el modelo empieza a degradarse. Mantener esa disciplina requiere que el equipo entienda bien por qué el núcleo es cerrado a modificación, no solo que sepa que lo es.

Todo ese costo tiene un punto de equilibrio. Si el sistema tiene un solo tipo de caso y es poco probable que eso cambie, el modelo agrega complejidad estructural sin beneficio real. La separación entre núcleo y módulos, las dos máquinas de estados, el contrato de extensión, los endpoints de consulta: todo eso se justifica cuando hay variabilidad real entre casos, cuando el comportamiento transversal necesita mantenerse consistente y evolucionar de forma independiente, y cuando la incorporación de nuevos casos debe ser posible sin riesgo sobre lo que ya está operando. Cuanto más de esas tres condiciones se cumplen, más sentido tiene asumir la exigencia que el modelo impone.

De vuelta al banco

Con el modelo completo sobre la mesa, el caso del banco deja de verse como un flujo de productos financieros y empieza a revelar el problema arquitectónico que realmente estaba presente desde el principio.

La dificultad nunca fue únicamente validar identidad, consultar historial crediticio o pedir documentos distintos según el producto. Eso podía resolverse de muchas maneras. El problema real era otro: cómo permitir que el sistema creciera sin que cada nuevo producto aumentara el acoplamiento, duplicara lógica o volviera más frágil el flujo completo.

Cuando el núcleo concentra únicamente las responsabilidades transversales y los productos viven en módulos independientes con su propia máquina de estados, el crecimiento deja de sentirse como una modificación del sistema existente y empieza a comportarse como una extensión controlada. Nuevos productos pueden incorporarse sin intervenir los flujos que ya operan, los equipos dejan de depender entre sí para evolucionar casos específicos y la complejidad deja de acumularse en un único lugar.

Hoy existen dos productos. Mañana habrá créditos hipotecarios, productos empresariales, validaciones regulatorias nuevas y recorridos especializados que todavía no existen. Cada uno traerá lógica distinta, pasos distintos y reglas distintas. Pero todos seguirán compartiendo la misma necesidad transversal: entender quién es el cliente antes de tomar cualquier decisión.

El valor del modelo no está en resolver bien los dos productos actuales. Está en evitar que el tercer producto convierta al sistema en algo más difícil de modificar que el segundo. Está en permitir que la variabilidad crezca sin que el núcleo pierda estabilidad. Está en separar la evolución de los productos de la evolución del flujo transversal.

Las tres soluciones iniciales parecían razonables mientras el sistema era pequeño. Duplicar lógica, centralizar mediante invocaciones directas o resolver todo con condicionales podían funcionar durante un tiempo. El problema aparecía después, cuando cada nuevo caso hacía que el sistema completo fuera más difícil de entender, probar y evolucionar. La pregunta que el banco se hacía al principio, dónde vive el comportamiento compartido, no tenía una respuesta técnica. Tenía una respuesta arquitectónica. Y la diferencia entre las dos es exactamente lo que determina si el cuarto producto se incorpora con la misma facilidad que el segundo o si para entonces ya nadie quiere tocar ese código.

La primera parte de este artículo construyó el argumento conceptual: por qué los logs dispersos se convierten en deuda técnica, cómo AOP permite centralizar la observabilidad sin contaminar la lógica de negocio, qué información debe registrarse en cada capa de una arquitectura DDD, y cómo los campos estructurados convierten un archivo de texto en una fuente de inteligencia operacional. Lo que quedó pendiente fue la demostración concreta: cómo se construye ese sistema, qué decisiones se toman en cada pieza, y por qué cada una de ellas importa.

Eso es exactamente lo que ocupa esta segunda parte. El objetivo es preciso: que al terminar de leerla, un desarrollador con experiencia en Spring pueda reproducir el sistema completo en su proyecto. No como una lista de pasos a seguir ciegamente, sino con el entendimiento de por qué cada componente existe, qué problema resuelve y qué ocurriría si se omitiera o se implementara de otra manera.

El stack es Java 21, Spring Boot 3.5.x, Gradle. Las dependencias que habilitan el sistema son spring-boot-starter-aop, que trae AspectJ y el soporte de proxies de Spring, y jackson-datatype-jsr310, que permite serializar correctamente los tipos de fecha y hora de Java 8 en los logs. Lombok está presente por conveniencia, pero no es estructuralmente necesario. Ninguna dependencia adicional es requerida.

El proyecto de ejemplo

Para que cada decisión técnica tenga contexto real, el sistema de logs se implementa sobre un proyecto concreto: una API REST que registra usuarios. Es un caso de uso deliberadamente simple, lo suficiente para que el flujo sea fácil de seguir, pero con la estructura completa de una arquitectura DDD: entrada HTTP, caso de uso, validaciones de dominio, persistencia, y manejo de errores.

El proyecto tiene esta estructura:

src/main/java/com/app_247/blog/id202603212000art/
│
├── Id202603212000artApplication.java                          ★ [LOG]
│
├── applications/
│   └── aop/
│       ├── aspect/
│       │   └── MethodLoggingAspect.java                      ★ [LOG]
│       └── config/
│           ├── JacksonConfig.java                            ★ [LOG]
│           └── LoggingAopProperties.java                     ★ [LOG]
│
├── domain/
│   ├── model/
│   │   ├── exception/
│   │   │   ├── BusinessException.java
│   │   │   └── DomainValidationException.java
│   │   └── usuario/
│   │       ├── gateway/
│   │       │   └── IUsuarioGateway.java
│   │       └── Usuario.java
│   └── usecase/
│       └── registrarusuario/
│           ├── dto/
│           │   ├── RegistrarUsuarioIn.java
│           │   └── RegistrarUsuarioOut.java
│           ├── enricher/
│           │   └── UsernameEnricher.java
│           ├── validator/
│           │   ├── EdadValidator.java
│           │   ├── EmailDominioValidator.java
│           │   └── NombreValidator.java
│           └── RegistrarUsuarioUseCase.java
│
└── infrastructure/
    ├── drivenadapters/
    │   └── jpa/
    │       └── usuario/
    │           ├── adapter/
    │           │   └── UsuarioPersistenciaAdapter.java
    │           ├── entity/
    │           │   └── UsuarioEntity.java
    │           ├── mapper/
    │           │   └── UsuarioPersistenciaMapper.java
    │           └── repository/
    │               └── UsuarioJpaRepository.java
    └── entrypoints/
        └── api/
            └── registrarusuario/
                ├── dto/
                │   ├── RegistrarUsuarioRequest.java
                │   └── RegistrarUsuarioResponse.java
                ├── mapper/
                │   └── RegistrarUsuarioApiMapper.java
                ├── RegistrarUsuarioController.java
                └── util/
                    └── Exception/
                        └── GlobalExceptionHandler.java

src/main/resources/
└── application.properties                                     ★ [LOG]

Las clases marcadas con ★ [LOG] son las que forman el sistema de observabilidad. Todo lo demás es la lógica del negocio y la infraestructura del proyecto, que no tiene ninguna instrucción de log y no necesita tenerla.

El flujo de una solicitud

Antes de abrir cualquier clase del sistema de logs vale la pena recorrer el flujo completo de una solicitud de registro de usuario. Es el flujo que el aspecto va a observar, y entenderlo con claridad hace que cada decisión de implementación tenga sentido inmediato.

El cliente envía un POST /api/v1/usuarios con un cuerpo JSON que contiene nombre, email y edad. A partir de ahí, la solicitud atraviesa estas capas en orden:

RegistrarUsuarioController es el punto de entrada. Recibe el request HTTP, lo valida con Bean Validation (@Valid), y usa RegistrarUsuarioApiMapper para convertir el RegistrarUsuarioRequest en un RegistrarUsuarioIn, que es el DTO que entiende el dominio. Luego invoca el caso de uso y convierte el resultado de vuelta a un RegistrarUsuarioResponse para la respuesta HTTP. El controlador no tiene lógica de negocio: solo traduce entre el mundo HTTP y el mundo del dominio.

RegistrarUsuarioUseCase es donde ocurre la orquestación. Recibe el RegistrarUsuarioIn y ejecuta la secuencia de negocio: primero llama a NombreValidator, EdadValidator y EmailDominioValidator para validar que los datos cumplan las reglas del dominio. Luego consulta el gateway para verificar que el email no esté ya registrado. Si todo es válido, usa UsernameEnricher para generar el nombre de usuario a partir del email, construye el objeto Usuario y lo persiste a través del gateway. Finalmente construye y retorna el RegistrarUsuarioOut.

Es importante notar que NombreValidator, EdadValidator, EmailDominioValidator y UsernameEnricher son clases con métodos estáticos, sin estado, sin anotaciones de Spring. El UseCase los llama directamente como utilidades. No son beans y el aspecto no los ve, lo cual es correcto: su comportamiento queda capturado por la observación del UseCase que los invoca.

IUsuarioGateway es la interfaz del puerto de salida. El dominio la define; la infraestructura la implementa. El UseCase solo conoce la interfaz, nunca la implementación concreta.

UsuarioPersistenciaAdapter es la implementación del gateway. Está anotado con @Component, es un bean de Spring, y es aquí donde realmente ocurre la interacción con la base de datos. Usa UsuarioPersistenciaMapper para convertir entre el modelo de dominio Usuario y la entidad JPA UsuarioEntity, y delega en UsuarioJpaRepository para las operaciones sobre H2.

GlobalExceptionHandler intercepta cualquier excepción que no haya sido manejada antes de llegar al cliente. Para DomainValidationException devuelve un 422 con el detalle del campo que falló. Para BusinessException devuelve un 409 con el código de error. Para errores de validación de Bean Validation devuelve un 400 con el mapa de campos y mensajes.

Con ese recorrido claro, el flujo completo se puede representar así:

POST /api/v1/usuarios
        │
        ▼
RegistrarUsuarioController        ← @RestController  ★ interceptado
        │ toCommand()
        ▼
RegistrarUsuarioApiMapper         ← @Component (MapStruct)
        │ RegistrarUsuarioIn
        ▼
RegistrarUsuarioUseCase           ← @Service         ★ interceptado
        │
        ├── NombreValidator.validar()        ← clase plana, NO interceptada
        ├── EdadValidator.validar()          ← clase plana, NO interceptada
        ├── EmailDominioValidator.validar()  ← clase plana, NO interceptada
        │
        ├── gateway.existeEmail()
        │       └── UsuarioPersistenciaAdapter#existeEmail  ← @Component ★ interceptado
        │               └── UsuarioJpaRepository (Spring Data)
        │
        ├── UsernameEnricher.generarUsername()  ← clase plana, NO interceptada
        │
        └── gateway.guardar()
                └── UsuarioPersistenciaAdapter#guardar      ← @Component ★ interceptado
                        └── UsuarioJpaRepository (Spring Data)
        │
        ▼ RegistrarUsuarioOut
RegistrarUsuarioController
        │ toResponse()
        ▼
RegistrarUsuarioApiMapper
        │
        ▼
RegistrarUsuarioResponse  →  HTTP 201

Este flujo es el que el aspecto va a observar en tiempo de ejecución. Cada clase marcada con ★ interceptado genera sus propios registros de INPUT, OUTPUT y TIMING sin que ninguna de ellas sepa que está siendo observada. Las clases planas que no son beans simplemente no aparecen en los logs, y eso es correcto: su comportamiento está implícito en la observación de las capas que las contienen.

La arquitectura del sistema de logs

Con el flujo del proyecto claro, el sistema de logs se puede describir con precisión. Son tres piezas con responsabilidades distintas que operan juntas:

LoggingAopProperties es la configuración. Define qué interceptar: qué paquetes, qué clases, qué métodos, en qué nivel de log y a partir de qué tiempo de ejecución emitir una advertencia. No sabe nada del aspecto ni de Jackson.

MethodLoggingAspect es el motor. Intercepta cada método elegible, mide el tiempo, serializa los argumentos y resultados, y emite los registros según las reglas que encontró en las propiedades. No sabe nada de la lógica de negocio del proyecto.

JacksonConfig proporciona el ObjectMapper que el aspecto usa para convertir objetos Java en texto JSON. Está configurado para manejar correctamente los tipos de fecha de Java 8, que sin esta configuración se serializarían como arrays de números en lugar de strings ISO.

La relación entre las tres piezas es deliberadamente asimétrica: LoggingAopProperties no sabe nada del aspecto, y el aspecto no sabe nada de Jackson más allá de que tiene un ObjectMapper disponible. Cada pieza tiene una responsabilidad única y bien delimitada.

LoggingAopProperties: el contrato de configuración

Todo el comportamiento del sistema de logs se controla desde application.properties a través de LoggingAopProperties. Esta clase es un @ConfigurationProperties que mapea el prefijo logging.aop a una estructura de objetos en memoria:

@Data
@ConfigurationProperties(prefix = "logging.aop")
public class LoggingAopProperties {
    private boolean enabled = true;
    private String basePackage = "com.app_247.blog.id202603212000art";
    private List<PatternConfig> patterns = List.of();

    @Data
    public static class PatternConfig {
        private String packageRegex = ".*";
        private String classRegex = ".*";
        private String methodRegex = ".*";
        private String logLevel = "INFO";
        private long warnThresholdMs = 500L;
    }
}

La estructura interna PatternConfig representa una regla de interceptación. Tiene tres expresiones regulares que se evalúan contra el paquete, el nombre simple de la clase y el nombre del método. Si las tres hacen match, la regla aplica y sus otros dos campos determinan el comportamiento: logLevel controla en qué nivel se emiten los registros normales de esa capa, y warnThresholdMs define el umbral de tiempo a partir del cual el registro de timing se eleva automáticamente a WARN independientemente del nivel configurado.

Los valores por defecto de las tres regex son ".*", que en regex significa "cualquier cosa". Esto garantiza que una PatternConfig construida sin configuración explícita intercepta todo, lo cual es un default seguro para desarrollo pero que en producción se reemplaza por reglas precisas.

Para que Spring Boot cargue esta clase al arrancar, la clase principal de la aplicación debe registrarla explícitamente:

@SpringBootApplication
@EnableConfigurationProperties(LoggingAopProperties.class)
public class Id202603212000artApplication {
    public static void main(String[] args) {
        SpringApplication.run(Id202603212000artApplication.class, args);
    }
}

@EnableConfigurationProperties es el mecanismo que le indica a Spring Boot que debe crear un bean de tipo LoggingAopProperties y enlazarlo con el prefijo logging.aop del archivo de propiedades. Sin esta anotación, la clase existe pero nunca se puebla: el aspecto recibiría una instancia con todos los valores por defecto y sin ningún patrón configurado, lo que significa que no interceptaría nada. Es un error silencioso difícil de diagnosticar si no se conoce el mecanismo.

La configuración del proyecto de ejemplo define tres patrones, uno por cada capa que se quiere observar:

logging.aop.enabled=true
logging.aop.base-package=com.app_247.blog.id202603212000art

# UseCase
logging.aop.patterns[0].package-regex=com\\.app_247\\.blog\\.id202603212000art\\.domain\\.usecase.*
logging.aop.patterns[0].class-regex=.*UseCase
logging.aop.patterns[0].method-regex=.*
logging.aop.patterns[0].log-level=INFO
logging.aop.patterns[0].warn-threshold-ms=300

# Adapter de persistencia
logging.aop.patterns[1].package-regex=com\\.app_247\\.blog\\.id202603212000art\\.infrastructure\\.drivenadapters.*
logging.aop.patterns[1].class-regex=.*Adapter
logging.aop.patterns[1].method-regex=.*
logging.aop.patterns[1].log-level=DEBUG
logging.aop.patterns[1].warn-threshold-ms=100

# Controller
logging.aop.patterns[2].package-regex=com\\.app_247\\.blog\\.id202603212000art\\.infrastructure\\.entrypoints.*
logging.aop.patterns[2].class-regex=.*Controller
logging.aop.patterns[2].method-regex=.*
logging.aop.patterns[2].log-level=INFO
logging.aop.patterns[2].warn-threshold-ms=500

Tres decisiones de diseño visibles en esta configuración merecen atención. Primera: el adapter de persistencia tiene log-level=DEBUG mientras que el UseCase y el Controller tienen log-level=INFO. Esto significa que en producción con nivel INFO configurado, los logs del adapter son invisibles por defecto y solo aparecen cuando se activa DEBUG dinámicamente para diagnosticar un problema. La lógica es que saber que el UseCase llamó al adapter y cuánto tardó ya es información suficiente en condiciones normales; el detalle de qué exactamente se guardó o consultó es información de diagnóstico que solo se necesita ocasionalmente.

Segunda: el umbral de WARN del adapter es de 100ms, mucho más estricto que los 300ms del UseCase y los 500ms del Controller. Esto refleja una expectativa operacional: una operación de base de datos que tarde más de 100ms en este proyecto es una señal de alerta, mientras que el UseCase puede acumular ese tiempo y más en su orquestación sin que sea necesariamente un problema.

Tercera: los patrones se evalúan en orden y se aplica el primero que haga match. Si en el futuro existiera una clase que fuera a la vez un UseCase y un Adapter, lo cual no debería ocurrir en una arquitectura DDD bien diseñada pero podría ocurrir en un proyecto en transición, el patrón 0 ganaría porque aparece primero. Esta semántica de primer match es predecible y fácil de razonar.

JacksonConfig: el ObjectMapper para los logs

El aspecto necesita convertir los argumentos y resultados de los métodos en texto para escribirlos en el log. Jackson es la herramienta natural para esto en un proyecto Spring, pero la configuración por defecto tiene un problema concreto con los tipos de fecha de Java 8.

Sin configuración adicional, un LocalDateTime como 2026-05-18T15:47:05.875 se serializa como un array de números: [2026,5,18,15,47,5,875000000]. En un log de producción eso es ilegible. La solución es registrar el módulo JavaTimeModule y deshabilitar la serialización de fechas como timestamps:

@Configuration
public class JacksonConfig {
    @Bean
    public ObjectMapper objectMapper() {
        ObjectMapper mapper = new ObjectMapper();
        mapper.registerModule(new JavaTimeModule());
        mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
        return mapper;
    }
}

El resultado es que LocalDateTime aparece en los logs como "2026-05-18T15:47:05.8756894", que es exactamente lo que se ve en la salida de consola de referencia.

Una pregunta legítima es por qué esta configuración vive en el paquete applications/aop/config y no en un paquete de configuración general de la aplicación. La respuesta es de propiedad: este ObjectMapper existe para el sistema de logs, no para la aplicación en general. En el futuro, cuando se incorpore el sistema de enmascaramiento que se documentará en la tercera parte de esta serie, este mapper recibirá configuración adicional específica para logs que no debe afectar a las respuestas HTTP. Mantenerlo en el paquete del sistema de logs hace explícita esa propiedad desde el principio.

MethodLoggingAspect: el motor de la interceptación

Con la configuración clara y el ObjectMapper disponible, el aspecto puede construirse. MethodLoggingAspect es un @Component anotado con @Aspect que recibe por inyección las propiedades y el mapper:

@Slf4j
@Aspect
@Component
@RequiredArgsConstructor
@ConditionalOnProperty(prefix = "logging.aop", name = "enabled", havingValue = "true", matchIfMissing = true)
public class MethodLoggingAspect {

    private final ObjectMapper objectMapper;
    private final LoggingAopProperties properties;
    private final ConcurrentHashMap<String, Optional<PatternConfig>> matchCache = new ConcurrentHashMap<>();

@ConditionalOnProperty con matchIfMissing = true significa que el aspecto está activo por defecto aunque la propiedad logging.aop.enabled no aparezca en el archivo de configuración. Solo se desactiva si la propiedad está explícitamente en false. Esto es un default sensato: en un proyecto nuevo donde todavía no se ha configurado nada, el sistema de logs funciona.

El matchCache es un ConcurrentHashMap de instancia, no estático. Esto es deliberado: si en algún escenario de pruebas o de recarga de contexto se creara una nueva instancia del aspecto, el cache empieza vacío y se reconstituye limpiamente. Un cache estático compartiría estado entre instancias del aspecto, lo que en tests de integración puede producir comportamientos inesperados difíciles de reproducir.

El pointcut y el filtro inicial

El pointcut captura todos los beans anotados con los estereotipos principales de Spring, excluyendo el propio paquete del aspecto:

@Around("(within(@org.springframework.stereotype.Service *)                    " +
        "|| within(@org.springframework.stereotype.Component *)                " +
        "|| within(@org.springframework.web.bind.annotation.RestController *)" +
        "|| within(@org.springframework.stereotype.Repository *))              " +
        "&& !within(com.app_247.blog.id202603212000art.aop..*)")
public Object logMethod(ProceedingJoinPoint joinPoint) throws Throwable {

Usar within con estereotipos en lugar de una expresión de paquete tiene una implicación directa en DDD que ya se mencionó al describir el flujo: los validadores y enrichers del dominio, que son clases planas sin anotaciones de Spring, no son interceptados. El aspecto solo ve lo que Spring gestiona, y eso es exactamente lo correcto.

Lo primero que hace el advice una vez que captura una invocación es extraer la información del método y aplicar el filtro de paquete base:

MethodSignature signature = (MethodSignature) joinPoint.getSignature();
Method method = signature.getMethod();
String packageName = method.getDeclaringClass().getPackageName();
String className = method.getDeclaringClass().getSimpleName();
String methodName = method.getName();

if (!packageName.startsWith(properties.getBasePackage())) {
    return joinPoint.proceed();
}

Este filtro descarta en una comparación de strings todas las invocaciones que provienen de beans de Spring propios del framework o de librerías de terceros. Es el filtro más barato posible y elimina la gran mayoría de las invocaciones que el pointcut captura pero que no son de la aplicación.

Las invocaciones que pasan ese filtro enfrentan la evaluación de patrones, protegida por el cache:

String cacheKey = packageName + "." + className + "#" + methodName;
Optional<PatternConfig> matchedPattern = matchCache.computeIfAbsent(
        cacheKey,
        k -> findMatchingPattern(packageName, className, methodName));

if (matchedPattern.isEmpty()) {
    return joinPoint.proceed();
}

Si ningún patrón hace match, la invocación pasa sin ningún registro. Si hay match, el PatternConfig resultante determina todo el comportamiento posterior: nivel de log, umbral de tiempo, y por extensión qué tan visible es esa capa en producción.

La firma comprimida

Cada registro incluye una firma que identifica el método observado. La firma completa de un método en este proyecto puede ocupar una línea entera de log por sí sola. El aspecto la comprime preservando solo la inicial de cada segmento del paquete excepto el último:

private String compressPackage(String packageName) {
    if (packageName == null || packageName.isBlank()) return "";
    String[] segments = packageName.split("\\.");
    if (segments.length == 1) return packageName;
    StringBuilder sb = new StringBuilder();
    for (int i = 0; i < segments.length - 1; i++) {
        sb.append(segments[i].charAt(0)).append('.');
    }
    sb.append(segments[segments.length - 1]);
    return sb.toString();
}

El resultado para com.app_247.blog.id202603212000art.infrastructure.drivenadapters.jpa.usuario.adapter es c.a.b.i.i.d.j.u.adapter. El último segmento se preserva completo porque es el que aporta contexto: adapter, usecase, entrypoints. Los segmentos anteriores son el prefijo que cualquier desarrollador del proyecto reconoce por su inicial. La firma completa que aparece en cada registro queda así:

c.a.b.i.i.d.j.u.adapter.UsuarioPersistenciaAdapter#guardar

Legible, compacta, y suficientemente precisa para ubicar el método en el árbol de archivos sin ambigüedad.

Los cuatro tipos de registro

El advice @Around tiene visibilidad completa sobre la invocación: puede ejecutar código antes, durante y en el camino de error. Esa visibilidad se materializa en cuatro tipos de registro con marcadores visuales distintos que permiten identificarlos de un vistazo en la consola:

private static final String INPUT_MARKER     = ">>> [INPUT] |";
private static final String OUTPUT_MARKER    = "<<< [OUTPUT] |";
private static final String TIMING_MARKER    = "*** [TIMING] |";
private static final String ERROR_MARKER     = "!!! [ERROR] |";
private static final String PROPAGATED_MARKER = "!!! [ERROR-PROPAGATED] |";

Los marcadores no son decorativos. En una consola con decenas de líneas por segundo, la diferencia visual entre >>>, <<<, *** y !!! permite al ojo localizar inmediatamente qué tipo de evento está leyendo sin procesar el texto completo de cada línea.

INPUT

El registro INPUT captura los argumentos del método en el momento de la invocación. La lógica recorre los parámetros usando reflexión para asociar cada valor con el nombre del parámetro declarado:

private void logInput(
        String methodSignature,
        MethodSignature signature,
        Object[] args,
        PatternConfig pattern) {
    Parameter[] parameters = signature.getMethod().getParameters();
    if (parameters.length == 0) {
        logAtLevel(pattern, "{} {} args: (none)", methodSignature, INPUT_MARKER);
        return;
    }
    Map<String, Object> inputMap = new LinkedHashMap<>();
    IntStream.range(0, parameters.length)
            .forEach(i -> inputMap.put(
                    parameters[i].getName(),
                    formatArg(args[i])));
    logAtLevel(pattern, "{} {} args: {}", methodSignature, INPUT_MARKER, inputMap);
}

LinkedHashMap preserva el orden de inserción, que coincide con el orden de declaración de los parámetros. El resultado en el log es un mapa legible donde cada clave es el nombre exacto del parámetro y cada valor es la representación JSON del argumento. Para que los nombres de los parámetros estén disponibles en tiempo de ejecución a través de parameter.getName(), el proyecto debe compilarse con la opción -parameters. En Spring Boot esto está habilitado por defecto desde la versión 3.2, así que en este stack no requiere ninguna configuración adicional.

La serialización de cada argumento pasa por formatArg:

private String formatArg(Object arg) {
    if (arg == null) return "null";
    try {
        return objectMapper.writeValueAsString(arg);
    } catch (Exception e) {
        e.printStackTrace();
        return arg.toString();
    }
}

Si Jackson no puede serializar el objeto, el método cae de vuelta a toString() como último recurso. Esto evita que un argumento no serializable rompa el flujo de logging y, por extensión, el flujo de negocio. El aspecto es un observador: nunca debe interferir con la ejecución que está observando.

OUTPUT

El registro OUTPUT captura el valor de retorno una vez que el método completa su ejecución normalmente:

private void logOutput(
        String methodSignature,
        Class<?> returnType,
        Object result,
        PatternConfig pattern) {
    if (void.class.equals(returnType) || Void.class.equals(returnType)) {
        logAtLevel(pattern, "{} {} return: void", methodSignature, OUTPUT_MARKER);
        return;
    }
    logAtLevel(pattern, "{} {} return: {}",
            methodSignature, OUTPUT_MARKER, formatArg(result));
}

El caso especial es cuando el tipo de retorno es void: no hay nada que serializar, pero sí vale la pena registrar que el método completó su ejecución. Un registro OUTPUT ausente en un flujo donde se esperaba puede ser la primera pista de que algo no terminó correctamente.

TIMING

El registro TIMING es el más rico en información operacional. Se emite siempre, tanto en el flujo normal como en el flujo de error, lo que garantiza que siempre hay una métrica de tiempo disponible independientemente de cómo terminó la ejecución:

private void logTiming(
        String methodSignature,
        Instant start,
        Instant end,
        long elapsedMs,
        PatternConfig pattern) {
    String startStr = formatInstant(start);
    String endStr = formatInstant(end);
    String elapsedFormatted = formatElapsed(elapsedMs);
    if (elapsedMs >= pattern.getWarnThresholdMs()) {
        log.warn("{} {} start: {} | end: {} | elapsed: {} ⚠️ superó umbral de {}ms",
                methodSignature, TIMING_MARKER,
                startStr, endStr,
                elapsedFormatted,
                pattern.getWarnThresholdMs());
        return;
    }
    logAtLevel(pattern, "{} {} start: {} | end: {} | elapsed: {}",
            methodSignature, TIMING_MARKER, startStr, endStr, elapsedFormatted);
}

La lógica del umbral merece atención: si elapsedMs supera warnThresholdMs, el registro se emite en WARN directamente con log.warn(), ignorando el nivel configurado en el patrón. Esto significa que aunque el adapter tenga log-level=DEBUG y en producción sus logs normales sean invisibles, un TIMING que supere el umbral siempre aparece en INFO y superior. La lentitud es siempre visible, independientemente del nivel de verbosidad configurado para esa capa.

El tiempo se formatea de forma legible según su magnitud:

private String formatElapsed(long elapsedMs) {
    if (elapsedMs < 1_000) {
        return elapsedMs + "ms";
    } else if (elapsedMs < 60_000) {
        return "%.3fs".formatted(elapsedMs / 1_000.0);
    } else {
        long minutes = elapsedMs / 60_000;
        long seconds = (elapsedMs % 60_000) / 1_000;
        long millis = elapsedMs % 1_000;
        return "%dm %ds %dms".formatted(minutes, seconds, millis);
    }
}

Menos de un segundo se muestra en milisegundos: 120ms. Entre un segundo y un minuto se muestra con tres decimales: 1.234s. Por encima de un minuto se desglosa en componentes: 2m 3s 456ms. Esta progresión hace que el número sea siempre legible en la unidad que le corresponde, sin que el ojo tenga que convertir 120000ms a 2 minutos mentalmente.

Los instantes de inicio y fin se formatean con precisión de milisegundos:

private static final DateTimeFormatter FORMATTER = 
    DateTimeFormatter.ofPattern("HH:mm:ss.SSS");

private String formatInstant(Instant instant) {
    return LocalDateTime
            .ofInstant(instant, ZoneId.systemDefault())
            .format(FORMATTER);
}

El resultado en el log es start: 15:47:05.750 | end: 15:47:05.870 | elapsed: 120ms. Con esos tres valores en cada registro TIMING es posible reconstruir la línea de tiempo completa de una transacción sin necesidad de ninguna herramienta externa: basta con ordenar los registros por hora de inicio y la secuencia de etapas queda visible.

ERROR y ERROR-PROPAGATED

El manejo de errores es donde el diseño del aspecto muestra su complejidad más interesante. El problema a resolver es este: cuando una excepción sube por el stack, cada capa interceptada la captura en su bloque catch, lo que sin ningún mecanismo de control produciría un registro ERROR en cada capa que la excepción atraviesa. En el flujo del proyecto de ejemplo, una BusinessException lanzada en el UseCase sería logueada como ERROR tanto en el UseCase como en el Controller, duplicando la información y contaminando los dashboards con falsos positivos.

La solución usa dos ThreadLocal que trabajan juntos:

private static final ThreadLocal<Throwable> loggedExceptionHolder = new ThreadLocal<>();
private static final ThreadLocal<Integer> depthHolder = 
    ThreadLocal.withInitial(() -> 0);

depthHolder cuenta cuántos métodos interceptados están activos simultáneamente en el stack del hilo actual. Se incrementa al entrar a cada método interceptado y se decrementa al salir, tanto en el flujo normal como en el flujo de error. loggedExceptionHolder almacena una referencia a la excepción que ya fue logueada como ERROR origen.

La lógica en el bloque de error funciona así:

} catch (Throwable ex) {
    Instant endInstant = Instant.now();
    long elapsed = endInstant.toEpochMilli() - startInstant.toEpochMilli();
    if (loggedExceptionHolder.get() == null) {
        loggedExceptionHolder.set(ex);
        logException(methodSignature, ex, elapsed, ERROR_MARKER);
    } else {
        logException(methodSignature, ex, elapsed, PROPAGATED_MARKER);
    }
    logTiming(methodSignature, startInstant, endInstant, elapsed, pattern);
    int currentDepth = depthHolder.get() - 1;
    depthHolder.set(currentDepth);
    if (currentDepth == 0) {
        loggedExceptionHolder.remove();
        depthHolder.remove();
    }
    throw ex;
}

La primera capa interceptada que captura la excepción encuentra loggedExceptionHolder vacío, la registra con ERROR_MARKER y la almacena en el holder. Cada capa superior que captura la misma excepción encuentra el holder poblado y la registra con PROPAGATED_MARKER en nivel DEBUG. En la consola, el ERROR aparece exactamente una vez, en el punto donde se originó el problema, y las capas superiores emiten un DEBUG discreto que confirma la propagación sin duplicar el ruido.

La limpieza de los ThreadLocal ocurre cuando depthHolder llega a cero, es decir, cuando el método más externo del stack interceptado termina su manejo del error. Este punto de limpieza es crítico: los hilos en un servidor web son reutilizados de un request al siguiente a través de un pool. Si los ThreadLocal no se limpian, el hilo llega al siguiente request con valores residuales del request anterior. El efecto concreto sería que la primera excepción del nuevo request encontraría loggedExceptionHolder ya poblado y se registraría como ERROR-PROPAGATED en lugar de ERROR, perdiendo el origen real del error. Es un bug silencioso que solo aparece bajo carga, cuando los hilos se reutilizan frecuentemente, y que es extremadamente difícil de reproducir en desarrollo.

La razón por la que depthHolder es necesario además de loggedExceptionHolder es precisamente esta: no basta con saber que hay una excepción registrada; hay que saber cuándo es seguro limpiarla. Sin el contador de profundidad, el aspecto no puede distinguir entre el momento en que la excepción está siendo propagada por capas internas, donde el holder debe mantenerse, y el momento en que salió completamente del stack interceptado, donde el holder debe limpiarse.

El método que emite el registro de error diferencia los dos casos:

private void logException(
        String methodSignature,
        Throwable ex,
        long elapsedMs,
        String marker) {
    if (marker.equals(PROPAGATED_MARKER)) {
        log.debug("{} {} exception: {} - {} | elapsed: {}",
                methodSignature,
                marker,
                ex.getClass().getSimpleName(),
                ex.getMessage(),
                formatElapsed(elapsedMs));
    } else {
        log.error("{} {} exception: {} - {} | elapsed: {}",
                methodSignature,
                marker,
                ex.getClass().getSimpleName(),
                ex.getMessage(),
                formatElapsed(elapsedMs));
    }
}

El ERROR origen siempre se emite en nivel ERROR, independientemente del nivel configurado en el patrón. La propagación se emite en DEBUG para que en producción con nivel INFO sea completamente invisible. Si se necesita ver la cadena de propagación para diagnosticar un problema, basta con activar DEBUG dinámicamente.

El flujo completo bajo la lupa

Con todos los componentes descritos, vale la pena recorrer la salida de consola real del proyecto para el flujo feliz y para el flujo de error. No como validación de que el código funciona, sino como lectura del sistema contando su propia historia.

Flujo feliz: registro exitoso de un usuario

La solicitud llega al Controller con nombre, email y edad. El aspecto captura la invocación antes de que el método ejecute su primera línea y emite el INPUT con los argumentos serializados:

INFO  : c.a.b.i.i.e.a.registrarusuario.RegistrarUsuarioController#registrar
        >>> [INPUT] | args: {request={"nombre":"Juan Perez","email":"[email protected]","edad":25}}

El Controller mapea el request a un RegistrarUsuarioIn e invoca el UseCase. El aspecto intercepta esa invocación también y emite el INPUT del UseCase con el comando ya mapeado:

INFO  : c.a.b.i.d.u.registrarusuario.RegistrarUsuarioUseCase#ejecutar
        >>> [INPUT] | args: {command={"nombre":"Juan Perez","email":"[email protected]","edad":25}}

Dentro del UseCase ocurren las validaciones de dominio: NombreValidator, EdadValidator y EmailDominioValidator se invocan secuencialmente. Son clases planas sin anotaciones de Spring, no son beans, y el aspecto no las ve. Su comportamiento queda implícito en el contexto del UseCase que las llama. Si alguna lanzara una excepción, aparecería en el log del UseCase como un ERROR, no en un log propio del validador.

Superadas las validaciones, el UseCase llama a gateway.existeEmail(). Spring resuelve esa llamada hacia UsuarioPersistenciaAdapter, que sí es un bean y sí está interceptado:

DEBUG : c.a.b.i.i.d.j.u.adapter.UsuarioPersistenciaAdapter#existeEmail
        >>> [INPUT] | args: {email="[email protected]"}

DEBUG : c.a.b.i.i.d.j.u.adapter.UsuarioPersistenciaAdapter#existeEmail
        <<< [OUTPUT] | return: false

WARN  : c.a.b.i.i.d.j.u.adapter.UsuarioPersistenciaAdapter#existeEmail
        *** [TIMING] | start: 15:47:05.750 | end: 15:47:05.870 | elapsed: 120ms ⚠️ superó umbral de 100ms

Tres registros para una sola llamada al adapter. El INPUT muestra exactamente qué email se consultó. El OUTPUT confirma que no existe. El TIMING revela que la operación tardó 120ms, superando el umbral de 100ms configurado para esta capa, lo que eleva automáticamente el registro a WARN aunque el nivel configurado para el adapter sea DEBUG. Este WARN es visible en producción con nivel INFO aunque todos los demás registros del adapter sean invisibles. La lentitud siempre se ve.

El UseCase continúa: genera el username, construye el objeto Usuario y llama a gateway.guardar(). El adapter es interceptado de nuevo:

DEBUG : c.a.b.i.i.d.j.u.adapter.UsuarioPersistenciaAdapter#guardar
        >>> [INPUT] | args: {usuario={"id":null,"nombre":"Juan Perez","email":"[email protected]","edad":25,"username":"juanperez","fechaRegistro":"2026-05-18T15:47:05.8756894"}}

DEBUG : c.a.b.i.i.d.j.u.adapter.UsuarioPersistenciaAdapter#guardar
        <<< [OUTPUT] | return: {"id":1,"nombre":"Juan Perez","email":"[email protected]","edad":25,"username":"juanperez","fechaRegistro":"2026-05-18T15:47:05.8756894"}

DEBUG : c.a.b.i.i.d.j.u.adapter.UsuarioPersistenciaAdapter#guardar
        *** [TIMING] | start: 15:47:05.877 | end: 15:47:05.939 | elapsed: 62ms

El INPUT del guardar muestra el objeto completo antes de persistirse, con id en null porque todavía no ha pasado por la base de datos. El OUTPUT muestra el mismo objeto con el id asignado por H2 ya presente. El TIMING marca 62ms, dentro del umbral de 100ms, así que se emite en DEBUG normal.

El UseCase completa su ejecución y retorna el RegistrarUsuarioOut. El aspecto lo captura:

INFO  : c.a.b.i.d.u.registrarusuario.RegistrarUsuarioUseCase#ejecutar
        <<< [OUTPUT] | return: {"id":1,"nombre":"Juan Perez","email":"[email protected]","username":"juanperez","fechaRegistro":"2026-05-18T15:47:05.8756894"}

INFO  : c.a.b.i.d.u.registrarusuario.RegistrarUsuarioUseCase#ejecutar
        *** [TIMING] | start: 15:47:05.748 | end: 15:47:05.940 | elapsed: 192ms

El OUTPUT del UseCase no incluye el campo edad porque RegistrarUsuarioOut no lo tiene: ese DTO de salida solo expone lo que el contrato del caso de uso devuelve. El TIMING del UseCase registra 192ms totales de orquestación, que incluyen las validaciones, las dos llamadas al adapter y la construcción de objetos intermedios.

Finalmente el Controller recibe el resultado, lo mapea a RegistrarUsuarioResponse y retorna:

INFO  : c.a.b.i.i.e.a.registrarusuario.RegistrarUsuarioController#registrar
        <<< [OUTPUT] | return: {"id":1,"nombre":"Juan Perez","email":"[email protected]","username":"juanperez","fechaRegistro":"2026-05-18T15:47:05.8756894","mensaje":"Usuario registrado exitosamente"}

INFO  : c.a.b.i.i.e.a.registrarusuario.RegistrarUsuarioController#registrar
        *** [TIMING] | start: 15:47:05.747 | end: 15:47:05.944 | elapsed: 197ms

El OUTPUT del Controller incluye el campo mensaje que RegistrarUsuarioResponse agrega al mapear desde el RegistrarUsuarioOut. El TIMING del Controller registra 197ms de extremo a extremo, 5ms más que el UseCase, que es exactamente el overhead del Controller en mappers y serialización de la respuesta HTTP.

Con esos once registros, sin ninguna línea de log escrita en ninguna clase del proyecto, el sistema cuenta su historia completa: qué llegó, por qué capas pasó, cuánto tardó cada una, y qué salió.

Flujo de error: email duplicado

La misma solicitud llega por segunda vez. El Controller y el UseCase emiten sus INPUT normalmente, idénticos a los del flujo feliz. El adapter consulta si el email existe:

DEBUG : c.a.b.i.i.d.j.u.adapter.UsuarioPersistenciaAdapter#existeEmail
        >>> [INPUT] | args: {email="[email protected]"}

DEBUG : c.a.b.i.i.d.j.u.adapter.UsuarioPersistenciaAdapter#existeEmail
        <<< [OUTPUT] | return: true

DEBUG : c.a.b.i.i.d.j.u.adapter.UsuarioPersistenciaAdapter#existeEmail
        *** [TIMING] | start: 15:47:12.883 | end: 15:47:12.887 | elapsed: 4ms

Esta vez el OUTPUT es true. El adapter completó su ejecución normalmente: encontró el email, retornó el resultado, el aspecto registró el TIMING. Hasta aquí no hay ningún error. El error ocurre en el UseCase, que recibe el true y lanza la BusinessException:

ERROR : c.a.b.i.d.u.registrarusuario.RegistrarUsuarioUseCase#ejecutar
        !!! [ERROR] | exception: BusinessException - El email ya está registrado | elapsed: 4ms

INFO  : c.a.b.i.d.u.registrarusuario.RegistrarUsuarioUseCase#ejecutar
        *** [TIMING] | start: 15:47:12.883 | end: 15:47:12.887 | elapsed: 4ms

Dos registros para el camino de error del UseCase. El ERROR captura el tipo de excepción y su mensaje, que en este caso es suficientemente descriptivo para entender qué ocurrió sin necesidad de un stacktrace. El TIMING se emite de todas formas: 4ms desde que entró el comando hasta que la excepción salió del UseCase. Nótese que no hay OUTPUT: el método no completó normalmente, así que el aspecto nunca llega al código que lo emite. La ausencia del OUTPUT es en sí misma información.

La excepción sube al Controller. El aspecto la intercepta, encuentra loggedExceptionHolder ya poblado por el UseCase, y la registra como propagación:

DEBUG : c.a.b.i.i.e.a.registrarusuario.RegistrarUsuarioController#registrar
        !!! [ERROR-PROPAGATED] | exception: BusinessException - El email ya está registrado | elapsed: 5ms

INFO  : c.a.b.i.i.e.a.registrarusuario.RegistrarUsuarioController#registrar
        *** [TIMING] | start: 15:47:12.883 | end: 15:47:12.888 | elapsed: 5ms

El ERROR-PROPAGATED se emite en DEBUG, invisible en producción con nivel INFO. El TIMING del Controller registra 5ms de extremo a extremo, 1ms más que el UseCase, que es el overhead del propio Controller antes de invocar el UseCase.

Desde el Controller la excepción sigue subiendo hasta el GlobalExceptionHandler, que la captura y construye la respuesta de error apropiada. El handler no está interceptado por el aspecto porque no tiene ninguno de los estereotipos del pointcut que coincida con un patrón configurado, así que su ejecución es completamente silenciosa desde el punto de vista del sistema de logs. El cliente recibe un HTTP 409 con el detalle del error.

Lo que este flujo demuestra es la distinción que se anticipó en la primera parte: un ERROR en el log del aspecto no siempre significa un fallo del sistema. Una BusinessException por email duplicado es una condición esperada del negocio. En un dashboard de monitoreo, filtrar por ERROR en los logs del aspecto va a incluir estos casos junto con los errores reales de infraestructura. La forma de separar ambos tipos es observar de dónde viene el ERROR: si viene de un UseCase lanzando una excepción de negocio, es ruido operacional esperado; si viene de un adapter fallando al conectar con la base de datos, es un problema genuino que requiere atención. El campo de la firma en el registro, que incluye la capa y la clase, es la clave para hacer esa distinción.

Producción sin redespliegue

Hay un escenario que todo sistema productivo enfrenta eventualmente: un comportamiento anómalo que no se reproduce en desarrollo y que requiere ver el detalle de las capas internas para diagnosticarse. En el modelo tradicional, la respuesta era subir el nivel de log a DEBUG, redesplegar, reproducir el problema, bajar el nivel, redesplegar de nuevo. En sistemas con tráfico real ese ciclo puede tomar horas y el volumen de logs generado puede saturar la infraestructura de observabilidad.

El diseño de este sistema evita ese ciclo de dos formas complementarias. La primera es estructural: los logs del adapter están en DEBUG por configuración, así que en producción con nivel INFO son completamente invisibles sin ningún costo operativo. No hay nada que desactivar porque nunca estuvieron activos. La segunda es dinámica: Spring Boot Actuator expone un endpoint que permite cambiar el nivel de log de cualquier paquete en tiempo de ejecución sin reiniciar la aplicación.

Para activarlo basta con incluir Actuator en las dependencias y exponer el endpoint de loggers en la configuración:

management.endpoints.web.exposure.include=loggers
management.endpoint.loggers.enabled=true

Con eso disponible, activar DEBUG para el paquete de los adapters en un ambiente productivo es una llamada HTTP:

POST /actuator/loggers/com.app_247.blog.id202603212000art.infrastructure.drivenadapters
Content-Type: application/json

{"configuredLevel": "DEBUG"}

A partir de ese momento, todos los registros del adapter que estaban silenciados aparecen en el log en tiempo real. Cuando el diagnóstico termina, una segunda llamada restaura el nivel a INFO y el silencio vuelve. Sin redespliegue, sin ventana de mantenimiento, sin riesgo de introducir cambios mientras se investiga un problema.

Este mecanismo refleja una filosofía más amplia que vale la pena nombrar explícitamente: el sistema de observabilidad debe poder adaptarse al momento sin modificar el sistema que está observando. La configuración por niveles y los patrones por capa son precisamente el mecanismo que hace eso posible.

Lo que se gana con este diseño

Vale la pena hacer explícito el inventario de lo que este sistema aporta, porque no todo es inmediatamente visible en el código.

La consistencia es quizás el beneficio más silencioso. Cada método interceptado produce exactamente el mismo formato de registro, con los mismos marcadores, la misma estructura de tiempo y la misma firma comprimida. No importa quién escribió la clase ni cuándo: el sistema de logs tiene siempre el mismo aspecto. En un equipo donde varias personas trabajan en paralelo sobre distintas partes del proyecto, esa consistencia es la diferencia entre un log que se puede leer y uno que requiere interpretación caso a caso.

La herencia automática es el segundo beneficio. Cada nueva clase que se añada al proyecto y que cumpla con los patrones configurados, un nuevo UseCase, un nuevo adapter, un nuevo Controller, hereda la observabilidad completa sin que nadie tenga que recordar añadir ninguna instrucción de log. El sistema crece y la observabilidad crece con él.

La separación de responsabilidades es el tercero. La lógica de negocio no sabe que está siendo observada. Los validadores de dominio no importan ninguna librería de logging. El UseCase no tiene ninguna instrucción de log. Si en el futuro el equipo decide cambiar el formato de los registros, añadir un campo nuevo a cada entrada, o integrar el sistema con OpenTelemetry, ese cambio ocurre en un único lugar: MethodLoggingAspect. Ninguna clase de negocio necesita ser modificada.

La granularidad controlable es el cuarto beneficio. El sistema tiene tres niveles de visibilidad configurables de forma independiente: los logs del Controller y el UseCase son INFO y siempre visibles, los logs del adapter son DEBUG y silenciosos en producción, y los WARN de latencia son siempre visibles independientemente del nivel de su capa. Esta estratificación permite operar en producción con un volumen de logs manejable mientras se mantiene la capacidad de activar el detalle completo en segundos cuando se necesita.

Mirando hacia adelante

Lo construido en este artículo es un sistema completo y funcional, pero no es un punto de llegada. Hay líneas naturales de evolución que vale la pena tener en el horizonte.

La más inmediata es el enmascaramiento de datos sensibles, que será el tema de la tercera parte de esta serie. El sistema actual serializa los argumentos y resultados tal como son: un email aparece en el log como texto plano, un número de identificación aparece completo. En muchos contextos eso es inaceptable desde el punto de vista de privacidad y cumplimiento regulatorio. La solución es extender el ObjectMapper que usa el aspecto con un introspector personalizado que lea anotaciones declaradas en el modelo de dominio y aplique estrategias de enmascaramiento antes de escribir el registro. El modelo de dominio declara qué es sensible; el sistema de logs lo respeta automáticamente.

Más allá del enmascaramiento, la integración con OpenTelemetry es otra extensión natural. Los registros estructurados que produce este sistema, con sus marcadores de capa y sus métricas de tiempo, son completamente compatibles con el modelo de spans de OpenTelemetry. Los mismos puntos de interceptación del aspecto que hoy emiten registros de texto podrían emitir spans instrumentados que una plataforma como Jaeger o Zipkin renderiza como árboles de llamadas con tiempos y metadatos. La transición no requeriría cambios en ninguna clase de negocio: solo en el aspecto.

La generación de métricas de aplicación a través de Micrometer desde los mismos puntos de intercepción es otra línea de evolución que elimina la duplicación entre el sistema de logs y el sistema de métricas. Hoy, para saber la latencia promedio de un adapter externo se necesita parsear los registros TIMING. Con Micrometer integrado en el aspecto, ese mismo dato podría alimentar un contador o un histograma directamente, sin pasar por texto. Una única fuente de verdad para logs y métricas, gestionada desde el mismo componente transversal.

Lo que todo esto ilustra, más allá de los detalles técnicos, es que un sistema de observabilidad diseñado con los mismos principios que se aplican a la lógica de negocio, separación de responsabilidades, consistencia, configurabilidad, no es una carga que el equipo arrastra sino una ventaja que el equipo usa. El código del proyecto queda limpio, la observabilidad queda centralizada, y la capacidad de entender qué está pasando en producción en cualquier momento queda disponible sin adivinar y sin redesplegar.

Anexo: Código fuente completo

Las clases que siguen son exactamente las que forman el sistema de logs. Todo lo demás, los validadores, los mappers, las entidades JPA, el handler de excepciones, es lógica del proyecto de ejemplo que no tiene ninguna relación con el sistema de observabilidad y que se puede reemplazar por la lógica propia de cualquier proyecto sin afectar el funcionamiento del aspecto.

Estructura de carpetas

src/main/java/com/app_247/blog/id202603212000art/
│
├── Id202603212000artApplication.java                  ★
│
└── applications/
    └── aop/
        ├── aspect/
        │   └── MethodLoggingAspect.java               ★
        └── config/
            ├── JacksonConfig.java                     ★
            └── LoggingAopProperties.java              ★

src/main/resources/
└── application.properties                             ★

Cinco artefactos. Tres en el paquete applications/aop, uno en la raíz de la aplicación y uno en recursos. Todo el sistema de observabilidad vive en esas cinco piezas.

Grupo 1 — Propiedades de configuración

LoggingAopProperties.java

package com.app_247.blog.id202603212000art.applications.aop.config;

import java.util.List;

import org.springframework.boot.context.properties.ConfigurationProperties;

import lombok.Data;

@Data
@ConfigurationProperties(prefix = "logging.aop")
public class LoggingAopProperties {
    /** Habilita o deshabilita el aspecto completo */
    private boolean enabled = true;
    /** Paquete raíz de la aplicación, primer filtro antes de evaluar regex */
    private String basePackage = "com.app_247.blog.id202603212000art";
    /** Lista de patrones de interceptación */
    private List<PatternConfig> patterns = List.of();

    @Data
    public static class PatternConfig {
        /** Regex que debe cumplir el paquete completo */
        private String packageRegex = ".*";
        /** Regex que debe cumplir el nombre simple de la clase */
        private String classRegex = ".*";
        /** Regex que debe cumplir el nombre del método */
        private String methodRegex = ".*";
        /** Nivel de log: TRACE, DEBUG, INFO, WARN, ERROR */
        private String logLevel = "INFO";
        /** Umbral en ms a partir del cual se emite un WARN de tiempo */
        private long warnThresholdMs = 500L;
    }
}

Grupo 2 — Configuración de Jackson

JacksonConfig.java

package com.app_247.blog.id202603212000art.applications.aop.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;

@Configuration
public class JacksonConfig {
    @Bean
    public ObjectMapper objectMapper() {
        ObjectMapper mapper = new ObjectMapper();
        mapper.registerModule(new JavaTimeModule());
        mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
        return mapper;
    }
}

Grupo 3 — El aspecto

MethodLoggingAspect.java

package com.app_247.blog.id202603212000art.applications.aop.aspect;

import java.lang.reflect.Method;
import java.lang.reflect.Parameter;
import java.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.ConcurrentHashMap;
import java.util.stream.IntStream;

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.reflect.MethodSignature;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.stereotype.Component;

import com.app_247.blog.id202603212000art.applications.aop.config.LoggingAopProperties;
import com.app_247.blog.id202603212000art.applications.aop.config.LoggingAopProperties.PatternConfig;
import com.fasterxml.jackson.databind.ObjectMapper;

import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;

@Slf4j
@Aspect
@Component
@RequiredArgsConstructor
@ConditionalOnProperty(prefix = "logging.aop", name = "enabled", havingValue = "true", matchIfMissing = true)
public class MethodLoggingAspect {

    private final ObjectMapper objectMapper;
    private final LoggingAopProperties properties;

    // -------------------------------------------------------------------------
    // Marcadores visuales
    // -------------------------------------------------------------------------
    private static final String INPUT_MARKER      = ">>> [INPUT] |";
    private static final String OUTPUT_MARKER     = "<<< [OUTPUT] |";
    private static final String TIMING_MARKER     = "*** [TIMING] |";
    private static final String ERROR_MARKER      = "!!! [ERROR] |";
    private static final String PROPAGATED_MARKER = "!!! [ERROR-PROPAGATED] |";
    private static final DateTimeFormatter FORMATTER =
            DateTimeFormatter.ofPattern("HH:mm:ss.SSS");

    // -------------------------------------------------------------------------
    // ThreadLocal: registra la excepción que ya fue logueada como ERROR origen
    // evita que capas superiores la vuelvan a loguear como ERROR
    // -------------------------------------------------------------------------
    private static final ThreadLocal<Throwable> loggedExceptionHolder =
            new ThreadLocal<>();

    // -------------------------------------------------------------------------
    // ThreadLocal: contador de profundidad de métodos interceptados activos
    // permite saber cuándo estamos en el método más externo del stack
    // -------------------------------------------------------------------------
    private static final ThreadLocal<Integer> depthHolder =
            ThreadLocal.withInitial(() -> 0);

    // -------------------------------------------------------------------------
    // Cache de matching por firma de método
    // Key: "com.app_247...RegistrarUsuarioUseCase#ejecutar"
    // Value: PatternConfig que hizo match, o empty si no hubo match
    // -------------------------------------------------------------------------
    private final ConcurrentHashMap<String, Optional<PatternConfig>> matchCache =
            new ConcurrentHashMap<>();

    // -------------------------------------------------------------------------
    // Pointcut: limitado a beans Spring, excluye el propio paquete aop
    // -------------------------------------------------------------------------
    @Around("(within(@org.springframework.stereotype.Service *)                    " +
            "|| within(@org.springframework.stereotype.Component *)                " +
            "|| within(@org.springframework.web.bind.annotation.RestController *)" +
            "|| within(@org.springframework.stereotype.Repository *))              " +
            "&& !within(com.app_247.blog.id202603212000art.aop..*)")
    public Object logMethod(ProceedingJoinPoint joinPoint) throws Throwable {
        MethodSignature signature = (MethodSignature) joinPoint.getSignature();
        Method method = signature.getMethod();
        String packageName = method.getDeclaringClass().getPackageName();
        String className   = method.getDeclaringClass().getSimpleName();
        String methodName  = method.getName();

        // Filtro rápido por paquete base antes de evaluar regex
        if (!packageName.startsWith(properties.getBasePackage())) {
            return joinPoint.proceed();
        }

        // Cache de matching: evita re-evaluar regex en invocaciones repetidas
        String cacheKey = packageName + "." + className + "#" + methodName;
        Optional<PatternConfig> matchedPattern = matchCache.computeIfAbsent(
                cacheKey,
                k -> findMatchingPattern(packageName, className, methodName));

        if (matchedPattern.isEmpty()) {
            return joinPoint.proceed();
        }

        PatternConfig pattern = matchedPattern.get();

        // Firma comprimida:
        // c.a.b.i.d.u.registrarusuario.RegistrarUsuarioUseCase#ejecutar
        String methodSignature = "%s.%s#%s".formatted(
                compressPackage(packageName),
                className,
                methodName);

        // Incrementar profundidad al entrar en un método interceptado
        depthHolder.set(depthHolder.get() + 1);

        logInput(methodSignature, signature, joinPoint.getArgs(), pattern);

        Instant startInstant = Instant.now();
        Object result;
        try {
            result = joinPoint.proceed();
        } catch (Throwable ex) {
            Instant endInstant = Instant.now();
            long elapsed = endInstant.toEpochMilli() - startInstant.toEpochMilli();

            if (loggedExceptionHolder.get() == null) {
                // Primera captura → origen del error
                loggedExceptionHolder.set(ex);
                logException(methodSignature, ex, elapsed, ERROR_MARKER);
            } else {
                // Ya fue logueada más abajo → propagación
                logException(methodSignature, ex, elapsed, PROPAGATED_MARKER);
            }

            logTiming(methodSignature, startInstant, endInstant, elapsed, pattern);

            // Decrementar profundidad al salir con excepción
            int currentDepth = depthHolder.get() - 1;
            depthHolder.set(currentDepth);

            // Limpiar ThreadLocals solo cuando salimos del método más externo
            if (currentDepth == 0) {
                loggedExceptionHolder.remove();
                depthHolder.remove();
            }

            throw ex;
        }

        Instant endInstant = Instant.now();
        long elapsed = endInstant.toEpochMilli() - startInstant.toEpochMilli();

        // Decrementar profundidad al salir en flujo normal
        depthHolder.set(depthHolder.get() - 1);

        logOutput(methodSignature, method.getReturnType(), result, pattern);
        logTiming(methodSignature, startInstant, endInstant, elapsed, pattern);

        return result;
    }

    // -------------------------------------------------------------------------
    // Compresión de paquete
    // com.app_247.blog.id202603212000art.domain.usecase.registrarusuario
    // → c.a.b.i.d.u.registrarusuario
    // -------------------------------------------------------------------------
    private String compressPackage(String packageName) {
        if (packageName == null || packageName.isBlank()) return "";
        String[] segments = packageName.split("\\.");
        if (segments.length == 1) return packageName;
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < segments.length - 1; i++) {
            sb.append(segments[i].charAt(0)).append('.');
        }
        sb.append(segments[segments.length - 1]);
        return sb.toString();
    }

    // -------------------------------------------------------------------------
    // Busca el primer patrón configurado que haga match con el método
    // -------------------------------------------------------------------------
    private Optional<PatternConfig> findMatchingPattern(
            String packageName,
            String className,
            String methodName) {
        return properties.getPatterns()
                .stream()
                .filter(pattern -> packageName.matches(pattern.getPackageRegex())
                        && className.matches(pattern.getClassRegex())
                        && methodName.matches(pattern.getMethodRegex()))
                .findFirst();
    }

    // -------------------------------------------------------------------------
    // Log INPUT
    // -------------------------------------------------------------------------
    private void logInput(
            String methodSignature,
            MethodSignature signature,
            Object[] args,
            PatternConfig pattern) {
        Parameter[] parameters = signature.getMethod().getParameters();
        if (parameters.length == 0) {
            logAtLevel(pattern, "{} {} args: (none)", methodSignature, INPUT_MARKER);
            return;
        }
        Map<String, Object> inputMap = new LinkedHashMap<>();
        IntStream.range(0, parameters.length)
                .forEach(i -> inputMap.put(
                        parameters[i].getName(),
                        formatArg(args[i])));
        logAtLevel(pattern, "{} {} args: {}", methodSignature, INPUT_MARKER, inputMap);
    }

    // -------------------------------------------------------------------------
    // Log OUTPUT
    // -------------------------------------------------------------------------
    private void logOutput(
            String methodSignature,
            Class<?> returnType,
            Object result,
            PatternConfig pattern) {
        if (void.class.equals(returnType) || Void.class.equals(returnType)) {
            logAtLevel(pattern, "{} {} return: void", methodSignature, OUTPUT_MARKER);
            return;
        }
        logAtLevel(pattern, "{} {} return: {}",
                methodSignature, OUTPUT_MARKER, formatArg(result));
    }

    // -------------------------------------------------------------------------
    // Log TIMING
    // -------------------------------------------------------------------------
    private void logTiming(
            String methodSignature,
            Instant start,
            Instant end,
            long elapsedMs,
            PatternConfig pattern) {
        String startStr        = formatInstant(start);
        String endStr          = formatInstant(end);
        String elapsedFormatted = formatElapsed(elapsedMs);
        if (elapsedMs >= pattern.getWarnThresholdMs()) {
            log.warn("{} {} start: {} | end: {} | elapsed: {} ⚠️ superó umbral de {}ms",
                    methodSignature, TIMING_MARKER,
                    startStr, endStr,
                    elapsedFormatted,
                    pattern.getWarnThresholdMs());
            return;
        }
        logAtLevel(pattern, "{} {} start: {} | end: {} | elapsed: {}",
                methodSignature, TIMING_MARKER, startStr, endStr, elapsedFormatted);
    }

    // -------------------------------------------------------------------------
    // Log ERROR / PROPAGATED
    // El marcador se recibe como parámetro para distinguir origen de propagación
    // Siempre se emite en ERROR independiente del nivel configurado en el patrón
    // -------------------------------------------------------------------------
    private void logException(
            String methodSignature,
            Throwable ex,
            long elapsedMs,
            String marker) {
        if (marker.equals(PROPAGATED_MARKER)) {
            // Solo informativo — el error real ya fue logueado en el origen
            log.debug("{} {} exception: {} - {} | elapsed: {}",
                    methodSignature,
                    marker,
                    ex.getClass().getSimpleName(),
                    ex.getMessage(),
                    formatElapsed(elapsedMs));
        } else {
            // Origen del error — siempre visible
            log.error("{} {} exception: {} - {} | elapsed: {}",
                    methodSignature,
                    marker,
                    ex.getClass().getSimpleName(),
                    ex.getMessage(),
                    formatElapsed(elapsedMs));
        }
    }

    // -------------------------------------------------------------------------
    // Emisión de log según nivel configurado en el patrón
    // -------------------------------------------------------------------------
    private void logAtLevel(PatternConfig pattern, String message, Object... args) {
        switch (pattern.getLogLevel().toUpperCase()) {
            case "TRACE" -> log.trace(message, args);
            case "DEBUG" -> log.debug(message, args);
            case "WARN"  -> log.warn(message, args);
            case "ERROR" -> log.error(message, args);
            default      -> log.info(message, args);
        }
    }

    // -------------------------------------------------------------------------
    // Helpers
    // -------------------------------------------------------------------------
    private String formatInstant(Instant instant) {
        return LocalDateTime
                .ofInstant(instant, ZoneId.systemDefault())
                .format(FORMATTER);
    }

    private String formatElapsed(long elapsedMs) {
        if (elapsedMs < 1_000) {
            return elapsedMs + "ms";
        } else if (elapsedMs < 60_000) {
            return "%.3fs".formatted(elapsedMs / 1_000.0);
        } else {
            long minutes = elapsedMs / 60_000;
            long seconds = (elapsedMs % 60_000) / 1_000;
            long millis  = elapsedMs % 1_000;
            return "%dm %ds %dms".formatted(minutes, seconds, millis);
        }
    }

    private String formatArg(Object arg) {
        if (arg == null) return "null";
        try {
            return objectMapper.writeValueAsString(arg);
        } catch (Exception e) {
            e.printStackTrace();
            return arg.toString();
        }
    }
}

Grupo 4 — Bootstrap

Id202603212000artApplication.java

package com.app_247.blog.id202603212000art;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;

import com.app_247.blog.id202603212000art.applications.aop.config.LoggingAopProperties;

@SpringBootApplication
@EnableConfigurationProperties(LoggingAopProperties.class)
public class Id202603212000artApplication {

    public static void main(String[] args) {
        SpringApplication.run(Id202603212000artApplication.class, args);
    }
}

Grupo 5 — Configuración de la aplicación

application.properties

spring.application.name=id202603212000art

# ================================
# SERVER
# ================================
server.port=8080

# ================================
# H2 DATABASE
# ================================
spring.datasource.url=jdbc:h2:mem:usuariosdb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
spring.datasource.driver-class-name=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=

# H2 Console (http://localhost:8080/h2-console)
spring.h2.console.enabled=true
spring.h2.console.path=/h2-console

# ================================
# JPA / HIBERNATE
# ================================
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect
spring.jpa.hibernate.ddl-auto=create-drop

# ================================
# JACKSON
# ================================
spring.jackson.serialization.write-dates-as-timestamps=false
spring.jackson.time-zone=America/Bogota

# ================================
# AOP LOGGING
# ================================
logging.aop.enabled=true
logging.aop.base-package=com.app_247.blog.id202603212000art

# UseCase
logging.aop.patterns[0].package-regex=com\\.app_247\\.blog\\.id202603212000art\\.domain\\.usecase.*
logging.aop.patterns[0].class-regex=.*UseCase
logging.aop.patterns[0].method-regex=.*
logging.aop.patterns[0].log-level=INFO
logging.aop.patterns[0].warn-threshold-ms=300

# Adapter de persistencia
logging.aop.patterns[1].package-regex=com\\.app_247\\.blog\\.id202603212000art\\.infrastructure\\.drivenadapters.*
logging.aop.patterns[1].class-regex=.*Adapter
logging.aop.patterns[1].method-regex=.*
logging.aop.patterns[1].log-level=DEBUG
logging.aop.patterns[1].warn-threshold-ms=100

# Controller
logging.aop.patterns[2].package-regex=com\\.app_247\\.blog\\.id202603212000art\\.infrastructure\\.entrypoints.*
logging.aop.patterns[2].class-regex=.*Controller
logging.aop.patterns[2].method-regex=.*
logging.aop.patterns[2].log-level=INFO
logging.aop.patterns[2].warn-threshold-ms=500

Con esas cinco piezas el sistema está completo. LoggingAopProperties define las reglas, JacksonConfig provee el serializador, MethodLoggingAspect aplica la observabilidad, Id202603212000artApplication registra las propiedades en el contenedor, y application.properties conecta la configuración con el comportamiento deseado para cada capa. Cualquier proyecto que adopte estas cinco piezas y ajuste los patrones a su propia estructura de paquetes tiene el sistema funcionando desde el primer arranque, sin ninguna modificación en las clases de negocio.

Son las 11 de la noche. El servicio de pagos lleva cuarenta minutos fallando silenciosamente — no con un error dramático que dispara alertas, sino con transacciones que se pierden sin dejar rastro en los logs. Un cliente lo detectó antes que el equipo y ya escribió enojado en el chat de soporte. El volumen de ventas del día está cayendo en tiempo real.

Alguien tiene que decidir: ¿revertir el último despliegue y perder dos semanas de trabajo del equipo, o seguir investigando con el riesgo de que el problema se agrave? No hay tiempo para una reunión. No hay forma de reunir a todos. Cada minuto que pasa es dinero que se pierde y confianza que se erosiona.

En ese momento, la pregunta más importante no es técnica. Es estructural: ¿quién tiene la autoridad para tomar esa decisión ahora mismo, sin consultar a nadie más, y con la confianza de que el equipo va a ejecutar lo que decida?

Si la respuesta a esa pregunta demora más de treinta segundos en aparecer, el equipo tiene un problema que no está en el código.

Dos modelos, dos promesas, un mismo contexto de caos

La industria del software lleva décadas construyendo respuestas a esa pregunta, y ha producido fundamentalmente dos modelos de organización que prometen resolverla de formas opuestas.

El primero se conoce informalmente como la Catedral: una estructura donde la jerarquía es deliberada y la responsabilidad técnica final tiene nombre y apellido. El Arquitecto, el Líder Técnico, el Tech Lead — el título varía según la empresa — es quien toma la decisión difícil cuando el sistema falla, quien responde ante el negocio por las consecuencias y quien firma con su reputación cada decisión de arquitectura. La promesa de este modelo es claridad: siempre hay alguien a quien llamar, siempre hay alguien que puede actuar sin pedir permiso. Pero esa claridad tiene un prerequisito que el modelo suele omitir en su descripción ideal: para que ese líder pueda tomar decisiones técnicas con autoridad real, necesita haber construido y operado sistemas similares. No es un rol de coordinación — es un rol de criterio técnico profundo con responsabilidad organizacional encima.

El segundo se conoce como el Bazar: una red orgánica donde la autoridad emana del conocimiento técnico del momento, no de un cargo en un organigrama. Los roles son fluidos, la propiedad del producto es compartida y la apuesta es que la inteligencia colectiva del equipo supera consistentemente a la de cualquier individuo. La promesa de este modelo es agilidad y autonomía: el equipo puede moverse rápido porque no necesita esperar que una sola persona apruebe cada decisión. Pero esa agilidad también tiene su prerequisito silencioso: para que funcione, cada miembro del equipo necesita tener el criterio técnico suficiente para tomar decisiones sin supervisión. No basta con que alguien del equipo sea técnicamente sólido — todos deben serlo, porque en ausencia de jerarquía formal, la calidad de las decisiones depende de la calidad técnica de quien las toma en cada momento.

Ambos modelos tienen defensores apasionados con argumentos sólidos. Ambos tienen casos de éxito reales y fracasos documentados. Y el debate entre ellos suele quedarse en el plano teórico, comparando los beneficios abstractos de cada uno sin hacerse la pregunta que realmente importa: ¿en qué contexto se aplica cada modelo, y qué pasa cuando se aplica en el contexto equivocado?

Lo que ambos modelos dan por sentado y nadie dice en voz alta

Antes de comparar jerarquía y autonomía, hay algo que los dos modelos asumen en silencio y que casi nunca se nombra en las discusiones sobre estructura de equipos: ninguno funciona sin una base técnica sólida como punto de partida. La diferencia está en dónde debe estar concentrada esa base.

En la Catedral, el peso técnico recae principalmente sobre el líder. Él es quien debe poder leer un stack trace a las 3 de la mañana y saber en qué capa del sistema está el problema. Quien debe entender las implicaciones de elegir consistencia eventual sobre consistencia fuerte en un modelo de datos. Quien puede evaluar si la propuesta de un ingeniero junior resuelve el problema de hoy pero crea uno mayor en seis meses. Sin ese fundamento técnico, el líder no tiene jerarquía real — tiene un título. Y un título sin criterio técnico produce algo peor que la ausencia de liderazgo: produce decisiones con autoridad pero sin fundamento, que el equipo aprende rápidamente a rodear o ignorar.

En el Bazar, ese mismo peso técnico debe estar distribuido en cada miembro del equipo. No basta con que haya dos o tres personas técnicamente sólidas rodeadas de ingenieros que ejecutan. Cuando la autoridad emana del conocimiento del momento, cada persona que toma una decisión — sobre arquitectura, sobre deuda técnica, sobre qué vale la pena optimizar ahora y qué puede esperar — necesita tener el criterio para tomarla bien. Un equipo con responsabilidad fluida y base técnica desigual no es un equipo autónomo: es un equipo donde las decisiones importantes las toman silenciosamente las dos o tres personas que saben más, mientras los demás asienten sin entender del todo las implicaciones. Eso no es horizontalidad — es una jerarquía informal y no reconocida, que tiene todos los problemas de la jerarquía sin ninguna de sus ventajas.

Nombrar esto importa porque hay una tendencia creciente en la industria a separar el liderazgo técnico de la base técnica. Cada vez más, los roles de liderazgo en equipos de software se llenan con perfiles esencialmente directivos: personas con habilidades de gestión, comunicación y coordinación, pero con poca o ninguna experiencia construyendo los sistemas que van a liderar. El argumento que suele justificarlo es que el líder no necesita saber programar — necesita saber gestionar personas y procesos. Eso puede ser cierto para un gerente de producto o un director de operaciones. Para alguien que debe tomar decisiones técnicas con consecuencias reales sobre un sistema en producción, es una trampa. El equipo lo nota desde la primera semana. Y cuando lo nota, la estructura jerárquica colapsa en la práctica aunque siga existiendo en el organigrama.

El problema que ninguno de los dos nombra

Tanto la Catedral como el Bazar comparten un supuesto silencioso: que la estructura del equipo puede diseñarse de forma independiente al sistema que ese equipo va a construir y mantener. Y ese supuesto es el origen de la mayoría de los fracasos que se atribuyen a uno u otro modelo.

La variable que ninguno de los dos nombra con suficiente claridad es el horizonte temporal del sistema.

Una landing page de campaña es efímera por diseño. Una herramienta interna de validación de datos puede ser efímera por accidente. Pero un CRM, un sistema de autenticación, una plataforma de pagos — estos sistemas nacen con la intención explícita de sobrevivir ciclos de negocio, rotaciones de personal y cambios de tecnología. Nadie construye un CRM pensando en tirarlo en dieciocho meses.

¿Cómo se distingue en la práctica un sistema persistente de uno efímero? No siempre por el tamaño ni por la complejidad técnica, sino por la intención de origen: ¿se espera que este sistema funcione más allá del equipo que lo construyó? ¿Sus decisiones de arquitectura, sus integraciones, su modelo de datos, van a necesitar ser entendidas y mantenidas por personas que todavía no han sido contratadas? Cuando la respuesta es sí, el sistema es persistente. Y los sistemas persistentes acumulan algo que no aparece en ningún diagrama de arquitectura: contexto implícito. Decisiones tomadas hace tres años por personas que ya no están. Compromisos con clientes que nunca quedaron en ningún ticket. Workarounds que resuelven problemas que nadie recuerda haber tenido. Ese conocimiento no vive en la documentación — vive en las personas.

El Bazar, con su promesa de propiedad compartida, asume que ese conocimiento se distribuye de forma natural entre el equipo. Pero en la práctica, cuando alguien se va — y en el mercado actual la rotación es la norma, no la excepción — el conocimiento se va con esa persona sin que nadie tenga la responsabilidad de haberlo transferido. Cuando esto ocurre de forma repetida, el sistema persistente se convierte en un sistema frágil que nadie entiende del todo y que todos temen tocar.

Para sistemas efímeros, la responsabilidad fluida puede funcionar razonablemente bien, especialmente cuando el equipo es pequeño, cohesionado y tiene un objetivo claro y acotado. El costo de la ambigüedad de roles es tolerable cuando el proyecto tiene fecha de muerte. Para sistemas persistentes, la ecuación cambia radicalmente.

Lo que el lector ya está pensando

Antes de continuar, vale la pena nombrar las objeciones que probablemente ya están tomando forma.

La primera es la más obvia: ¿qué pasa si el líder es mediocre? Un líder técnico malo en una estructura jerárquica produce un equipo dependiente y un sistema frágil. Es verdad. Pero un equipo mediocre en una estructura fluida produce algo diferente y en muchos aspectos peor: decisiones que nadie tomó, responsabilidades que nadie asumió y sistemas que se degradan silenciosamente porque no hay nadie a quien señalar cuando algo sale mal. La mediocridad no desaparece con la horizontalidad — solo se vuelve más difícil de identificar y, por lo tanto, más difícil de corregir.

Aquí está la pregunta que el debate suele esquivar: entre encontrar un líder técnico que sea genuinamente bueno y encontrar un equipo completo donde cada persona sea genuinamente buena, ¿cuál es estadísticamente más probable? La respuesta incómoda es que es más fácil identificar, contratar y desarrollar una persona excepcional que construir de golpe un equipo donde todos lo sean. No porque los equipos excepcionales no existan — existen, y son notables cuando aparecen — sino porque construirlos toma años de trabajo deliberado, y la mayoría de los proyectos no tienen ese tiempo ni esa estabilidad. Lo fluido funciona con equipos excepcionales. La jerarquía bien ejercida funciona con equipos buenos liderados por alguien excepcional. Esa diferencia en el umbral de entrada es, en la práctica, enorme.

La segunda objeción es igualmente legítima: la jerarquía atrofia al equipo. Si el líder concentra todas las decisiones, los ingenieros se convierten en ejecutores que esperan instrucciones y pierden la capacidad de resolver problemas por su cuenta. También es verdad — pero describe un liderazgo mal ejercido, no la jerarquía como estructura. La diferencia entre un líder que concentra y uno que distribuye es real, y tiene consecuencias técnicas enormes que conviene detallar antes de seguir.

La tercera viene con ejemplos famosos: Google, Spotify y Netflix construyeron sistemas de escala global con estructuras horizontales. Si funciona ahí, ¿por qué no acá? La respuesta requiere mirar con más cuidado lo que esas organizaciones realmente hacen — y lo que no se menciona cuando se cita su ejemplo.

El caso de Google y Spotify: lo que el ejemplo omite

Es el argumento favorito de los defensores de la autonomía radical, y merece una respuesta que no lo descarte con un gesto sino que lo examine en serio.

Primero: esas organizaciones tienen jerarquía. Spotify tiene Chapter Leads, Tribe Leads y arquitectos de plataforma. Google tiene Staff Engineers y Distinguished Engineers cuya función explícita es ser custodios del criterio técnico a escala. Lo que estas empresas han logrado no es eliminar la jerarquía sino hacerla menos visible y más permeable — lo cual es un logro notable, pero no equivale a eliminarla. Cuando en Spotify un equipo toma una decisión de arquitectura que afecta a otros equipos, hay alguien con la autoridad y el contexto para evaluar ese impacto. Ese alguien tiene un título, aunque ese título no aparezca en el organigrama que se comparte en las conferencias.

Segundo: esas empresas tienen algo que la mayoría de equipos no tiene y que rara vez se menciona cuando se cita su ejemplo: densidad de talento excepcional acumulada durante años. Google puede darse el lujo de tener autonomía radical en sus equipos porque el umbral de entrada para trabajar ahí filtra a la mayoría del mercado. Sus equipos "horizontales" están compuestos por personas que en cualquier otra empresa serían los líderes técnicos más senior. Cuando todos en el equipo tienen ese nivel de criterio técnico, la jerarquía puede volverse implícita porque cada persona ya sabe qué decisiones le corresponden y cuáles requieren coordinación. Eso no es horizontalidad — es una jerarquía tan interiorizada que ya no necesita formalizarse.

Tercero, y quizás lo más importante: esas empresas llegaron a sus modelos actuales después de haber pasado por estructuras más jerárquicas en sus primeros años. La horizontalidad que exhiben hoy es el resultado de haber construido cultura, procesos y criterio técnico compartido durante mucho tiempo, no la condición con la que empezaron. Tomar el modelo de madurez de una organización de veinte años y aplicarlo a un equipo que lleva seis meses trabajando junto es importar la conclusión sin haber hecho el trabajo.

La solución: jerarquía con función pedagógica

Lo que funciona para sistemas persistentes no es la jerarquía tradicional donde el líder acumula decisiones, ni la horizontalidad donde nadie las tiene con claridad. Es algo más preciso: una jerarquía con función pedagógica explícita, donde la autoridad se usa para distribuir capacidad, no para concentrarla.

En este modelo, el líder técnico no es el embudo de todas las decisiones. Es el arquitecto del conocimiento del equipo. Su responsabilidad principal no es tomar decisiones — es asegurarse de que el equipo pueda tomarlas sin él para el día a día, mientras él retiene la autoridad y la responsabilidad sobre las decisiones que determinan la dirección de largo plazo del sistema.

La herramienta central de este modelo es la delegación de autoridad con responsabilidad retenida. El líder puede — y debe — dar a otro miembro del equipo autoridad total sobre una subtarea específica cuando ese miembro tiene la expertise necesaria. Si el problema requiere optimización profunda de base de datos, quien tiene ese conocimiento recibe no solo la tarea sino la autoridad completa sobre esa decisión. Pero la responsabilidad de que esa persona fue elegida bien, fue informada correctamente y tiene el soporte necesario para ejecutar, sigue siendo del líder. La responsabilidad no fluye. La autoridad sí.

Esta distinción es exactamente lo que diferencia este modelo de la responsabilidad fluida: en todo momento hay claridad absoluta sobre quién responde si algo sale mal, incluso cuando quien está ejecutando no es el líder. Y es lo que resuelve la objeción de la atrofia: el equipo gana autonomía real dentro de dominios bien definidos, con la red de seguridad de saber que hay alguien que puede intervenir si la decisión excede su criterio actual.

El segundo componente es la mentoría como obligación estructural, no como virtud opcional. El líder asigna micro-responsabilidades calibradas según la capacidad de cada persona — no para quitarse trabajo de encima, sino para desarrollar el criterio técnico de quienes trabajan con él. Cuando alguien en el equipo se equivoca, el líder no corrige el error y sigue adelante: usa ese momento como insumo de aprendizaje. El objetivo explícito es que, con el tiempo, cada miembro del equipo pueda asumir responsabilidades más grandes y, eventualmente, reemplazar al líder en su función.

El tercer componente es la cadena organizacional como red de seguridad. Una de las preguntas más difíciles para cualquier estructura jerárquica es qué pasa cuando el líder se va antes de haber formado a su reemplazo. En mercados con rotación alta — que es la norma en la industria actual — esa transferencia no siempre alcanza a completarse. Pero aquí está la respuesta que el debate teórico suele omitir: ningún equipo existe en el vacío. El líder técnico reporta a alguien que tiene contexto sobre el sistema y sobre el equipo, y sobre quiénes dentro del grupo tienen el potencial de asumir más responsabilidad. Cuando hay una ruptura en la cadena de transferencia, la organización tiene el mecanismo para absorber ese golpe y reinsertar un responsable desde arriba. La responsabilidad fluida no tiene ese mecanismo: cuando el miembro más conocedor se va, simplemente distribuye el vacío entre todos los que quedan.

Lo que este modelo produce en la práctica

La diferencia más inmediata y visible es la que ocurre a las 11 de la noche cuando el servicio de pagos falla. En un equipo con esta estructura, hay una persona que puede tomar la decisión de revertir o investigar sin convocar una reunión de emergencia. Esa persona conoce el sistema, conoce el historial de decisiones y tiene la autoridad para actuar. El tiempo de respuesta se mide en minutos, no en horas de coordinación.

Pero el impacto más profundo no es la crisis — es lo que ocurre entre crisis. Un líder que mentoriza activamente produce ingenieros que crecen. Con el tiempo, las personas del equipo desarrollan criterio propio, asumen responsabilidades más complejas y operan con creciente autonomía dentro de su dominio. El sistema no queda atado a la visión de una sola persona — queda sostenido por un equipo que entiende la visión porque alguien se tomó el trabajo de transferirla.

Hay también un efecto sobre la arquitectura base que es difícil de cuantificar pero fácil de observar. Un líder que sabe que su nombre está en el sistema tiende a tomar mejores decisiones de largo plazo. No porque la responsabilidad lo haga más capaz técnicamente, sino porque lo hace más cuidadoso: la arquitectura que construye es su carta de presentación ante el equipo, ante la organización y ante el próximo proyecto donde quiera trabajar. Los atajos que funcionan esta semana pero destruyen el sistema el próximo año también llevan el nombre de quien los autorizó.

Por último, este modelo tiene un mecanismo que la responsabilidad fluida no puede replicar fácilmente: la capacidad de corregir lo que no funciona. Un equipo sin jerarquía clara no puede fácilmente remover a alguien que está frenando al grupo, porque nadie tiene la autoridad formal para hacerlo sin generar un conflicto político que paraliza al equipo entero. Un líder con responsabilidad clara tiene ese mecanismo. No es un poder cómodo de ejercer, pero su ausencia tiene un costo que se acumula en silencio durante meses hasta que se vuelve insostenible.

El modelo fluido: cuándo funciona y por qué no es el punto de partida

Sería deshonesto no dedicarle un espacio honesto al modelo que se está cuestionando. La responsabilidad fluida tiene valor real, pero en condiciones muy específicas que rara vez se discuten con honestidad cuando se promueve.

Para que funcione sin colapsar en ambigüedad y evasión, se necesitan simultáneamente varias condiciones difíciles de alcanzar: un equipo que lleva años trabajando junto, con rotación casi nula, donde cada persona ha interiorizado tan profundamente su rol y el del resto que la estructura ya no necesita ser explícita porque está implícita en la cultura. Se necesita también un sentido de pertenencia o profesionalismo lo suficientemente elevado como para que cada persona asuma responsabilidades difíciles sin que nadie se las asigne formalmente. Y se necesita que todos tengan claridad sobre el objetivo — no a nivel de ticket, sino a nivel de hacia dónde va el sistema y por qué.

Pero hay una condición que suele omitirse incluso en las descripciones más honestas del modelo: todos los miembros del equipo deben tener una base técnica sólida y homogénea. No similar — homogénea. Porque en un modelo donde la autoridad emana del conocimiento del momento, la calidad de las decisiones depende directamente de la calidad técnica de quien las toma. Un equipo fluido con base técnica desigual no es autónomo: es un equipo donde las decisiones importantes recaen silenciosamente sobre los más capaces, mientras los demás participan en la ilusión del consenso sin poder evaluarlo con criterio real. Eso no es horizontalidad — es una jerarquía informal sin los mecanismos de rendición de cuentas que la jerarquía formal provee.

Cuando esas condiciones existen, lo fluido funciona porque la jerarquía está interiorizada, no porque haya desaparecido. El equipo se comporta de forma ordenada y responsable no porque haya un organigrama que lo fuerce, sino porque años de trabajo conjunto han producido algo más poderoso que cualquier estructura formal: confianza mutua y claridad implícita de roles. Ese estado es exactamente adonde apunta la jerarquía pedagógica descrita antes — es el destino, no el método.

Usar la responsabilidad fluida como estructura inicial en un equipo nuevo, con personas que no se conocen, en un sistema que acaba de nacer, es confundir el destino con el método. Y el costo de ese error no aparece de inmediato. Aparece dieciocho meses después, cuando alguien renuncia y nadie sabe exactamente qué sabía esa persona, ni quién tiene autoridad para decidir cómo llenar ese vacío, ni cómo se toma una decisión urgente sin convocar a diez personas que tienen opiniones igualmente válidas pero ninguna responsabilidad final.

Hay además un efecto secundario que pocas organizaciones están dispuestas a nombrar en voz alta: la ambigüedad de rol no libera a las personas. Las paraliza. Un equipo donde nadie sabe con certeza qué es suyo y qué no lo es no es un equipo autónomo — es un equipo ansioso. Cuando "todos son responsables", las tareas menos gratificantes no encuentran dueño, las decisiones difíciles se postergan en busca de un consenso que a veces nunca llega, y el estrés de la incertidumbre se distribuye silenciosamente entre todos los miembros sin que nadie lo nombre como problema estructural. La claridad de responsabilidad no es una limitación a la creatividad técnica. Es la condición que la hace posible.

Los desafíos que este modelo no resuelve solo

Sería igualmente deshonesto presentar la jerarquía pedagógica sin nombrar sus dificultades reales.

El primero y más obvio es que depende de encontrar a la persona correcta para el rol de liderazgo. Un líder que acumula en lugar de distribuir, que protege sus decisiones malas porque admitirlas equivale a dañar su carta de presentación, o que carece de la vocación de mentorizar, produce exactamente el equipo atrofiado que los críticos de la jerarquía describen. El modelo no funciona con cualquier persona en el rol — funciona con alguien que entiende que su éxito se mide por la capacidad del equipo, no por su propia indispensabilidad.

Hay además una variante de este problema que se está volviendo cada vez más común y que merece nombrarse directamente: el líder técnico que dejó de ser técnico. Con el tiempo, muchos ingenieros excelentes ascienden a roles de liderazgo y gradualmente se alejan de la práctica técnica — dejan de revisar código, de entender las decisiones de arquitectura a fondo, de tener opinión informada sobre las herramientas que usa el equipo. Se vuelven coordinadores: gestionan reuniones, comunican hacia arriba, administran tiempos. El problema no es que gestionen — es que siguen teniendo la autoridad técnica final sin tener ya el criterio técnico para ejercerla bien. El equipo lo percibe, y el resultado es predecible: las decisiones técnicas reales las toman informalmente quienes sí tienen el criterio, mientras el líder firma lo que le presentan sin poder evaluarlo con profundidad. La estructura sigue existiendo en el papel, pero la autoridad real se ha desconectado de la responsabilidad formal. Ese desacople es uno de los orígenes más frecuentes y menos diagnosticados de la deuda técnica acumulada en sistemas persistentes.

El segundo desafío es que la mentoría toma tiempo que compite con la entrega. Desarrollar el criterio técnico de un equipo es un trabajo de largo plazo que no produce resultados inmediatos. En organizaciones con presión de corto plazo constante, el líder que mentoriza bien puede parecer menos productivo en el trimestre que el que simplemente ejecuta y entrega. Esa tensión es real y requiere que la organización — no solo el líder — entienda y valore el trabajo de formación de equipo como inversión, no como overhead.

El tercero es que la transición de un equipo nuevo a un equipo maduro no es lineal. Al principio, el líder necesariamente concentra más decisiones porque el equipo no tiene todavía el contexto ni el criterio para tomarlas. Con el tiempo, esa concentración debe ir disminuyendo de forma deliberada. Si no disminuye — si el líder sigue siendo el embudo de todo dos años después — el modelo ha fallado sin que nadie lo haya nombrado explícitamente.

Cómo aplicarlo sin esperar condiciones perfectas

La buena noticia es que este modelo no requiere que todo esté resuelto desde el primer día. Requiere claridad sobre el punto de partida y honestidad sobre hacia dónde se quiere llegar.

El primer paso es nombrar explícitamente el horizonte temporal del sistema. Antes de diseñar la estructura del equipo, la organización debe poder responder con honestidad: ¿se espera que este sistema funcione más allá de las personas que lo están construyendo hoy? Si la respuesta es sí, la estructura debe reflejarlo desde el inicio, no improvisarse cuando los primeros miembros del equipo comiencen a rotar.

El segundo paso es definir con claridad quién tiene la responsabilidad final, y asegurarse de que esa persona entiende que su rol incluye transferir conocimiento, no solo ejercer autoridad. Eso puede hacerse explícito en la definición del rol, en los objetivos de desempeño y en las conversaciones de seguimiento. Un líder técnico que no puede describir cómo está formando a su sucesor no está cumpliendo la parte más importante de su trabajo.

El tercero, y quizás el más importante en la práctica, es empezar a construir la cadena de reemplazo antes de necesitarla. El líder técnico debe poder señalar, en cualquier momento, quién dentro del equipo tiene el criterio y el contexto suficientes para asumir su rol si él se va mañana. Si esa persona no existe todavía, desarrollarla es la tarea más urgente del líder — más urgente que cualquier decisión técnica pendiente. Un equipo donde esa pregunta no tiene respuesta clara no es un equipo resiliente: es un equipo que está a una renuncia de distancia de una crisis.

El círculo que se cierra

Cuando una organización decide entre jerarquía y responsabilidad fluida, cree que está eligiendo una estructura de equipo. En realidad está eligiendo algo más fundamental: quién carga con el peso cuando las cosas salen mal, y qué mecanismo existe para que ese peso nunca quede sin dueño.

En un sistema jerárquico bien ejercido, esa persona es conocida por todos. Tiene la autoridad necesaria para actuar, la responsabilidad de haber construido un equipo capaz de operar cuando ella no está, y el incentivo de cuidar el sistema porque su reputación está ligada a él. Su trabajo no termina cuando asigna tareas — termina cuando el equipo puede prescindir de ella para las decisiones del día a día y aun así mantener la dirección correcta.

En un sistema verdaderamente fluido — no el fluido teórico de los libros, sino el fluido real de los equipos con plazos y presiones — esa carga se distribuye de forma que a menudo resulta en que nadie la carga del todo. Las decisiones difíciles se postergan, las tareas menos gratificantes no encuentran dueño, y cuando el sistema falla a las 11 de la noche, la primera pregunta no es "¿cómo lo arreglamos?" sino "¿a quién le corresponde arreglarlo?". Esa pregunta, en un momento de crisis, es el lujo que un sistema persistente no puede permitirse.

Volvamos al martes. El servicio de pagos sigue fallando. El equipo está disperso. El cliente espera.

En un equipo con la estructura descrita, hay una persona que toma el teléfono, evalúa la situación con el contexto que lleva meses acumulando y toma la decisión en minutos. Puede ser el líder técnico, puede ser quien él formó para ese tipo de situación, puede ser quien escaló desde la organización cuando el líder no estaba disponible. Pero hay alguien. Y ese alguien tiene tanto la autoridad como el conocimiento para actuar.

Esa certeza — saber que hay alguien que puede responder — no es un lujo organizacional. Es la diferencia entre un sistema que sobrevive el paso del tiempo y uno que se vuelve frágil cada vez que alguien del equipo decide irse.

El martes de las 11 de la noche no es la excepción. Es el criterio de verdad de cualquier estructura de equipo. Y la pregunta que toda organización debería hacerse antes de diseñar la suya no es "¿jerarquía o autonomía?" sino algo más honesto: si el sistema falla ahora mismo, ¿quién responde?

Seguramente has pasado por esa etapa de "luna de miel" con las plataformas propietarias. Al principio, todo es idílico: lanzas una aplicación en Firebase en minutos, gestionas tus notas en Notion sin fricciones y despliegas en Vercel con un simple clic. Sin embargo, a medida que el proyecto crece, la realidad empieza a morder. Llega una factura inesperada por un exceso de uso o te das cuenta de que tus datos están atrapados en una estructura que no puedes exportar fácilmente. Es la famosa "jaula de oro".

Esta sensación de vulnerabilidad es lo que está impulsando a miles de desarrolladores a buscar el código abierto. Pero no lo hacen solo por ahorro; lo hacen por soberanía. Quieren ser dueños del motor, no solo conductores. Para lograrlo, el primer paso es elegir los cimientos sobre los que construirás tu próxima idea.

El corazón de la App: ¿Qué motor elegimos para nuestros datos?

Cuando decides alejarte de soluciones cerradas, la primera gran pregunta es cómo sustituir la comodidad de un Backend como Servicio (BaaS). Aquí es donde el camino se bifurca según la complejidad de lo que tienes en mente.

Si buscas el rascacielos de las bases de datos, Supabase es tu respuesta. Al estar construido sobre PostgreSQL y Deno, te ofrece integridad relacional, autenticación y hasta capacidades de Inteligencia Artificial con bases de datos vectoriales. Es la opción para quien no quiere sacrificar nada. Pero quizás sientas que es "demasiada herramienta" para un proyecto personal. En ese caso, PocketBase es una revelación: un solo archivo ejecutable que usa SQLite y almacena todo localmente. Es sencillez pura, aunque requiere que tú mismo configures detalles como el servidor de correos (SMTP).

Para quienes prefieren un enfoque moderno y reactivo, Convex permite hacer consultas directamente en TypeScript, mientras que Appwrite destaca por su enfoque en la IA y su marketplace de integraciones, permitiéndote incluso alojar tu frontend en el mismo sitio. Y si eres de los que prefiere ensuciarse las manos con arquitecturas más puras, siempre puedes optar por alternativas basadas en GraphQL que se conectan a Postgres y ofrecen extensiones para gRPC o Kafka, aunque esto te obligará a escribir mucho más código propio.

Elegir el motor es vital, pero surge la duda inmediata: ¿Dónde vamos a poner a funcionar todo esto sin depender de las nubes tradicionales?

El despliegue: De inquilinos a dueños del servidor

Pasar de Vercel a un servidor propio (VPS) solía ser un proceso árido de comandos. Hoy, herramientas como Coolify actúan como tu propio panel de control privado. Con una interfaz gráfica, puedes desplegar proyectos de Node, React o bases de datos como MongoDB sin límites. Es el puente perfecto para quien quiere la facilidad de la nube en hardware propio.

Si buscas algo todavía más intuitivo y ligero, Dokploy ofrece una administración de usuarios y copias de seguridad que te hará olvidar que estás gestionando un servidor. Para los nostálgicos de Heroku que prefieren la terminal, Dokku sigue siendo el estándar del minimalismo, mientras que CapRover es la opción para el desarrollador avanzado que no quiere que una interfaz le oculte el acceso a la configuración de Nginx o Docker Swarm.

Una vez que la app está "viva", el flujo de trabajo diario nos lleva a la comunicación con el servidor. ¿Cómo probamos nuestras APIs de forma privada?

El laboratorio de APIs: Pruebas sin intermediarios

El malestar creció cuando herramientas como Postman forzaron la nube. Como respuesta, Bruno propone algo brillante: tus colecciones de API se guardan localmente en Git. Si quieres que la documentación viaje con el código, esta es la vía. Si prefieres algo más tradicional, Insomnia ofrece una experiencia casi idéntica a Postman, aunque su capa gratuita sea limitada para equipos.

Para pruebas rápidas desde el navegador, Hoppscotch (antes hop.io) es imbatible por su minimalismo. Pero el ecosistema es amplio: tienes a Yaak para despliegues en Docker, HTTPie para quienes aman la terminal legible estilo Curl, o Red Fox, un cliente minimalista para peticiones rápidas de gRPC o GraphQL sin distracciones.

Con las tuberías conectadas, el siguiente paso es organizar la mente del equipo. ¿Cómo gestionar el conocimiento sin regalar nuestras ideas a terceros?

Productividad y Datos: El cerebro del equipo

Es contradictorio construir un backend seguro si luego toda la estrategia vive en Notion. Para recuperar ese espacio, AppFlowy es el clon más fiel: tableros y bloques con la rapidez de Rust. Si necesitas algo más robusto para documentación técnica, Docmost soporta hasta ecuaciones y corre bajo Docker con Postgres y Redis.

Para quienes piensan de forma visual y conectada, Logseq usa un grafo de conocimiento y pizarras infinitas que rompen con la jerarquía de carpetas. Si el foco es la colaboración en tiempo real, Affine.pro es el especialista, mientras que BookStack se mantiene como el clásico para organizar notas anidadas de forma sencilla.

A veces, sin embargo, no necesitas notas, sino una base de datos visual. NocoDB transforma cualquier base de datos en una hoja de cálculo tipo Airtable, permitiéndote manejar imágenes y formatos complejos. Si buscas automatizar procesos, Baserow brilla con sus flujos visuales de eventos, mientras que Grist sigue siendo la opción veterana para consultas sencillas.

Pero un proyecto que crece se convierte en una organización. ¿Cómo escalamos la comunicación y los procesos de negocio?

El ecosistema empresarial: Gestión y Comunicación

Cuando Jira o ClickUp se vuelven lentos, Plane aparece como un reemplazo directo y ágil, con tableros e IA para gestionar tickets. Para la comunicación interna, Mattermost es el "Slack privado" por excelencia, ofreciendo canales y tableros en tu servidor.

Si necesitas videollamadas, Jitsi te permite tener tu propio "Zoom", aunque es de las herramientas que más hardware exige. Y para el control total de la empresa (ventas, pagos, logística), gigantes como Odoo (modular y en Python) o ERPNext te permiten administrar áreas completas bajo tu propio control.

Estimación de Recursos: ¿Qué nos cuesta la libertad?

Autohospedar te da control total, pero requiere que planifiques bien el hardware. Aquí tienes una estimación de lo que consumirá tu servidor según el uso:

Conclusión: El círculo de la autonomía

Empezamos hablando de esa factura inesperada y de la fragilidad de no ser dueños de nuestra casa tecnológica. El recorrido por este ecosistema demuestra que la alternativa existe y es madura. No tienes que mudarte de golpe; la soberanía tecnológica es un hábito. Puedes empezar cambiando tus pruebas de API a Bruno hoy mismo, o levantando un pequeño PocketBase para tu próximo prototipo. Cada herramienta que recuperas es una llave que vuelve a tu bolsillo.

Has estado ahí. Es lunes por la mañana, abres el proyecto en tu IDE, y necesitas modificar cómo se procesa un pedido. Treinta minutos después, todavía estás navegando entre carpetas intentando encontrar todas las piezas del rompecabezas. El caso de uso está en algún lugar del módulo de dominio, el controlador REST disperso en los entry points, el adaptador de base de datos perdido en persistencia, y probablemente algunos DTOs compartidos en carpetas que juraste que recordarías. Este es el dilema que enfrentamos constantemente: las herramientas que usamos nos imponen una estructura técnica impecable, pero nuestro cerebro humano necesita algo diferente. Necesitamos que todo lo relacionado con "procesar un pedido" esté junto, fácil de encontrar, fácil de entender, fácil de modificar.

La Estructura que las Herramientas Imponen

Para entender el problema, primero necesitamos entender cómo funcionan las herramientas de scaffolding modernas, particularmente Scaffolding of Clean Architecture—una herramienta que muchas organizaciones adoptan porque estandariza proyectos y acelera su inicio. Esta herramienta genera automáticamente una estructura basada en Clean Architecture, pero con una característica particular: todo se organiza estrictamente por naturaleza técnica a través de módulos independientes de Gradle. No son simples carpetas; son módulos que se compilan independientemente, gestionan sus propias dependencias, y establecen fronteras arquitectónicas reales. La estructura generada típicamente incluye: Un módulo de dominio completamente independiente, sin dependencias hacia otros módulos del proyecto. Aquí viven las entidades, los casos de uso, los servicios de dominio, y crucialmente, las interfaces (gateways) que definen qué operaciones necesita el dominio sin especificar cómo se implementan. Es el núcleo puro de la lógica de negocio. Un módulo de infraestructura que se subdivide en dos grandes grupos. Por un lado, los "driven adapters"—módulos para implementar persistencia (jpa-repository), para consumir servicios externos (rest-consumer), para publicar mensajes (message-sender), y otros adaptadores que implementan los contratos que el dominio define. Por otro lado, los "entry points"—módulos para exponer APIs REST (api-rest), para consumir eventos (message-listener), para tareas programadas (scheduled-task), y otros puntos de entrada al sistema. Un módulo de aplicación que ensambla todo, conteniendo la configuración que conecta las piezas, los aspectos transversales como logging y auditoría, y el punto de arranque que levanta el sistema. Desde una perspectiva arquitectónica pura, es hermoso. Inversión de dependencias impecable: el dominio define contratos, la infraestructura los implementa. Separación clara de responsabilidades: cada módulo tiene su propósito bien definido. Fronteras forzadas por el sistema de build: no puedes violar accidentalmente las dependencias porque Gradle simplemente no compilará.

El Problema que Nadie Quiere Admitir

Pero entonces llega el día a día del desarrollo, y la fricción se hace evidente. Necesitas implementar una nueva funcionalidad: registrar un usuario. Ejecutas el comando de scaffolding para generar el caso de uso. La herramienta lo crea en domain/usecase/ en una estructura genérica. Ejecutas otro comando para generar el entry point REST. Se crea en infrastructure/entry-points/api-rest/ en otra ubicación genérica. Necesitas persistencia, ejecutas el comando para generar el adaptador JPA. Aparece en infrastructure/driven-adapters/jpa-repository/ en su propia ubicación técnica. Cada componente vive exactamente donde debe vivir según su naturaleza técnica. El problema es que conceptualmente todos estos componentes están relacionados—todos son parte de "registrar un usuario"—pero físicamente están dispersos por toda la estructura del proyecto según su clasificación técnica. El resultado es predecible: cinco pestañas abiertas en tu IDE, navegación constante entre módulos y carpetas, DTOs compartidos en ubicaciones centralizadas que sirven a múltiples propósitos, validadores reutilizables que intentan ser genéricos, y mappers comunes que traducen entre representaciones para varios casos de uso. Y hay algo peor: seis meses después, cuando otro desarrollador necesita modificar esa funcionalidad de registro de usuarios, el proceso se repite. Buscar, navegar, intentar recordar dónde quedaron todas las piezas dispersas. El conocimiento está fragmentado, la comprensión es difícil, y cada modificación se siente como resolver un rompecabezas. La pregunta natural surge: ¿por qué no simplemente abandonar esta estructura modular y volver a algo más simple donde todo esté junto? Porque entonces perdemos beneficios reales que los módulos independientes proporcionan: compilación incremental que solo recompila lo que cambió, gestión explícita de dependencias que previene acoplamiento accidental, y fronteras arquitectónicas forzadas que mantienen la integridad del diseño a largo plazo. O podrías pensar: ¿por qué no compartir más componentes entre funcionalidades? Crear carpetas centralizadas de DTOs reutilizables, validadores comunes, mapeadores genéricos. Suena eficiente hasta que dos funcionalidades que comparten un validador divergen en sus necesidades. Entonces enfrentas la decisión imposible: ¿modificas el validador compartido arriesgando romper la otra funcionalidad, o duplicas el código que justamente intentabas evitar?

La Solución Está en la Dualidad

La respuesta no está en elegir entre estructura técnica o cohesión conceptual. La respuesta está en reconocer que ambas son valiosas pero en diferentes niveles. Imagina mantener la estructura de módulos técnicos que Scaffolding of Clean Architecture genera—porque proporciona beneficios arquitectónicos reales—pero cambiar radicalmente cómo organizas el código dentro de cada módulo. En lugar de estructuras técnicas genéricas donde todos los componentes del mismo tipo conviven en carpetas planas, organizas por contextos de negocio donde cada funcionalidad tiene su propio espacio autocontenido. El módulo de dominio sigue siendo un módulo de dominio, pero cuando lo abres, en lugar de encontrar una carpeta usecase/ con cincuenta casos de uso en una lista plana, encuentras algo diferente. Cada caso de uso vive en su propia carpeta de contexto: usecase/registrar-usuario/, usecase/procesar-pedido/, usecase/consultar-inventario/. Cada contexto agrupa todo lo que esa funcionalidad específica necesita. Dentro de registrar-usuario/ no solo está el archivo del caso de uso. Está su carpeta dto/ con los DTOs de entrada y salida diseñados exactamente para lo que este caso de uso necesita—no DTOs genéricos compartidos que intentan servir múltiples propósitos. Está su carpeta mapper/ con traductores que mapean precisamente entre las representaciones que este caso de uso maneja. Está su carpeta validator/ con validadores que aplican las reglas específicas de negocio de registrar usuarios. Si necesita enriquecer datos desde otras fuentes, tiene su carpeta enricher/. Si requiere utilidades especializadas, tiene su carpeta util/. Todo junto. Todo cohesivo. Todo autocontenido. Lo mismo sucede en el módulo de entry points. En lugar de una carpeta genérica api-rest/ con todos los controladores mezclados, encuentras api-rest/registrar-usuario-api/ como su propio contexto. Dentro están los DTOs específicos de la API REST—diferentes de los DTOs del caso de uso porque representan el contrato externo, no el contrato de dominio. Están los mapeadores que traducen entre el mundo HTTP y el mundo del dominio. Están los validadores específicos de la capa de presentación que verifican formatos y restricciones del protocolo. Y en el módulo de adaptadores, en lugar de entidades JPA genéricas en una carpeta común, encuentras jpa-repository/usuario-persistencia/ como contexto autocontenido con sus entidades JPA, sus repositorios Spring Data, su implementación del gateway del dominio, sus mapeadores entre entidades JPA y entidades de dominio, todo junto porque conceptualmente pertenece junto. La estructura de módulos técnicos permanece intacta. El dominio sigue siendo independiente. Los adaptadores siguen implementando contratos del dominio. Los entry points siguen invocando casos de uso. Clean Architecture se mantiene en todo su esplendor. Pero dentro de cada módulo, la organización refleja el negocio, no solo la técnica.

Los Beneficios Tangibles que Cambian Todo

Esta dualidad—módulos técnicos afuera, contextos de negocio adentro—transforma radicalmente la experiencia de desarrollo. Cuando necesitas modificar el registro de usuarios seis meses después de implementarlo, abres domain/usecase/registrar-usuario/ y todo está ahí. No hay búsquedas en carpetas compartidas. No hay intentos de recordar dónde quedó el validador o el mapper. La lógica del caso de uso, sus DTOs, sus validadores, sus enriquecedores, sus utilidades—todo en un solo lugar. Abres api-rest/registrar-usuario-api/ y encuentras todo lo relacionado con cómo esa funcionalidad se expone vía REST. Abres jpa-repository/usuario-persistencia/ y encuentras todo lo relacionado con cómo se persiste. La velocidad de comprensión se dispara. Un desarrollador nuevo asignado a modificar una funcionalidad específica puede abrir su contexto y ver inmediatamente qué hace, cómo lo hace, y qué elementos utiliza. No necesita entender todo el sistema, solo el contexto específico con el que trabajará. El onboarding que solía tomar semanas ahora toma días porque el conocimiento no está disperso por todo el código base sino contenido en unidades comprensibles. El mantenimiento se simplifica dramáticamente. Un bug en el procesamiento de pedidos significa ir a domain/usecase/procesar-pedido/. La mayoría de las veces, el problema y la solución están completamente contenidos en ese contexto. Haces el cambio, ejecutas los tests de ese contexto específico, y tienes alta confianza de que no rompiste nada más porque la independencia entre contextos minimiza los efectos colaterales. La evolución del sistema se vuelve orgánica y natural. Una funcionalidad crítica del negocio crece en complejidad: agregas más validadores en su carpeta validator/, más enriquecedores en su carpeta enricher/, más utilidades en su carpeta util/. Otra funcionalidad permanece simple porque así lo requiere el negocio, con solo el caso de uso, un par de DTOs, y un mapper básico. No hay presión por mantener todo al mismo nivel de complejidad o estructura uniforme. Cada contexto crece según sus propias necesidades. El trabajo en equipo fluye mejor sin fricción constante. Múltiples desarrolladores trabajan simultáneamente en diferentes contextos—uno en registrar usuarios, otro en procesar pedidos, un tercero en consultar inventario—sin colisionar porque el código está físicamente separado. Los conflictos de merge que solían ser diarios ahora son raros. Las revisiones de código son más efectivas porque los cambios están claramente contenidos: puedes ver exactamente qué se modificó dentro de un contexto específico y entender su alcance sin necesitar conocimiento exhaustivo de todo el sistema. Y quizás lo más valioso: la confianza al hacer cambios. Cuando todo lo relacionado con una funcionalidad está junto y los contextos son genuinamente independientes, puedes modificar código con la confianza de que tus cambios no tendrán efectos colaterales sorpresa en funcionalidades no relacionadas. Los tests del contexto verifican que no rompiste esa funcionalidad específica, y la independencia entre contextos garantiza que no afectaste otras inadvertidamente.

El Principio de Duplicación Intencional

Pero hay un elefante en la habitación que necesitamos abordar directamente: verás código aparentemente duplicado. Y eso va a incomodarte. Dos contextos tendrán validadores que lucen similares. Tres contextos tendrán mappers que parecen hacer traducciones parecidas. Varios contextos tendrán utilidades que se ven redundantes. Tu instinto—entrenado por años de escuchar "Don't Repeat Yourself"—gritará que esto está mal, que debes extraer, generalizar, compartir. Necesitas resistir ese impulso porque está basado en una falsa equivalencia entre similitud y identidad. Dos validadores que hoy lucen idénticos no son el mismo concepto. Uno valida emails en el contexto de registrar usuarios, donde quizás solo verificas el formato básico. Otro valida emails en el contexto de enviar campañas de marketing, donde quizás verificas que el dominio no esté en una lista de bloqueo, que el usuario haya dado consentimiento, que el email haya sido verificado previamente. Parecen el mismo código hoy, pero representan reglas de negocio de contextos diferentes que inevitablemente divergirán mañana. Si hubieras compartido ese validador "para no duplicar código", cuando uno de los contextos necesite evolucionar—y lo necesitará—enfrentarás una decisión imposible. O modificas el validador compartido y arriesgas romper todos los contextos que lo usan, o agregas condicionales que verifican desde qué contexto se está llamando (acoplamiento horrible), o terminas duplicando el código de todas formas cuando la presión del deadline no te deja tiempo para refactorizaciones elegantes. La duplicación intencional es el precio que pagas por la independencia. Y resulta ser un precio extraordinariamente bajo comparado con el costo del acoplamiento que crearías compartiendo componentes prematuramente. Esto no significa nunca compartir nada. Significa compartir solo lo que tiene una razón de negocio genuina para ser compartido. Un modelo de dominio como Usuario que representa el mismo concepto fundamental a través de múltiples contextos merece vivir en domain/model/usuario/ como elemento transversal. Un servicio de dominio con lógica compleja de cálculo de precios que múltiples casos de uso invocan justifica su existencia en domain/service/calculo-precios/. Pero un validador que casualmente verifica el mismo formato en dos contextos diferentes no necesita ser compartido solo porque el código se ve similar. La guía es simple: extrae como transversal solo cuando hay identidad conceptual de negocio, no cuando hay mera similitud técnica superficial. Y cuando dudes, prefiere duplicar. Es más fácil extraer código duplicado después cuando verdaderamente lo necesitas que desenredar dependencias compartidas cuando los contextos necesitan divergir.

Cómo Convive con las Herramientas de Scaffolding

La pregunta práctica que surge inmediatamente es: si Scaffolding of Clean Architecture genera código en ubicaciones genéricas basadas en naturaleza técnica, ¿cómo logras esta organización por contextos? La respuesta es un flujo de trabajo disciplinado que combina generación automática con reorganización consciente. Cuando necesitas crear un caso de uso, ejecutas el comando de scaffolding que lo genera en domain/usecase/ en una estructura base genérica. Inmediatamente después, antes de escribir una línea de lógica, creas manualmente la carpeta de contexto domain/usecase/nombre-funcionalidad/ y mueves el archivo generado ahí. Creas las subcarpetas que ese caso de uso específico necesitará: dto/, mapper/, validator/, etc. Cuando generas un entry point REST, el scaffolding lo crea en infrastructure/entry-points/api-rest/ en ubicación genérica. De inmediato creas la carpeta de contexto api-rest/nombre-funcionalidad-api/ y reorganizas. Cuando generas un adaptador de persistencia, se crea en infrastructure/driven-adapters/jpa-repository/ genéricamente. Creas jpa-repository/contexto-persistencia/ y contextualizas. El scaffolding proporciona el esqueleto técnico correcto en el módulo correcto con la estructura base apropiada. Tú proporcionas la organización conceptual que refleja el negocio. Es trabajo adicional, sí, pero es trabajo que pagas una vez y recuperas mil veces cada vez que necesitas encontrar, entender, o modificar código. Esta reorganización no puede ser opcional ni algo que "haremos cuando tengamos tiempo". Debe ser parte no negociable del proceso de desarrollo desde el día uno. Cada componente generado se contextualiza inmediatamente antes de comenzar a escribir su lógica. Las revisiones de código verifican no solo que el código funciona sino que está correctamente organizado en su contexto apropiado. La disciplina es crucial porque es fácil tomar atajos bajo presión. "Solo por esta vez dejaré el código donde el scaffolding lo generó, no tengo tiempo de reorganizar ahora." Pero esos atajos se acumulan. La estructura se vuelve inconsistente—algunos componentes contextualizados, otros dispersos genéricamente—y gradualmente pierdes todos los beneficios. Es como mantener limpia una cocina: si lavas los platos después de cada comida es fácil, si los dejas acumular se vuelve insoportable.

Maximizando los Beneficios: Desarrollo Outside-In

Con la estructura clara y el proceso de reorganización establecido, hay una práctica que potencia enormemente los beneficios de esta organización por contextos: el desarrollo outside-in. No es obligatorio seguir este enfoque, pero resulta extraordinariamente efectivo para avanzar con la seguridad de que cada paso está correctamente implementado antes de pasar al siguiente. Esta afirmación se entiende mejor al contrastarla con los inconvenientes de la forma tradicional de iniciar el desarrollo. En la forma tradicional normalmente se comienza desde el dominio y se trabaja hacia afuera. Esto implica que no puedes validar realmente que algo funciona hasta que todas las capas están implementadas. Pasas días o semanas escribiendo código sin poder ejecutar nada end-to-end, descubriendo problemas de integración solo al final cuando son más caros de resolver. El enfoque que mejor aprovecha esta estructura es el opuesto: comenzar desde el punto de entrada y avanzar hacia adentro, validando cada capa inmediatamente después de crearla.

Empiezas con el entry point. Si la funcionalidad se expondrá vía REST, generas el controlador con scaffolding, lo reorganizas en su contexto api-rest/crear-pedido-api/, creas sus DTOs de request y response, y haces que devuelva datos inventados pero con la estructura correcta. Levantas la aplicación. Haces una petición HTTP real. El endpoint responde en menos de treinta minutos desde que comenzaste. Son datos falsos, pero el contrato de la API está validado y tienes algo tangible que puedes mostrar. Ahora creas el caso de uso. Generas con scaffolding, reorganizas en domain/usecase/crear-pedido/, creas sus DTOs—diferentes de los de la API—y lo haces devolver también datos simulados. Creas los mapeadores en api-rest/crear-pedido-api/mapper/ que traducen entre DTOs de API y DTOs de caso de uso. Inyectas el caso de uso en el controlador y conectas el flujo. Levantas la aplicación nuevamente. Haces una petición. Los datos fluyen: API recibe → mapea a lenguaje de dominio → caso de uso procesa → mapea a lenguaje de API → responde. Todo funciona. Siguen siendo datos simulados, pero la arquitectura de comunicación entre capas está validada. Has probado que las abstracciones encajan correctamente. Continúas capa por capa. Si el caso de uso necesita un modelo transversal que no existe, lo creas en domain/model/pedido/ con su gateway. Si necesita lógica reutilizable, creas el servicio en domain/service/calculo-descuentos/. Cada uno inicialmente con lógica simplificada o simulada. Implementas el adaptador de persistencia. Generas con scaffolding, organizas en jpa-repository/pedido-persistencia/ con sus entidades JPA, repositorios, implementación del gateway, mapeadores. Lo pruebas de forma aislada con tests de integración contra base de datos de prueba. Solo cuando funciona correctamente lo conectas al caso de uso. Haces una petición end-to-end y por primera vez los datos realmente se persisten y recuperan. Agregas validadores al caso de uso, uno a la vez, en domain/usecase/crear-pedido/validator/. Pruebas que rechazan correctamente datos inválidos. Agregas enriquecedores en enricher/ que complementan información. Implementas clientes para servicios externos, cada uno en su contexto en rest-consumer/servicio-inventario/. En cada paso tienes algo funcional que puedes probar. Este flujo outside-in con retroalimentación temprana transforma el desarrollo. Nunca estás más de un paso alejado de algo que funciona. Los problemas de integración se descubren tempranamente cuando son fáciles de resolver. Siempre tienes una versión funcional—aunque incompleta—en lugar de un sistema completo que no funciona hasta el final. Y la presión psicológica desaparece porque constantemente ves progreso tangible.

Con la estructura clara y el proceso de reorganización establecido, hay una práctica que potencia enormemente los beneficios de esta organización por contextos: el desarrollo outside-in. No es obligatorio seguir este enfoque, pero resulta extraordinariamente efectivo para avanzar con la seguridad de que cada paso está correctamente implementado antes de pasar al siguiente. Esta afirmación se entiende mejor al contrastarla con los inconvenientes de la forma tradicional de iniciar el desarrollo. En la forma tradicional normalmente se comienza desde el dominio y se trabaja hacia afuera. Esto implica que no puedes validar realmente que algo funciona hasta que todas las capas están implementadas. Pasas días o semanas escribiendo código sin poder ejecutar nada end-to-end, descubriendo problemas de integración solo al final cuando son más caros de resolver. El enfoque que mejor aprovecha esta estructura es el opuesto: comenzar desde el punto de entrada y avanzar hacia adentro, validando cada capa inmediatamente después de crearla.

Con la estructura clara y el proceso de reorganización establecido, hay una práctica que potencia enormemente los beneficios de esta organización por contextos: el desarrollo outside-in. No es obligatorio seguir este enfoque, pero resulta extraordinariamente efectivo para avanzar con la seguridad de que cada paso está correctamente implementado antes de pasar al siguiente. Esta afirmación se entiende mejor al contrastarla con los inconvenientes de la forma tradicional de iniciar el desarrollo. En la forma tradicional normalmente se comienza desde el dominio y se trabaja hacia afuera. Esto implica que no puedes validar realmente que algo funciona hasta que todas las capas están implementadas. Pasas días o semanas escribiendo código sin poder ejecutar nada end-to-end, descubriendo problemas de integración solo al final cuando son más caros de resolver. El enfoque que mejor aprovecha esta estructura es el opuesto: comenzar desde el punto de entrada y avanzar hacia adentro, validando cada capa inmediatamente después de crearla.

Las Incomodidades Reales

Seamos honestos sobre los desafíos porque existen y necesitas conocerlos antes de adoptar esta aproximación. La disciplina de reorganización después de cada generación de scaffolding es real y constante. Bajo presión de deadlines, saltarse este paso es tentador. "Lo reorganizaré después" se convierte en "nunca". La solución no es intentar automatizar la reorganización—requiere juicio humano sobre qué constituye un contexto apropiado—sino hacer de la reorganización una parte no negociable del proceso. La definición de "done" incluye código correctamente contextualizado. Las revisiones de código lo verifican. Los desarrolladores nuevos son entrenados en esto desde el día uno. Las estructuras de carpetas serán más profundas. Más niveles de anidamiento que en estructuras tradicionales. Inicialmente esto se siente lento y confuso. Los IDEs modernos ayudan significativamente con búsquedas rápidas y navegación inteligente, pero aún así hay un período de adaptación de algunas semanas. Después, la mayoría de desarrolladores encuentra que localizar código es más rápido porque saben exactamente dónde buscar: todo lo relacionado con una funcionalidad está en su contexto. Decidir qué extraer como transversal y qué mantener en contextos requiere experiencia y juicio. No hay reglas absolutas que puedas seguir mecánicamente. Un modelo de dominio usado extensamente claramente debe ser transversal. Un servicio con lógica compleja reutilizable justifica extracción. Pero un mapper usado por un solo caso de uso debe permanecer en ese contexto. Esta decisión requiere práctica, y a veces te equivocarás y necesitarás refactorizar. Eso es normal y esperado. El tamaño del código base crecerá más que en aproximaciones tradicionales debido a la duplicación intencional. Esto puede parecer problemático especialmente en equipos acostumbrados a optimizar por menos líneas de código. Pero la métrica relevante no es el tamaño absoluto sino la mantenibilidad y comprensibilidad. Un código base más grande pero bien organizado, donde cada pieza tiene su lugar claro, es infinitamente más fácil de mantener que un código base más pequeño con componentes compartidos complejos y dependencias cruzadas que hacen imposible entender el impacto de los cambios.

Haciendo la Transición en Tu Equipo

Si esto resuena contigo y quieres adoptarlo, la transición requiere más que cambiar la estructura de carpetas. Comienza solo con código nuevo. Intentar refactorizar todo un código base existente de una vez es una receta para el fracasgo: demasiado costo, demasiado riesgo, demasiada resistencia del equipo. Aplica la filosofía a nuevas funcionalidades que implementes desde cero. Refactoriza código existente solo cuando ese código necesita modificaciones significativas de todas formas—entonces aprovechar para reorganizarlo en contextos apropiados es inversión que ya estás haciendo. Esta adopción gradual permite que el equipo aprenda sin el trauma de una reescritura masiva. Por algunos meses convivirán dos estilos: código viejo en estructura tradicional, código nuevo en contextos. Está bien. Eventualmente, a medida que el código viejo se modifica, se va reorganizando. En un año, la mayoría del código activo estará contextualizado. Invierte en documentación viva con ejemplos concretos de tu código base real. Abstracciones teóricas sobre "contextos autocontenidos" no funcionan tan bien como mostrar "mira, así organizamos el caso de uso de procesar pedidos, aquí están todos sus elementos, esta es la razón por la que cada uno está donde está". Cuando los desarrolladores pueden ver ejemplos reales del propio proyecto, la comprensión es inmediata. Las sesiones de pair programming donde desarrolladores experimentados en la filosofía trabajan con nuevos miembros aplicándola en práctica valen más que cualquier documento. Ver cómo alguien genera código con scaffolding y luego inmediatamente lo reorganiza, cómo decide qué subcarpetas crear, cómo identifica qué debe ser transversal versus específico del contexto—eso se aprende haciendo, no leyendo. Las revisiones de código son críticas para mantener integridad arquitectónica. Verifica que el código está en el contexto correcto, que sigue principios de autocontención, que no está creando acoplamiento innecesario. Esta verificación debe tener el mismo peso que verificar corrección funcional. Si el código funciona pero está mal organizado, solicitar cambios no es pedantería—es proteger la mantenibilidad a largo plazo del sistema. Y mantén flexibilidad dentro del marco. No todo contexto necesita la misma estructura. Un caso de uso simple no necesita todas las subcarpetas que uno complejo requiere. Lo importante son los principios—autocontención, cohesión conceptual, independencia—no seguir rígidamente una plantilla.

Performance: La Pregunta que Todos Hacen

Eventualmente alguien preguntará: "¿Toda esta separación y múltiples traducciones entre DTOs no tiene costo de performance prohibitivo?" La respuesta pragmática: en la vasta mayoría de aplicaciones empresariales, no. El costo de mapear entre DTOs de API, DTOs de caso de uso, entidades de dominio, y entidades JPA se mide en microsegundos. Las operaciones que realmente importan—queries a base de datos, llamadas HTTP a servicios externos, procesamiento de lógica de negocio compleja—se miden en milisegundos o más. Los mapeos son ruido estadístico en comparación. Cuando la performance es genuinamente crítica—procesamiento batch de millones de registros, sistemas de alta frecuencia, servicios con SLAs de latencia extremos—la arquitectura no lo prohíbe. Un caso de uso puede saltarse algunos mapeos, trabajando más directamente con representaciones de niveles inferiores si es necesario. La clave es que esto sea una decisión consciente, documentada, y justificada por mediciones reales de performance bajo carga real, no por optimización prematura basada en suposiciones. Las optimizaciones del compilador Java y la JVM también ayudan enormemente. El inlining de métodos pequeños significa que muchos mapeos que parecen caros en el código fuente son esencialmente gratuitos en el bytecode optimizado. La eliminación de código muerto elimina paths que nunca se ejecutan. El profile-guided optimization del JIT compiler optimiza los caminos que realmente se usan frecuentemente. La guía es clara: construye con la arquitectura limpia por defecto. Mide cuando tengas dudas reales. Optimiza solo donde las mediciones bajo carga real muestren necesidad. La claridad arquitectónica facilita la optimización cuando es necesaria porque es trivial identificar dónde está el cuello de botella—está en un contexto específico—y modificar solo esa parte sin afectar el resto.

El Impacto en la Cultura del Equipo

Más allá de la estructura de carpetas, esta filosofía cambia cómo los equipos trabajan y colaboran. El ownership del código se vuelve natural y claro. Cuando todo lo relacionado con una funcionalidad está en un contexto específico, es fácil asignar ownership de ese contexto a alguien. No significa que solo esa persona puede tocarlo—eso crearía silos de conocimiento—pero hay alguien responsable de su calidad, coherencia, y evolución. Cuando surge una pregunta sobre esa funcionalidad, hay un punto de contacto claro. Cuando necesita evolucionar, hay alguien que entiende su contexto completo. La planificación de sprints se simplifica porque las historias de usuario frecuentemente se mapean directamente a casos de uso, y los casos de uso son contextos autocontenidos. Estimar el esfuerzo se vuelve más predecible: implementar un caso de uso significa crear su contexto con los elementos que necesita. La variabilidad viene de cuántos y qué tipo de elementos específicos requiere—validadores complejos versus simples, múltiples enriquecedores versus ninguno—pero el patrón general es consistente. Las estimaciones mejoran porque hay menos incertidumbre sobre alcance y dependencias. La colaboración cambia de naturaleza. En lugar de conflictos constantes por múltiples personas modificando los mismos archivos compartidos, diferentes desarrolladores trabajan en diferentes contextos con mínima interferencia. Cuando necesitan coordinación, típicamente es a través de interfaces bien definidas—un caso de uso invocando un servicio de dominio, un entry point usando un caso de uso—no modificando los mismos archivos internos simultáneamente. El testing se vuelve más natural. Cada contexto puede probarse de forma aislada con sus dependencias mockeadas apropiadamente. Los tests unitarios se enfocan en lógica específica del contexto. Los tests de integración verifican que el contexto se comunica correctamente con sus dependencias reales. Los tests end-to-end verifican que el flujo completo funciona atravesando múltiples contextos. Esta separación hace que los tests sean más simples de escribir, más rápidos de ejecutar, y más fáciles de mantener porque el alcance de cada nivel de testing es claro. La rotación de personas—tanto salidas como nuevas incorporaciones—se maneja mejor. El conocimiento no está uniformemente distribuido por un código base monolítico donde entender cualquier parte requiere entender el todo. El conocimiento está organizado por contextos. Un desarrollador saliente puede documentar y traspasar los contextos de los que tenía ownership específico. Un desarrollador entrante puede comenzar tomando ownership de contextos particulares, aprendiendo el sistema incrementalmente en lugar de necesitar una descarga masiva de conocimiento de todo desde el día uno.

Evolución y Futuro

Esta filosofía híbrida no es un destino final sino un punto en la evolución continua de cómo organizamos código complejo. Las herramientas seguirán mejorando. Los IDEs se volverán más inteligentes en entender y navegar estructuras modulares complejas. Las herramientas de scaffolding podrían eventualmente aprender a generar código ya organizado por contextos, preguntando al desarrollador a qué contexto de negocio pertenece el componente antes de generarlo. La generación de código asistida por IA podría entender patrones arquitectónicos como esta filosofía de contextos y generar código que automáticamente se organiza correctamente, reduciendo la carga de disciplina manual. Las herramientas de análisis estático podrían detectar violaciones de la organización por contextos, identificando cuando un contexto accede directamente a detalles internos de otro o cuando la estructura se está volviendo inconsistente. A medida que más sistemas evolucionan hacia arquitecturas distribuidas, la clara separación de contextos se vuelve aún más valiosa. Los bounded contexts bien definidos facilitan decisiones sobre qué debe desplegarse junto y qué podría beneficiarse de despliegue independiente como microservicios. Los módulos Gradle proporcionan las fronteras naturales para estas decisiones, y la organización por contextos asegura que cada unidad desplegable sea cohesiva y completa. Pero más allá de las herramientas futuras, los principios permanecen: autocontención facilita comprensión, cohesión conceptual facilita mantenimiento, independencia entre contextos facilita evolución. Estos principios son atemporales incluso si los detalles de implementación evolucionan con nuevas tecnologías.

Casos Reales y Lecciones Aprendidas

En equipos que han adoptado esta aproximación, ciertos patrones emergen consistentemente. La transición inicial típicamente toma entre cuatro y ocho semanas. Las primeras dos semanas son de confusión y resistencia—"esto parece más complicado", "por qué estamos duplicando código", "no entiendo dónde poner las cosas". Las siguientes dos a cuatro semanas son de adaptación—el músculo de reorganizar después de scaffolding se desarrolla, las decisiones sobre qué contextualizar versus qué extraer se vuelven más naturales. Después de seis a ocho semanas, la mayoría de desarrolladores reporta que encontrar y modificar código se siente significativamente más fácil que antes. El momento "ajá" típicamente llega cuando un desarrollador necesita modificar una funcionalidad que implementó semanas antes. Abre el contexto esperando tener que buscar piezas dispersas por todo el proyecto, y descubre sorprendido que todo está ahí. "Oh, esto realmente funciona." Los equipos exitosos típicamente desarrollan sus propias convenciones específicas sobre nombrado de contextos, cuándo crear subcarpetas adicionales, cómo documentar decisiones de diseño dentro de contextos. Estas convenciones locales complementan los principios generales, adaptando la filosofía a las necesidades específicas del dominio y la cultura del equipo. Un error común es intentar que todos los contextos tengan exactamente la misma estructura. Un caso de uso complejo puede tener ocho subcarpetas diferentes. Uno simple puede tener solo tres. Ambos están bien. La estructura sirve a la funcionalidad, no al revés. Forzar uniformidad rígida crea carpetas vacías o artificialmente pobladas que no agregan valor. Otro error es ser demasiado conservador con la duplicación, intentando extraer cualquier similitud mínima. Esto recrea el problema original de componentes compartidos con dependencias complejas. La guía que funciona: cuando dudes si extraer, espera. Duplica inicialmente. Solo extrae cuando el tercer o cuarto contexto necesita exactamente lo mismo y tienes evidencia clara de que representa un concepto verdaderamente transversal del negocio, no solo similitud técnica superficial.

Relación con Otros Patrones

Esta filosofía no existe en vacío sino que complementa y se integra con otros patrones y prácticas establecidas. Domain-Driven Design proporciona el vocabulario para identificar y organizar contextos. Los bounded contexts de DDD se mapean naturalmente a agrupaciones de contextos en esta arquitectura. Las entidades, value objects, aggregates, y domain events de DDD encuentran su lugar en los contextos de modelo. Los servicios de dominio de DDD corresponden directamente a los servicios de dominio en esta estructura. CQRS puede aplicarse dentro de la organización por contextos. Los casos de uso que modifican estado (comandos) pueden organizarse claramente separados de los que solo leen (queries), permitiendo optimizaciones diferentes para cada tipo sin sacrificar claridad organizacional. Event Sourcing se integra naturalmente. Los domain events que las entidades generan pueden persistirse como event stream. Los adaptadores de persistencia implementan event stores. Los casos de uso publican eventos que otros contextos consumen, manteniendo independencia entre bounded contexts mientras permiten coordinación. La relación con Microservicios es interesante. Cada bounded context con sus casos de uso, servicios, y adaptadores podría potencialmente extraerse como microservicio independiente. Los módulos Gradle proporcionan fronteras naturales para esta extracción. Los gateways que actualmente se implementan con adaptadores locales podrían reemplazarse con adaptadores que hacen llamadas remotas. La organización por contextos facilita esta evolución porque las dependencias entre contextos son explícitas a través de gateways, haciendo visible el acoplamiento que necesitaría convertirse en comunicación remota.

El Verdadero Valor

Al final, todo esto se reduce a una verdad simple: la arquitectura de software existe para facilitar resolver problemas de negocio de manera efectiva y sostenible en el tiempo. Una buena arquitectura es aquella que permite a los desarrolladores entender rápidamente qué hace el código, hacer cambios con confianza, y evolucionar el sistema según las necesidades del negocio cambian. No es la que se ve más elegante en un diagrama. No es la que usa las tecnologías más nuevas. No es la que tiene menos líneas de código. Es la que funciona para el equipo que la mantiene y el negocio que la necesita. Esta filosofía híbrida de contextos dentro de módulos técnicos busca precisamente eso. No promete eliminar toda complejidad—la complejidad es inherente a sistemas empresariales que resuelven problemas complejos—pero promete organizarla de manera que sea manejable y comprensible. Promete que cuando necesites modificar algo, sabrás dónde buscar porque todo lo relacionado está junto. Promete que tus cambios estarán contenidos y sus efectos predecibles porque los contextos son independientes. Promete que nuevos desarrolladores pueden comenzar a contribuir sin necesitar entender todo el sistema porque pueden tomar ownership de contextos específicos. No es la única manera de organizar código, y no será la mejor para todos los proyectos y equipos. Pero para equipos que trabajan con herramientas de scaffolding que generan estructura modular, que construyen aplicaciones empresariales complejas donde el código vive y evoluciona durante años, y que valoran tanto la disciplina arquitectónica como la productividad práctica, ofrece un balance probado entre estructura y pragmatismo. La adopción requiere más que cambiar carpetas. Requiere cambiar cómo piensas sobre organización de código. Requiere disposición a cuestionar dogmas como "nunca duplicar código" y reconocer que la duplicación intencional es frecuentemente mejor que el acoplamiento prematuro. Requiere disciplina para mantener integridad arquitectónica incluso bajo presión. Requiere inversión en documentación, entrenamiento, y procesos de revisión que refuercen los principios. Pero para equipos dispuestos a hacer esa inversión, los retornos son reales y duraderos. Código que seis meses después todavía puedes entender rápidamente. Cambios que implementas con confianza sabiendo que no romperás cosas no relacionadas. Sistemas que crecen en funcionalidad sin colapsar bajo su propio peso. En un mundo donde el software exitoso inevitablemente crece en complejidad, eso no es poca cosa. Así que la próxima vez que abras un proyecto y necesites modificar cómo se procesa un pedido, no pasarás treinta minutos buscando piezas dispersas por toda la estructura. Abrirás domain/usecase/procesar-pedido/ y todo estará ahí. Esa es la promesa. Esa es la diferencia.

Hay una tensión que todo equipo de desarrollo enfrenta tarde o temprano: la necesidad de saber qué está pasando dentro del sistema sin que esa necesidad contamine el código que lo hace funcionar. Los logs son la herramienta más inmediata para satisfacer esa necesidad, pero también son, cuando no se gestionan con criterio, una de las fuentes más frecuentes de deuda técnica, acoplamiento silencioso y dolores de cabeza en producción.

Lo que se propone en este artículo es un modelo de observabilidad para sistemas construidos con Java 21, Spring Boot 3.5.x, Gradle y arquitectura DDD. El objetivo no es solo definir dónde va cada logger.info(), sino construir un esquema en el que la observabilidad sea una preocupación transversal completamente separada de la lógica de negocio, implementada mediante Programación Orientada a Aspectos (AOP) y sostenida por convenciones que cualquier miembro del equipo pueda seguir sin ambigüedad.

El problema que queremos resolver

Antes de hablar de la solución vale la pena entender con precisión el problema. En la mayoría de los proyectos, los logs nacen de forma orgánica: el desarrollador que escribe un caso de uso añade un par de líneas de debug para entender qué está pasando durante el desarrollo, y esas líneas se quedan ahí. Llega otro desarrollador, añade las suyas, y así sucesivamente. El resultado, algunos meses después, es un codebase donde la lógica de negocio está entrelazada con instrucciones de log que nadie revisa, que no siguen ningún formato consistente, que en algunos métodos son excesivas y en otros brillan por su ausencia, y que en más de una ocasión exponen datos sensibles de los usuarios en texto plano.

El problema no es que los desarrolladores sean descuidados. El problema es estructural: cuando la responsabilidad de loguear está distribuida en cada clase del sistema, es inevitable que el resultado sea inconsistente. La única forma de garantizar consistencia es centralizar esa responsabilidad en un mecanismo que opere de forma transversal, sin depender de que cada desarrollador recuerde seguir una convención.

Eso es, en esencia, lo que ofrece la Programación Orientada a Aspectos.

AOP: observar sin intervenir

La idea central de AOP es simple aunque su implementación puede ser sofisticada: existen preocupaciones en un sistema, como la seguridad, las transacciones o el logging, que no pertenecen a ningún módulo en particular pero que afectan a todos. En lugar de dispersar el código que gestiona esas preocupaciones por todo el sistema, AOP permite encapsularlo en un componente separado llamado aspecto, que el framework inyecta de forma transparente en los puntos de ejecución que se le indiquen.

En el contexto de Spring, esto funciona a través de proxies. Cuando el contenedor de inversión de control crea un bean, puede envolverlo en un proxy que intercepta las llamadas a sus métodos. Ese proxy ejecuta el aspecto antes, después o alrededor de la llamada real. El método original no sabe que está siendo observado; simplemente hace su trabajo.

Para que este mecanismo funcione hay una condición que no siempre es obvia: los objetos deben ser beans de Spring. Si una clase no está gestionada por el contenedor, Spring no puede envolverla en un proxy y el aspecto no puede interceptarla. Este detalle tiene una implicación directa en cómo se diseña la observabilidad en una arquitectura DDD, y es precisamente el punto de partida para resolver uno de los dilemas más frecuentes en este tipo de proyectos.

La capa de dominio y el dilema del logging

En una arquitectura DDD estricta, la capa de dominio es la más interna y la más pura. No debe tener dependencias de infraestructura, no debe saber si está siendo ejecutada en una API REST o en un job batch, y definitivamente no debería importar librerías de logging. Esta pureza es lo que la hace testeable, portable y mantenible.

Pero esa misma pureza genera una pregunta legítima: ¿qué pasa con los servicios de dominio? Un servicio que valida si un cliente tiene crédito suficiente, que aplica reglas de descuento, que verifica el stock disponible, ¿no merece ser observado? Si algo falla en esa lógica, ¿cómo sabremos qué ocurrió?

La respuesta convencional suele ser una de dos: o se acepta contaminar el dominio con un logger, o se ignora completamente ese nivel de detalle y se espera que las excepciones cuenten la historia. Ninguna de las dos opciones es satisfactoria.

La salida está en un detalle de implementación que a veces pasa desapercibido: cuando los servicios de dominio y los casos de uso se registran como beans en el contenedor de Spring a través de la capa de aplicación, aunque el dominio no sabe nada de Spring, el contenedor sí los gestiona. Y si el contenedor los gestiona, AOP puede interceptarlos. El dominio sigue siendo puro porque no tiene ninguna dependencia en infraestructura. El aspecto lo observa desde afuera, a través del proxy, sin que el servicio de dominio sea consciente de ello.

Este es uno de esos casos donde las restricciones de una arquitectura, entendidas a fondo, abren posibilidades que no eran evidentes a primera vista.

Una sola responsabilidad por capa

Con ese fundamento claro, los puntos de observabilidad se organizan siguiendo la misma lógica que organiza la arquitectura: cada capa tiene su propio contrato de logging.

Los entry points, que son los controladores REST o cualquier otro mecanismo de entrada al sistema, son el primer y último punto que el aspecto intercepta en el flujo de una solicitud. Aquí se registra el request entrante con los datos de entrada saneados y, cuando el flujo termina, el response saliente con el tiempo total que tomó la operación. Es la vista más amplia del sistema: saber qué llegó y qué salió.

Los casos de uso aportan el siguiente nivel de granularidad. El aspecto registra el inicio y el fin de la orquestación, con el DTO de entrada ya mapeado y el resultado antes de que sea transformado para la respuesta. Esto permite correlacionar exactamente qué datos entran al corazón del sistema y qué produce como resultado.

Los servicios de dominio representan el nivel más detallado. Aquí el aspecto registra el resultado de cada validación, cada regla de negocio, cada decisión que toma el dominio. Este nivel de detalle, sin embargo, no necesita estar activo permanentemente en producción. Se emite en nivel DEBUG, lo que significa que en un ambiente productivo es invisible pero puede activarse dinámicamente en cuestión de segundos si se necesita diagnosticar un problema sin reiniciar la aplicación.

Finalmente, los driven adapters, que son las implementaciones de los puertos hacia el mundo exterior, tienen un requerimiento adicional que los diferencia de todas las demás capas: la latencia. No basta con saber que se hizo una llamada a un servicio externo o que se ejecutó una consulta a la base de datos; hay que saber cuánto tardó. Esa información es la que permite distinguir entre un problema de lógica interna y un problema de dependencia externa, una diferencia que en producción puede significar horas de diagnóstico incorrecto.

El tiempo como dato de primera clase

Medir el tiempo solo en las llamadas externas es un primer paso, pero insuficiente. Para entender verdaderamente el comportamiento de un sistema bajo carga es necesario conocer cuánto tarda cada etapa del flujo. Un total de 800 milisegundos en una solicitud puede ser perfectamente aceptable o completamente inaceptable dependiendo de dónde se origina ese tiempo.

Por eso cada punto de observabilidad debe registrar dos métricas de tiempo: durationMs, que mide cuánto tardó esa etapa específica, y elapsedMs, que mide el tiempo acumulado desde que llegó la solicitud hasta ese punto. Con ambas métricas en cada registro, reconstruir la línea de tiempo de una transacción en una herramienta de observabilidad es trivial.

A esto se suma un campo stage en cada registro, que identifica la capa que lo generó: ENTRY_POINT, USE_CASE, DOMAIN_SERVICE, EXTERNAL_CALL o REPOSITORY. Este campo convierte los logs de texto plano en datos estructurados sobre los que se pueden construir dashboards, alertas y análisis de performance sin necesidad de parsear mensajes de texto.

El valor de este diseño se hace evidente con un ejemplo concreto. Imaginemos una solicitud de creación de orden de compra que tarda 800 milisegundos en total. Sin el campo stage y sin durationMs por etapa, la única conclusión disponible es que la solicitud fue lenta. Con esos campos, el análisis revela en segundos que 600 de esos 800 milisegundos los consumió la API externa de cobertura logística, mientras que la lógica de dominio tomó menos de 15 milisegundos. La optimización correcta es evidente: no hay que tocar el dominio, hay que atacar la dependencia externa.

Privacidad por diseño, no por convención

Uno de los aspectos más delicados del logging es la privacidad. Cada vez que un sistema registra información existe el riesgo de que datos sensibles terminen en un archivo de log, en una herramienta de indexación o en el radar de una auditoría de seguridad. La respuesta habitual a este riesgo es la convención: "no logueen datos personales". El problema con las convenciones es que dependen de que cada desarrollador las recuerde y las aplique correctamente en cada caso.

Un enfoque más robusto es que la privacidad se declare en el modelo de datos, no en el código que loguea.

Para materializar esto se definen dos anotaciones que se aplican directamente sobre los campos del modelo de dominio. La primera, @NoLog, indica que un campo nunca debe aparecer en ningún log bajo ninguna circunstancia: omisión total. Se usa para campos como imágenes en Base64, documentos adjuntos, o cualquier objeto cuyo tamaño o naturaleza lo hace inadecuado para un registro. La segunda, @Confidential, indica que el campo contiene datos personales y que su valor debe enmascararse antes de escribirse. El aspecto aplica una función de máscara según el tipo configurado: una dirección de correo como [email protected] se convierte en j***@mail.com, un número de identificación se convierte en ***, un teléfono muestra solo los últimos cuatro dígitos.

Lo elegante de este diseño es que las reglas de privacidad viven donde tienen sentido: en el modelo de dominio, junto a la definición del dato. Cuando un desarrollador crea un campo en un modelo y lo anota con @Confidential, esa anotación se respeta automáticamente en todos los logs del sistema, sin necesidad de recordar actualizar ningún otro componente. La privacidad deja de ser una convención y se convierte en una propiedad del dato.

Más allá de las anotaciones, hay categorías de información que nunca deben aparecer en logs independientemente de si están anotadas: credenciales, tokens de autenticación, datos completos de tarjetas de crédito, cookies de sesión, datos biométricos. La regla práctica que sintetiza todos estos casos es directa: si el dato permite suplantar la identidad de un usuario o acceder a un sistema, no va en el log.

Trazabilidad: el hilo que conecta todo

Un log aislado tiene valor limitado. El valor real emerge cuando se pueden correlacionar todos los eventos de una transacción, desde que llega la solicitud hasta que sale la respuesta, incluyendo cada llamada externa y cada decisión de dominio que ocurrió en el camino.

El mecanismo que hace posible esta correlación es el message-id, un identificador único que se asigna a cada solicitud en el momento en que entra al sistema. Si el cliente lo envía en el header X-Message-Id, se reutiliza; si no viene, el sistema genera uno automáticamente. Este identificador se almacena en el MDC de SLF4J, que es un mapa de contexto asociado al hilo de ejecución. Todos los logs emitidos durante esa solicitud lo incluyen automáticamente.

El resultado es que en cualquier herramienta de observabilidad, filtrar por message-id produce exactamente la secuencia completa de eventos de una transacción, ordenada por tiempo, con cada etapa identificada por su stage y con sus métricas de duración. Lo que antes requería correlacionar manualmente decenas de líneas de log dispersas ahora es una consulta de una sola condición.

Este mecanismo presenta un desafío particular en operaciones asíncronas. Cuando Spring lanza un hilo para ejecutar una tarea marcada con @Async, ese hilo nuevo no hereda el MDC del hilo padre. El message-id y el tiempo de inicio de la solicitud se pierden, y los logs del hilo asíncrono quedan huérfanos sin correlación. La solución es un decorador de tareas que captura el MDC completo del hilo padre en el momento en que se lanza la tarea y lo restaura en el hilo hijo antes de ejecutarla. Este decorador se configura una sola vez en el executor del pool de hilos y aplica a todas las operaciones asíncronas del sistema sin ningún esfuerzo adicional por parte del desarrollador.

El mismo principio se extiende a arquitecturas de microservicios. Cuando el sistema hace una llamada HTTP a otro servicio, el message-id debe viajar en el header de la petición saliente. El microservicio receptor lo extrae, lo almacena en su propio MDC, y todos sus logs quedan correlacionados con la misma transacción origen. Esto se configura una sola vez en el cliente HTTP como un interceptor, y a partir de ahí todas las llamadas salientes propagan el identificador automáticamente. En una plataforma de observabilidad centralizada, una sola búsqueda por message-id puede reconstruir el árbol completo de llamadas entre servicios.

El flujo completo bajo la lupa

Para ilustrar cómo se manifiesta todo esto en la práctica, vale la pena recorrer un flujo real. Tomemos la creación de una orden de compra como caso de uso: el cliente envía los datos de la orden con sus productos, dirección de entrega e información personal; el sistema valida que el cliente esté activo, verifica el stock, homologa los códigos externos de los productos a los códigos internos del catálogo, consulta una API externa para validar la cobertura logística en la dirección indicada, persiste la orden en base de datos y devuelve el número de orden generado.

Sin escribir una sola línea de log en ninguno de esos componentes, el aspecto genera automáticamente doce registros a lo largo del flujo. El primero captura el request entrante con los datos saneados: el correo del cliente enmascarado, el número de identificación reemplazado por asteriscos, los documentos adjuntos simplemente omitidos. El segundo marca el inicio del caso de uso. Los registros tres, cuatro y cinco corresponden a los servicios de dominio: la validación del cliente, la validación de stock y la homologación de productos; estos se emiten en DEBUG y son invisibles en producción a menos que se activen dinámicamente. Los registros siete y ocho capturan la llamada a la API de cobertura logística con su latencia exacta. Los registros nueve y diez hacen lo mismo con la operación de base de datos. El registro once cierra el caso de uso con el tiempo total de orquestación. El doce emite el response saliente con el tiempo total de la solicitud de punta a punta.

El análisis de esos doce registros revela de inmediato la distribución del tiempo: cuatro milisegundos de overhead en los mappers de entrada, diez milisegundos en validaciones de dominio, doscientos diez milisegundos en la API de cobertura logística, cuarenta y cinco milisegundos en base de datos. Sin ningún profiler, sin instrumentación adicional, el sistema cuenta su propia historia con precisión quirúrgica.

El mismo flujo en un escenario de error muestra otra dimensión del diseño. Si el stock es insuficiente, el servicio de dominio lanza una excepción de negocio controlada. El aspecto la captura a nivel DEBUG en el servicio de dominio y la deja subir. El @ControllerAdvice la intercepta y emite un registro en nivel WARN, no ERROR, porque una validación fallida es una condición esperada del negocio, no un fallo del sistema. Sin stacktrace completo, solo el mensaje de negocio y el message-id. En cambio, si la API externa de cobertura logística devuelve un timeout, el adapter emite un registro en nivel ERROR con stacktrace completo y la latencia exacta que revela los cinco segundos de espera antes del fallo.

Esta distinción entre WARN y ERROR no es cosmética. En los dashboards de monitoreo permite separar el ruido normal del negocio de los fallos reales que requieren atención inmediata. Un equipo de operaciones que recibe alertas solo para registros ERROR puede confiar en que cada alerta representa un problema genuino del sistema, no una validación fallida que el usuario debe corregir.

Producción sin sorpresas

Hay un escenario que todo sistema productivo enfrenta eventualmente: un comportamiento anómalo que no se reproduce en desarrollo y que requiere ver el detalle de la lógica interna para diagnosticarse. En el modelo tradicional, la respuesta a este escenario era subir el nivel de log a DEBUG, redesplegar, esperar, bajar el nivel, redesplegar de nuevo. Un proceso lento, arriesgado y que en sistemas con tráfico real puede generar un volumen de logs suficiente para saturar la infraestructura de observabilidad.

Dos mecanismos complementarios evitan ese ciclo. El primero es la jerarquía de niveles ya descrita: los logs de DOMAIN_SERVICE se emiten en DEBUG, así que en producción con nivel INFO son completamente invisibles y no generan ningún costo operativo. El segundo es el cambio dinámico de nivel a través de un endpoint interno que delega en la API de loggers de Spring Boot Actuator. Activar DEBUG para un paquete específico, observar el comportamiento, y volver a INFO es una operación de segundos sin ningún redespliegue.

Este diseño refleja una filosofía más amplia: las herramientas de observabilidad deben poder adaptarse al momento sin modificar el sistema observado.

Lo que también importa, aunque no se vea en el código

Hay una dimensión del logging que no suele documentarse pero que es igualmente crítica: saber qué no loguear. Las anotaciones @NoLog y @Confidential cubren los datos que el modelo declara explícitamente como sensibles, pero hay categorías de información que nunca deben aparecer en logs independientemente de cualquier anotación.

Los tokens de autenticación son el ejemplo más obvio. Un JWT completo, una API key o un refresh token en un log es esencialmente una credencial expuesta que puede ser extraída por cualquiera con acceso a la plataforma de observabilidad, que en muchas organizaciones incluye a un número considerable de personas. Lo mismo aplica para contraseñas, PINs, datos completos de tarjetas de crédito, cookies de sesión y datos biométricos.

La lista no es exhaustiva ni puede serlo, porque los datos sensibles dependen del contexto de cada sistema. Lo que sí puede establecerse como hábito es hacerse la pregunta antes de que un dato llegue a un registro. Y en la duda, la respuesta correcta es siempre la omisión.

De los logs a la inteligencia operacional

Un sistema de logs bien diseñado no es solo un mecanismo de diagnóstico reactivo. Es la materia prima de la inteligencia operacional. Los campos estructurados que este esquema produce, stage, durationMs, elapsedMs, event, adapter, permiten derivar métricas sin instrumentación adicional en el código.

La latencia promedio por adapter externo permite monitorear el SLA de cada dependencia. La tasa de registros con event=BUSINESS_EXCEPTION agrupada por tipo de excepción permite entender qué reglas de negocio fallan con más frecuencia y orientar decisiones de producto. El tiempo total por endpoint permite construir alertas que disparen cuando la latencia supera el percentil 99 histórico. La correlación entre EXTERNAL_CALL_START sin su correspondiente EXTERNAL_CALL_END permite detectar llamadas que nunca respondieron.

Y quizás el beneficio más silencioso de todos: cada nueva funcionalidad que se añada al sistema hereda automáticamente la observabilidad con el mismo nivel de detalle y el mismo formato estructurado, simplemente por seguir la arquitectura. No hay nada que recordar, nada que configurar, nada que pueda olvidarse.

Mirando hacia adelante

Lo descrito en este artículo establece una base sólida, pero no es un punto de llegada. Hay líneas de evolución naturales que vale la pena tener en el horizonte.

La integración con sistemas de tracing distribuido como OpenTelemetry lleva la correlación entre microservicios un paso más allá, al construir árboles de spans que representan visualmente la jerarquía de llamadas, con tiempos y metadatos, en una interfaz diseñada específicamente para ese propósito. Los logs estructurados que produce este esquema son compatibles con ese modelo y pueden complementarlo sin contradicción.

La generación automática de métricas de aplicación a través de Micrometer desde los mismos puntos de intercepción del AOP es otra extensión natural, ya que evita la duplicación entre el sistema de logs y el sistema de métricas, manteniendo una única fuente de verdad para ambos tipos de datos.

El mismo patrón de aspectos transversales también puede extenderse a otros dominios de preocupación: auditoría de cambios de estado, registro de accesos a datos sensibles para cumplimiento regulatorio, o validación automática de contratos entre capas.

Lo que todo esto ilustra, más allá de los detalles técnicos, es que la observabilidad no tiene por qué ser un ciudadano de segunda clase en la arquitectura de un sistema. Cuando se diseña con la misma intención que se diseña la lógica de negocio, cuando se le aplican los mismos principios de separación de responsabilidades y consistencia, se convierte en una ventaja operacional genuina: el equipo gana la capacidad de entender qué está pasando en producción en cualquier momento, con el nivel de detalle que necesita, sin adivinar y sin contaminar el código que hace que el sistema funcione.

La implementación concreta de este diseño, con el código de cada artefacto, los aspectos completos, el sanitizador de datos y el ejemplo funcional del flujo de orden de compra, se documenta en detalle en la segunda parte de este artículo.

PARTE I: PRINCIPIOS Y NORMATIVA

1. Fundamentos de Consistencia Eventual

Debido a la naturaleza distribuida del sistema, se abandona el modelo ACID tradicional (Atomicidad inmediata con bloqueos) en favor del modelo BASE (Basically Available, Soft state, Eventually consistent).

Implicaciones arquitectónicas:

• Los datos pueden estar temporalmente inconsistentes entre servicios
• La consistencia se alcanza mediante propagación de eventos y compensaciones
• Cada servicio mantiene su propia fuente de verdad (base de datos)
• No existen transacciones atómicas que abarquen múltiples servicios

Garantías del sistema:

• Disponibilidad: Los servicios responden incluso si otros están caídos
• Durabilidad: Los eventos se persisten antes de considerarse publicados
• Convergencia: El sistema eventualmente alcanzará un estado consistente

2. Patrones Permitidos

2.1 Patrón Primario: Saga basada en Coreografía

Los servicios participantes reaccionan a eventos de dominio de manera autónoma sin conocer el flujo completo de la transacción distribuida. Cada servicio:

• Escucha eventos relevantes de su dominio
• Ejecuta su lógica de negocio local
• Publica eventos de resultado
• No tiene conocimiento de qué otros servicios participan en el proceso

Ventajas: Bajo acoplamiento, alta escalabilidad, sin punto único de fallo.

Desventajas: Flujo implícito, difícil depuración, complejidad en el rastreo.

2.2 Patrón Complementario: Orquestación Ligera de Estado

Se permite que UN servicio actúe como Coordinador de Estado (no como orquestador tradicional) con las siguientes restricciones:

Permitido:

• Mantener una tabla de estado que rastree el progreso de la saga
• Escuchar todos los eventos relevantes del flujo
• Tomar decisiones de cancelación basadas en eventos recibidos
• Emitir comandos de compensación cuando sea necesario
• Proveer endpoints de consulta del estado de la transacción

Prohibido:

• Invocar directamente (HTTP/gRPC) a otros servicios para ejecutar pasos
• Mantener lógica de negocio que corresponde a otros dominios
• Actuar como proxy o gateway entre servicios

Clarificación: El coordinador observa y reacciona, no comanda y espera. La comunicación sigue siendo asíncrona mediante el bus de eventos.

2.3 Prohibiciones Absolutas

• Two-Phase Commit (2PC): No se permite debido a bloqueos prolongados y baja disponibilidad
• XA Transactions: Prohibido extender transacciones de base de datos entre servicios
• Distributed Locks: No se permiten bloqueos compartidos entre servicios (excepto Semantic Locks de negocio, ver Parte III)
• Llamadas Síncronas en Flujo Crítico: HTTP/REST/gRPC solo para consultas (queries), nunca para comandos (writes) en sagas

3. Comunicación y Mensajería

3.1 Intermediario Obligatorio

Toda comunicación entre pasos de una saga debe realizarse a través de un Message Broker con las siguientes características:

Requisitos mínimos del broker:

• Persistencia en disco (durabilidad de mensajes)
• Garantía de entrega "al menos una vez" (at-least-once delivery)
• Capacidad de reintento automático
• Soporte para Dead Letter Queues (DLQ)
• Ordenamiento por partición (opcional pero recomendado)

Brokers aprobados: Kafka, RabbitMQ, Amazon SQS/SNS, Azure Service Bus, Google Pub/Sub.

3.2 Topología de Mensajería

Para eventos de dominio:

• Utilizar patrón Publish-Subscribe (pub/sub)
• Múltiples consumidores pueden suscribirse al mismo evento
• Los productores no conocen a los consumidores

Para comandos directos (casos excepcionales):

• Utilizar colas punto-a-punto
• Un solo consumidor procesa el mensaje
• Incluir timeout de procesamiento

3.3 Restricciones de Comunicación Síncrona

Prohibido para:

• Ejecutar el siguiente paso de una transacción crítica
• Confirmar operaciones de escritura entre servicios
• Propagar cambios de estado en flujos transaccionales

Permitido para:

• Consultas de solo lectura (queries)
• Validaciones previas no bloqueantes
• Obtención de datos de referencia
• Healthchecks y monitoreo

4. Transactional Outbox Pattern (Obligatorio)

4.1 Definición del Problema

El Dual Write Problem ocurre cuando un servicio intenta:

1. Actualizar su base de datos local
2. Publicar un evento en el broker

Si la publicación falla después del commit de BD, el sistema queda inconsistente. Si falla antes, se pierde el evento.

4.2 Solución Mandatoria

Regla de Oro: Un servicio nunca debe publicar directamente en el broker dentro de su código de negocio.

Implementación del patrón:

Primera fase - Transacción Atómica Local:

1. Iniciar transacción de base de datos
2. Ejecutar operación de negocio (INSERT/UPDATE/DELETE en tablas de dominio)
3. Insertar el evento a publicar en una tabla especial llamada OUTBOX
4. Confirmar transacción completa (COMMIT atómico)

Segunda fase - Publicación Asíncrona: 5. Un proceso independiente (Relay/Publisher) lee continuamente la tabla OUTBOX 6. Publica los eventos pendientes en el broker 7. Marca los eventos como publicados o los elimina

Tabla OUTBOX - Estructura requerida:

Campos obligatorios:

• Identificador único del mensaje (UUID)
• Tipo de evento (nombre del evento de dominio)
• Cuerpo del evento (payload serializado)
• Timestamp de creación
• Estado de publicación (pendiente, publicado, fallido)
• Número de intentos de publicación
• Agregado raíz asociado (para ordenamiento)
• Versión del esquema del evento

4.3 Estrategias de Relay

Opción A - Polling:

• Proceso que consulta periódicamente la tabla OUTBOX
• Publica eventos pendientes ordenados por timestamp
• Marca como publicados tras confirmación del broker
• Intervalo recomendado: 100-500 milisegundos

Opción B - Change Data Capture (CDC):

• Herramienta que lee el transaction log de la base de datos
• Detecta inserts en OUTBOX en tiempo real
• Publica automáticamente en el broker
• Ejemplos: Debezium, Maxwell, AWS DMS

Opción C - Database Triggers:

• Trigger que se activa al insertar en OUTBOX
• Invoca procedimiento que publica en broker
• No recomendado por acoplamiento y menor resiliencia

5. Resiliencia e Idempotencia

5.1 Principio de Idempotencia

Dado que los brokers garantizan entrega "al menos una vez", es inevitable que algunos mensajes se entreguen duplicados. Todo consumidor de eventos DEBE ser idempotente.

Definición: Una operación es idempotente si ejecutarla múltiples veces produce el mismo resultado que ejecutarla una sola vez.

Verificación obligatoria: Antes de procesar un evento, el consumidor debe verificar si el identificador del mensaje ya fue procesado previamente.

5.2 Implementación de Deduplicación

Tabla de Registro de Mensajes Procesados:

Cada servicio debe mantener una tabla dedicada con:

• Identificador del mensaje (clave primaria)
• Tipo de evento procesado
• Timestamp de procesamiento
• Estado final (éxito/fallo)
• Índice en timestamp para limpieza periódica

Flujo de procesamiento idempotente:

1. Recibir mensaje del broker
2. Iniciar transacción de base de datos local
3. Intentar insertar el identificador del mensaje en la tabla de registro
4. Si la inserción falla por duplicado: hacer rollback y retornar éxito (ya fue procesado)
5. Si la inserción es exitosa: ejecutar lógica de negocio
6. Insertar evento resultante en tabla OUTBOX (si aplica)
7. Confirmar transacción completa
8. Enviar ACK al broker

Política de limpieza: Eliminar registros con más de siete días de antigüedad mediante proceso nocturno.

5.3 Estrategias de Compensación

Para toda operación de escritura que modifique estado de negocio, el servicio debe implementar una Transacción Compensatoria.

Definición: Acción lógicamente inversa que deshace (o mitiga) el efecto de una operación previamente confirmada.

Ejemplos de compensación:

Operación original → Compensación:

• CrearPedido → AnularPedido
• ReservarInventario → LiberarReserva
• CobrarPago → ReembolsarPago
• EnviarNotificacion → EnviarNotificacionCorreccion
• AsignarRecurso → DesasignarRecurso

Características de compensaciones:

• Debe ser idempotente (puede ejecutarse múltiples veces)
• Puede ser semántica (no necesariamente restaura estado exacto)
• Debe registrarse en logs de auditoría
• Debe emitir eventos de compensación para trazabilidad

Tipos de compensación:

• Compensación perfecta: Restaura el estado exacto anterior (ej: cancelar reserva)
• Compensación aproximada: Restaura un estado equivalente (ej: reembolso en créditos en vez de dinero)
• Compensación simbólica: Registra el intento de reversión cuando la compensación real es imposible (ej: no se puede "des-enviar" un email, pero se envía corrección)

5.4 Manejo de Errores y Reintentos

Clasificación de fallos:

Fallos Transitorios: Errores temporales que pueden resolverse reintentando

• Pérdida de conexión de red
• Timeouts de base de datos por carga
• Servicio dependiente temporalmente no disponible
• Límites de rate limiting

Fallos Permanentes: Errores que no se resolverán reintentando

• Validaciones de negocio fallidas
• Datos malformados o incompletos
• Violaciones de reglas de dominio
• Permisos insuficientes
• Recursos no encontrados

Estrategia de Reintentos - Exponential Backoff:

Para fallos transitorios se debe implementar:

• Espera inicial entre primer y segundo intento: 500 milisegundos
• Multiplicador exponencial: factor de 2
• Espera máxima entre intentos (techo): 60 segundos
• Número máximo de intentos: 5
• Jitter aleatorio: añadir variación del 10-25% para evitar thundering herd

Progresión ejemplo: 500ms → 1s → 2s → 4s → 8s → DLQ

Dead Letter Queue (DLQ):

Después de agotar los reintentos, el mensaje debe enviarse a una cola especial para:

• Análisis manual posterior
• Alertas al equipo de operaciones
• Posible reprocesamiento manual tras corrección
• Auditoría de fallos recurrentes

Propiedades requeridas en mensajes de DLQ:

• Mensaje original completo
• Número de intentos realizados
• Timestamps de cada intento
• Detalles de cada error ocurrido
• Trace completo del último error

6. Versionado y Evolución de Contratos

6.1 Esquemas Explícitos Obligatorios

Todo evento de dominio publicado en el bus debe tener un esquema formal que defina:

• Nombre y tipo de cada campo
• Campos obligatorios vs opcionales
• Tipos de datos permitidos
• Restricciones de validación
• Descripción semántica de cada campo

Formatos aprobados: Avro, Protocol Buffers (Protobuf), JSON Schema.

Prohibido: Publicar eventos con estructura ad-hoc sin definición formal.

6.2 Versionado Semántico de Eventos

Todo evento debe incluir un campo de metadatos que indique su versión siguiendo el formato semántico: MAJOR.MINOR.PATCH

Ejemplo: "schema_version": "1.2.0"

Interpretación de versiones:

• MAJOR: Cambios incompatibles que requieren actualización del consumidor

  • Eliminar campos
  • Cambiar tipo de dato existente
  • Cambiar semántica del campo
  • Renombrar campos

• MINOR: Cambios retrocompatibles que agregan funcionalidad

  • Agregar nuevos campos opcionales
  • Agregar nuevos valores a enumeraciones
  • Deprecar campos (sin eliminarlos)

• PATCH: Correcciones menores sin impacto funcional

  • Corregir descripciones
  • Mejorar documentación
  • Correcciones de typos en nombres

6.3 Estrategias de Evolución

Para cambios ADITIVOS (Minor/Patch):

• Agregar solo campos opcionales con valores por defecto
• Los consumidores antiguos ignoran campos nuevos
• Los productores nuevos deben tolerar consumidores antiguos
• No requiere coordinación de despliegue

Para cambios BREAKING (Major):

• Crear un nuevo tipo de evento con sufijo de versión
  • Ejemplo: "OrdenSolicitada_v2"
• Mantener publicación dual por período de transición
  • El productor emite tanto evento v1 como v2
• Los consumidores migran gradualmente a la nueva versión
• Período mínimo de convivencia: 90 días calendario
• Después del período, deprecar y eliminar versión antigua

Política de deprecación:

1. Anunciar deprecación con 90 días de anticipación
2. Añadir warnings en logs cuando se use versión antigua
3. Publicar métricas de uso de versiones obsoletas
4. Coordinar migración con todos los equipos consumidores
5. Eliminar soporte solo cuando uso sea cero por 30 días

6.4 Registro Centralizado de Esquemas

Obligatorio: Mantener un Schema Registry centralizado que:

• Almacena todas las versiones de esquemas de eventos
• Valida compatibilidad antes de registrar nuevas versiones
• Provee APIs para consulta programática de esquemas
• Genera documentación automática de contratos
• Permite validación en tiempo de runtime

Herramientas recomendadas: Confluent Schema Registry, AWS Glue Schema Registry, Apicurio Registry.

7. Observabilidad y Rastreabilidad

7.1 Rastreo Distribuido

Generación de Identificadores:

El servicio que inicia una saga debe generar los siguientes identificadores únicos:

• Saga ID: Identificador global único (UUID versión 4) que representa toda la transacción distribuida. Se genera una sola vez al inicio y se propaga sin cambios.

• Span ID: Identificador único para cada paso o evento individual dentro de la saga. Cada servicio que procesa genera su propio Span ID.

• Parent Span ID: Referencia al Span ID del paso anterior, creando una jerarquía de trazas.

Propagación de Contexto:

Estos identificadores deben incluirse como headers/metadatos en todos los mensajes:

• Nombre del header de Saga ID: "X-Saga-ID"
• Nombre del header de Span ID: "X-Span-ID"
• Nombre del header de Parent Span: "X-Parent-Span-ID"

Los servicios intermedios deben:

• Preservar el Saga ID sin modificarlo
• Generar su propio Span ID
• Copiar el Span ID recibido como su Parent Span ID
• Propagar estos tres valores en todos los eventos que emitan

7.2 Logging Estructurado

Formato Obligatorio:

Cada entrada de log relacionada con procesamiento de eventos de saga debe ser estructurada (no texto plano) e incluir los siguientes campos:

Campos mandatorios de contexto:

• Identificador de saga (copiado del mensaje)
• Tipo de evento procesado
• Versión del esquema del evento
• Nombre del servicio que genera el log
• Timestamp en formato ISO-8601 con zona horaria UTC
• Identificador del span actual
• Identificador del span padre

Campos mandatorios de resultado:

• Estado del procesamiento: RECEIVED, PROCESSING, SUCCESS, FAILED, COMPENSATING, COMPENSATED
• Duración en milisegundos de la operación
• Número de intento (para reintentos)

Campos opcionales pero recomendados:

• Identificador de correlación de negocio (ej: número de orden)
• Identificador del usuario o entidad que inició la transacción
• Datos relevantes del payload (sin información sensible)
• Detalles del error (en caso de fallo)
• Nombre del nodo/instancia que procesó

Niveles de Log:

• INFO: Inicio y fin exitoso de procesamiento de evento
• WARN: Reintentos por fallos transitorios
• ERROR: Fallos permanentes, envío a DLQ
• DEBUG: Detalles de validaciones y decisiones de negocio

Ejemplo descriptivo de entrada de log:

Un log estructurado indicando que el servicio de Inventario procesó exitosamente un evento PagoExitoso en 150 milisegundos, este fue el primer intento, pertenece a la saga con ID alfa-123, el span actual es beta-456 hijo del span gamma-789, ocurrió el 7 de febrero de 2026 a las 10:30:00 UTC, procesó la versión 1.0 del evento, y resultó en éxito.

7.3 Métricas Requeridas

Todos los servicios participantes en sagas deben exponer las siguientes métricas en formato compatible con sistemas de monitoreo:

Métricas de duración:

• Nombre: saga_duration_seconds
• Tipo: Histogram
• Etiquetas: tipo_de_saga, estado_final (success, failed, compensated)
• Descripción: Tiempo total desde inicio hasta conclusión de la saga

Métricas de errores por paso:

• Nombre: saga_step_errors_total
• Tipo: Counter (contador acumulativo)
• Etiquetas: nombre_servicio, tipo_evento, tipo_error
• Descripción: Cantidad total de fallos al procesar eventos

Métricas de compensaciones:

• Nombre: saga_compensations_total
• Tipo: Counter
• Etiquetas: nombre_servicio, razón_compensación
• Descripción: Cantidad de transacciones compensatorias ejecutadas

Métricas de mensajes pendientes:

• Nombre: outbox_pending_messages
• Tipo: Gauge (valor instantáneo)
• Etiquetas: nombre_servicio
• Descripción: Cantidad de eventos en tabla OUTBOX pendientes de publicar

Métricas de mensajes en DLQ:

• Nombre: dlq_messages_total
• Tipo: Gauge
• Etiquetas: nombre_servicio, tipo_evento
• Descripción: Cantidad de mensajes en Dead Letter Queue por servicio

Formato de exportación: Prometheus, OpenMetrics, o CloudWatch.

7.4 Trazabilidad de Auditoría

Para procesos críticos de negocio se debe mantener:

• Tabla de auditoría de saga con todos los cambios de estado
• Timestamp de cada transición de estado
• Razón del cambio (evento que lo provocó)
• Usuario o sistema responsable del inicio
• Datos relevantes de negocio (sin información sensible duplicada)
• Retención mínima: según políticas regulatorias (típicamente 7 años)

8. Límites Operacionales y Timeouts

8.1 Parámetros Configurables Mandatorios

Todo servicio participante en sagas debe exponer y documentar los siguientes parámetros de configuración:

Reintentos:

• Número máximo de intentos antes de enviar a DLQ

  • Valor mínimo permitido: 3 intentos
  • Valor recomendado: 5 intentos

• Espera inicial entre primer y segundo intento (backoff inicial)

  • Valor mínimo permitido: 100 milisegundos
  • Valor recomendado: 500 milisegundos

• Espera máxima entre intentos (techo de backoff)

  • Valor mínimo permitido: 30 segundos
  • Valor recomendado: 60 segundos

Timeouts de saga completa:

• Tiempo máximo total para completar toda la saga
  • Valor mínimo permitido: 1 hora
  • Valor recomendado: 24 horas
  • Nota: Ajustar según naturaleza del proceso de negocio

Timeouts por paso individual:

• Tiempo máximo de espera por respuesta de un paso
  • Valor mínimo permitido: 30 segundos
  • Valor recomendado: 5 minutos (300 segundos)

Estos valores deben ser configurables sin recompilar código (variables de entorno, archivos de configuración, configuration server).

8.2 Política de Timeouts

Para timeouts de paso individual:

Si un evento esperado no llega dentro del plazo configurado:

1. El servicio coordinador (si existe) debe emitir un evento de timeout
2. Nombre del evento: "StepTimedOut" o similar
3. Incluir en el payload: saga_id, paso esperado, tiempo transcurrido
4. Iniciar proceso de compensación
5. Registrar en logs con nivel ERROR
6. Incrementar métrica de timeouts

Para timeouts de saga completa:

Si la saga no se completa dentro del plazo total configurado:

1. Ejecutar compensación automática de todos los pasos confirmados
2. Marcar la saga con estado TIMED_OUT
3. Emitir evento de saga expirada para auditoría
4. Notificar al usuario/sistema iniciador del fallo
5. Generar alerta para equipo de operaciones
6. No eliminar datos de auditoría (mantener para análisis)

8.3 Monitoreo de Umbrales

Alertas obligatorias:

• Si el porcentaje de sagas fallidas supera 5% en ventana de 15 minutos
• Si el tiempo promedio de saga supera el doble del baseline histórico
• Si la cantidad de mensajes en DLQ supera 10 por servicio
• Si hay mensajes en OUTBOX pendientes por más de 10 minutos
• Si una saga individual supera el 80% del timeout configurado

Niveles de severidad:

• CRITICAL: Afecta flujos de negocio críticos (pagos, pedidos)
• HIGH: Afecta funcionalidad importante pero no crítica
• MEDIUM: Degradación de rendimiento sin pérdida de funcionalidad
• LOW: Anomalías detectadas pero sin impacto inmediato

PARTE II: IMPLEMENTACIÓN DE REFERENCIA

1. Caso de Uso: Procesamiento de Órdenes con Validación Preventiva

Dominio de negocio: Sistema de comercio electrónico

Objetivo: Procesar una orden de compra asegurando disponibilidad de inventario antes de ejecutar el cobro, minimizando reembolsos por falta de stock.

Estrategia elegida: Check-Then-Act (Verificación antes de Acción Financiera)

Justificación: Reducir costos de transacciones bancarias fallidas y mejorar experiencia del cliente evitando cobros seguidos de reembolsos.

2. Definición del Flujo Transaccional

El proceso se divide en cuatro fases secuenciales:

Fase 1 - Intención:

• Acción: Registro inicial de la orden en el sistema
• Estado resultante: PENDIENTE_VALIDACION
• Evento emitido: OrdenSolicitada

Fase 2 - Validación:

• Acción: Consulta de disponibilidad de inventario sin reserva
• Tipo de operación: Lectura (SELECT) sin bloqueos
• Eventos posibles: StockVerificado o StockNoDisponible

Fase 3 - Cobro Condicional:

• Acción: Ejecución de transacción financiera
• Precondición: Solo si Fase 2 fue exitosa
• Eventos posibles: PagoExitoso o PagoRechazado

Fase 4 - Asignación con Bloqueo:

• Acción: Descuento definitivo de inventario
• Tipo de operación: Escritura (UPDATE) con bloqueo pesimista
• Eventos posibles: StockAsignado o FalloAsignacion

3. Servicios Participantes y Responsabilidades

3.1 Servicio: Gestor de Pedidos

Rol: Coordinador de estado (Orquestación Ligera)

Responsabilidades:

• Recibir la solicitud inicial del cliente
• Crear el registro de orden con estado inicial
• Generar el Saga ID único
• Emitir el evento OrdenSolicitada vía patrón Outbox
• Escuchar eventos de progreso del resto de participantes
• Mantener máquina de estados de la orden
• Actualizar estado según eventos recibidos
• Notificar al cliente sobre el resultado final

Transiciones de estado:

Estado PENDIENTE_VALIDACION al recibir:

• StockVerificado → PENDIENTE_PAGO
• StockNoDisponible → CANCELADA_SIN_STOCK (flujo termina)
• Timeout de validación → CANCELADA_TIMEOUT

Estado PENDIENTE_PAGO al recibir:

• PagoExitoso → PENDIENTE_ASIGNACION
• PagoRechazado → CANCELADA_PAGO_RECHAZADO

Estado PENDIENTE_ASIGNACION al recibir:

• StockAsignado → COMPLETADA (flujo exitoso)
• FalloAsignacion → CANCELADA_CON_REEMBOLSO (requiere compensación)

Eventos que escucha:

• StockVerificado
• StockNoDisponible
• PagoExitoso
• PagoRechazado
• StockAsignado
• FalloAsignacion
• ReembolsoEjecutado

Eventos que emite:

• OrdenSolicitada (inicio del flujo)
• OrdenCompletada (conclusión exitosa)
• OrdenCancelada (conclusión con fallo)

3.2 Servicio: Gestor de Inventario

Rol: Validador y Ejecutor (participa en dos momentos diferentes)

Responsabilidades:

Momento 1 - Validación (Fase 2):

• Escuchar evento OrdenSolicitada
• Consultar disponibilidad actual en base de datos
• Validar si existe stock suficiente para los ítems solicitados
• NO realizar ninguna reserva ni modificación de datos
• Emitir resultado de validación

Momento 2 - Asignación (Fase 4):

• Escuchar evento PagoExitoso
• Iniciar transacción de base de datos con bloqueo pesimista
• Re-verificar disponibilidad actual (puede haber cambiado desde Fase 2)
• Descontar las unidades si aún hay stock disponible
• Confirmar transacción o hacer rollback según resultado
• Emitir resultado de asignación

Lógica de validación (Momento 1):

Para cada ítem en la orden:

• Consultar tabla de productos con el SKU solicitado
• Leer campo de cantidad disponible actual
• Comparar cantidad solicitada vs cantidad disponible
• Si para TODOS los ítems hay stock suficiente: emitir StockVerificado
• Si para ALGÚN ítem no hay stock suficiente: emitir StockNoDisponible con detalles

Lógica de asignación (Momento 2):

1. Iniciar transacción con nivel de aislamiento REPEATABLE_READ o superior
2. Aplicar bloqueo pesimista (SELECT FOR UPDATE) sobre los productos afectados
3. Re-leer cantidad disponible actual
4. Validar nuevamente que hay stock suficiente
5. Si validación exitosa:
   • Ejecutar UPDATE restando las unidades
   • Insertar evento StockAsignado en tabla OUTBOX
   • COMMIT de transacción
6. Si validación falla (race condition, stock consumido por otra transacción):
   • Insertar evento FalloAsignacion en tabla OUTBOX
   • COMMIT de transacción (el evento de fallo debe publicarse)

Eventos que escucha:

• OrdenSolicitada (trigger de validación)
• PagoExitoso (trigger de asignación)

Eventos que emite:

• StockVerificado
• StockNoDisponible
• StockAsignado
• FalloAsignacion

Compensación: Si recibe evento de compensación (por fallo en paso posterior):

• Restaurar las unidades de inventario sumando la cantidad original
• Emitir evento StockLiberado

3.3 Servicio: Procesador de Pagos

Rol: Intermediario financiero condicional

Responsabilidades:

Operación Normal:

• Escuchar evento StockVerificado (NO OrdenSolicitada, para evitar cobros sin stock)
• Extraer información de pago del payload del evento
• Invocar API de pasarela de pagos externa (Stripe, PayPal, etc.)
• Manejar respuesta de la pasarela
• Emitir resultado de la operación financiera

Operación de Compensación:

• Escuchar evento FalloAsignacion
• Identificar la transacción financiera original asociada
• Ejecutar reembolso o reversa en la pasarela de pagos
• Emitir evento de confirmación de compensación

Lógica de cobro:

1. Recibir evento StockVerificado
2. Validar que evento no fue procesado previamente (idempotencia)
3. Extraer datos: monto, método de pago, token de tarjeta, etc.
4. Llamar API de pasarela con timeout de 30 segundos
5. Si respuesta es exitosa:
   • Almacenar ID de transacción de la pasarela
   • Insertar evento PagoExitoso en OUTBOX con referencia de transacción
   • COMMIT
6. Si respuesta es rechazo (fondos insuficientes, tarjeta inválida):
   • Insertar evento PagoRechazado en OUTBOX con código de error
   • COMMIT
7. Si hay timeout o error de red:
   • Aplicar política de reintentos con exponential backoff
   • Tras agotar intentos: enviar a DLQ para revisión manual

Lógica de compensación:

1. Recibir evento FalloAsignacion
2. Extraer Saga ID para identificar la transacción financiera original
3. Buscar en base de datos local el ID de transacción de la pasarela
4. Llamar API de reembolso de la pasarela con el ID original
5. Si reembolso exitoso:
   • Insertar evento ReembolsoEjecutado en OUTBOX
   • COMMIT
6. Si reembolso falla:
   • Reintentar con backoff exponencial
   • Tras 5 intentos fallidos: enviar alerta crítica a equipo de finanzas
   • Marcar para reembolso manual

Eventos que escucha:

• StockVerificado (trigger de cobro)
• FalloAsignacion (trigger de compensación)

Eventos que emite:

• PagoExitoso
• PagoRechazado
• ReembolsoEjecutado
• FalloReembolso (para casos críticos)

4. Escenarios de Ejecución

4.1 Escenario A: Flujo Exitoso (Happy Path)

Contexto inicial:

• Cliente solicita 1 unidad del producto SKU-123
• Inventario actual: 10 unidades disponibles
• No hay operaciones concurrentes

Secuencia de eventos:

1. Cliente envía solicitud HTTP POST al endpoint de Pedidos

2. Pedidos crea registro de orden con estado PENDIENTE_VALIDACION

3. Pedidos genera Saga ID: "550e8400-e29b-41d4-a716-446655440000"

4. Pedidos inserta en OUTBOX el evento OrdenSolicitada

5. Relay de Pedidos publica evento en topic "order-events"

6. Inventario consume evento OrdenSolicitada

7. Inventario consulta: SELECT cantidad FROM productos WHERE sku = 'SKU-123'

8. Inventario verifica: 10 unidades disponibles, pedido requiere 1, verificación OK

9. Inventario inserta en OUTBOX el evento StockVerificado

10. Relay de Inventario publica evento en topic "inventory-events"

11. Pedidos consume StockVerificado y actualiza estado a PENDIENTE_PAGO

12. Pagos consume StockVerificado

13. Pagos invoca API de pasarela: "Cobrar 50.00 USD a tarjeta terminada en 4242"

14. Pasarela responde: "Aprobado, transaction_id: txn_abc123"

15. Pagos inserta en OUTBOX el evento PagoExitoso con referencia txn_abc123

16. Relay de Pagos publica evento en topic "payment-events"

17. Pedidos consume PagoExitoso y actualiza estado a PENDIENTE_ASIGNACION

18. Inventario consume PagoExitoso

19. Inventario inicia transacción con: BEGIN; SELECT cantidad FROM productos WHERE sku = 'SKU-123' FOR UPDATE

20. Inventario lee cantidad bloqueada: 10 unidades

21. Inventario valida: 10 >= 1, OK

22. Inventario ejecuta: UPDATE productos SET cantidad = cantidad - 1 WHERE sku = 'SKU-123'

23. Inventario inserta en OUTBOX el evento StockAsignado

24. Inventario confirma: COMMIT

25. Relay de Inventario publica evento en topic "inventory-events"

26. Pedidos consume StockAsignado y actualiza estado a COMPLETADA

27. Pedidos emite evento OrdenCompletada

28. Pedidos envía notificación al cliente: "Tu orden ha sido confirmada"

Resultado final:

• Orden completada exitosamente
• Inventario reducido a 9 unidades
• Cliente cobrado y notificado
• Duración total: aproximadamente 2-5 segundos

4.2 Escenario B: Fallo Temprano (Sin Stock Disponible)

Contexto inicial:

• Cliente solicita 5 unidades del producto SKU-456
• Inventario actual: 0 unidades disponibles
• Optimización: evitar cobro innecesario

Secuencia de eventos:

1. Cliente envía solicitud HTTP POST al endpoint de Pedidos

2. Pedidos crea registro de orden con estado PENDIENTE_VALIDACION

3. Pedidos genera Saga ID: "7c9e6679-7425-40de-944b-e07fc1f90ae7"

4. Pedidos inserta en OUTBOX el evento OrdenSolicitada

5. Relay de Pedidos publica evento en topic "order-events"

6. Inventario consume evento OrdenSolicitada

7. Inventario consulta: SELECT cantidad FROM productos WHERE sku = 'SKU-456'

8. Inventario verifica: 0 unidades disponibles, pedido requiere 5, verificación FALLA

9. Inventario inserta en OUTBOX el evento StockNoDisponible con detalles

10. Relay de Inventario publica evento en topic "inventory-events"

11. Pedidos consume StockNoDisponible

12. Pedidos actualiza estado a CANCELADA_SIN_STOCK

13. Pedidos emite evento OrdenCancelada con razón "stock insuficiente"

14. Pedidos envía notificación al cliente: "Lo sentimos, el producto está agotado"

Comportamiento de Pagos:

• El servicio de Pagos NO escucha el evento StockNoDisponible
• Por tanto, NO se ejecuta ninguna operación financiera
• No hay cargos ni reembolsos

Resultado final:

• Orden cancelada rápidamente (en menos de 1 segundo)
• Cliente no fue cobrado
• Costo financiero: cero
• Experiencia de cliente: transparente y honesta

Beneficio del patrón: Esta arquitectura evita aproximadamente el 95% de reembolsos comparado con estrategias de "cobrar primero, verificar después".

4.3 Escenario C: Fallo Tardío (Race Condition)

Contexto inicial:

• Cliente A solicita 1 unidad del producto SKU-789
• Inventario actual: 1 unidad disponible
• Evento concurrente: Cliente B también solicita 1 unidad del mismo producto

Secuencia de eventos para Cliente A:

1. Pedidos A crea orden con Saga ID: "saga-aaa"

2. Pedidos A emite OrdenSolicitada

3. Inventario verifica disponibilidad para saga-aaa

4. Inventario consulta: 1 unidad disponible

5. Inventario emite StockVerificado para saga-aaa

6. Pagos procesa cobro para saga-aaa

7. Pasarela aprueba transacción: txn_xyz789

8. Pagos emite PagoExitoso para saga-aaa

Evento concurrente (Cliente B):

Mientras el flujo de Cliente A está entre Fase 3 y Fase 4:

• Pedidos B emite OrdenSolicitada para saga-bbb
• Inventario verifica: aún hay 1 unidad, emite StockVerificado para saga-bbb
• Pagos cobra a Cliente B: txn_def456
• Pagos emite PagoExitoso para saga-bbb

Continuación para Cliente A (intenta asignar primero):

9. Inventario consume PagoExitoso para saga-aaa

10. Inventario inicia: BEGIN; SELECT cantidad FROM productos WHERE sku = 'SKU-789' FOR UPDATE

11. Inventario lee cantidad: 1 unidad

12. Inventario valida: 1 >= 1, OK

13. Inventario ejecuta: UPDATE productos SET cantidad = 0

14. Inventario inserta evento StockAsignado para saga-aaa

15. Inventario confirma: COMMIT

16. Pedidos A recibe StockAsignado

17. Orden A finaliza con estado COMPLETADA

Continuación para Cliente B (llega segundo):

18. Inventario consume PagoExitoso para saga-bbb

19. Inventario inicia: BEGIN; SELECT cantidad FROM productos WHERE sku = 'SKU-789' FOR UPDATE

20. Inventario lee cantidad: 0 unidades (ya fue consumida por Cliente A)

21. Inventario valida: 0 >= 1, FALLA

22. Inventario NO ejecuta UPDATE

23. Inventario inserta evento FalloAsignacion para saga-bbb con razón "race condition"

24. Inventario confirma: COMMIT (importante: confirmar para que evento se publique)

25. Pagos consume FalloAsignacion para saga-bbb

26. Pagos busca transacción original: txn_def456

27. Pagos invoca API de pasarela: "Reembolsar txn_def456"

28. Pasarela confirma: "Reembolso procesado, refund_id: rfnd_xyz"

29. Pagos inserta evento ReembolsoEjecutado para saga-bbb

30. Relay de Pagos publica evento

31. Pedidos B consume ReembolsoEjecutado

32. Pedidos B actualiza estado a CANCELADA_CON_REEMBOLSO

33. Pedidos B envía notificación al Cliente B: "Tu pago ha sido reembolsado, el producto se agotó durante el proceso"

Resultado final:

• Cliente A: orden completada, inventario asignado
• Cliente B: orden cancelada, dinero reembolsado automáticamente
• Sistema mantuvo consistencia a pesar de concurrencia
• No hubo sobreventa (overselling)

Observación crítica: Este escenario demuestra por qué la verificación en Fase 2 es "optimista" (sin bloqueo) y la asignación en Fase 4 es "pesimista" (con bloqueo). El bloqueo temprano causaría alta contención. El bloqueo tardío minimiza ventana crítica.

5. Consideraciones de Implementación

5.1 Ordenamiento de Eventos

Problema: Los brokers garantizan orden dentro de una partición, no globalmente.

Solución para este caso de uso:

• Particionar eventos por Saga ID
• Todos los eventos de una misma saga van a la misma partición
• Configurar clave de partición: Saga ID
• Garantiza que eventos de UNA orden se procesan en orden
• No importa el orden entre órdenes diferentes

5.2 Manejo de Duplicados

Ejemplo de deduplicación en Inventario:

Cuando llega evento PagoExitoso:

1. Extraer Message ID del header: "msg-12345"
2. Iniciar transacción
3. Intentar: INSERT INTO processed_messages (message_id, event_type) VALUES ('msg-12345', 'PagoExitoso')
4. Si falla por clave duplicada:
   • Significa que este mensaje ya fue procesado
   • Hacer ROLLBACK
   • Retornar ACK al broker (no reintentar)
   • Registrar en log: "Evento duplicado ignorado"
5. Si inserción exitosa:
   • Proceder con lógica de asignación de stock
   • COMMIT incluye tanto la nueva fila en processed_messages como el UPDATE de inventario
   • Retornar ACK al broker

5.3 Consistencia de OUTBOX

Garantía crítica: El evento en OUTBOX y el cambio de estado de negocio deben confirmarse en la misma transacción atómica de base de datos.

Ejemplo en Pedidos al recibir StockVerificado:

Transacción única:

1. BEGIN
2. UPDATE orders SET status = 'PENDIENTE_PAGO' WHERE saga_id = '550e8400...'
3. INSERT INTO outbox (event_type, payload, saga_id) VALUES ('OrdenActualizada', '{...}', '550e8400...')
4. COMMIT

Si falla el COMMIT, ningún cambio se persiste. Si se confirma, ambos cambios quedan guardados atómicamente.

5.4 Configuración de Timeouts por Servicio

Pedidos:

• Timeout de validación de stock: 30 segundos
• Timeout de pago: 60 segundos (APIs bancarias pueden ser lentas)
• Timeout de asignación: 15 segundos
• Timeout total de saga: 2 horas

Inventario:

• Timeout de consulta de BD: 5 segundos
• Timeout de bloqueo pesimista: 10 segundos

Pagos:

• Timeout de llamada a pasarela: 30 segundos
• Reintentos en pasarela: 3 intentos con backoff de 2-8-18 segundos
• Timeout de reembolso: 60 segundos

PARTE III: PATRONES AVANZADOS (OPCIONAL)

1. Sagas de Larga Duración

Definición: Procesos que requieren más de una hora para completarse, típicamente por intervención humana, validaciones externas, o pasos asíncronos lentos.

Ejemplos:

• Proceso de aprobación de crédito (requiere revisión manual)
• Workflow de incorporación de empleado (múltiples pasos en días)
• Proceso de compra B2B con aprobaciones corporativas
• Integración con sistemas legacy batch que procesan nocturnamente

1.1 Desafíos Específicos

Problema 1: Estado en Memoria No es viable mantener el estado de la saga en memoria de un servicio durante horas o días. El servicio puede reiniciarse.

Problema 2: Escalabilidad Miles de sagas activas simultáneas durante días consumen recursos si no se gestionan apropiadamente.

Problema 3: Visibilidad Usuarios y operadores necesitan consultar el estado de procesos que toman días.

1.2 Estrategia de Implementación

Persistencia de Estado Explícita:

Crear una tabla dedicada para rastrear sagas activas:

Campos requeridos:

• Identificador único de saga (PK)
• Tipo de saga (ej: "AprobacionCredito")
• Estado actual (ej: "ESPERANDO_REVISION_MANUAL")
• Timestamp de inicio
• Timestamp de última actualización
• Paso actual en el flujo
• Contexto de negocio (datos necesarios para reanudar)
• Usuario o entidad propietaria
• Fecha de expiración o timeout

Timers Persistentes:

En lugar de mantener timers en memoria, usar:

• Scheduled jobs que consultan tabla de sagas periódicamente
• Buscar sagas en estado de espera cuyo timeout ha expirado
• Emitir eventos de timeout para reanudar o compensar
• Ejemplo: Job cada 5 minutos revisa sagas con "expected_event_by" < NOW()

Endpoints de Consulta:

Exponer APIs REST para que usuarios consulten estado:

• GET /sagas/saga-id/status → Retorna estado actual y progreso
• GET /sagas/saga-id/history → Retorna todos los eventos y transiciones
• POST /sagas/saga-id/cancel → Permite cancelación manual (ejecuta compensación)

1.3 Patrón de Reanudación

Caso de uso: Proceso pausado esperando aprobación humana.

Flujo:

1. Saga llega a paso que requiere aprobación
2. Servicio emite evento "AprobacionSolicitada"
3. Servicio actualiza tabla de sagas: estado = "ESPERANDO_APROBACION"
4. Se envía notificación a aprobador (email, dashboard, etc.)
5. Servicio NO mantiene nada en memoria, libera recursos
6. Horas o días después, aprobador toma decisión
7. Sistema de UI/backoffice emite evento "AprobacionOtorgada" o "AprobacionRechazada"
8. Servicio escucha evento, consulta estado de saga en tabla
9. Servicio carga contexto de negocio desde tabla
10. Servicio reanuda flujo desde el paso siguiente
11. Servicio actualiza estado en tabla

Beneficio: El servicio es stateless, puede reiniciarse sin perder progreso.

2. Sub-Sagas Anidadas

Definición: Una saga que, como parte de uno de sus pasos, inicia otra saga completa e independiente.

Ejemplo:

• Saga principal: "ProcesarCompraEmpresarial"
• Paso 3 de la saga requiere: "ValidarCreditoProveedor"
• ValidarCreditoProveedor es en sí una saga con múltiples pasos (consultar bureaus, validar referencias, aprobar monto)

2.1 Reglas de Anidación

Máximo permitido: 2 niveles de profundidad

• Saga Nivel 0 (raíz)
• Saga Nivel 1 (hija directa)
• Prohibido: Saga Nivel 2 (nieta)

Razón: Complejidad exponencial de compensación. Si una saga de nivel 2 falla, hay que compensar nivel 2, luego nivel 1, luego nivel 0. El rastreo se vuelve intratable.

2.2 Responsabilidad de Compensación

Principio: La saga padre es responsable de compensar sagas hijas si el flujo general falla.

Ejemplo:

Saga Padre: ProcesarCompra

• Paso 1: CrearOrden → OK
• Paso 2: ValidarCredito (invoca sub-saga) → OK
• Paso 3: EnviarMercancia → FALLA

Compensación:

1. Saga Padre emite evento de compensación para Paso 3 (no aplica, nunca ocurrió)
2. Saga Padre emite evento "CancelarValidacionCredito" para sub-saga
3. Sub-saga ejecuta su propia compensación interna (liberar límite de crédito reservado)
4. Saga Padre compensa Paso 1 (CancelarOrden)

Implementación:

La saga padre debe:

• Mantener registro de todas las sub-sagas iniciadas (almacenar Sub-Saga IDs)
• Al compensar, emitir eventos de compensación dirigidos a cada sub-saga
• Esperar confirmación de compensación de sub-sagas antes de completar su propia compensación
• Implementar timeout: si sub-saga no confirma compensación en X tiempo, alertar para intervención manual

2.3 Propagación de Contexto

Identificadores requeridos:

• Saga ID del padre (Root Saga ID)
• Saga ID de la hija (Child Saga ID)
• Nivel de anidación (0 = raíz, 1 = hija)

Headers en eventos de sub-saga:

• X-Root-Saga-ID: ID de la saga raíz
• X-Parent-Saga-ID: ID de la saga que inició esta
• X-Saga-Level: Nivel numérico de anidación

Uso en observabilidad: Permite visualizar jerarquía completa en herramientas de tracing:

• Root Saga: ProcesarCompra-123
  • Child Saga: ValidarCredito-456
    • Event: ConsultarBureau
    • Event: ValidarReferencias
  • Event: EnviarMercancia

3. Semantic Lock (Bloqueo Semántico de Negocio)

Problema: Prevenir race conditions en recursos críticos sin recurrir a bloqueos pesimistas de base de datos que reducen throughput.

Ejemplo del problema: Dos usuarios intentan reservar el mismo asiento de avión simultáneamente. Sin bloqueo, ambos podrían ver "asiento disponible" y ambos intentar comprarlo.

3.1 Concepto de Reserva Soft

En lugar de modificar inmediatamente el estado del recurso, se marca como "reservado temporalmente" con:

• Identificador de quién reservó (Saga ID)
• Timestamp de expiración (TTL - Time To Live)

Diferencia con bloqueo tradicional:

• Bloqueo tradicional (SELECT FOR UPDATE): Mantiene lock de base de datos hasta commit/rollback
• Semantic Lock: Marca lógica en el dato que otros respetan, lock se libera automáticamente por TTL

3.2 Flujo de Tres Fases

Fase 1 - Reserva Soft (Check):

• Servicio verifica disponibilidad del recurso
• Si está disponible, marca como "reservado" con Saga ID y TTL de 5 minutos
• Emite evento "RecursoReservado"
• NO compromete definitivamente el recurso

Fase 2 - Operación Crítica (Execute):

• Se ejecuta la operación costosa (ej: cobro de pago)
• Si falla, la reserva expira automáticamente por TTL
• Si tiene éxito, emite evento para confirmar

Fase 3 - Confirmación Hard (Commit):

• Servicio escucha evento de éxito de operación crítica
• Convierte reserva soft en asignación definitiva
• Cambia estado de "reservado" a "vendido"
• Limpia TTL

Fase Alternativa - Liberación Automática:

• Si saga falla o expira, el TTL llega a cero
• Job periódico (cada minuto) busca reservas expiradas
• Cambia estado de "reservado" a "disponible"
• Recurso queda libre para otros

3.3 Ejemplo Completo: Reserva de Asiento

Tabla de asientos:

Campos:

• id_asiento (PK)
• numero_asiento
• estado: DISPONIBLE, RESERVADO, VENDIDO
• reservado_por_saga_id (nullable)
• reservado_hasta_timestamp (nullable)

Paso 1 - Validación y Reserva:

Servicio de Asientos escucha OrdenDeVueloSolicitada:

1. Consultar: SELECT estado, reservado_hasta FROM asientos WHERE numero = '12A'
2. Si estado = VENDIDO: emitir AsientoNoDisponible
3. Si estado = RESERVADO AND reservado_hasta > NOW: emitir AsientoNoDisponible
4. Si estado = DISPONIBLE OR (estado = RESERVADO AND reservado_hasta <= NOW):
   • UPDATE asientos SET estado = 'RESERVADO', reservado_por_saga_id = 'saga-123', reservado_hasta = NOW + 5 minutos
   • Emitir AsientoReservado
   • COMMIT

Paso 2 - Pago:

Servicio de Pagos procesa cobro (toma 30 segundos):

• Si éxito: emite PagoExitoso
• Si fallo: NO emite nada, saga expira

Paso 3 - Confirmación:

Servicio de Asientos escucha PagoExitoso:

1. Verificar que saga_id coincide: SELECT reservado_por_saga_id FROM asientos WHERE numero = '12A'
2. UPDATE asientos SET estado = 'VENDIDO', reservado_por_saga_id = NULL, reservado_hasta = NULL
3. Emitir AsientoConfirmado
4. COMMIT

Job de Limpieza (cada 1 minuto):

1. SELECT numero FROM asientos WHERE estado = 'RESERVADO' AND reservado_hasta <= NOW
2. Para cada asiento encontrado:
   • UPDATE asientos SET estado = 'DISPONIBLE', reservado_por_saga_id = NULL, reservado_hasta = NULL
   • Registrar en log: "Reserva expirada para asiento X de saga Y"

Ventajas de este patrón:

• Alta concurrencia: No bloquea filas durante el pago
• Auto-recuperación: Fallos liberan recursos automáticamente
• Fairness: Primer solicitante obtiene reserva temporal
• Sin deadlocks: No hay bloqueos de base de datos

Desventajas:

• Complejidad adicional en lógica de negocio
• Requiere job de limpieza confiable
• Ventana de race condition muy pequeña (pero existe) en actualización de reserva

PARTE IV: GUÍAS DE IMPLEMENTACIÓN

1. Checklist de Desarrollo

Todo servicio que participe en una saga debe cumplir los siguientes requisitos antes de pasar a producción:

1.1 Persistencia y Mensajería

Verificar que:

• Existe tabla OUTBOX con todos los campos mandatorios
• Existe tabla de mensajes procesados para deduplicación
• Existe proceso Relay que publica eventos desde OUTBOX al broker
• El Relay se ejecuta con intervalo no mayor a 1 segundo
• Todos los eventos incluyen campo schema_version
• Todos los eventos tienen esquemas registrados en Schema Registry

1.2 Idempotencia

Verificar que:

• Todo handler de evento verifica Message ID antes de procesar
• La verificación y el procesamiento están en la misma transacción
• Existe test automatizado que envía mismo mensaje 3 veces y verifica resultado único
• Existe limpieza automática de tabla de mensajes procesados

1.3 Compensación

Verificar que:

• Para cada operación de escritura existe handler de compensación
• La compensación es idempotente (puede ejecutarse N veces)
• Existen tests que verifican que compensación revierte el estado
• La compensación emite evento de confirmación
• La compensación se registra en logs de auditoría

1.4 Configuración

Verificar que:

• Todos los parámetros de timeout son configurables externamente
• Valores por defecto cumplen con mínimos del estándar
• Configuración se carga al inicio y se valida
• Cambios de configuración no requieren recompilación

1.5 Observabilidad

Verificar que:

• Todos los logs de saga son estructurados (no texto plano)
• Saga ID se propaga en todos los eventos emitidos
• Todas las métricas mandatorias están implementadas
• Existe dashboard de monitoreo con visualización de métricas
• Existen alertas configuradas para casos anómalos

1.6 Testing

Verificar que:

• Existen tests de happy path completo
• Existen tests de cada escenario de compensación
• Existen tests de race conditions simuladas
• Existen tests de chaos engineering (matar servicio en medio de saga)
• Existe test de duplicación de mensaje

2. Templates de Eventos Estándar

Todos los eventos deben seguir una estructura consistente para facilitar consumo y rastreo.

2.1 Estructura Base de Evento

Todo evento publicado debe incluir tres secciones:

Sección 1 - Metadatos de Rastreo:

• Identificador único del mensaje (UUID)
• Identificador de la saga (UUID)
• Identificador del span actual (UUID)
• Identificador del span padre (UUID o null si es raíz)
• Versión del esquema del evento (formato semántico)
• Timestamp de creación en UTC ISO-8601
• Nombre del servicio que emitió el evento
• Tipo de evento (nombre descriptivo)

Sección 2 - Datos de Negocio (Payload):

• Información específica del dominio
• Solo datos necesarios para los consumidores
• Sin información sensible sin encriptar
• Con tipos de datos explícitos

Sección 3 - Metadatos Adicionales (Opcional):

• Identificador de correlación de negocio
• Identificador del usuario que inició el flujo
• Información de contexto relevante
• Tags o labels para filtrado

2.2 Ejemplo Descriptivo: Evento OrdenSolicitada

Metadatos de rastreo:

• message_id contiene un UUID único generado al crear el evento
• saga_id contiene el identificador de la saga completa de procesamiento de orden
• span_id contiene un UUID único para este evento específico
• parent_span_id contiene null porque este es el evento inicial
• schema_version contiene el string "1.0.0"
• timestamp contiene la fecha y hora de creación en formato ISO-8601 UTC
• source_service contiene el string "pedidos"
• event_type contiene el string "OrdenSolicitada"

Payload de negocio:

• order_id contiene el identificador único de la orden en el sistema de pedidos
• customer_id contiene el identificador del cliente que hizo la orden
• items es una lista de objetos, cada uno contiene:
  • sku: código del producto
  • quantity: cantidad solicitada (número entero)
  • price: precio unitario (número decimal con dos decimales)
• total_amount contiene el monto total de la orden (número decimal)
• shipping_address es un objeto que contiene:
  • street: calle
  • city: ciudad
  • country: país
  • postal_code: código postal
• payment_method es un objeto que contiene:
  • type: tipo de pago (string: "credit_card", "paypal", etc.)
  • token: token de pago tokenizado (NO el número de tarjeta real)

Metadatos adicionales:

• correlation_id contiene un identificador de correlación de negocio (ej: número de orden visible al cliente)
• user_id contiene el identificador del usuario autenticado
• channel contiene el canal de origen: "web", "mobile", "api"

3. Estrategias de Testing

3.1 Tests de Unidad para Idempotencia

Objetivo: Verificar que procesar el mismo evento múltiples veces produce el mismo resultado.

Escenario de test:

1. Preparar estado inicial de base de datos
2. Crear un evento de prueba con Message ID específico
3. Ejecutar handler del evento por primera vez
4. Capturar estado resultante de base de datos
5. Ejecutar handler del mismo evento (mismo Message ID) por segunda vez
6. Verificar que estado de base de datos es idéntico al del paso 4
7. Ejecutar handler por tercera vez
8. Verificar nuevamente estado idéntico
9. Verificar que tabla de mensajes procesados tiene solo UNA entrada para ese Message ID

Resultado esperado:

• Operación de negocio se ejecutó solo una vez
• Llamadas subsecuentes fueron ignoradas
• No hubo duplicación de datos
• No hubo errores

3.2 Tests de Compensación

Objetivo: Verificar que la transacción compensatoria revierte el efecto de la operación original.

Escenario de test para Inventario:

1. Estado inicial: Producto SKU-999 tiene 100 unidades
2. Publicar evento PagoExitoso para orden de 5 unidades de SKU-999
3. Esperar procesamiento
4. Verificar: Producto SKU-999 tiene 95 unidades
5. Publicar evento FalloAsignacion (trigger de compensación)
6. Esperar procesamiento de compensación
7. Verificar: Producto SKU-999 tiene 100 unidades nuevamente
8. Verificar en logs: Existe entrada de compensación ejecutada
9. Verificar: Se emitió evento StockLiberado

Casos adicionales a probar:

• Compensar cuando la operación original nunca ocurrió (compensación debe ser no-op)
• Compensar dos veces (debe ser idempotente)
• Compensar cuando el recurso ya no existe (debe manejarse gracefully)

3.3 Tests de Chaos Engineering

Objetivo: Verificar resiliencia ante fallos de infraestructura.

Escenario 1 - Matar Servicio Después de COMMIT:

1. Iniciar saga de prueba
2. Instrumentar código para matar proceso inmediatamente después de COMMIT en base de datos pero ANTES de enviar ACK al broker
3. Iniciar servicio
4. Esperar que saga procese
5. Servicio muere
6. Verificar: Cambio en BD se persistió
7. Verificar: Evento en OUTBOX se persistió
8. Reiniciar servicio
9. Verificar: Relay publica evento pendiente
10. Verificar: Saga continúa normalmente

Escenario 2 - Desconectar Broker Durante Saga:

1. Iniciar saga
2. Cuando llegue al paso 2, simular desconexión de red al broker
3. Verificar: Servicio reintenta con exponential backoff
4. Verificar: Eventos quedan pendientes en OUTBOX
5. Restaurar conexión después de 2 minutos
6. Verificar: Relay publica eventos pendientes
7. Verificar: Saga completa exitosamente

Escenario 3 - Latencia Extrema de Base de Datos:

1. Simular latencia de 10 segundos en todas las queries de BD
2. Iniciar saga
3. Verificar: Timeouts se activan correctamente
4. Verificar: Mensajes van a DLQ después de reintentos
5. Verificar: Se emiten alertas apropiadas
6. Verificar: No hay deadlocks ni procesos zombies

3.4 Tests End-to-End de Saga Completa

Objetivo: Verificar flujo completo en ambiente similar a producción.

Infraestructura de test:

• Broker real (Kafka o RabbitMQ dockerizado)
• Bases de datos reales por servicio (PostgreSQL dockerizado)
• Los tres servicios corriendo (Pedidos, Inventario, Pagos)
• Mock de pasarela de pagos externa

Test de Happy Path:

1. Insertar datos de prueba en BD de Inventario: SKU-TEST con 50 unidades
2. Enviar request HTTP POST a servicio de Pedidos: crear orden de 10 unidades de SKU-TEST
3. Esperar máximo 10 segundos
4. Verificar en BD de Pedidos: orden existe con estado COMPLETADA
5. Verificar en BD de Inventario: SKU-TEST tiene 40 unidades
6. Verificar en BD de Pagos: existe registro de transacción aprobada
7. Verificar en logs: todos los eventos se emitieron en orden correcto
8. Verificar en métricas: saga_duration_seconds registró tiempo total

Test de Fallo y Compensación:

1. Configurar mock de pasarela para rechazar pagos
2. Insertar datos: SKU-TEST2 con 20 unidades
3. Enviar request: crear orden de 5 unidades de SKU-TEST2
4. Esperar procesamiento
5. Verificar: Orden en estado CANCELADA_PAGO_RECHAZADO
6. Verificar: Inventario NO se modificó (sigue en 20 unidades)
7. Verificar: NO existe registro de transacción en BD de Pagos
8. Verificar en logs: evento PagoRechazado fue emitido

Test de Race Condition:

1. Insertar datos: SKU-TEST3 con 1 unidad
2. Lanzar DOS requests simultáneos: ambos piden 1 unidad de SKU-TEST3
3. Esperar procesamiento
4. Verificar: UNA orden en estado COMPLETADA
5. Verificar: OTRA orden en estado CANCELADA_CON_REEMBOLSO
6. Verificar: Inventario en 0 unidades (solo una asignación exitosa)
7. Verificar en logs: evento FalloAsignacion emitido para segunda saga
8. Verificar: Mock de pasarela recibió llamada de reembolso

ANEXO A: Architecture Decision Records (ADR)

ADR-001: Prohibición de Two-Phase Commit y XA Transactions

Fecha: 2026-02-01
Estado: Aceptado
Contexto:

En arquitecturas de microservicios distribuidos, la coordinación de transacciones entre múltiples servicios requiere decisiones sobre consistencia vs disponibilidad. El protocolo Two-Phase Commit (2PC) y las transacciones XA ofrecen atomicidad estricta pero con costos significativos.

Decisión:

Se prohíbe el uso de transacciones distribuidas bloqueantes (2PC, XA Transactions) en todo el ecosistema de microservicios. En su lugar, se adopta el patrón Saga con consistencia eventual.

Razones:

• Disponibilidad: 2PC requiere que todos los participantes estén disponibles simultáneamente. Si un servicio está caído, toda la transacción se bloquea. En sistemas distribuidos con múltiples servicios, la probabilidad de que algún componente esté temporalmente no disponible es alta.

• Latencia: El protocolo requiere múltiples roundtrips de red (prepare, vote, commit). Esto incrementa significativamente la latencia percibida por usuarios finales.

• Bloqueos: Los recursos (filas de base de datos) quedan bloqueados durante todo el protocolo. En sistemas de alta concurrencia, esto reduce dramáticamente el throughput.

• Complejidad Operacional: Requiere coordinador transaccional centralizado (Transaction Manager) que se convierte en punto único de fallo. La recuperación de fallos en 2PC es compleja y propensa a estados inconsistentes.

• Escalabilidad Limitada: No escala horizontalmente bien porque el coordinador se convierte en bottleneck.

Consecuencias:

Positivas:

• Mayor disponibilidad del sistema (cada servicio puede operar independientemente)
• Mejor throughput en operaciones concurrentes (sin bloqueos prolongados)
• Escalabilidad horizontal sin límites de coordinador central
• Resiliencia ante fallos parciales (saga puede progresar aunque un servicio esté caído temporalmente)

Negativas:

• Complejidad lógica incrementada (implementación de compensaciones)
• Ventanas de inconsistencia temporal (datos pueden estar desincronizados por segundos o minutos)
• Mayor complejidad en testing (necesidad de probar escenarios de compensación)
• Debugging más complejo (flujo implícito, necesidad de rastreo distribuido)

Mitigaciones de Consecuencias Negativas:

• Implementar Transactional Outbox Pattern para garantizar publicación de eventos
• Establecer observabilidad robusta con rastreo distribuido
• Documentar claramente lógica de compensación
• Implementar idempotencia estricta en todos los consumidores
• Definir límites de timeout para evitar sagas infinitas

ADR-002: Validación de Inventario Antes de Pago

Fecha: 2026-02-01
Estado: Aceptado
Contexto:

En sistemas de comercio electrónico, existen dos estrategias principales para manejar inventario en el flujo de compra:

• Estrategia A (Pay-First): Cobrar primero, luego verificar/asignar inventario. Si no hay stock, reembolsar.
• Estrategia B (Check-Then-Pay): Verificar inventario primero, luego cobrar solo si hay disponibilidad.

Decisión:

Se adopta la estrategia Check-Then-Pay: validar disponibilidad de inventario ANTES de ejecutar el cobro financiero.

Razones:

• Costos Financieros: Cada transacción con pasarela de pagos tiene un costo (típicamente 2.9% + 0.30 USD). Los reembolsos también incurren en costos. La estrategia Pay-First genera costos innecesarios cuando el pedido finalmente se cancela por falta de stock.

• Experiencia de Usuario: Los clientes perciben negativamente ser cobrados y luego reembolsados días después. Genera desconfianza y fricción. La estrategia Check-Then-Pay ofrece feedback inmediato sobre disponibilidad.

• Complejidad Contable: Los reembolsos complican la contabilidad y reconciliación bancaria. Requieren procesos adicionales de seguimiento.

• Carga en Soporte: Clientes cobrados y luego reembolsados generan tickets de soporte preguntando por el cargo temporal.

Trade-offs Considerados:

• Ventana de Race Condition: Entre la validación (Fase 2) y la asignación (Fase 4), el inventario puede ser consumido por otra transacción concurrente. Esto resulta en que algunos pagos exitosos requieran reembolso de todos modos.

• Latencia Adicional: Agregar paso de validación aumenta latencia total del flujo en aproximadamente 200-500ms.

Mitigación del Race Condition:

• Implementar re-verificación con bloqueo pesimista en Fase 4
• Implementar compensación automática de pago (reembolso) cuando ocurra race condition
• Monitorear tasa de race conditions y ajustar inventario buffer si es muy alta

Consecuencias:

Positivas:

• Reducción del 95% en costos de transacciones fallidas (según estudios de caso de e-commerce)
• Mejor experiencia de usuario (feedback inmediato de falta de stock)
• Menor carga operacional (menos reembolsos manuales)
• Contabilidad más limpia

Negativas:

• Posibilidad de race condition (aproximadamente 5% de casos en alta concurrencia)
• Latencia adicional de 200-500ms por validación previa
• Complejidad de implementar lógica de re-verificación con bloqueo

Métricas de Éxito:

• Tasa de reembolsos por falta de stock < 5%
• Latencia total de checkout < 3 segundos en percentil 95
• Tasa de quejas de clientes por cobros incorrectos < 0.1%

ADR-003: Coreografía con Coordinador de Estado vs Coreografía Pura

Fecha: 2026-02-01
Estado: Aceptado
Contexto:

Las sagas pueden implementarse mediante dos patrones principales:

• Coreografía Pura: Cada servicio escucha eventos relevantes y emite eventos de resultado sin conocer el flujo completo. No existe ningún componente central.

• Orquestación: Un servicio centralizado (orquestador) coordina toda la saga invocando directamente a participantes y esperando respuestas.

• Híbrido (Coreografía con Coordinador de Estado): Servicios se comunican vía eventos (coreografía) pero uno de ellos mantiene estado de la saga para visibilidad y decisiones de alto nivel.

Decisión:

Se adopta el patrón híbrido: Coreografía con Coordinador de Estado opcional. Se prohíbe orquestación tradicional con llamadas síncronas.

Razones a Favor de Coreografía:

• Bajo acoplamiento entre servicios
• Alta escalabilidad y resiliencia
• Facilita evolución independiente de servicios
• No hay punto único de fallo

Razones Contra Coreografía Pura:

• Difícil rastrear estado completo de una saga
• Complejo identificar en qué punto está una transacción de negocio
• No hay lugar obvio para implementar timeouts de saga completa
• Testing end-to-end más complejo

Razones Contra Orquestación Tradicional:

• Orquestador se convierte en bottleneck
• Alto acoplamiento (orquestador conoce todos los servicios)
• Punto único de fallo
• Dificulta escalabilidad horizontal

Solución Híbrida:

Permitir que el servicio iniciador (ej: Pedidos) actúe como Coordinador de Estado con restricciones:

• Puede mantener tabla de estado de saga
• Puede escuchar eventos de progreso
• Puede tomar decisiones de compensación
• NO puede invocar directamente a otros servicios
• NO puede ejecutar lógica de negocio de otros dominios

Consecuencias:

Positivas:

• Mantiene beneficios de coreografía (bajo acoplamiento, escalabilidad)
• Provee visibilidad centralizada de estado de saga
• Facilita implementación de timeouts
• Simplifica queries de estado para usuarios
• Facilita testing y debugging

Negativas:

• Incremento leve de complejidad en servicio coordinador
• Riesgo de que coordinador acumule lógica que debería estar en otros servicios (debe vigilarse en code reviews)

Reglas de Implementación:

• El coordinador solo mantiene estado, no ejecuta lógica de negocio
• Toda comunicación sigue siendo asíncrona vía eventos
• El coordinador es stateless (estado persiste en BD, no en memoria)
• Debe ser posible eliminar el coordinador sin romper el flujo (otros servicios siguen funcionando)

ADR-004: Outbox Pattern como Estándar Obligatorio

Fecha: 2026-02-01
Estado: Aceptado
Contexto:

Al trabajar con microservicios y messaging, existe el problema de Dual Writes: un servicio necesita actualizar su base de datos local Y publicar un evento en el broker. No existe transacción distribuida que abarque ambos sistemas.

Escenarios problemáticos sin Outbox:

• Escenario 1: Servicio actualiza BD, luego intenta publicar en broker, pero broker está caído → Cambio persiste pero evento nunca se publica → Inconsistencia
• Escenario 2: Servicio publica en broker exitosamente, luego intenta commit en BD, pero falla → Evento publicado pero cambio no persiste → Inconsistencia
• Escenario 3: Servicio hace commit en BD, luego proceso muere antes de publicar → Evento perdido → Inconsistencia

Decisión:

Hacer obligatorio el uso de Transactional Outbox Pattern en todos los servicios que participen en sagas.

Razones:

• Atomicidad Garantizada: La tabla OUTBOX está en la misma base de datos que las tablas de negocio. Un commit atómico garantiza que ambos (cambio de negocio + evento) se persistan juntos o ninguno se persista.

• Resiliencia ante Fallos: Si el proceso muere después del commit pero antes de publicar, el Relay independiente eventualmente publicará el evento pendiente.

• Simplicidad Conceptual: La lógica de negocio se simplifica: solo se preocupa por persistir en BD local. La publicación en broker es responsabilidad del Relay.

• Debugging Facilitado: Todos los eventos a publicar quedan registrados en una tabla. Se puede auditar qué eventos se publicaron, cuándo, cuántos intentos tomó, etc.

Implementaciones Consideradas:

• Opción A - Polling: Proceso que consulta tabla OUTBOX periódicamente

  • Pros: Simple de implementar, funciona con cualquier BD
  • Contras: Latencia adicional (según intervalo de polling)

• Opción B - Change Data Capture (CDC): Herramienta lee transaction log de BD

  • Pros: Latencia mínima (casi real-time), no impacta rendimiento de BD
  • Contras: Requiere herramienta adicional (Debezium), complejidad operacional

• Opción C - Triggers de BD: Trigger que publica al insertar en OUTBOX

  • Pros: Latencia cero
  • Contras: Acopla BD con broker, dificulta testing, problemas de resiliencia

Decisión de Implementación:

• Opción A (Polling) es mandatoria para todos los servicios
• Opción B (CDC) es recomendada para servicios críticos de alto volumen
• Opción C (Triggers) está prohibida por acoplamiento

Consecuencias:

Positivas:

• Cero pérdida de eventos
• Garantía de atomicidad entre cambio de negocio y publicación
• Resiliencia ante fallos de broker o red
• Auditoría completa de eventos

Negativas:

• Latencia adicional (100-500ms típicamente con polling)
• Necesidad de proceso Relay adicional
• Tabla OUTBOX crece y requiere limpieza
• Complejidad adicional en infraestructura

Mitigaciones:

• Optimizar intervalo de polling (100-500ms es aceptable)
• Implementar limpieza automática de eventos publicados después de 7 días
• Usar índices apropiados en tabla OUTBOX para queries eficientes
• Monitorear tamaño de OUTBOX y alertar si crece anormalmente

ANEXO B: Glosario de Términos

BASE: Modelo de consistencia para sistemas distribuidos. Acrónimo de Basically Available (Básicamente Disponible), Soft state (Estado Suave), Eventually consistent (Eventualmente Consistente). Contrasta con ACID.

Broker de Mensajes: Sistema intermediario que facilita comunicación asíncrona entre servicios mediante colas y topics. Ejemplos: Kafka, RabbitMQ.

Change Data Capture (CDC): Técnica para detectar y capturar cambios en base de datos mediante lectura del transaction log. Usado para publicar eventos sin Dual Write Problem.

Compensación: Transacción lógicamente inversa que deshace o mitiga el efecto de una operación previamente confirmada. Ejemplo: Si se cargó una tarjeta, la compensación es reembolsar.

Consistencia Eventual: Propiedad de sistemas distribuidos donde, en ausencia de nuevas actualizaciones, eventualmente todas las réplicas convergerán al mismo estado. No garantiza cuándo ocurrirá.

Coreografía: Patrón de saga donde cada servicio escucha eventos relevantes y reacciona autónomamente sin coordinación central. Comparable a bailarines que siguen música sin director.

Correlation ID: Identificador único que se propaga a través de múltiples servicios y operaciones para rastrear una transacción de negocio completa en logs y métricas distribuidos.

Dead Letter Queue (DLQ): Cola especial donde se envían mensajes que fallaron repetidamente después de múltiples intentos de procesamiento. Permite análisis y reprocesamiento manual.

Dual Write Problem: Problema de consistencia que ocurre al intentar escribir en dos sistemas diferentes (ej: base de datos + message broker) sin transacción atómica que abarque ambos.

Exponential Backoff: Estrategia de reintentos donde el tiempo de espera entre intentos crece exponencialmente. Ejemplo: 1s, 2s, 4s, 8s, 16s. Previene sobrecarga durante fallos.

Idempotencia: Propiedad de una operación que puede ejecutarse múltiples veces sin cambiar el resultado más allá de la primera ejecución. Ejemplo: "Establecer X = 5" es idempotente, "Incrementar X" no lo es.

Message Broker: Ver Broker de Mensajes.

Orquestación: Patrón de saga donde un componente central (orquestador) coordina explícitamente todos los pasos invocando a participantes y esperando respuestas.

Outbox Pattern: Ver Transactional Outbox Pattern.

Race Condition: Situación donde el resultado de una operación depende del tiempo relativo de eventos concurrentes. Ejemplo: dos transacciones leyendo el mismo inventario antes de que cualquiera lo actualice.

Relay: Proceso que lee eventos de la tabla OUTBOX y los publica en el message broker. Puede ser implementado via polling o CDC.

Saga: Patrón de diseño para manejar transacciones distribuidas mediante secuencia de transacciones locales coordinadas por eventos, con compensaciones para revertir en caso de fallo.

Schema Registry: Servicio centralizado que almacena y versiona esquemas de eventos/mensajes. Permite validación de compatibilidad y generación de documentación.

Semantic Lock: Bloqueo lógico a nivel de negocio (no de base de datos) que marca un recurso como "reservado temporalmente" con TTL, permitiendo alta concurrencia.

Span: En rastreo distribuido, representa una unidad de trabajo individual. Una saga completa contiene múltiples spans (uno por cada paso/evento).

Timeout: Límite de tiempo máximo para esperar una respuesta o completar una operación. Previene esperas infinitas ante fallos.

Transactional Outbox Pattern: Patrón que resuelve Dual Write Problem insertando eventos en tabla local (OUTBOX) dentro de la misma transacción de negocio, para luego publicarlos asíncronamente.

TTL (Time To Live): Tiempo de vida de un recurso o dato después del cual expira automáticamente. Usado en Semantic Locks para liberar reservas no confirmadas.

Two-Phase Commit (2PC): Protocolo de transacciones distribuidas bloqueantes que garantiza atomicidad mediante fase de preparación y fase de commit. Prohibido en este estándar.

ANEXO C: Referencias y Recursos

Documentación Técnica Recomendada

Libros:

• "Designing Data-Intensive Applications" por Martin Kleppmann - Capítulos 7-9 sobre transacciones distribuidas y consistencia
• "Microservices Patterns" por Chris Richardson - Capítulo 4 completo sobre Sagas
• "Building Microservices" por Sam Newman - Segunda edición, capítulo sobre workflows y consistencia

Papers Académicos:

• "Sagas" por Hector Garcia-Molina y Kenneth Salem (1987) - Paper original que define el patrón
• "Life beyond Distributed Transactions: an Apostate's Opinion" por Pat Helland - Argumentos contra transacciones distribuidas
• "Building on Quicksand" por Pat Helland y Dave Campbell - Fundamentos de consistencia eventual

Recursos Online:

• Microservices.io - Patrón Saga: https://microservices.io/patterns/data/saga.html
• Documentación de Debezium para CDC: https://debezium.io
• Confluent Schema Registry documentation: https://docs.confluent.io/platform/current/schema-registry/

Bibliotecas y Frameworks Recomendados

Para Java/JVM:

• Eventuate Tram Saga Framework - Framework especializado en sagas con outbox pattern
• Axon Framework - CQRS y Event Sourcing con soporte para sagas
• Apache Camel - Integración con múltiples brokers y patrones de mensajería

Para .NET:

• MassTransit - Framework de messaging con soporte nativo para sagas
• NServiceBus - Bus de servicios con soporte para sagas de larga duración
• Rebus - Bus de mensajes ligero con soporte para sagas

Para Node.js:

• Moleculer - Framework de microservicios con soporte para sagas
• NestJS con Bull - Soporte para colas y workflows complejos

Para Python:

• Nameko - Framework de microservicios con soporte para eventos
• Celery - Sistema de colas distribuidas con soporte para workflows

Herramientas de Observabilidad

Rastreo Distribuido:

• Jaeger - Sistema open-source de rastreo distribuido
• Zipkin - Rastreo distribuido con múltiples integraciones
• AWS X-Ray - Servicio administrado de AWS para rastreo
• Google Cloud Trace - Servicio de rastreo para GCP

Logging:

• ELK Stack (Elasticsearch, Logstash, Kibana) - Stack completo de logging
• Grafana Loki - Sistema de agregación de logs
• Splunk - Plataforma enterprise de análisis de logs

Métricas:

• Prometheus - Sistema de métricas con modelo pull
• Grafana - Visualización de métricas
• Datadog - Plataforma SaaS completa de observabilidad

Comunidades y Foros

• CNCF Slack - Canal #microservices
• Stack Overflow - Tag "saga-pattern" y "distributed-transactions"
• Reddit r/microservices
• DDD/CQRS Google Group

FIN DEL DOCUMENTO

Última Actualización: Febrero 2026
Próxima Revisión: Agosto 2026
Responsable: Equipo de Arquitectura Empresarial
Contacto: [email protected]

En el mundo de los sistemas distribuidos, hay una verdad incómoda que enfrentamos tarde o temprano: no podemos tenerlo todo. La promesa de las transacciones ACID tradicionales —esa garantía tranquilizadora de que nuestros datos siempre estarán perfectamente sincronizados— se desvanece en el momento en que decidimos distribuir nuestra aplicación monolítica en múltiples servicios independientes. Es un momento de madurez arquitectónica que muchos equipos experimentan con cierta resistencia, similar a cuando un adolescente comprende que el mundo no es tan simple como parecía en la infancia.

Esta transformación no es meramente técnica; representa un cambio filosófico en cómo concebimos la consistencia de datos. Abandonamos el confort de las transacciones atómicas inmediatas, donde todo sucede o nada sucede en un instante perfecto, y abrazamos algo más orgánico, más real: la consistencia eventual. Los datos pueden estar temporalmente desalineados entre servicios, como músicos de una orqestra que momentáneamente pierden el compás para luego reconectarse con la melodía principal. La belleza de este modelo —conocido como BASE (Basically Available, Soft state, Eventually consistent)— radica en su pragmatismo: el sistema responde incluso cuando algunos servicios están caídos, los eventos se persisten antes de considerarse publicados, y eventualmente, con la paciencia de un jardinero que espera la floración, el sistema converge hacia un estado consistente.

El Arte de la Coreografía Distribuida

Imagina un ballet donde los bailarines no siguen a un director de orquesta central, sino que responden a las acciones de sus compañeros de manera autónoma. Este es el corazón del patrón Saga basado en coreografía. Cada servicio actúa como un participante independiente que escucha eventos relevantes de su dominio, ejecuta su lógica de negocio local, publica eventos de resultado y —esto es crucial— no tiene conocimiento completo de qué otros servicios participan en el proceso general.

Esta autonomía trae consigo ventajas significativas: bajo acoplamiento entre servicios, alta escalabilidad y la ausencia de un punto único de fallo. Pero también presenta desafíos genuinos. El flujo completo de la transacción se vuelve implícito, emergente de las interacciones locales, lo que puede hacer que la depuración se asemeje a seguir las huellas de un animal esquivo en el bosque. La complejidad en el rastreo es real, y no debemos minimizarla.

Para contextos donde necesitamos mayor visibilidad del flujo completo, existe una alternativa complementaria: la orquestación ligera de estado. Aquí, un servicio actúa como coordinador de estado —no como un tirano centralizado que comanda cada movimiento, sino como un observador atento que rastrea el progreso, mantiene una tabla de estado de la saga, escucha todos los eventos relevantes y puede tomar decisiones de cancelación cuando sea necesario. La distinción es sutil pero fundamental: el coordinador observa y reacciona, no comanda y espera. La comunicación sigue siendo asíncrona mediante el bus de eventos, preservando así los beneficios de la arquitectura desacoplada.

Hay, por supuesto, caminos que debemos evitar absolutamente. El Two-Phase Commit (2PC) y las transacciones XA, que extienden transacciones de base de datos entre servicios, están prohibidos debido a los bloqueos prolongados que generan y la baja disponibilidad resultante. Los bloqueos distribuidos compartidos entre servicios son igualmente problemáticos, con la excepción de los bloqueos semánticos de negocio que discutiremos más adelante. Las llamadas síncronas en flujos críticos —HTTP, REST, gRPC— deben reservarse exclusivamente para consultas de solo lectura, nunca para comandos que modifican estado en el contexto de una saga.

El Problema Dual Write y su Solución Elegante

Uno de los desafíos más insidiosos en sistemas distribuidos es el "Dual Write Problem". El escenario es simple pero traicionero: un servicio necesita actualizar su base de datos local y publicar un evento en el broker de mensajería. Si la publicación falla después del commit de la base de datos, el sistema queda inconsistente. Si falla antes, perdemos el evento y el flujo se interrumpe sin que nadie lo sepa.

La solución a este dilema es el patrón Transactional Outbox, una técnica elegante que convierte un problema de coordinación distribuida en dos problemas locales secuenciales. La regla de oro es simple: un servicio nunca debe publicar directamente en el broker dentro de su código de negocio. En su lugar, la operación se divide en dos fases distintas.

La primera fase es una transacción atómica local donde todo sucede dentro de los límites seguros de una sola base de datos. Iniciamos la transacción, ejecutamos nuestra operación de negocio —quizás un INSERT, UPDATE o DELETE en las tablas de dominio— e inmediatamente después insertamos el evento que queremos publicar en una tabla especial llamada OUTBOX. Finalmente, confirmamos la transacción completa. El punto crítico aquí es que ambas escrituras están protegidas por el mismo commit atómico: o ambas suceden, o ninguna sucede.

La segunda fase es completamente asíncrona y resiliente. Un proceso independiente —típicamente llamado Relay o Publisher— lee continuamente la tabla OUTBOX, encuentra eventos pendientes, los publica en el broker y los marca como publicados o los elimina. Este proceso puede fallar, reintentar, detenerse y reiniciarse sin comprometer la integridad de nuestros datos, porque la fuente de verdad —la tabla OUTBOX— está segura en nuestra base de datos.

La estructura de la tabla OUTBOX debe incluir campos obligatorios que garanticen su funcionamiento correcto: un identificador único del mensaje (típicamente un UUID), el tipo de evento de dominio, el cuerpo del evento serializado, timestamp de creación, estado de publicación (pendiente, publicado, fallido), número de intentos, el agregado raíz asociado para ordenamiento, y la versión del esquema del evento.

Para implementar el proceso de relay tenemos tres opciones principales. El polling tradicional es simple y confiable: un proceso consulta periódicamente la tabla OUTBOX —recomendamos intervalos de 100 a 500 milisegundos— publica eventos pendientes ordenados por timestamp y los marca como publicados tras confirmación del broker. Change Data Capture (CDC) es más sofisticado: herramientas como Debezium, Maxwell o AWS DMS leen el transaction log de la base de datos, detectan inserts en OUTBOX en tiempo real y publican automáticamente en el broker. Los triggers de base de datos son la opción menos recomendada debido al acoplamiento que generan y su menor resiliencia, aunque técnicamente funcional: un trigger se activa al insertar en OUTBOX e invoca un procedimiento que publica en el broker.

Idempotencia: El Escudo Contra la Duplicación

Aquí nos encontramos con otra verdad incómoda de los sistemas distribuidos: los brokers de mensajería garantizan entrega "al menos una vez", lo que significa que inevitablemente algunos mensajes llegarán duplicados. No es un error del broker, es una característica inherente a sistemas que priorizan la disponibilidad sobre la consistencia perfecta. Por tanto, todo consumidor de eventos debe ser idempotente.

La definición es directa pero profunda: una operación es idempotente si ejecutarla múltiples veces produce el mismo resultado que ejecutarla una sola vez. Es como presionar el botón del elevador repetidamente —el elevador viene una sola vez, sin importar cuántas veces presionamos el botón. Cada servicio debe mantener una tabla dedicada de mensajes procesados con el identificador del mensaje como clave primaria, el tipo de evento procesado, timestamp de procesamiento, estado final (éxito o fallo) y un índice en timestamp para limpieza periódica.

El flujo de procesamiento idempotente se convierte en un ritual casi ceremonial. Al recibir un mensaje del broker, iniciamos una transacción de base de datos local e intentamos insertar el identificador del mensaje en la tabla de registro. Si la inserción falla por clave duplicada, sabemos que este mensaje ya fue procesado anteriormente: hacemos rollback y retornamos éxito al broker sin ejecutar nada. Si la inserción es exitosa, procedemos con la lógica de negocio, potencialmente insertamos un evento resultante en nuestra tabla OUTBOX, confirmamos la transacción completa y enviamos ACK al broker. Como medida de higiene, eliminamos registros con más de siete días de antigüedad mediante un proceso nocturno.

La Danza de la Compensación

Cuando las cosas van mal en un sistema distribuido —y eventualmente lo harán— necesitamos una estrategia para deshacer operaciones que ya fueron confirmadas. Aquí entra el concepto de transacción compensatoria: una acción lógicamente inversa que deshace o mitiga el efecto de una operación previamente confirmada.

Los ejemplos son intuitivos una vez que comprendemos el patrón. CrearPedido se compensa con AnularPedido. ReservarInventario con LiberarReserva. CobrarPago con ReembolsarPago. EnviarNotificacion con EnviarNotificacionCorreccion. AsignarRecurso con DesasignarRecurso. Pero la compensación no siempre es perfecta en el sentido matemático de restaurar el estado exacto anterior.

Existen tres tipos de compensación, cada uno con su propia filosofía. La compensación perfecta restaura el estado exacto anterior —como cancelar una reserva que aún no ha sido utilizada. La compensación aproximada restaura un estado equivalente pero no idéntico —como ofrecer un reembolso en créditos de la tienda en lugar de dinero, cuando ambos tienen valor similar para el cliente. La compensación simbólica es la más interesante: registra el intento de reversión cuando la compensación real es físicamente imposible. No podemos "des-enviar" un email una vez que salió, pero podemos enviar un email de corrección o aclaración.

Las compensaciones deben ser idempotentes (pueden ejecutarse múltiples veces sin efectos adversos), deben registrarse en logs de auditoría para trazabilidad, y deben emitir eventos de compensación para que otros servicios puedan reaccionar apropiadamente.

El Arte del Reintento Inteligente

No todos los errores son creados iguales. Esta distinción es fundamental para implementar una estrategia de reintentos efectiva. Los fallos transitorios son errores temporales que pueden resolverse reintentando: pérdida de conexión de red, timeouts de base de datos por carga momentánea, un servicio dependiente temporalmente no disponible, o límites de rate limiting alcanzados. Los fallos permanentes no se resolverán sin intervención humana o cambios en el código: validaciones de negocio fallidas, datos malformados o incompletos, violaciones de reglas de dominio, permisos insuficientes, o recursos no encontrados.

Para fallos transitorios implementamos exponential backoff con jitter. La progresión es elegante: empezamos con una espera inicial de 500 milisegundos entre el primer y segundo intento, luego multiplicamos por un factor de 2 en cada intento subsecuente, con un techo máximo de 60 segundos entre intentos y un límite de 5 intentos totales. Añadimos jitter aleatorio —una variación del 10-25%— para evitar el fenómeno de "thundering herd" donde múltiples procesos reintentan simultáneamente, creando picos de carga que agravan el problema original. La progresión típica sería: 500ms → 1s → 2s → 4s → 8s → Dead Letter Queue.

La Dead Letter Queue (DLQ) es nuestro hospital para mensajes enfermos. Después de agotar los reintentos automáticos, el mensaje se envía a esta cola especial donde espera análisis manual posterior, genera alertas al equipo de operaciones, puede ser reprocesado manualmente tras corrección del problema subyacente, y sirve para auditoría de fallos recurrentes. Los mensajes en DLQ deben preservar información forense completa: el mensaje original completo, número de intentos realizados, timestamps de cada intento, detalles de cada error ocurrido, y el trace completo del último error.

Evolución sin Ruptura: El Versionado de Contratos

Los sistemas vivos evolucionan, y los contratos entre servicios deben evolucionar con ellos sin romper el ecosistema existente. Todo evento de dominio publicado debe tener un esquema formal —Avro, Protocol Buffers o JSON Schema— que defina nombre y tipo de cada campo, campos obligatorios versus opcionales, tipos de datos permitidos, restricciones de validación, y descripción semántica de cada campo.

El versionado semántico se convierte en nuestra brújula. Cada evento incluye un campo "schema_version" con formato MAJOR.MINOR.PATCH. Un cambio MAJOR indica incompatibilidad que requiere actualización del consumidor: eliminar campos, cambiar tipos de datos existentes, cambiar la semántica de un campo, o renombrar campos. Un cambio MINOR representa adiciones retrocompatibles: agregar nuevos campos opcionales, agregar nuevos valores a enumeraciones, o deprecar campos sin eliminarlos. Un PATCH es para correcciones menores sin impacto funcional: corregir descripciones, mejorar documentación, o corregir typos en nombres.

Para cambios aditivos (Minor o Patch), agregamos solo campos opcionales con valores por defecto. Los consumidores antiguos ignoran campos nuevos que no conocen, los productores nuevos toleran consumidores antiguos, y no se requiere coordinación de despliegue. Es evolución pacífica y gradual.

Para cambios breaking (Major), necesitamos una estrategia más cuidadosa. Creamos un nuevo tipo de evento con sufijo de versión —por ejemplo, "OrdenSolicitada_v2"— y mantenemos publicación dual por un período de transición. El productor emite tanto el evento v1 como el v2, permitiendo que los consumidores migren gradualmente. El período mínimo de convivencia es 90 días calendario. Solo después de este período podemos deprecar y eventualmente eliminar la versión antigua.

La política de deprecación es deliberadamente conservadora: anunciamos la deprecación con 90 días de anticipación, añadimos warnings en logs cuando se use la versión antigua, publicamos métricas de uso de versiones obsoletas, coordinamos la migración con todos los equipos consumidores, y eliminamos soporte solo cuando el uso sea cero por 30 días consecutivos. Es un proceso tedioso, sí, pero necesario para la salud del ecosistema.

Observabilidad: Iluminando la Caja Negra

Un sistema distribuido sin observabilidad es como navegar un barco en niebla densa sin instrumentos. El rastreo distribuido nos permite seguir el viaje completo de una transacción a través de múltiples servicios. El servicio que inicia una saga genera un Saga ID —un identificador global único, típicamente UUID versión 4— que representa toda la transacción distribuida. Este ID se genera una sola vez al inicio y se propaga sin cambios a través de todos los pasos subsecuentes.

Adicionalmente, cada servicio que procesa genera su propio Span ID —un identificador único para ese paso específico— y mantiene referencia al Parent Span ID del paso anterior, creando así una jerarquía de trazas como un árbol genealógico de operaciones. Estos identificadores viajan como headers en todos los mensajes: "X-Saga-ID", "X-Span-ID" y "X-Parent-Span-ID". Los servicios intermedios preservan el Saga ID sin modificarlo, generan su propio Span ID, copian el Span ID recibido como su Parent Span ID, y propagan estos tres valores en todos los eventos que emitan.

El logging estructurado es nuestra memoria colectiva. Cada entrada de log relacionada con procesamiento de eventos debe incluir campos mandatorios de contexto —identificador de saga, tipo de evento, versión del esquema, nombre del servicio, timestamp en ISO-8601 con zona horaria UTC, identificador del span actual y padre— junto con campos mandatorios de resultado: estado del procesamiento (RECEIVED, PROCESSING, SUCCESS, FAILED, COMPENSATING, COMPENSATED), duración en milisegundos de la operación, y número de intento para reintentos.

Las métricas son nuestros sensores vitales. saga_duration_seconds es un histograma que mide el tiempo total desde inicio hasta conclusión, etiquetado por tipo de saga y estado final. saga_step_errors_total es un contador acumulativo de fallos al procesar eventos, etiquetado por nombre de servicio, tipo de evento y tipo de error. saga_compensations_total cuenta las transacciones compensatorias ejecutadas. outbox_pending_messages es un gauge que muestra cuántos eventos están pendientes de publicar en cada servicio. dlq_messages_total indica la cantidad de mensajes problemáticos en Dead Letter Queue.

Para procesos críticos de negocio mantenemos tablas de auditoría completas con todos los cambios de estado de la saga, timestamp de cada transición, razón del cambio (evento que lo provocó), usuario o sistema responsable del inicio, y datos relevantes de negocio. La retención mínima sigue políticas regulatorias, típicamente siete años para sectores financieros.

Límites Temporales y la Paciencia del Sistema

Todo proceso distribuido debe tener límites temporales claramente definidos. No podemos esperar indefinidamente. Los parámetros configurables son nuestra red de seguridad: número máximo de intentos antes de enviar a DLQ (recomendamos 5 intentos con mínimo de 3), espera inicial entre primer y segundo intento (recomendamos 500 milisegundos con mínimo de 100), espera máxima entre intentos (recomendamos 60 segundos con mínimo de 30), timeout de saga completa (recomendamos 24 horas con mínimo de 1 hora, ajustable según naturaleza del proceso), y timeout por paso individual (recomendamos 5 minutos con mínimo de 30 segundos).

La filosofía de timeouts tiene dos niveles. Para timeouts de paso individual, si un evento esperado no llega dentro del plazo configurado, el coordinador emite un evento de timeout, inicia proceso de compensación, registra en logs con nivel ERROR e incrementa métricas de timeouts. Para timeouts de saga completa, si la saga no se completa dentro del plazo total, ejecutamos compensación automática de todos los pasos confirmados, marcamos la saga con estado TIMED_OUT, emitimos evento de saga expirada para auditoría, notificamos al usuario o sistema iniciador del fallo, y generamos alerta para el equipo de operaciones. Crucialmente, no eliminamos datos de auditoría —los mantenemos para análisis post-mortem.

Las alertas obligatorias actúan como sistema de alerta temprana: si el porcentaje de sagas fallidas supera 5% en ventana de 15 minutos, si el tiempo promedio supera el doble del baseline histórico, si la cantidad de mensajes en DLQ supera 10 por servicio, si hay mensajes en OUTBOX pendientes por más de 10 minutos, o si una saga individual supera el 80% del timeout configurado. Cada alerta tiene su nivel de severidad: CRITICAL para flujos de negocio críticos como pagos y pedidos, HIGH para funcionalidad importante pero no crítica, MEDIUM para degradación de rendimiento sin pérdida de funcionalidad, y LOW para anomalías sin impacto inmediato.

Del Concepto a la Realidad: Un Caso Práctico

La teoría cobra vida cuando la aplicamos a un caso concreto. Consideremos un sistema de comercio electrónico donde necesitamos procesar una orden de compra asegurando disponibilidad de inventario antes de ejecutar el cobro. El objetivo es claro: minimizar reembolsos por falta de stock, reducir costos de transacciones bancarias fallidas, y mejorar la experiencia del cliente evitando cobros seguidos de reembolsos inmediatos.

Nuestra estrategia es Check-Then-Act: verificación antes de acción financiera. El proceso se divide en cuatro fases secuenciales, cada una con su propósito específico. En la fase de intención, registramos la orden inicial con estado PENDIENTE_VALIDACION y emitimos el evento OrdenSolicitada. En la fase de validación, consultamos disponibilidad de inventario sin realizar ninguna reserva —es una operación de lectura pura, sin bloqueos— que resulta en StockVerificado o StockNoDisponible. En la fase de cobro condicional, ejecutamos la transacción financiera solo si la fase anterior fue exitosa, resultando en PagoExitoso o PagoRechazado. Finalmente, en la fase de asignación con bloqueo, realizamos el descuento definitivo de inventario con un UPDATE que usa bloqueo pesimista, resultando en StockAsignado o FalloAsignacion.

Tres servicios orquestan este ballet: el Gestor de Pedidos actúa como coordinador de estado, el Gestor de Inventario participa en dos momentos diferentes (validación y asignación), y el Procesador de Pagos actúa como intermediario financiero condicional.

El Gestor de Pedidos mantiene la máquina de estados de la orden. Cuando está en estado PENDIENTE_VALIDACION y recibe StockVerificado, transiciona a PENDIENTE_PAGO. Si recibe StockNoDisponible, va directamente a CANCELADA_SIN_STOCK y el flujo termina. Desde PENDIENTE_PAGO, al recibir PagoExitoso transiciona a PENDIENTE_ASIGNACION, pero si recibe PagoRechazado va a CANCELADA_PAGO_RECHAZADO. Finalmente, desde PENDIENTE_ASIGNACION, StockAsignado lleva a COMPLETADA (el flujo exitoso), mientras que FalloAsignacion resulta en CANCELADA_CON_REEMBOLSO y requiere compensación.

El Gestor de Inventario tiene una doble vida fascinante. En el momento de validación, al escuchar OrdenSolicitada, simplemente consulta disponibilidad actual sin tocar nada. Es como asomarse a la despensa para ver si hay suficiente harina sin tomar nada todavía. Si hay stock suficiente para todos los ítems, emite StockVerificado. Si algún ítem no tiene stock suficiente, emite StockNoDisponible con detalles. En el momento de asignación, al escuchar PagoExitoso, la cosa se pone seria: inicia una transacción con bloqueo pesimista (SELECT FOR UPDATE), re-verifica disponibilidad actual —que puede haber cambiado desde la validación inicial— descuenta las unidades si aún hay stock, y confirma transacción o hace rollback según el resultado.

Esta re-verificación en la fase de asignación es crítica. Durante el tiempo transcurrido entre la validación optimista (fase 2) y la asignación pesimista (fase 4), otra transacción concurrente podría haber consumido ese stock. El bloqueo pesimista en la fase 4 garantiza que, una vez que obtenemos el lock, nadie más puede modificar esos registros hasta que terminemos.

El Procesador de Pagos es deliberadamente ciego a OrdenSolicitada. Solo reacciona a StockVerificado, lo que previene cobros innecesarios cuando no hay stock disponible. Al recibir StockVerificado, valida que el evento no fue procesado previamente (idempotencia), extrae datos de pago, llama a la API de la pasarela con timeout de 30 segundos, y maneja la respuesta apropiadamente. Si la pasarela aprueba, almacena el ID de transacción e inserta PagoExitoso en OUTBOX. Si hay rechazo por fondos insuficientes o tarjeta inválida, inserta PagoRechazado. Si hay timeout o error de red, aplica la política de reintentos con exponential backoff, y tras agotar intentos envía a DLQ para revisión manual.

La compensación en Pagos es igualmente importante. Al recibir FalloAsignacion, extrae el Saga ID para identificar la transacción financiera original, busca en su base de datos local el ID de transacción de la pasarela, llama a la API de reembolso, y si es exitoso inserta ReembolsoEjecutado en OUTBOX. Si el reembolso falla, reintenta con backoff exponencial, y tras 5 intentos fallidos envía alerta crítica al equipo de finanzas y marca para reembolso manual.

Tres Historias, Tres Destinos

El flujo exitoso —el happy path que todos queremos ver— es casi poético en su simplicidad. Un cliente solicita 1 unidad del producto SKU-123. El inventario actual tiene 10 unidades disponibles. No hay operaciones concurrentes. El cliente envía su solicitud HTTP POST, Pedidos crea el registro con estado PENDIENTE_VALIDACION, genera un Saga ID único, inserta OrdenSolicitada en OUTBOX. El relay publica el evento. Inventario lo consume, consulta la base de datos, verifica que hay 10 unidades y el pedido requiere solo 1, inserta StockVerificado en OUTBOX. Pagos consume StockVerificado, invoca la API de la pasarela que aprueba el cobro, inserta PagoExitoso. Inventario consume PagoExitoso, inicia transacción con bloqueo pesimista, re-verifica que aún hay stock, ejecuta el UPDATE restando 1 unidad, inserta StockAsignado, confirma la transacción. Pedidos consume StockAsignado, actualiza estado a COMPLETADA, emite OrdenCompletada, y notifica al cliente. Todo el proceso toma aproximadamente 2-5 segundos. Elegante, eficiente, exitoso.

El fallo temprano es igualmente instructivo. Un cliente solicita 5 unidades del producto SKU-456. El inventario actual tiene 0 unidades. Pedidos crea la orden y emite OrdenSolicitada. Inventario consulta, verifica que hay 0 unidades pero el pedido requiere 5, inmediatamente inserta StockNoDisponible en OUTBOX. Pedidos consume este evento, actualiza estado a CANCELADA_SIN_STOCK, emite OrdenCancelada, y notifica al cliente que el producto está agotado. Lo crucial aquí es que el servicio de Pagos nunca se entera de nada —no escucha StockNoDisponible— por tanto no se ejecuta ninguna operación financiera. No hay cargos, no hay reembolsos. La orden se cancela en menos de 1 segundo. El costo financiero es cero. Esta arquitectura evita aproximadamente el 95% de reembolsos comparado con estrategias de "cobrar primero, verificar después".

El fallo tardío —la race condition— es donde el diseño realmente brilla. Cliente A solicita 1 unidad del producto SKU-789. Inventario actual: 1 unidad disponible. Cliente B también solicita 1 unidad del mismo producto simultáneamente. Ambos pasan la validación optimista porque en ese momento había 1 unidad disponible. Ambos son cobrados exitosamente por la pasarela de pagos. Pero en la fase de asignación, solo uno puede ganar.

Digamos que Cliente A llega primero a la fase de asignación. Inventario inicia transacción con SELECT FOR UPDATE, obtiene el lock, lee 1 unidad disponible, valida que 1 >= 1, ejecuta UPDATE restando la unidad, deja el inventario en 0, inserta StockAsignado, confirma. Cliente A recibe su orden completa. Segundos después, Cliente B llega a la fase de asignación. Inventario inicia otra transacción con SELECT FOR UPDATE, obtiene el lock (Cliente A ya liberó el lock al hacer COMMIT), pero ahora lee 0 unidades disponibles, valida que 0 < 1, la validación falla, no ejecuta el UPDATE, pero —esto es crucial— sí confirma la transacción para que el evento FalloAsignacion se publique correctamente.

Pagos consume FalloAsignacion para Cliente B, busca la transacción original que había aprobado, invoca la API de reembolso de la pasarela, recibe confirmación, inserta ReembolsoEjecutado. Pedidos consume este evento, actualiza estado a CANCELADA_CON_REEMBOLSO, y notifica a Cliente B que su pago ha sido reembolsado porque el producto se agotó durante el proceso. Cliente A tiene su orden completada, Cliente B tiene su dinero de vuelta automáticamente, el sistema mantuvo consistencia a pesar de la concurrencia, y crucialmente, no hubo sobreventa (overselling).

Este escenario demuestra por qué la verificación en fase 2 es optimista (sin bloqueo) y la asignación en fase 4 es pesimista (con bloqueo). Si bloqueáramos en la fase de validación, tendríamos alta contención —cada consulta de disponibilidad bloquearía las filas, forzando a otras transacciones a esperar. El bloqueo tardío minimiza la ventana crítica a solo el momento de la asignación definitiva.

Consideraciones Finales de Implementación

El ordenamiento de eventos merece atención especial. Los brokers garantizan orden dentro de una partición, no globalmente. La solución es particionar eventos por Saga ID, asegurando que todos los eventos de una misma saga vayan a la misma partición. Configuramos la clave de partición como el Saga ID. Esto garantiza que eventos de una orden específica se procesen en orden correcto, aunque no importa el orden entre órdenes diferentes —cada orden es independiente.

El manejo de duplicados es un ritual bien definido. Cuando llega un evento PagoExitoso al servicio de Inventario, extraemos el Message ID del header, iniciamos una transacción, e intentamos insertar ese ID en la tabla processed_messages. Si la inserción falla por clave duplicada, sabemos que este mensaje ya fue procesado: hacemos rollback, retornamos ACK al broker sin hacer nada más, y registramos en logs "Evento duplicado ignorado". Si la inserción es exitosa, procedemos con la lógica de asignación de stock, y el COMMIT incluye tanto la nueva fila en processed_messages como el UPDATE de inventario. Ambos cambios o ninguno —atomicidad local garantizada.

La consistencia de OUTBOX es una garantía crítica inviolable: el evento en OUTBOX y el cambio de estado de negocio deben confirmarse en la misma transacción atómica de base de datos. Por ejemplo, cuando Pedidos recibe StockVerificado, en una sola transacción ejecuta UPDATE de la orden cambiando estado a PENDIENTE_PAGO e INSERT en OUTBOX del evento OrdenActualizada, seguido de COMMIT. Si el COMMIT falla, ningún cambio se persiste. Si se confirma, ambos cambios quedan guardados atómicamente. Esta es la base de toda la confiabilidad del sistema.

Los timeouts deben configurarse pensando en las características reales de cada operación. Para Pedidos: timeout de validación de stock de 30 segundos (consultas de base de datos son rápidas), timeout de pago de 60 segundos (APIs bancarias pueden ser lentas), timeout de asignación de 15 segundos (es un UPDATE simple), y timeout total de saga de 2 horas (permitiendo delays en procesamiento de eventos). Para Inventario: timeout de consulta de base de datos de 5 segundos, timeout de bloqueo pesimista de 10 segundos. Para Pagos: timeout de llamada a pasarela de 30 segundos, 3 reintentos con backoff de 2-8-18 segundos, y timeout de reembolso de 60 segundos.

Reflexiones sobre la Consistencia Eventual

Implementar el patrón Saga es, en esencia, aceptar la naturaleza distribuida de la realidad. No estamos simulando un sistema monolítico con trucos de coordinación; estamos abrazando honestamente que nuestros servicios son entidades autónomas que colaboran a través de eventos. La consistencia eventual no es una limitación que debemos lamentar, sino una propiedad emergente que podemos diseñar deliberadamente.

Los desafíos son reales: flujos implícitos, depuración compleja, compensaciones que requieren pensamiento cuidadoso, race conditions que debemos anticipar, y la necesidad constante de idempotencia. Pero las recompensas también son sustanciales: servicios verdaderamente desacoplados que pueden evolucionar independientemente, escalabilidad horizontal sin límites artificiales, resiliencia ante fallos parciales, y la capacidad de razonar sobre procesos de negocio complejos mediante eventos de dominio.

La clave está en la disciplina. El patrón Transactional Outbox elimina el dual write problem. La deduplicación sistemática maneja mensajes duplicados. Las compensaciones bien diseñadas permiten deshacer operaciones. Los reintentos inteligentes distinguen entre fallos transitorios y permanentes. El versionado cuidadoso permite evolución sin ruptura. La observabilidad exhaustiva ilumina lo que de otra manera sería opaco.

Cada uno de estos elementos es un pilar que sostiene el edificio completo. Eliminar cualquiera de ellos compromete la integridad estructural. Pero implementados en conjunto, con la atención al detalle que merece cada uno, nos permiten construir sistemas distribuidos que no solo funcionan sino que son comprensibles, mantenibles y confiables a largo plazo.

Al final, el patrón Saga nos enseña una lección más amplia sobre la arquitectura de software: los sistemas complejos emergen de la composición de partes simples que interactúan mediante protocolos bien definidos. No necesitamos coordinación central omnisciente. No necesitamos transacciones globales mágicas. Necesitamos servicios que comprendan sus responsabilidades, eventos que comuniquen intenciones claras, y mecanismos de compensación que permitan corrección de errores. Con estos ingredientes, la consistencia eventual emerge naturalmente, como un patrón que se forma en la arena cuando las olas retroceden.

Esta es la belleza del diseño distribuido: aceptamos las limitaciones fundamentales de la física —la información viaja a velocidad finita, los sistemas fallan parcialmente, el tiempo no es absoluto— y construimos abstracciones que funcionan dentro de estas limitaciones en lugar de pretender superarlas. El patrón Saga es nuestra forma de bailar con la entropía en lugar de luchar contra ella.

Cuando se habla de seguridad en el contexto de una aplicación, la conversación casi siempre gira en torno a las capas visibles: el cifrado en tránsito, las políticas de contraseñas, los tokens de autenticación. Son piezas visibles e importantes, pero debajo de todas ellas existe una estructura que determina si un sistema IAM puede sostenerse en producción o si eventualmente colapsará bajo su propia complejidad. Esa estructura es el modelo de datos.

Diseñar una base de datos para gestionar identidad, autenticación y autorización no es simplemente crear una tabla de usuarios con nombre, email y contraseña. Es resolver, desde el nivel más fundamental, preguntas como: ¿quién es una entidad dentro del sistema? ¿cómo demuestra que es quien dice ser? ¿qué puede hacer? ¿a qué organización pertenece? Y hacerlo de una forma que no requiera rediseños costosos cuando la aplicación crezca de diez usuarios a diez millones.

Este artículo explora un modelo de datos completo para IAM, desde sus principios arquitectónicos más fundamentales hasta las decisiones de implementación que determinan si el sistema puede escalar, cumplir requisitos de seguridad en producción y adaptarse a entornos enterprise sin romperse en el proceso.

La separación entre identidad y autenticación

El punto de partida de todo el modelo es una decisión que parece obvia pero que la mayoría de las implementaciones no respetan: la identidad de una entidad y el mecanismo por el cual se autentica son dos cosas completamente distintas.

En la práctica, esto se traduce en separar el concepto de actor del concepto de cuenta de acceso. Un actor es cualquier entidad que existe en el sistema: una persona, una empresa cliente, un bot interno, un proveedor externo. Una cuenta de acceso es el mecanismo que permite a ese actor demostrarlo cuando lo necesita. Y la clave es que no todos los actores necesitan una cuenta.

Piense en el escenario de una plataforma SaaS donde un usuario registra una empresa como cliente. En ese momento la empresa existe como entidad en el sistema, tiene datos de contacto y puede ser referenciada desde otros registros. Pero quizás nadie en esa empresa necesita ingresar al sistema aún. Si el modelo obligara a crear una cuenta de autenticación cada vez que se crea una entidad, ese escenario sería imposible sin truismos como usuarios ficticios o campos nulos que van acumulando deuda técnica.

La tabla actor en el modelo es deliberadamente mínima: un identificador único, un tipo de entidad y un nombre. Todo lo demás se construye a partir de ahí.

CREATE TABLE actor (
    actor_id     UUIDv7       PRIMARY KEY,
    tipo_actor   UUIDv7       NOT NULL REFERENCES actor_tipo(tipo_id),
    nombre       VARCHAR(256) NOT NULL,
    eliminado_en TIMESTAMP    NULL
);

El campo eliminado_en merece una mención especial porque representa otra decisión fundamental: estas entidades nunca se eliminan físicamente en producción. En lugar de borrar un registro, se marca con una fecha lógica de eliminación. La razón es pragmática: la tabla de auditoría va a referenciar este actor durante años. Si el registro desapareciera, esa referencia estaría rota, y con ella cualquier intento de reconstruir qué sucedió y cuándo. Además, regulaciones como el GDPR exigen retención de datos por períodos definidos, lo cual es imposible si ya no existen.

Los datos específicos de cada tipo de actor se almacenan por separado, en tablas que se relacionan al actor mediante una clave foránea que es simultáneamente clave primaria. Así, la información de una persona natural —nombre, apellidos— vive en actor_persona, los documentos de identidad en actor_documento, y los contactos en tablas propias para correos, teléfonos y direcciones. Cada uno de estos, además, soporta múltiples valores con un campo de contexto que distingue entre un correo personal, uno laboral o uno de facturación, sin que la aplicación tenga que adivinar cuál usar según la circunstancia.

Por qué UUIDv7 y no otro identificador

Una decisión que atraviesa todo el modelo es el uso de UUIDv7 como identificador primario en todas las tablas principales. Es una elección que tiene consecuencias concretas en rendimiento y operación, no solo en diseño.

El problema con usar valores como el email o el número de documento como clave es simple: cambian. Un usuario puede cambiar su correo electrónico mañana. Si ese email era la clave que todos los otros registros usaban para referirlo, cada uno de ellos necesitaría actualizarse en cascada, con el riesgo de inconsistencias y la costosa operación de actualizar claves foráneas en decenas de tablas.

UUIDv4, el estándar más común, resuelve eso: genera identificadores únicos que no cambian. Pero UUIDv7 va un paso más allá. Sus primeros 48 bits contienen un timestamp del momento de creación. Eso tiene dos efectos inmediatos en la base de datos.

El primero es de rendimiento. Los índices B-tree, que son la estructura por defecto en la gran mayoría de bases de datos relacional, se mantienen ordenados por el valor de la clave. Con UUIDv7, ese orden es automáticamente cronológico. En una tabla como la de auditoría, que puede crecer a millones de filas por día, las consultas que buscan los eventos de las últimas 24 horas no necesitan un sort adicional: los datos ya están en ese orden físicamente.

El segundo es de operación diaria. Cuando un desarrollador ve un ID en un log de producción a las 3 de la mañana investigando un incidente, con UUIDv7 puede derivar aproximadamente cuándo fue creado ese registro sin tener que ir a la base de datos. Es un detalle pequeño, pero en las situaciones de mayor presión esos detalles marcan la diferencia entre resolver un problema en minutos o en horas.

La cuenta y sus credenciales

La cuenta de acceso (cuenta_acceso) es el puente entre un actor y el sistema de autenticación. Se crea únicamente cuando el actor necesita autenticarse, y contiene los campos que el sistema necesita para controlar el acceso en tiempo real: el estado de la cuenta, un contador de intentos fallidos consecutivos y una fecha de bloqueo automático.

CREATE TABLE cuenta_acceso (
    cuenta_id                      UUIDv7      PRIMARY KEY,
    actor_id                       UUIDv7      NOT NULL REFERENCES actor(actor_id),
    estado                         VARCHAR(20) NOT NULL DEFAULT 'activa',
    intentos_fallidos_consecutivos INT         NOT NULL DEFAULT 0,
    bloqueada_hasta                TIMESTAMP   NULL,
    creado_en                      TIMESTAMP   NOT NULL DEFAULT NOW(),
    eliminado_en                   TIMESTAMP   NULL
);

El diseño de los campos de lockout en esta tabla no es accidental. El contador intentos_fallidos_consecutivos se incrementa con cada fallo y se reinicia al cero en cada login exitoso. Cuando supera el umbral configurado por la organización —por defecto cinco intentos— el sistema calcula una fecha de bloqueo y la escribe en bloqueada_hasta. Desde ese momento, cualquier intento de login contra esa cuenta falla automáticamente hasta que la fecha pase. Este mecanismo es necesario para defender contra ataques de fuerza bruta, pero el umbral y la duración del bloqueo no están hardcoded: cada organización puede configurarlos de forma independiente según sus requisitos de seguridad.

Las credenciales reales viven en una tabla separada, cuenta_credencial, y aquí el modelo hace otra cosa interesante. Una sola cuenta puede tener varias credenciales simultáneamente. Un usuario puede entrar con contraseña local, conectar su cuenta de Google y usar SAML corporativo, todo bajo la misma cuenta. Cada credencial tiene un campo proveedor que indica de dónde viene —LOCAL, GOOGLE, SAML— y el sistema sabe cómo procesar cada una según ese valor.

CREATE TABLE cuenta_credencial (
    credencial_id   UUIDv7       PRIMARY KEY,
    cuenta_id       UUIDv7       NOT NULL REFERENCES cuenta_acceso(cuenta_id),
    proveedor       VARCHAR(40)  NOT NULL,
    identificador  VARCHAR(320) NOT NULL,
    secreto_hash    VARCHAR(256) NULL,
    algoritmo_hash  VARCHAR(40)  NULL,
    parametros_hash JSONB        NULL,
    creado_en       TIMESTAMP    NOT NULL DEFAULT NOW(),
    UNIQUE (cuenta_id, proveedor, identificador)
);

Para las credenciales locales, la contraseña se almacena como hash —nunca en texto plano— y junto a ella se guardan dos campos que habitualmente se olvidan: algoritmo_hash y parametros_hash. La razón de su existencia tiene que ver con un problema real que aparece cuando una aplicación madura. En el momento en que el sistema decide migrar de bcrypt a Argon2id —algo que eventualmente todo sistema serio debe hacer— no es posible invalidar todas las contraseñas de la base de datos de una vez. La solución es lo que se conoce como migración lazy: cuando un usuario hace login, si su hash fue generado con un algoritmo antiguo, el sistema lo regenera con el algoritmo actual sin pedir que el usuario cambie su contraseña. Para que eso funcione, el sistema necesita saber exactamente qué algoritmo y qué parámetros usó para generar cada hash. De ahí vienen esos dos campos.

Sesiones, tokens y el problema de la revocación

Una vez que un usuario se autentica exitosamente, el sistema crea una sesión. La sesión es el registro que representa una instancia activa de uso desde un dispositivo específico, y es el lugar donde vive una de las decisiones más importantes del modelo desde el punto de vista de seguridad.

CREATE TABLE cuenta_sesion (
    sesion_id      UUIDv7      PRIMARY KEY,
    cuenta_id      UUIDv7      NOT NULL REFERENCES cuenta_acceso(cuenta_id),
    version        BIGINT      NOT NULL DEFAULT 1,
    dispositivo_id UUIDv7      NULL REFERENCES cuenta_dispositivo(dispositivo_id),
    creada_en      TIMESTAMP   NOT NULL DEFAULT NOW(),
    expira_en      TIMESTAMP   NOT NULL,
    ip             INET        NOT NULL,
    user_agent     TEXT        NOT NULL
);

El campo version es el que hace la diferencia. En un sistema típico que usa JWT —JSON Web Tokens— como mecanismo de autenticación por token, cada access token tiene una duración fija, por ejemplo quince minutos. Si un token es robado, el sistema no puede invalidarlo antes de que llegue a expirar: el token es autosuficiente por diseño. Durante esos quince minutos, el token robado es completamente válido. En una cuenta que ha sido comprometida, quince minutos pueden ser más que suficientes para causas daños significativos.

La solución que implementa este modelo es elegante en su simplicidad. Cada access token emitido incluye la versión actual de la sesión en su payload. Cuando el usuario realiza una acción que debe invalidar sus tokens —cambiar contraseña, habilitar MFA, cerrar sesión remota— el sistema simplemente incrementa la versión en la base de datos. El middleware de autenticación compara la versión del token con la versión almacenada. Si no coinciden, el token es rechazado inmediatamente, en milisegundos, sin esperar a que expiré.

Los refresh tokens operan en un esquema complementario. Son de duración larga —hasta treinta días— y su propósito es permitir obtener nuevos access tokens sin que el usuario vuelva a ingresar sus credenciales. La tabla cuenta_refresh_token incluye un campo que vale la pena destacar: reemplazado_por. Cuando un refresh token se rota —lo cual debe ocurrir cada vez que se genera un nuevo access token— el antiguo apunta al nuevo mediante ese campo. Esto crea una cadena auditable, pero más importante, permite detectar ataques. Si alguien roba un refresh token y lo usa después de que ya fue rotado, el sistema detecta que el token de la cadena ya fue reemplazado y puede revocar toda la sesión.

Protección contra ataques y el arte de no revelar demasiado

El control de intentos de login es donde la seguridad se enfrenta directamente con la experiencia del usuario, y donde las decisiones de diseño en la base de datos tienen consecuencias de seguridad reales.

CREATE TABLE cuenta_intento_login (
    intento_id     UUIDv7       PRIMARY KEY,
    cuenta_id      UUIDv7       NULL REFERENCES cuenta_acceso(cuenta_id),
    identificador  VARCHAR(320) NOT NULL,
    exito          BOOLEAN      NOT NULL,
    ip             INET         NOT NULL,
    user_agent     TEXT         NOT NULL,
    motivo_fallo   VARCHAR(64)  NULL,
    creado_en      TIMESTAMP    NOT NULL DEFAULT NOW()
);

El detalle más sutil de esta tabla es que cuenta_id es nulable. Cuando alguien intenta hacer login con un email que no existe en el sistema, el registro se crea con cuenta_id = NULL. La razón tiene que ver con un ataque conocido como enumeración de usuarios: si el sistema respondiera de forma diferente ante un email no registrado versus una contraseña incorrecta, un atacante podría ir probando emails hasta confirmar cuáles están registrados. Al registrar todos los intentos de forma uniforme, independientemente de si la cuenta existe o no, y al no distinguir entre tipos de error en la respuesta al cliente, el sistema cierra esa puerta.

El campo motivo_fallo almacena la información detallada del fallo, pero esta información es para uso interno exclusivamente. El sistema nunca la retorna al cliente: desde afuera, un fallo es simplemente un fallo, sin distingos. Es un patrón que aparece repetido en varios lugares del modelo, esta idea de que hay información que el sistema necesita almacenar para su propia operación pero que no debe revelar hacia afuera.

El lockout funciona en dos niveles independientes. El primero es por cuenta: cuando los intentos fallidos consecutivos supera el umbral, la cuenta se bloquea por un período configurable. El segundo es por IP: si una misma dirección IP genera demasiados intentos fallidos contra cuentas diferentes en un período corto, se activa rate limiting a nivel de red. Ese segundo nivel es el que detecta credential stuffing, uno de los ataques más comunes hoy.

Políticas de contraseña como modelo de datos

Las políticas de contraseñas en la mayoría de las aplicaciones se implementan como constantes en el código: mínimo ocho caracteres, debe tener mayúscula, debe tener número. El problema con ese enfoque es que es imposible auditorlo, imposible que cada organización tenga requisitos diferentes, y requiere un deploy cada vez que cambie una regla.

En este modelo las políticas son una tabla en sí misma, con un campo tenant_id nulable que determina su alcance. Si es NULL, es la política global que aplica a todos; si tiene valor, es específica de esa organización y tiene prioridad.

CREATE TABLE politica_password (
    politica_id         UUIDv7      PRIMARY KEY,
    tenant_id           UUIDv7      NULL REFERENCES tenant(tenant_id),
    min_longitud        INT         NOT NULL DEFAULT 12,
    max_longitud        INT         NOT NULL DEFAULT 128,
    requiere_mayuscula  BOOLEAN     NOT NULL DEFAULT TRUE,
    requiere_minuscula  BOOLEAN     NOT NULL DEFAULT TRUE,
    requiere_numeros    BOOLEAN     NOT NULL DEFAULT TRUE,
    requiere_especiales BOOLEAN     NOT NULL DEFAULT TRUE,
    max_edad_dias       INT         NULL,
    historial_prohibido INT         NOT NULL DEFAULT 5,
    creado_en           TIMESTAMP   NOT NULL DEFAULT NOW()
);

El campo historial_prohibido merece explicación porque implica la existencia de otra tabla: cuenta_historial_password. Cuando un usuario cambia su contraseña, el sistema necesita verificar que la nueva no coincida con las últimas N que tuvo. Para poder hacer esa comparación, los hashes de las contraseñas anteriores deben estar almacenados en algún lugar. En esa tabla, junto con cada hash antiguo se guardan también el algoritmo y los parámetros que fueron usados para generarlo, por la misma razón de compatibilidad que ya mencionamos: el algoritmo puede haber cambiado entre cuando se creó ese hash y el momento en que se necesita compararlo.

El límite máximo de longitud, que a primera vista parece arbitrario, tiene una razón de seguridad: una contraseña extremadamente larga puede usarse para un ataque de denegación de servicio, ya que calcular el hash de una cadena de miles de caracteres consume recursos significativos.

Multi-tenancy: aislamiento sin multiplicar la base de datos

Cuando una aplicación necesita servir a múltiples organizaciones independientes, la tentación es crear una base de datos separada por cada una. Es la solución más aislada, pero también la más costosa en operación: N bases de datos significan N planes de backup, N procesos de monitoreo, N niveles de mantenimiento.

El modelo propone la alternativa estándar en la industria: una sola base de datos compartida donde cada organización —llamada tenant— tiene sus datos lógicamente aislados mediante una clave tenant_id que atraviesa todas las tablas relevantes.

CREATE TABLE tenant (
    tenant_id     UUIDv7       PRIMARY KEY,
    nombre        VARCHAR(256) NOT NULL,
    estado        VARCHAR(20)  NOT NULL DEFAULT 'activo',
    plan          VARCHAR(64)  NULL,
    configuracion JSONB        NULL,
    creado_en     TIMESTAMP    NOT NULL DEFAULT NOW(),
    eliminado_en  TIMESTAMP    NULL
);

Un actor puede ser miembro de múltiples tenants simultáneamente, lo cual refleja la realidad de consultores o profesionales que trabajan con varias empresas. La membresía se gestiona en tenant_miembro, y las invitaciones en tenant_invitacion, donde tanto el email del invitado como el token de validación se almacenan como hash. Esto evita que alguien con acceso directo a la base de datos pueda enumerar qué emails tienen invitaciones pendientes en cada organización, un vector de ataque que suena teórico hasta que alguien lo explota.

Cada organización puede además tener sus propios requisitos de seguridad: cuántos intentos fallidos se permiten antes del lockout, si el MFA es obligatorio, qué métodos de MFA están permitidos, cuál es la política de contraseñas. Todas estas configuraciones se almacenan en tablas de configuración por tenant, lo cual significa que una organización enterprise puede exigir FIDO2 como único método de MFA mientras otra más pequeña se conforma con TOTP, sin que eso afecte al resto del sistema.

Autorización por roles y grupos

El módulo de autorización implementa RBAC, Role-Based Access Control, con una extensión importante: soporte para grupos organizacionales. La estructura básica es la clásica: roles que contienen permisos, y usuarios que tienen roles asignados. Pero la realidad de las organizaciones grandes no funciona así de simple.

En una empresa real, los permisos no se asignan uno por uno a cada persona. Se asignan por departamento, por unidad organizacional. Cuando un nuevo empleado entra al área de finanzas, debería recibir automáticamente los permisos que corresponden a esa función, sin que un administrador los configure manualmente uno por uno.

Para resolver eso, el modelo incluye una capa de grupos dentro de cada tenant. Un grupo como "Finanzas" tiene asignado el rol CONTADOR. Cuando alguien se agrega al grupo, hereda automáticamente todos los permisos de ese rol. Si además necesita algo extra —un permiso que no aplica a todo el grupo— se le asigna un rol adicional a nivel individual mediante la tabla miembro_rol. Las dos vías coexisten sin conflicto.

CREATE TABLE tenant_grupo (
    grupo_id    UUIDv7       PRIMARY KEY,
    tenant_id   UUIDv7       NOT NULL REFERENCES tenant(tenant_id),
    nombre      VARCHAR(128) NOT NULL,
    descripcion VARCHAR(256) NULL,
    UNIQUE (tenant_id, nombre)
);

La restricción UNIQUE (tenant_id, nombre) es un detalle que evita un error de diseño frecuente: que dos grupos con el mismo nombre existan en la misma organización, lo cual generaría confusión tanto en la interfaz administrativa como en la lógica de asignación.

Delegación temporal y dispositivos confiables

Hay dos escenarios frecuentes en organizaciones que RBAC por sí solo no resuelve. El primero es la delegación temporal: un manager que se va de vacaciones y necesita que alguien apruebe en su lugar durante dos semanas. El segundo es la experiencia del usuario en sistemas con MFA: si ya completaste la verificación en tu laptop esta mañana, no deberías tener que hacerlo de nuevo cada quince minutos.

La delegación se implementa mediante delegacion_permiso, una tabla que tiene una fecha de inicio y una fecha de fin obligatoria. No existen delegaciones perpetuas en el modelo, y es una decisión consciente: cualquier delegación sin límite temporal es un riesgo de seguridad que eventualmente alguien olvidará revocar. La delegación puede ser un rol completo —"durante mis vacaciones, esta persona actúa como aprobador"— o permisos individuales —"solo necesita firmar esta factura específica".

Los dispositivos confiables funcionan con un concepto de fingerprint: una combinación de browser, sistema operativo y otros atributos del dispositivo, almacenada como hash. Cuando un usuario completa MFA exitosamente en un dispositivo y acepta marcarlo como confiable, el sistema crea un registro con una fecha de expiración de la confianza —configurada por tenant. En logins futuros desde ese mismo dispositivo, si la confianza aún no ha expirado, el paso de MFA se omite automáticamente.

CREATE TABLE cuenta_dispositivo (
    dispositivo_id  UUIDv7       PRIMARY KEY,
    cuenta_id       UUIDv7       NOT NULL REFERENCES cuenta_acceso(cuenta_id),
    fingerprint     VARCHAR(256) NOT NULL,
    nombre          VARCHAR(128) NULL,
    confiable       BOOLEAN      NOT NULL DEFAULT FALSE,
    confiable_hasta TIMESTAMP    NULL,
    creado_en       TIMESTAMP    NOT NULL DEFAULT NOW(),
    ultimo_uso_en   TIMESTAMP    NOT NULL DEFAULT NOW(),
    UNIQUE (cuenta_id, fingerprint)
);

El campo ultimo_uso_en tiene un propósito de seguridad que no es inmediatamente obvio: permite mostrar al usuario cuándo fue usado cada dispositivo registrado, lo cual es la mecanismo por el cual un usuario puede detectar que alguien más está usando su cuenta desde un dispositivo que no reconoce.

Extensiones enterprise: SSO, SCIM y ABAC

Cuando una aplicación necesita integrarse con el ecosistema de identidad corporativo existente —Active Directory, Okta, Azure AD— el modelo incluye las tablas necesarias para eso sin rediseñar lo que ya existe.

SSO se implementa mediante cuenta_identidad_externa, que vincula una cuenta del sistema con un identificador externo proporcionado por el proveedor de identidad corporativo. SCIM, el estándar de provisioning automático, agrega otra dimensión: cuando un empleado se crea o elimina en el directorio corporativo, los cambios se reflejan automáticamente en el sistema. La tabla scim_provisioning registra el estado de cada usuario sincronizado y sus metadatos, los cuales pueden ser usados por las políticas ABAC.

ABAC —Attribute-Based Access Control— es la extensión más potente del sistema de autorización. En lugar de depender únicamente de roles estáticos, permite definir políticas basadas en atributos dinámicos tanto del usuario como del recurso.

CREATE TABLE politica_abac (
    politica_id UUIDv7       PRIMARY KEY,
    tenant_id   UUIDv7       NULL REFERENCES tenant(tenant_id),
    nombre      VARCHAR(128) NOT NULL,
    expresion   TEXT         NOT NULL,
    efecto      VARCHAR(10)  NOT NULL,
    activa      BOOLEAN      NOT NULL DEFAULT TRUE,
    creado_en   TIMESTAMP    NOT NULL DEFAULT NOW()
);

Una política ABAC puede expresar reglas como "permitir el acceso si el departamento del usuario coincide con el departamento del recurso y el nivel del usuario es mayor o igual a 2". El campo expresion debe estar en un lenguaje controlado evaluado por un motor dedicado —como OPA con Rego— y no como texto libre, precisamente para evitar que esas expresiones sean vectores de inyección y para poder testarlas de forma aislada antes de ponerlas en producción.

Auditoría: el registro que no puede faltar

La tabla de auditoría es el componente que conecta todo el modelo con los requisitos de compliance. Cada evento de seguridad que ocurre en el sistema —login, logout, cambio de contraseña, creación de usuario, modificación de roles— se registra aquí con el actor que realizó la acción, el actor afectado si es diferente, el tenant en cuyo contexto ocurrió, y metadatos adicionales.

CREATE TABLE auditoria_seguridad (
    evento_id         UUIDv7       PRIMARY KEY,
    actor_id          UUIDv7       NOT NULL REFERENCES actor(actor_id),
    actor_afectado_id UUIDv7       NULL REFERENCES actor(actor_id),
    tenant_id         UUIDv7       NULL REFERENCES tenant(tenant_id),
    accion            VARCHAR(64)  NOT NULL,
    objeto_tipo       VARCHAR(64)  NULL,
    objeto_id         VARCHAR(256) NULL,
    fecha             TIMESTAMP    NOT NULL DEFAULT NOW(),
    ip                INET         NULL,
    user_agent        TEXT         NULL,
    metadata          JSONB        NULL
) PARTITION BY RANGE (fecha);

El detalle más importante desde el punto de vista de operación es la última línea: PARTITION BY RANGE (fecha). Esta tabla puede crecer a millones de filas por día en un sistema de actividad moderada. Sin partitioning, las consultas de auditoría se convierten en sequential scans que se vuelven más lentas semana tras semana hasta que el sistema necesita una intervención de emergencia. Con partitioning por mes, cada consulta solo escanea la partición relevante. Las particiones antiguas —más de doce meses— se archivan a almacenamiento frío y se eliminan de la base activa, manteniendo el tamaño operacional manejable.

Cifrado y clasificación de datos

No todos los datos requieren el mismo nivel de protección, y el modelo reconoce eso con una clasificación en cuatro niveles. Los datos críticos como hashes de contraseñas y tokens nunca se almacenan en texto plano. Los datos de identidad personal —email, teléfono, documento— se cifran en reposo a nivel de columna mediante cifrado a nivel de aplicación con AES-256-GCM, con las claves de cifrado almacenadas en un KMS externo, no en la base de datos.

Para campos PII que necesitan ser buscables, como el email, el modelo propone almacenar junto al valor cifrado un hash determinístico separado. El hash permite hacer búsquedas —"¿existe un usuario con este email?"— sin que la base de datos contenga el email en texto plano. Es un patrón que aparece también en las invitaciones y en los tokens de refresh.

Índices estratégicos

Los índices son donde el modelo pasa de ser un diseño teórico a ser un sistema que puede operar en producción. Las queries más frecuentes en un sistema IAM son predecibles: login, verificación de permisos, búsqueda de sesiones activas, consultas de auditoría. Sin los índices correctos para cada una de estas operaciones, cada request adicional de un usuario se convierte en un scan secuencial que crece linealmente con el tamaño de la tabla.

-- Login: el camino crítico de cada autenticación
CREATE UNIQUE INDEX idx_credencial_proveedor_identificador
    ON cuenta_credencial (proveedor, identificador);

-- Sesiones: buscar y limpiar sesiones expiradas
CREATE INDEX idx_sesion_cuenta_expira
    ON cuenta_sesion (cuenta_id, expira_en);

-- Intentos: detectar ataques por IP (los más recientes primero)
CREATE INDEX idx_intento_ip_fecha
    ON cuenta_intento_login (ip, creado_en DESC);

-- Auditoría: queries de compliance por actor
CREATE INDEX idx_auditoria_actor_fecha
    ON auditoria_seguridad (actor_id, fecha DESC);

-- Auditoría: queries de compliance por tenant
CREATE INDEX idx_auditoria_tenant_fecha
    ON auditoria_seguridad (tenant_id, fecha DESC);

El orden de las columnas en los índices compuestos no es arbitrario. En un índice como (tenant_id, actor_id), la primera columna debe ser la que aparece más frecuentemente en las condiciones de búsqueda. Como las queries siempre filtran por organización antes de filtrar por usuario, tenant_id va primero. Los índices DESC en columnas de fecha evitan que la base de datos necesite ordenar los resultados después de buscarlos cuando la query busca los últimos N registros.

Crecimiento progresivo sin rediseños

Una de las frustraciones más comunes al diseñar sistemas IAM es que la arquitectura inicial no anticipa la complejidad futura y eventualmente requiere rediseños que costo tiempo y dinero. Este modelo resuelve esa fricción con una estratificación por niveles de implementación.

El nivel más básico —login con email y contraseña— requiere apenas las tablas de actor, cuenta, credencial, intentos y política de contraseñas. Es suficiente para una aplicación interna pequeña. A partir de ahí, cada nivel agrega las tablas correspondientes sin modificar las existentes: sesiones y MFA para aplicaciones modernas, roles para paneles administrativos, tenants y grupos para plataformas SaaS, y finalmente SSO, SCIM, ABAC y OAuth para entornos enterprise.

Esta progresión no es solo teórica. Cada tabla en el modelo fue diseñada con las relaciones futuras en mente, de modo que agregar el nivel siguiente es una operación aditiva, no una refactorización. La clave que habilita eso es la separación original entre actor y cuenta, y el uso de identificadores inmutables que no cambian independientemente de cuántas tablas se agreguen después.

Líneas futuras y consideraciones de madurez

El modelo que se describe aquí cubre las necesidades de la gran mayoría de aplicaciones desde un login básico hasta un sistema enterprise. Sin embargo, existen áreas donde la complejidad puede crecer más allá de lo que un modelo relacional estándar puede manejar eficientemente.

La primera es la verificación de permisos en tiempo real en sistemas de alta concurrencia. Cuando la cantidad de roles, grupos y políticas ABAC crecen significativamente, la consulta que determina si un actor puede realizar una acción puede volverse costosa. Una línea de investigación viable es implementar una capa de caché —Redis o similar— que almacene las resoluciones de permisos por actor y se invalide cuando ocurren cambios en roles o políticas. La tabla de auditoría puede ser el trigger para esa invalidación.

La segunda área es la escalabilidad horizontal de la tabla de auditoría. Aunque el partitioning por fecha resuelve el problema de crecimiento a mediano plazo, en sistemas con millones de eventos diarios puede ser necesario considerar la migración de datos históricos a un almacenamiento analítico separado —un data warehouse o un sistema de búsqueda como Elasticsearch— mientras que la base relacional retiene solo los datos activos necesarios para la operación.

Finalmente, la evolución hacia modelos de identidad decentralizada —DID, credenciales verificables— es una dirección que la industria está explorando activamente. El modelo actual, al separar la identidad del mecanismo de autenticación desde el principio, tiene la estructura necesaria para adaptarse a esos cambios sin rediseño fundamental. Es otra prueba de que las decisiones arquitectónicas correctas no solo resuelven los problemas de hoy, sino que reducen la fricción de los cambios que vienen después.

Docker Compose ha democratizado el despliegue de aplicaciones gracias a una premisa seductora: la simplicidad. Con un archivo YAML y un comando, servicios complejos cobran vida, interconectados y listos para operar. Sin embargo, esta abstracción, que es su mayor virtud para la productividad, suele convertirse en su talón de Aquiles en términos de seguridad. Por defecto, Docker Compose crea una red default donde todos los contenedores pueden comunicarse libremente entre sí. En este escenario, si no se define una arquitectura de red explícita, se genera un entorno de confianza total implícita: el frontend tiene línea directa con la base de datos, y servicios auxiliares pueden ver componentes críticos sin necesidad alguna.

Si bien al inicio del desarrollo esto facilita la integración, en producción plantea una vulnerabilidad crítica conocida como movimiento lateral. La pregunta que debemos hacernos no es si el sistema funciona, sino: en caso de que un componente periférico sea comprometido, ¿qué alcance tendría el atacante? En la mayoría de las configuraciones estándar, la respuesta es alarmante: acceso total a la red interna del stack.

La arquitectura que exploraremos a continuación propone desmantelar esa confianza implícita. Adoptaremos un enfoque de Zero Trust (Confianza Cero) aplicado a la orquestación de contenedores, donde ningún servicio tiene permiso de comunicación por defecto y cada ruta de red debe estar justificada por una necesidad funcional estricta.

El Principio de la Puerta Única: Centralización del Acceso

Para visualizar la seguridad perimetral, podemos imaginar la infraestructura como una fortaleza. En un diseño ingenuo o descuidado, cada torre (servicio) tendría su propia puerta hacia el exterior, multiplicando los puntos de entrada y dificultando la vigilancia. La primera decisión de arquitectura segura es clausurar todos esos accesos directos y establecer un único punto de entrada, fuertemente vigilado.

En el ecosistema de contenedores, este rol lo desempeña el Proxy Inverso.

Este componente actúa como la única entidad autorizada para interactuar con la red pública (Internet). Reside en una red externa ("public") y su única función es recibir el tráfico, validarlo (potencialmente gestionando SSL/TLS) y enrutarlo hacia el interior. Desde la perspectiva externa, no existen bases de datos, ni backends, ni APIs internas; solo existe el proxy. Esta reducción de la superficie de ataque es fundamental: aunque un atacante escanee el host, solo encontrará los puertos estrictamente necesarios (80/443) abiertos por un servicio diseñado específicamente para manejar tráfico hostil.

Aislamiento Horizontal: Ciudades Amuralladas

Al escalar la infraestructura, es común alojar múltiples aplicaciones (o "stacks") en el mismo host. Un error frecuente es permitir que estos stacks compartan redes globales, lo que crearía "carreteras" invisibles entre proyectos que no tienen relación entre sí.

Para mitigar esto, debemos tratar cada aplicación como una "ciudad independiente". Aunque compartan el mismo territorio físico (el servidor host), no deben existir caminos directos entre ellas. Docker Compose facilita este aislamiento mediante el concepto de Namespacing en las redes. Al definir redes específicas dentro de cada docker-compose.yml, el orquestador prefija los nombres de red con el nombre del proyecto. Esto garantiza que la red interna del "Proyecto A" sea criptográficamente distinta e inaccesible para el "Proyecto B", asegurando que un compromiso en una aplicación no se propague horizontalmente a otras vecinas.

Segmentación Vertical: Barrios con Acceso Controlado

Dentro de cada "ciudad" o stack, la seguridad debe ser granular. No basta con estar dentro del perímetro para ser confiable. Aquí aplicamos una arquitectura de capas, dividiendo la aplicación según la sensibilidad de los datos y la función de los componentes: Frontend (recepción), Backend (lógica) y Datos (bóveda).

La Recepción: El Frontend y la Red Pública

El servicio de frontend es el único que mantiene contacto con el Proxy. Su ubicación es estratégica: tiene un pie en la red pública (para recibir tráfico del proxy) y un pie en una red privada interna para comunicarse con el backend. Sin embargo, carece totalmente de acceso a la capa de datos. Si un atacante lograra vulnerar el frontend, se encontraría en un callejón sin salida respecto a la base de datos, ya que no existe una ruta de red física (virtualizada) para alcanzarla.

La Sala de Control: El Backend como Intermediario

El backend opera en una zona de penumbra controlada. No es accesible desde internet, no expone puertos al host y solo acepta tráfico proveniente de la red front-back. A su vez, es el único componente autorizado para iniciar conexiones hacia la red back-db. Actúa como un guardia de lógica de negocio, validando cada petición antes de solicitar información a la capa de persistencia.

La Bóveda: Aislamiento de la Base de Datos

La base de datos reside en la zona más profunda de la arquitectura. Su aislamiento es tal que ni el proxy ni el frontend saben de su existencia; la resolución de nombres DNS de Docker ni siquiera les permitirá resolver su dirección IP. Además, para elevar el nivel de seguridad, es recomendable configurar las redes de datos con la propiedad internal: true. Esta directiva de Docker impide que los contenedores en esa red tengan acceso a la puerta de enlace predeterminada hacia internet, evitando que un posible malware en la base de datos pueda "llamar a casa" o exfiltrar datos hacia el exterior.

Implementación Técnica: La Configuración como Documentación

La teoría de la segmentación cobra sentido cuando se materializa en código. A continuación, se presenta una implementación de referencia que orquesta un proxy global y dos aplicaciones (stacks) totalmente aisladas entre sí, demostrando cómo la topología de red define las políticas de seguridad.

1. El Stack del Proxy: La Frontera

Este servicio define la red pública compartida. Su configuración es minimalista, enfocada únicamente en la exposición de puertos.

version: "3.9"

services:
  proxy:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    networks:
      - public
    # En un escenario real, aquí se montarían volúmenes para certificados y configuración.

networks:
  public:
    name: public_gateway # Nombre explícito para que otros stacks la encuentren

2. Stack A: Aplicación con Arquitectura de Tres Capas

Este archivo demuestra la segmentación interna. Nótese cómo frontend, backend y db nunca comparten una red común los tres a la vez. La comunicación es estrictamente transitiva.

version: "3.9"

services:
  frontend:
    image: nginx:alpine
    networks:
      - public      # Para hablar con el Proxy
      - front_back  # Para hablar con el Backend
    depends_on:
      - backend

  backend:
    image: node:18-alpine
    networks:
      - front_back  # Recibe del Frontend
      - back_db     # Consulta a la DB
    # No expone puertos al host. Su seguridad radica en su invisibilidad externa.

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_PASSWORD: example_secure_password
    networks:
      - back_db     # Solo accesible por el Backend

networks:
  public:
    external: true  # Se conecta a la red creada por el Proxy
    name: public_gateway
  front_back:
    internal: true  # Opcional: restringe salida a internet si no se requieren APIs externas
  back_db:
    internal: true  # Crítico: La DB no necesita acceso a internet

3. Stack B: Aislamiento por Diseño

Al replicar la estructura para una segunda aplicación, Docker Compose garantiza el aislamiento. Aunque los nombres de las redes internas (front_back, back_db) sean idénticos en el archivo YAML, el motor de Docker les asigna identificadores únicos basados en el proyecto.

version: "3.9"

services:
  # La estructura es idéntica, pero el contexto de ejecución es estanco.
  frontend:
    image: nginx:alpine
    networks:
      - public
      - front_back

  backend:
    image: python:3.10-alpine
    networks:
      - front_back
      - back_db

  db:
    image: redis:alpine
    networks:
      - back_db

networks:
  public:
    external: true
    name: public_gateway
  front_back:
    internal: true
  back_db:
    internal: true

En este esquema, el backend del Stack A intentando resolver el DNS db obtendrá la IP de su propia base de datos Postgres, y jamás la del Redis del Stack B. No hay posibilidad de colisión ni de acceso cruzado accidental.

Conclusiones y Horizonte de Evolución

El diseño de red en Docker Compose no debe considerarse una tarea de configuración trivial, sino la base fundacional de la seguridad de la aplicación. Al pasar de una red plana por defecto a una topología segmentada, logramos:

1. Reducción de la Superficie de Ataque: Limitamos drásticamente qué contenedores son accesibles desde el exterior.
2. Contención de Daños: Un servicio comprometido queda atrapado en su segmento de red, protegiendo la integridad de la base de datos y de otros stacks vecinos.
3. Claridad Operativa: La arquitectura de red documenta por sí misma el flujo de datos de la aplicación.

Este modelo establece una base sólida sobre la cual construir medidas de seguridad más avanzadas. Como líneas futuras de mejora, esta arquitectura prepara el terreno para implementar mTLS (Mutual TLS) entre contenedores, asegurando no solo que la red sea la correcta, sino que el servicio interlocutor sea quien dice ser mediante certificados criptográficos. Asimismo, facilita la integración de herramientas de escaneo de vulnerabilidades y la gestión de secretos (Docker Secrets), cerrando el círculo de una estrategia de defensa en profundidad moderna y resiliente.

   graph TB
      subgraph Internet["🌐 Internet"]
         EXT[External Users]
      end

  subgraph PublicNetwork["Public Network (bridge)"]
     PROXY[("🔀 Reverse Proxy<br/>(NGINX/Traefik)")]
  end

  subgraph StackA["Stack A"]
     subgraph NetworkFB_A["Network: front-back-a"]
           FRONT_A["📱 Front A"]
           BACK_A["⚙️ Back A"]
     end
     subgraph NetworkBD_A["Network: back-db-a"]
           BACK_A2["⚙️ Back A"]
           DB_A[("💾 DB A")]
     end
  end

  subgraph StackB["Stack B"]
     subgraph NetworkFB_B["Network: front-back-b"]
           FRONT_B["📱 Front B"]
           BACK_B["⚙️ Back B"]
     end
     subgraph NetworkBD_B["Network: back-db-b"]
           BACK_B2["⚙️ Back B"]
           DB_B[("💾 DB B")]
     end
  end

  subgraph StackN["Stack N"]
     subgraph NetworkFB_N["Network: front-back-n"]
           FRONT_N["📱 Front N"]
           BACK_N["⚙️ Back N"]
     end
     subgraph NetworkBD_N["Network: back-db-n"]
           BACK_N2["⚙️ Back N"]
           DB_N[("💾 DB N")]
     end
  end

  %% Conexiones permitidas
  EXT -.->|HTTPS| PROXY
  PROXY -->|"✓ Acceso permitido"| FRONT_A
  PROXY -->|"✓ Acceso permitido"| FRONT_B
  PROXY -->|"✓ Acceso permitido"| FRONT_N
  
  FRONT_A -->|"✓ API calls"| BACK_A
  BACK_A2 -->|"✓ Queries"| DB_A
  
  FRONT_B -->|"✓ API calls"| BACK_B
  BACK_B2 -->|"✓ Queries"| DB_B
  
  FRONT_N -->|"✓ API calls"| BACK_N
  BACK_N2 -->|"✓ Queries"| DB_N


  %% Estilos
  classDef publicNet fill:#e1f5ff,stroke:#01579b,stroke-width:3px
  classDef stackBox fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
  classDef networkBox fill:#fff3e0,stroke:#e65100,stroke-width:2px
  classDef proxy fill:#4fc3f7,stroke:#01579b,stroke-width:3px,color:#000
  classDef front fill:#81c784,stroke:#2e7d32,stroke-width:2px,color:#000
  classDef back fill:#ffb74d,stroke:#e65100,stroke-width:2px,color:#000
  classDef db fill:#e57373,stroke:#c62828,stroke-width:2px,color:#000
  classDef internet fill:#bbdefb,stroke:#1976d2,stroke-width:2px

  class PublicNetwork publicNet
  class StackA,StackB,StackN stackBox
  class NetworkFB_A,NetworkBD_A,NetworkFB_B,NetworkBD_B,NetworkFB_N,NetworkBD_N networkBox
  class PROXY proxy
  class FRONT_A,FRONT_B,FRONT_N front
  class BACK_A,BACK_A2,BACK_B,BACK_B2,BACK_N,BACK_N2 back
  class DB_A,DB_B,DB_N db
  class Internet,EXT internet

  

Durante años, las metodologías ágiles —y Scrum en particular— han demostrado ser eficaces para organizar el trabajo y acelerar la entrega de valor. Sin embargo, muchas de sus prácticas nacieron en un contexto tecnológico muy distinto al actual: aplicaciones monolíticas, equipos pequeños y despliegues centralizados. En ese escenario, asumir que una historia de usuario equivalía a una funcionalidad completa y visible para el usuario final era no solo razonable, sino práctico.

Hoy, esa premisa se pone en tensión cuando las organizaciones adoptan arquitecturas de microservicios con frontend desacoplado. La funcionalidad de negocio ya no reside en un único lugar ni se entrega como una sola pieza. Se construye de forma distribuida, a través de múltiples servicios, repositorios y equipos que avanzan a ritmos distintos. Este documento nace precisamente para abordar esa fricción: cómo seguir siendo ágiles sin ignorar la realidad técnica, y cómo reconocer valor allí donde tradicionalmente no se ha sabido mirar.

El objetivo no es redefinir Scrum ni entrar en debates dogmáticos, sino establecer una base clara y compartida que permita gestionar el ciclo de vida del desarrollo de software de forma coherente, predecible y sostenible en entornos distribuidos.

El problema de fondo: cuando una historia ya no contiene toda la funcionalidad

En una aplicación monolítica, la relación entre código, despliegue y experiencia de usuario era directa. Una historia de usuario solía implicar cambios en la interfaz, la lógica de negocio y la base de datos, todo dentro del mismo repositorio y liberado al mismo tiempo. El resultado era una funcionalidad tangible y visible para el usuario final.

Aplicación Monolítica:

┌────────────────────────────────────────┐
│  Una Historia = Una Funcionalidad      │
│  Visible en Pantalla                   │
│                                        │
│  Código UI + Lógica + BD en mismo repo │
│  Desplegado todo junto                 │
└────────────────────────────────────────┘

Al pasar a una arquitectura de microservicios, esta equivalencia se rompe. Una misma funcionalidad de negocio depende ahora de un frontend independiente, varios servicios backend y, en muchos casos, integraciones externas. Cada uno de estos elementos tiene su propio ciclo de desarrollo, su propio backlog y su propia cadencia de despliegue.

Arquitectura Distribuida:

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│  Frontend   │─────▶│  Backend 1  │─────▶│  Backend 2  │
│  (Repo A)   │      │  (Repo B)   │      │  (Repo C)   │
│  Deploy 1   │      │  Deploy 2   │      │  Deploy 3   │
└─────────────┘      └─────────────┘      └─────────────┘

      ▲                    ▲                    ▲
      │                    │                    │
   3 equipos           3 backlogs         3 velocidades

Insistir en que cada historia de usuario debe representar valor inmediato y visible para el usuario final genera consecuencias previsibles: bloqueos entre equipos, dependencia constante de integraciones y una percepción distorsionada de la velocidad real. El trabajo backend queda “invisible”, la calidad técnica se resiente y la entrega se vuelve errática.

La pregunta incómoda: ¿una API puede tener valor?

Uno de los puntos de fricción más habituales aparece cuando se cuestiona si una API backend, por sí sola, puede considerarse valor. Desde una interpretación estricta de Scrum, la respuesta suele ser negativa: si el usuario final no puede interactuar con ella, no hay valor entregado.

El problema de esta visión es que ignora cómo se construyen realmente los sistemas complejos. En un entorno distribuido, el valor no aparece de golpe al final del proceso, sino que se va materializando en forma de activos técnicos que reducen incertidumbre, habilitan trabajo paralelo y evitan retrabajo futuro.

De este modo, es necesario distinguir entre dos tipos de valor que coexisten en el flujo de entrega. Por un lado, el valor de negocio directo, que se manifiesta cuando una funcionalidad completa está integrada de extremo a extremo y disponible para el usuario final. Por otro, el valor de activo técnico, que se entrega cuando un componente queda listo, probado y certificado para ser usado por otros equipos.

Timeline de Entrega de Valor:

Día 1-3: Habilitadores completos
         └─ Valor: equipos desbloqueados

Día 4-6: HU Backend completa
         └─ Valor de ACTIVO: API certificada

Día 5-7: HU Frontend completa
         └─ Valor de ACTIVO: UI certificada

Día 8-9: Integración E2E en QA
         └─ Valor de NEGOCIO

Día 10: Producción
         └─ Valor capturado por usuarios

Reconocer este segundo tipo de valor no implica bajar el estándar, sino hacerlo explícito. Una API bien diseñada y validada antes de la integración final reduce riesgos, acelera la entrega y mejora la calidad global del sistema.

Una analogía necesaria para entender el enfoque

La lógica detrás de este modelo resulta más evidente cuando se traslada al mundo físico. En una fábrica de automóviles, el motor, la transmisión y el chasis se construyen por separado. Cada uno de estos componentes tiene valor una vez que ha sido fabricado y probado, incluso aunque el coche completo todavía no exista.

Nadie consideraría desperdicio construir un motor certificado solo porque el vehículo aún no puede circular. De la misma manera, una API backend validada y desplegada en un entorno de pruebas tiene valor real, aunque el usuario final todavía no la vea. Ese valor reside en su capacidad de integrarse sin sorpresas y de servir como base sólida para el resto del sistema.

Cómo se traduce este modelo al desarrollo con microservicios

Cuando este razonamiento se aplica al desarrollo de software, la estructura se vuelve más clara. Una feature representa el objetivo de negocio final, pero su construcción requiere distintos niveles de trabajo que no pueden mezclarse sin generar confusión.

Primero aparecen los habilitadores, como la definición del contrato de la API o la configuración de la infraestructura. Estos elementos no tienen narrativa de usuario final, pero son imprescindibles para que el desarrollo avance sin bloqueos. A continuación, las historias de usuario de backend y frontend entregan componentes certificados de forma independiente. Solo cuando estos componentes se integran se materializa el valor de negocio directo.

FEATURE: "Transferir dinero entre cuentas"

Habilitador:
- Contrato OpenAPI definido y validado

HU Backend:
- API desplegada en QA
- Tests de contrato pasando
- Lista para consumo inmediato

HU Frontend:
- UI validada contra stubs
- Flujos de error implementados

Feature Completa:
- Integración E2E certificada
- Funcionalidad disponible en producción

Este enfoque no fragmenta la entrega; la hace explícita. Cada equipo sabe qué está entregando, para quién y con qué criterio de calidad.

Por qué esto no es waterfall encubierto

Una crítica frecuente es que esta separación recuerda a un modelo en cascada. La diferencia fundamental es que aquí no existen fases bloqueantes. Frontend y backend trabajan en paralelo, desacoplados mediante contratos y stubs, obteniendo feedback temprano y continuo.

En un modelo waterfall, los equipos esperan a que otros terminen para empezar. En este enfoque, los componentes se certifican de forma independiente y la integración se convierte en un paso predecible, no en un cuello de botella tardío.

Un concepto de usuario más amplio

Otro cambio clave es la evolución del concepto de “usuario”. En arquitecturas modernas, no solo las personas consumen funcionalidades. También lo hacen otros sistemas y los desarrolladores que integran servicios.

Una pasarela de pagos como Stripe lo ilustra con claridad: tiene compradores finales, aplicaciones que consumen la API y desarrolladores que necesitan documentación clara para integrar el servicio. Cada uno de ellos recibe valor distinto, y todos son usuarios legítimos. Ignorar alguno de estos niveles degrada el producto y ralentiza su adopción.

Cuando el dogma supera a la realidad

La experiencia demuestra que aplicar Scrum de forma rígida en sistemas distribuidos suele generar efectos contraproducentes. Organizaciones que solo reconocen valor cuando el cliente final ve algo en pantalla tienden a invisibilizar el trabajo técnico, acumular deuda y sufrir bloqueos constantes.

En contraste, aquellas que distinguen claramente entre valor de activo y valor de negocio logran reducir defectos, mejorar la previsibilidad y aumentar la motivación de los equipos. Reconocer el valor técnico no es una concesión, sino una condición necesaria para la sostenibilidad.

Niveles de trabajo como marco común

Para evitar ambigüedades, este enfoque distingue cuatro niveles de trabajo: Feature, Habilitador, Historia de Usuario y Tarea. Cada uno cumple una función específica y tiene criterios de finalización distintos, lo que permite planificar y medir el progreso sin mezclar expectativas.

Relación jerárquica:

1 Feature
 ├─ Habilitadores
 ├─ Historias de Usuario (Frontend / Backend)
 │   └─ Tareas técnicas

Esta jerarquía no añade burocracia; añade claridad. Permite que cada equipo sepa cuándo su trabajo está realmente terminado y cómo contribuye al objetivo global.

Conclusión

La adopción de arquitecturas de microservicios exige una reinterpretación pragmática de los principios ágiles. El valor ya no aparece en un único momento ni en una sola capa del sistema. Se construye progresivamente, a través de activos técnicos certificados que habilitan la entrega final de valor de negocio.

Este documento establece una base para trabajar con esa realidad, permitiendo desacoplar equipos, visibilizar el trabajo técnico y mejorar la calidad global del sistema. A partir de aquí, el marco puede evolucionar hacia métricas más avanzadas, automatización de certificaciones y una gestión aún más madura de dependencias e integraciones.

El Arte de la Consistencia: Creando Respuestas API Predecibles en Spring MVC Imagina a un desarrollador frontend consumiendo tu API. En un endpoint, recibe un objeto JSON. En otro, una simple lista. Si ocurre un error de validación, obtiene una estructura compleja; si el servidor falla, recibe un texto plano. Cada variación, por pequeña que sea, introduce una nueva lógica condicional en el cliente. Rápidamente, esa falta de estándar se convierte en un caos silencioso, una deuda técnica que frena la innovación y fragiliza el sistema.

La estandarización de las respuestas de una API no es una cuestión de estética, sino una decisión de arquitectura fundamental. El verdadero desafío es cómo lograr esta uniformidad sin contaminar nuestra lógica de negocio con código repetitivo. Afortunadamente, Spring MVC nos ofrece herramientas de una elegancia sorprendente, @RestControllerAdvice y ResponseBodyAdvice, diseñadas precisamente para resolver estos problemas transversales de forma limpia y centralizada.

Este artículo te guiará en la implementación de un patrón de respuesta robusto y unificado en un entorno Spring Boot con Lombok, cubriendo tanto los casos de éxito como los de error de manera consistente y profesional.

El Contrato: La Piedra Angular de la Previsibilidad

Antes de escribir una sola línea de lógica, debemos definir nuestro objetivo: un formato de respuesta único que sirva tanto para éxitos como para errores. Esta es la base de la predictibilidad. En lugar de improvisar, diseñaremos una estructura genérica que actúe como un contrato inmutable con nuestros clientes.

La clave de nuestra estrategia es la clase ApiResponse. Este DTO (Data Transfer Object) genérico contendrá tres componentes principales:

• meta: Un objeto con metadatos de la solicitud (timestamp, ID de la petición, etc.), útil para la depuración y el monitoreo.
• data: El payload real de la respuesta en caso de éxito. Será de tipo genérico (T).
• errors: Una lista de errores detallados si algo sale mal.

Una de las decisiones más importantes aquí es el uso de la anotación @JsonInclude(JsonInclude.Include.NON_NULL). Esta simple línea le indica a Jackson (el serializador JSON de Spring) que omita cualquier campo con valor nulo. ¿El resultado? Las respuestas exitosas no tendrán el campo errors y las de error no tendrán el campo data, manteniendo así los JSON limpios y relevantes sin necesidad de crear múltiples clases.

Para construir este contrato, asegúrate de tener las dependencias esenciales en tu pom.xml:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

Y aquí está el diseño de nuestro contrato unificado:

// src/main/java/com/example/demo/common/ApiResponse.java
package com.example.demo.common;

import com.fasterxml.jackson.annotation.JsonInclude;
import lombok.Builder;
import lombok.Data;
import java.time.Instant;
import java.util.List;
import java.util.UUID;

@Data
@Builder
@JsonInclude(JsonInclude.Include.NON_NULL)
public class ApiResponse<T> {

    private Meta meta;
    private T data;
    private List<ErrorDetail> errors;

    @Data
    @Builder
    public static class Meta {
        private String timestamp = Instant.now().toString();
        @Builder.Default
        private String requestId = UUID.randomUUID().toString().substring(0, 10);
        private String path;
        private int status;
    }

    @Data
    @Builder
    public static class ErrorDetail {
        private String code;
        private String message;
    }

    public static <T> ApiResponse<T> success(T data, String path, int status) {
        return ApiResponse.<T>builder()
                .meta(Meta.builder().path(path).status(status).build())
                .data(data)
                .build();
    }

    public static ApiResponse<?> error(List<ErrorDetail> errors, String path, int status) {
        return ApiResponse.builder()
                .meta(Meta.builder().path(path).status(status).build())
                .errors(errors)
                .build();
    }
}

La Arquitectura de la Consistencia: Separando Responsabilidades

Para una solución robusta y mantenible, aplicaremos el Principio de Responsabilidad Única. En lugar de una sola clase monolítica, dividiremos nuestra lógica en dos componentes especializados, ambos anotados con @RestControllerAdvice. Spring es lo suficientemente inteligente como para detectar y aplicar ambos.

Primero, crearemos una configuración para permitirnos habilitar, deshabilitar o excluir rutas de este comportamiento, dándonos flexibilidad para casos especiales como los endpoints de Actuator o Swagger.

// src/main/java/com/example/demo/common/ResponseWrapperProperties.java
package com.example.demo.common;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import java.util.ArrayList;
import java.util.List;

@Data
@Component
@ConfigurationProperties(prefix = "api.response.wrapper")
public class ResponseWrapperProperties {
    private boolean enabled = true;
    private List<String> excludedPaths = new ArrayList<>();
}

1. El Guardián de Respuestas Exitosas

Nuestra primera clase, GlobalResponseHandler, tendrá una sola misión: interceptar las respuestas exitosas de los controladores y envolverlas en nuestra estructura ApiResponse. Utiliza la interfaz ResponseBodyAdvice para modificar el cuerpo de la respuesta justo antes de que se envíe.

// src/main/java/com/example/demo/common/GlobalResponseHandler.java
package com.example.demo.common;

import jakarta.servlet.http.HttpServletRequest;
import lombok.RequiredArgsConstructor;
import org.springframework.core.MethodParameter;
import org.springframework.http.MediaType;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.server.ServerHttpRequest;
import org.springframework.http.server.ServerHttpResponse;
import org.springframework.http.server.ServletServerHttpRequest;
import org.springframework.http.server.ServletServerHttpResponse;
import org.springframework.util.AntPathMatcher;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;

@RestControllerAdvice
@RequiredArgsConstructor
public class GlobalResponseHandler implements ResponseBodyAdvice<Object> {

    private final ResponseWrapperProperties properties;
    private final AntPathMatcher pathMatcher = new AntPathMatcher();

    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        return true;
    }

    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType,
                                  Class<? extends HttpMessageConverter<?>> selectedConverterType,
                                  ServerHttpRequest request, ServerHttpResponse response) {

        HttpServletRequest servletRequest = ((ServletServerHttpRequest) request).getServletRequest();
        String path = servletRequest.getRequestURI();

        // Si el cuerpo ya es un ApiResponse (creado por el manejador de excepciones)
        // o la ruta está excluida, no hacemos nada.
        if (body instanceof ApiResponse || isExcluded(path)) {
            return body;
        }

        int status = ((ServletServerHttpResponse) response).getServletResponse().getStatus();
        return ApiResponse.success(body, path, status);
    }
    
    private boolean isExcluded(String path) {
        return !properties.isEnabled() || properties.getExcludedPaths().stream()
                .anyMatch(pattern -> pathMatcher.match(pattern, path));
    }
}

2. El Centinela Central de Errores

La segunda clase, GlobalExceptionHandler, se dedicará exclusivamente a capturar excepciones lanzadas desde cualquier controlador. Usando @ExceptionHandler, las convierte en nuestra respuesta ApiResponse estandarizada. Este aislamiento hace que el código de manejo de errores sea fácil de encontrar, mantener y extender.

// src/main/java/com/example/demo/common/GlobalExceptionHandler.java
package com.example.demo.common;

import jakarta.servlet.http.HttpServletRequest;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import java.util.Collections;
import java.util.List;
import java.util.stream.Collectors;

@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ApiResponse<?> handleValidationExceptions(MethodArgumentNotValidException ex, HttpServletRequest request) {
        List<ApiResponse.ErrorDetail> errors = ex.getBindingResult().getFieldErrors().stream()
                .map(error -> ApiResponse.ErrorDetail.builder()
                        .code("VALIDATION_ERROR")
                        .message(String.format("'%s': %s", error.getField(), error.getDefaultMessage()))
                        .build())
                .collect(Collectors.toList());
        return ApiResponse.error(errors, request.getRequestURI(), HttpStatus.BAD_REQUEST.value());
    }

    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public ApiResponse<?> handleAllUncaughtException(Exception ex, HttpServletRequest request) {
        log.error("Error no controlado en la ruta {}: {}", request.getRequestURI(), ex.getMessage(), ex);
        ApiResponse.ErrorDetail error = ApiResponse.ErrorDetail.builder()
                .code("INTERNAL_SERVER_ERROR")
                .message("Ocurrió un error inesperado. Por favor, contacte al soporte.")
                .build();
        return ApiResponse.error(Collections.singletonList(error), request.getRequestURI(), HttpStatus.INTERNAL_SERVER_ERROR.value());
    }
}

Ganando Confianza: Pruebas que Validan la Arquitectura

Probar componentes transversales es crucial. Con @WebMvcTest, creamos un contexto de prueba ligero que se enfoca en la capa web. La clave es importar ambas clases de Advice en nuestro test para asegurar que el comportamiento combinado (formateo de éxito y manejo de errores) se verifica correctamente.

// src/test/java/com/example/demo/common/GlobalResponseHandlerTest.java
package com.example.demo.common;

import jakarta.validation.Valid;
import jakarta.validation.constraints.NotEmpty;
import lombok.AllArgsConstructor;
import lombok.Data;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.context.annotation.Import;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
import static org.mockito.Mockito.when;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@WebMvcTest(controllers = GlobalResponseHandlerTest.TestController.class)
// Importamos AMBAS clases para que el contexto de prueba refleje la configuración real.
@Import({GlobalResponseHandler.class, GlobalExceptionHandler.class})
class GlobalResponseHandlerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private ResponseWrapperProperties responseWrapperProperties;

    // ... (El resto de la clase de prueba, incluyendo setUp, TestController, TestDto y los métodos de prueba, permanece igual) ...

    @BeforeEach
    void setUp() {
        when(responseWrapperProperties.isEnabled()).thenReturn(true);
        when(responseWrapperProperties.getExcludedPaths()).thenReturn(List.of("/excluded/**"));
    }

    @RestController
    static class TestController {
        @GetMapping("/test/success")
        public TestDto getSuccess() { return new TestDto("ok"); }

        @PostMapping("/test/validation")
        public TestDto postValidation(@Valid @RequestBody TestDto dto) { return dto; }

        @GetMapping("/excluded/path")
        public TestDto getExcluded() { return new TestDto("excluded"); }
    }
    
    @Data
    @AllArgsConstructor
    static class TestDto {
        @NotEmpty
        private String message;
    }

    @Test
    @DisplayName("Debería envolver una respuesta exitosa en el formato ApiResponse")
    void shouldWrapSuccessResponse() throws Exception {
        mockMvc.perform(get("/test/success"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.meta").exists())
                .andExpect(jsonPath("$.data.message").value("ok"))
                .andExpect(jsonPath("$.errors").doesNotExist());
    }

    @Test
    @DisplayName("No debería envolver una respuesta si la ruta está excluida")
    void shouldNotWrapExcludedPath() throws Exception {
        mockMvc.perform(get("/excluded/path"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.meta").doesNotExist())
                .andExpect(jsonPath("$.message").value("excluded"));
    }

    @Test
    @DisplayName("Debería manejar un error de validación y devolver ApiResponse con detalles de error")
    void shouldHandleValidationError() throws Exception {
        String invalidDtoJson = "{\"message\":\"\"}";

        mockMvc.perform(post("/test/validation")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content(invalidDtoJson))
                .andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.meta").exists())
                .andExpect(jsonPath("$.data").doesNotExist())
                .andExpect(jsonPath("$.errors").isArray())
                .andExpect(jsonPath("$.errors[0].code").value("VALIDATION_ERROR"));
    }
}

Más Allá del Código: El Impacto de una Arquitectura Consistente

Hemos recorrido un camino que va más allá de un simple truco de código. Partimos de un problema real —el caos de las respuestas inconsistentes— y, en lugar de aplicar parches, diseñamos una solución arquitectónica limpia basada en la separación de responsabilidades.

El resultado es un patrón robusto y no invasivo que unifica todas las respuestas bajo un contrato predecible. La lógica está aislada, es configurable y completamente testeable. Esta inversión en diseño reduce la carga cognitiva para todos, desde los desarrolladores del backend hasta los consumidores de la API, creando sistemas más mantenibles, escalables y, en definitiva, más sencillos de razonar.

Este patrón no es un punto final, sino una base sólida. Las posibilidades futuras son claras:

• Documentación de API: El siguiente paso es asegurar que herramientas como OpenAPI/Swagger reflejen esta estructura ApiResponse automáticamente, proporcionando una documentación precisa del contrato real.
• Trazabilidad Distribuida: El requestId en los metadatos es la semilla para una trazabilidad completa. Integrarlo con herramientas como Micrometer Tracing permitiría seguir una petición a través de múltiples microservicios, simplificando la depuración en entornos complejos.
• Observabilidad Mejorada: El bloque meta puede enriquecerse con más datos, como el tiempo de procesamiento, para alimentar dashboards en herramientas como Grafana y Prometheus, ofreciendo una visión más profunda del rendimiento de la API.

En el universo del desarrollo de software empresarial, nos enfrentamos a un dilema constante: cómo manejar información transversal —ese rastro de datos vitales como IDs de correlación, información del usuario o el tenant de un sistema multi-inquilino— sin que contamine la pureza de nuestro dominio. Estos datos son el sistema nervioso de la aplicación, esenciales para la trazabilidad, la auditoría y la seguridad, pero no son parte del lenguaje de negocio. Incluirlos como parámetros en cada método del dominio es una solución rápida que, a la larga, genera un código verboso y acoplado.

Imagina que estás construyendo un sistema complejo con Java 21, Spring Boot y una filosofía Domain-Driven Design (DDD). Tu arquitectura está elegantemente separada en capas de dominio, infraestructura y aplicación. ¿Cómo logras que ese "contexto" de ejecución fluya mágicamente a través de todas las capas, disponible cuando se necesita, pero invisible cuando no? El objetivo es crear un mecanismo que sea a la vez transparente y robusto, que funcione igual de bien para una petición REST, un proceso batch o un mensaje de una cola.

La encrucijada del diseño: ¿Parámetro o Magia?

Cuando nos enfrentamos a la propagación de contexto, hay dos caminos. El primero es el de la explicitud: si un dato es parte del lenguaje de negocio (como el "autor" de una acción), debe ser un parámetro explícito en el dominio. No hay discusión. El segundo camino es el de la transversalidad, reservado para metadatos puramente técnicos. Aquí es donde queremos un poco de "magia controlada", una forma de acceder a la información sin que ensucie nuestras interfaces de negocio.

Para esta magia, ThreadLocal se presenta como un candidato ideal en el ecosistema tradicional de Spring. Es, en esencia, una caja de almacenamiento que cada hilo de ejecución lleva consigo. Lo que un hilo guarda en su ThreadLocal, solo ese hilo puede verlo, garantizando un aislamiento perfecto en entornos concurrentes.

Nuestra herramienta será un ExecutionContext, un contenedor simple que vivirá en ese ThreadLocal. Usamos un Map<String, Object> en su interior por una razón clave: flexibilidad. Podríamos crear una clase con campos fijos (correlationId, userId, etc.), pero un mapa nos permite añadir nuevos datos al contexto en el futuro sin modificar la clase base. Es un compromiso consciente entre la seguridad de tipos y la extensibilidad.

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

// Un contenedor simple y flexible para los datos de nuestro contexto.
public class ExecutionContext {
    private static final ThreadLocal<ExecutionContext> CONTEXT = new ThreadLocal<>();
    private final Map<String, Object> values = new ConcurrentHashMap<>();

    // ... (métodos init, current, clear, put, get)
    public static ExecutionContext current() { return CONTEXT.get(); }
    public static void set(ExecutionContext context) { CONTEXT.set(context); }
    public static void clear() { CONTEXT.remove(); }
    public static ExecutionContext init() {
        ExecutionContext ctx = new ExecutionContext();
        set(ctx);
        return ctx;
    }
    public void put(String key, Object value) { values.put(key, value); }
    @SuppressWarnings("unchecked")
    public <T> T get(String key, Class<T> type) { return (T) values.get(key); }
}

El guardián del ciclo de vida: Automatización con un Filter

Tener el ExecutionContext es solo el primer paso. El mayor riesgo de ThreadLocal es el olvido. En un servidor como Tomcat, los hilos se reciclan. Si no limpiamos el contexto al final de una petición, ese hilo reutilizado podría servir a otro usuario con los datos del anterior, una brecha de seguridad y de datos catastrófica.

Aquí es donde entra en juego el Filter de Servlet, el guardián de nuestro contexto. Un Filter es perfecto porque opera a un nivel más bajo que los controladores de Spring. Intercepta toda petición entrante, dándonos el lugar ideal para:

1. Inicializar el contexto al empezar.
2. Poblarlo con datos de la petición, como cabeceras.
3. Garantizar su limpieza al terminar, pase lo que pase.

El bloque try...finally no es una opción, es una obligación. Es el seguro de vida que nos protege contra las fugas de memoria y la contaminación de datos. En el siguiente código, no solo capturamos un ID de correlación, sino también un token JWT, demostrando la flexibilidad del mapa.

import jakarta.servlet.*;
import jakarta.servlet.http.HttpServletRequest;
import org.apache.logging.log4j.ThreadContext;
import org.springframework.stereotype.Component;
import java.io.IOException;
import java.util.UUID;

@Component
public class ExecutionContextFilter implements Filter {
    // ... (constantes para las claves)
    private static final String CORRELATION_ID_HEADER = "X-Correlation-ID";
    private static final String AUTH_HEADER = "Authorization";
    private static final String CORRELATION_ID_KEY = "correlationId";
    private static final String JWT_KEY = "jwtToken";

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        
        ExecutionContext.init(); // Nace el contexto
        
        try {
            // Se enriquece con datos de la petición
            if (request instanceof HttpServletRequest httpRequest) {
                String correlationId = httpRequest.getHeader(CORRELATION_ID_HEADER);
                // ... (lógica para generar correlationId si no existe)
                ExecutionContext.current().put(CORRELATION_ID_KEY, correlationId);
                ThreadContext.put(CORRELATION_ID_KEY, correlationId); // Se lo pasamos a Log4j2

                String token = httpRequest.getHeader(AUTH_HEADER);
                if (token != null) {
                    ExecutionContext.current().put(JWT_KEY, token);
                }
            }
            chain.doFilter(request, response);
        } finally {
            // Se limpia, garantizando que el hilo reciclado esté impoluto
            ThreadContext.clearMap();
            ExecutionContext.clear();
        }
    }
}

Observabilidad sin esfuerzo: El poder del Logging contextual

Depurar un problema en producción sin un ID de correlación es como buscar una aguja en un pajar. Al integrar nuestro contexto con el sistema de logging (vía el MDC de Log4j2, que es su propia versión de ThreadLocal), cada línea de log generada durante la petición quedará marcada con ese identificador único. De repente, el pajar se organiza en hilos de paja perfectamente trazables.

Solo necesitamos decirle a Log4j2 que muestre esa información en su patrón:

<Configuration status="WARN">
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - [%X{correlationId}] - %msg%n"/>
        </Console>
    </Appenders>
    </Configuration>

Un ejemplo práctico para unirlo todo

La teoría está muy bien, pero veámoslo en acción. Imaginemos un flujo simple: un controlador recibe una petición, llama a un caso de uso que a su vez depende de un repositorio para hablar con un servicio externo.

El Dominio, un oasis de pureza: El código del dominio no sabe nada del contexto. Define los contratos (HelloWorldRepository) y orquesta la lógica (GetHelloWorldUseCase), manteniéndose limpio y enfocado.

// Caso de Uso: depende de una abstracción y no sabe de dónde saldrán los datos.
public class GetHelloWorldUseCase {
    private final HelloWorldRepository helloWorldRepository;
    // ... (constructor)

    public String execute() {
        // ... (log de inicio)
        String externalGreeting = helloWorldRepository.getGreeting();
        
        // ¡Aquí es donde el dominio se beneficia de la "magia"!
        // Accede al contexto de forma segura y opcional.
        String correlationId = ExecutionContext.current().get("correlationId", String.class);
        
        System.out.println("DESDE CASO DE USO: Mensaje del repo: '" + externalGreeting + 
                           "'. Trazabilidad: " + correlationId);
        return externalGreeting;
    }
}

La Infraestructura, donde ocurre la magia: Aquí es donde implementamos los detalles. Nuestro RestHelloWorldRepository simula ser un cliente REST. Antes de hacer su "llamada", consulta el ExecutionContext para obtener el token JWT que necesita para autenticarse. ¡El caso de uso nunca tuvo que pasárselo!

// Implementación del Repositorio: el "fontanero" que conecta con el mundo exterior.
public class RestHelloWorldRepository implements HelloWorldRepository {
    @Override
    public String getGreeting() {
        // Obtiene el token que el Filter puso en el contexto.
        String jwt = ExecutionContext.current().get("jwtToken", String.class);
        System.out.println("DESDE REPOSITORIO (CLIENTE REST): Usando el token para la llamada -> " + jwt);
        return "Hola desde el servicio externo!";
    }
}

Al ejecutar una petición con curl que incluya las cabeceras X-Correlation-ID y Authorization, la salida en la consola nos cuenta la historia completa: el log con el ID, la implementación del repositorio usando el token, y el caso de uso accediendo de nuevo al ID. Todo fluyó sin que una sola firma de método se viera alterada.

Conclusión: Un patrón poderoso con responsabilidades

Hemos construido un sistema robusto para manejar el contexto. Sin embargo, este poder conlleva responsabilidades. El patrón ThreadLocal es una herramienta fantástica para arquitecturas síncronas basadas en el modelo "un hilo por petición", pero es el enfoque incorrecto para sistemas reactivos (como WebFlux), donde la ejecución no está atada a un único hilo. Allí, la solución nativa es el Context de Project Reactor.

Además, con la llegada de los Hilos Virtuales en Java, el uso masivo de ThreadLocal puede limitar sus beneficios de escalabilidad. El futuro apunta a los Scoped Values (JEP 446), diseñados precisamente para este tipo de propagación de datos de forma más eficiente.

Entender estas fronteras es tan importante como conocer el patrón en sí. La clave del éxito es siempre la misma: mantener el dominio puro y delegar las complejidades técnicas a una capa de infraestructura bien diseñada.

En entornos modernos de microservicios, la consistencia en las respuestas de una API es más que una cuestión de estética: es un factor crítico para la mantenibilidad, observabilidad y experiencia del consumidor. Aplicaciones frontend, integraciones con terceros, herramientas de monitoreo y otros microservicios esperan estructuras de respuesta predecibles. Cada variación no planificada introduce fricción: más lógica en los clientes, validaciones dispersas y puntos ciegos en trazabilidad.

En este contexto, estandarizar las respuestas de manera transversal —sin ensuciar cada controlador con lógica repetitiva— no solo simplifica el desarrollo, también abre la puerta a métricas uniformes, trazabilidad distribuida y soporte para nuevas funcionalidades sin tocar el código de negocio.

Este artículo explica cómo lograrlo en aplicaciones reactivas con Spring WebFlux, donde la naturaleza streaming de la respuesta introduce desafíos distintos a los de un stack imperativo como Spring MVC.

El Contrato de Respuesta: Mucho más que Datos

Antes de modificar nada, debemos definir el destino. Una respuesta estándar debe separar claramente los datos de negocio de la información contextual que permite entender la petición en su conjunto.

Un diseño común y extensible puede lucir así:

package com.app247.api.shared.response_wrapper.model;

import lombok.Builder;
import lombok.Data;

@Data
@Builder
public class ApiResponse<T> {
    private Meta meta;
    private T data;

    @Data
    @Builder
    public static class Meta {
        private String timestamp;
        private String path;
        private int status;
        private String requestId;
    }
}

Este contrato permite:

• Consistencia: cada respuesta, sin importar el endpoint, sigue la misma forma.
• Trazabilidad: con requestId y timestamp podemos correlacionar logs, métricas y reportes.
• Extensibilidad: podemos agregar campos en meta (e.g., tiempos de respuesta, versión del servicio) sin afectar al cliente.

En entornos con OpenAPI/Swagger, este modelo puede documentarse fácilmente para que los consumidores conozcan el formato exacto de las respuestas.

WebFlux y el Desafío del Streaming

En aplicaciones no reactivas, ResponseBodyAdvice permite interceptar y modificar respuestas antes de serializarse. Pero en WebFlux, las respuestas son streams (Publisher<DataBuffer>), no objetos finales en memoria.

Esto implica dos retos:

1. Respetar el modelo reactivo: no bloquear el flujo ni forzar materializaciones tempranas.
2. Actuar en el punto correcto: cuando la respuesta está completa, pero antes de enviarla al cliente.

Aquí entra en juego el dúo WebFilter + ServerHttpResponseDecorator. El filtro decide si aplicar la transformación; el decorador define cómo hacerlo.

El Filtro: Decidiendo Cuándo Intervenir

Nuestro WebFilter actúa como middleware, excluyendo rutas (por ejemplo, Swagger o Actuator) y habilitando/deshabilitando la lógica según configuración externa:

package com.app247.api.shared.response_wrapper.filter;

import com.app247.api.shared.response_wrapper.config.ResponseWrapperProperties;
import com.app247.api.shared.response_wrapper.decorator.ResponseWrapperDecorator;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.core.annotation.Order;
import org.springframework.http.server.reactive.ServerHttpResponseDecorator;
import org.springframework.stereotype.Component;
import org.springframework.util.AntPathMatcher;
import org.springframework.web.server.ServerWebExchange;
import org.springframework.web.server.WebFilter;
import org.springframework.web.server.WebFilterChain;
import reactor.core.publisher.Mono;


@Slf4j
@Component
@Order(-2)
@RequiredArgsConstructor
public class ResponseWrapperFilter implements WebFilter {

    private final ResponseWrapperProperties properties;
    private final ObjectMapper objectMapper;
    private final AntPathMatcher pathMatcher = new AntPathMatcher();

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
        String path = exchange.getRequest().getURI().getPath();

        // Verificamos si la ruta está excluida
        boolean isExcluded = !properties.isEnabled() || properties.getExcludedPaths().stream()
                .anyMatch(pattern -> pathMatcher.match(pattern, path));

        if (isExcluded) {
            return chain.filter(exchange);
        }

        // Creamos una instancia de nuestro nuevo decorador
        ServerHttpResponseDecorator decoratedResponse = new ResponseWrapperDecorator(
                exchange.getResponse(),
                path,
                objectMapper
        );

        // Pasamos el exchange con la respuesta decorada al siguiente filtro en la cadena
        return chain.filter(exchange.mutate().response(decoratedResponse).build());
    }
}

Las rutas excluidas y la activación del wrapper se controlan con propiedades externas, evitando recompilar para cambios operativos:

package com.app247.api.shared.response_wrapper.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import java.util.ArrayList;
import java.util.List;

/*
Ejemplo: 
api:
  response:
    wrapper:
      enabled: true
      # Patrones de URL para excluir. Usa el formato Ant.
      excluded-paths:
        - "/v3/api-docs/**"
        - "/swagger-ui/**"
        - "/webjars/**"
        - "/swagger-resources/**"
        - "/actuator/**"
 */

@Data
@Component
@ConfigurationProperties(prefix = "api.response.wrapper")
public class ResponseWrapperProperties {

    private boolean enabled = true;
    private List<String> excludedPaths = new ArrayList<>();

}

El Decorador: Interviniendo sin Romper el Flujo

ServerHttpResponseDecorator nos da acceso al cuerpo de la respuesta. El método clave es writeWith, que recibe el stream de datos antes de enviarlo al cliente.

package com.app247.api.shared.response_wrapper.decorator;

import com.app247.api.shared.response_wrapper.model.ApiResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.extern.slf4j.Slf4j;
import org.reactivestreams.Publisher;
import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.core.io.buffer.DataBufferUtils;
import org.springframework.core.io.buffer.DefaultDataBufferFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.HttpStatusCode;
import org.springframework.http.MediaType;
import org.springframework.http.server.reactive.ServerHttpResponse;
import org.springframework.http.server.reactive.ServerHttpResponseDecorator;
import reactor.core.publisher.Mono;

import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.UUID;

/**
 * Decorador para ServerHttpResponse que intercepta las respuestas exitosas
 * y las envuelve en una estructura estandarizada de ApiResponse (meta y data).
 */
@Slf4j
public class ResponseWrapperDecorator extends ServerHttpResponseDecorator {

    private final ObjectMapper objectMapper;
    private final String path;

    public ResponseWrapperDecorator(ServerHttpResponse delegate, String path, ObjectMapper objectMapper) {
        super(delegate);
        this.path = path;
        this.objectMapper = objectMapper;
    }

    /**
     * Sobrescribe el método que escribe el cuerpo de la respuesta en el flujo de salida.
     * Aquí es donde ocurre toda la magia de la intercepción y transformación.
     * @param body El publicador original del cuerpo de la respuesta.
     * @return Un Mono<Void> que representa la finalización de la operación de escritura.
     */
    @Override
    public Mono<Void> writeWith(Publisher<? extends DataBuffer> body) {
        // PASO 1: Almacenar el cuerpo completo en un búfer.
        // DataBufferUtils.join() consume tod_o el flujo del 'body' y lo une en un solo DataBuffer.
        // Esto es CRUCIAL porque crea un punto de sincronización. La lógica siguiente
        // no se ejecutará hasta que el controlador haya terminado y el cuerpo completo esté disponible.
        Mono<DataBuffer> bufferedBody = DataBufferUtils.join(body)
                .defaultIfEmpty(new DefaultDataBufferFactory().wrap(new byte[0])); // Maneja cuerpos vacíos (ej: 204 No Content)

        // PASO 2: Usar flatMap para transformar el cuerpo almacenado en búfer.
        // El código dentro de flatMap está garantizado a ejecutarse DESPUÉS de que 'bufferedBody' se complete.
        return bufferedBody.flatMap(originalBuffer -> {
            // PASO 3: Obtener el código de estado.
            // En este punto, la llamada a getStatusCode() es 100% fiable porque el controlador
            // ya ha finalizado y el framework ha establecido el estado final de la respuesta.
            HttpStatusCode statusCode = getStatusCode();

            // PASO 4: Decidir si se debe envolver la respuesta.
            // Si el estado es un error explícito (4xx o 5xx), no hacemos nada y devolvemos el cuerpo original.
            if (statusCode != null && !statusCode.is2xxSuccessful()) {
                // Se escribe el buffer original en la respuesta real.
                return getDelegate().writeWith(Mono.just(originalBuffer));
            }

            // PASO 5: Manejar el caso del entorno de pruebas.
            // En WebFluxTest, un 200 OK por defecto puede resultar en un statusCode 'null'.
            // Asumimos HttpStatus.OK si el estado es null para que las pruebas pasen.
            HttpStatusCode statusToUse = (statusCode != null) ? statusCode : HttpStatus.OK;

            // PASO 6: Procesar y envolver el cuerpo de la respuesta.
            byte[] bytes = new byte[originalBuffer.readableByteCount()];
            originalBuffer.read(bytes);
            DataBufferUtils.release(originalBuffer); // Liberar memoria del buffer original.
            String originalBodyJson = new String(bytes, StandardCharsets.UTF_8);

            // Evitar envolver una respuesta que ya tiene nuestro formato.
            if (originalBodyJson.contains("\"meta\"")) {
                return getDelegate().writeWith(Mono.just(new DefaultDataBufferFactory().wrap(bytes)));
            }

            try {
                // Deserializar el cuerpo original para poder ponerlo dentro del campo 'data'.
                // Si el cuerpo está vacío, se asigna 'null' a los datos.
                Object originalBodyObject = originalBodyJson.isEmpty() ? null : objectMapper.readValue(originalBodyJson, Object.class);

                // Construir la nueva respuesta envuelta.
                ApiResponse<?> apiResponse = buildSuccessResponse(originalBodyObject, path, statusToUse);

                // Serializar la respuesta envuelta a bytes.
                byte[] responseBytes = objectMapper.writeValueAsBytes(apiResponse);

                // Actualizar las cabeceras HTTP con la nueva longitud y tipo de contenido.
                getHeaders().setContentLength(responseBytes.length);
                getHeaders().setContentType(MediaType.APPLICATION_JSON);

                // Crear un nuevo buffer con la respuesta envuelta.
                DataBuffer wrappedBuffer = new DefaultDataBufferFactory().wrap(responseBytes);

                // Escribir el nuevo cuerpo en la respuesta real. Esta es la llamada final y única
                // que envía los datos al cliente, siguiendo las buenas prácticas reactivas.
                return getDelegate().writeWith(Mono.just(wrappedBuffer));

            } catch (Exception e) {
                log.error("Error al envolver la respuesta para la ruta {}: {}", path, e.getMessage(), e);
                return getDelegate().writeWith(Mono.just(new DefaultDataBufferFactory().wrap(bytes)));
            }
        });
    }

    /**
     * Método de ayuda para construir la estructura estandarizada de ApiResponse.
     * @param data El objeto de datos original que se incluirá en el campo 'data'.
     * @param path La ruta de la petición actual.
     * @param status El código de estado HTTP final.
     * @return Una instancia de ApiResponse.
     */
    private ApiResponse<?> buildSuccessResponse(Object data, String path, HttpStatusCode status) {
        ApiResponse.Meta meta = ApiResponse.Meta.builder()
                .timestamp(Instant.now().toString())
                .path(path)
                .requestId(UUID.randomUUID().toString().substring(0, 10))
                .status(status.value())
                .build();

        return ApiResponse.builder()
                .meta(meta)
                .data(data)
                .build();
    }
}

Consideraciones Técnicas

• Performance: DataBufferUtils.join() carga todo en memoria; para respuestas muy grandes, conviene evaluar streaming JSON.
• Idempotencia: el filtro detecta si ya existe "meta" para evitar doble envoltura.
• Trazabilidad distribuida: requestId puede integrarse con Spring Cloud Sleuth o MDC para correlacionar logs entre microservicios.

Pruebas: Validando Comportamiento y Robustez

Con @WebFluxTest podemos probar controladores y filtros en un entorno aislado.

package com.app247.api.shared.response_wrapper.filter;

import com.app247.api.shared.response_wrapper.config.ResponseWrapperProperties;
import com.app247.api.shared.response_wrapper.model.ApiResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.reactive.WebFluxTest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.test.context.bean.override.mockito.MockitoBean;
import org.springframework.test.web.reactive.server.WebTestClient;
import org.springframework.util.AntPathMatcher;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.time.Instant;
import java.util.Collections;
import java.util.List;
import java.util.Map;

import static org.mockito.Mockito.when;

/**
 * Pruebas de integración para el ResponseWrapperFilter.
 * Valida que las respuestas exitosas se envuelvan y que las de error o excluidas se ignoren.
 */
@WebFluxTest
@Import(ResponseWrapperFilterTest.TestConfig.class)
class ResponseWrapperFilterTest {

    @Autowired
    private WebTestClient webTestClient;

    @MockitoBean
    private ResponseWrapperProperties responseWrapperProperties;

    @BeforeEach
    void setUp() {
        when(responseWrapperProperties.isEnabled()).thenReturn(true);
        when(responseWrapperProperties.getExcludedPaths()).thenReturn(List.of("/excluded/**"));
    }

    @Test
    @DisplayName("Debería envolver una respuesta Mono exitosa en ApiResponse")
    void shouldWrapSuccessfulMonoResponse() {
        webTestClient.get().uri("/test/mono")
                .exchange()
                .expectStatus().isOk()
                .expectHeader().contentType(MediaType.APPLICATION_JSON)
                .expectBody()
                .jsonPath("$.meta").exists()
                .jsonPath("$.meta.status").isEqualTo(200)
                .jsonPath("$.meta.path").isEqualTo("/test/mono")
                .jsonPath("$.data").exists()
                .jsonPath("$.data.id").isEqualTo(1)
                .jsonPath("$.data.name").isEqualTo("Test Mono");
    }

    @Test
    @DisplayName("Debería envolver una respuesta Flux exitosa en ApiResponse con una lista")
    void shouldWrapSuccessfulFluxResponse() {
        webTestClient.get().uri("/test/flux")
                .exchange()
                .expectStatus().isOk()
                .expectHeader().contentType(MediaType.APPLICATION_JSON)
                .expectBody()
                .jsonPath("$.meta").exists()
                .jsonPath("$.meta.status").isEqualTo(200)
                .jsonPath("$.data").isArray()
                .jsonPath("$.data[0].id").isEqualTo(1)
                .jsonPath("$.data[0].name").isEqualTo("Test Flux 1")
                .jsonPath("$.data[1].id").isEqualTo(2)
                .jsonPath("$.data[1].name").isEqualTo("Test Flux 2");
    }

    @Test
    @DisplayName("No debería envolver una respuesta de una ruta excluida")
    void shouldNotWrapExcludedPath() {
        webTestClient.get().uri("/excluded/path")
                .exchange()
                .expectStatus().isOk()
                .expectHeader().contentType(MediaType.APPLICATION_JSON)
                .expectBody()
                .jsonPath("$.meta").doesNotExist()
                .jsonPath("$.data").doesNotExist()
                .jsonPath("$.id").isEqualTo(99)
                .jsonPath("$.name").isEqualTo("Excluded");
    }

    @Test
    @DisplayName("No debería envolver una respuesta de error (ej: 400 Bad Request)")
    void shouldNotWrapErrorResponse() {
        webTestClient.get().uri("/test/error")
                .exchange()
                .expectStatus().isBadRequest()
                .expectHeader().contentType(MediaType.APPLICATION_JSON)
                .expectBody()
                .jsonPath("$.meta").exists()
                .jsonPath("$.errors").exists()
                .jsonPath("$.errors[0].code").isEqualTo("400-CUSTOM-ERROR")
                .jsonPath("$.data").doesNotExist();
    }

    @Test
    @DisplayName("No debería envolver una respuesta que ya tiene el formato ApiResponse")
    void shouldNotDoubleWrapAlreadyFormattedResponse() {
        webTestClient.get().uri("/test/pre-wrapped")
                .exchange()
                .expectStatus().isOk()
                .expectHeader().contentType(MediaType.APPLICATION_JSON)
                .expectBody()
                .jsonPath("$.meta").exists()
                .jsonPath("$.meta.status").isEqualTo(200)
                .jsonPath("$.data.message").isEqualTo("This is already wrapped")
                .jsonPath("$.data.meta").doesNotExist(); // La comprobación clave: no hay un 'meta' dentro del 'data'.
    }

    @Test
    @DisplayName("Debería devolver un error 500 estándar si la serialización del framework falla")
    void shouldReturnStandard500ErrorOnFrameworkSerializationFailure() {
        webTestClient.get().uri("/test/unserializable")
                .exchange()
                // 1. Aserción clave: el estado DEBE ser 500 Internal Server Error.
                .expectHeader().contentType(MediaType.APPLICATION_JSON)
                .expectBody()
                // 2. Aserciones sobre el cuerpo de error estándar de Spring Boot.
                //    Este cuerpo NO es el original, sino el generado por el manejador de errores de Spring.
                .jsonPath("$.status").isEqualTo(500)
                .jsonPath("$.error").isEqualTo("Internal Server Error")
                .jsonPath("$.path").isEqualTo("/test/unserializable")
                // 3. Confirmamos que no hay rastro del cuerpo original ni de nuestra envoltura personalizada.
                .jsonPath("$.meta").doesNotExist()
                .jsonPath("$.data").doesNotExist()
                .jsonPath("$.id").doesNotExist();
    }


    // --- CONFIGURACIÓN INTERNA Y COMPONENTES DE PRUEBA ---

    @Data
    @NoArgsConstructor
    @AllArgsConstructor
    static class TestDto {
        private int id;
        private String name;
    }

    // DTO diseñado para fallar durante la serialización de Jackson debido a una referencia circular.
    @Data
    static class UnserializableDto {
        private int id = 123;
        private Object problematicField = this;
    }

    @RestController
    static class TestController {
        @GetMapping("/test/mono")
        Mono<TestDto> getMono() {
            return Mono.just(new TestDto(1, "Test Mono"));
        }

        @GetMapping("/test/flux")
        Flux<TestDto> getFlux() {
            return Flux.just(new TestDto(1, "Test Flux 1"), new TestDto(2, "Test Flux 2"));
        }

        @GetMapping("/excluded/path")
        Mono<TestDto> getExcluded() {
            return Mono.just(new TestDto(99, "Excluded"));
        }

        @GetMapping("/test/error")
        Mono<TestDto> getError() {
            return Mono.error(new BusinessException("Error forzado", "400-CUSTOM-ERROR"));
        }

        @GetMapping("/test/pre-wrapped")
        Mono<ApiResponse<Map<String, String>>> getPreWrappedResponse() {
            ApiResponse.Meta meta = ApiResponse.Meta.builder().status(200).build();
            Map<String, String> data = Collections.singletonMap("message", "This is already wrapped");
            return Mono.just(ApiResponse.<Map<String, String>>builder().meta(meta).data(data).build());
        }

        @GetMapping("/test/unserializable")
        Mono<UnserializableDto> getUnserializableObject() {
            return Mono.just(new UnserializableDto());
        }
    }

    static class BusinessException extends RuntimeException {
        private final String errorCode;
        public BusinessException(String message, String errorCode) {
            super(message);
            this.errorCode = errorCode;
        }
        public String getErrorCode() {
            return errorCode;
        }
    }

    @org.springframework.web.bind.annotation.RestControllerAdvice
    static class TestGlobalExceptionHandler {
        @org.springframework.web.bind.annotation.ExceptionHandler(BusinessException.class)
        @org.springframework.web.bind.annotation.ResponseStatus(HttpStatus.BAD_REQUEST)
        public Mono<Map<String, Object>> handleBusinessException(BusinessException ex) {
            Map<String, String> error = Map.of("code", ex.getErrorCode(), "message", ex.getMessage());
            Map<String, Object> meta = Map.of("timestamp", Instant.now().toString());
            return Mono.just(Map.of("meta", meta, "errors", List.of(error)));
        }
    }

    @Configuration
    static class TestConfig {
        @Bean
        public ObjectMapper objectMapper() {
            return new ObjectMapper();
        }

        @Bean
        public AntPathMatcher antPathMatcher() {
            return new AntPathMatcher();
        }

        @Bean
        public TestGlobalExceptionHandler testGlobalExceptionHandler() {
            return new TestGlobalExceptionHandler();
        }

        @Bean
        public ResponseWrapperFilter responseWrapperFilter(
                ResponseWrapperProperties properties, ObjectMapper objectMapper
        ) {
            return new ResponseWrapperFilter(properties, objectMapper);
        }

        @Bean
        public TestController testController() {
            return new TestController();
        }
    }
}

Podemos extender las pruebas con StepVerifier para validar que el flujo sigue siendo reactivo y no introduce bloqueos inesperados.

Próximos Pasos y Extensiones

La solución presentada puede evolucionar hacia:

• Trazabilidad distribuida: Propagando requestId con Spring Cloud Sleuth, Zipkin o Jaeger.
• Internacionalización: Soporte para mensajes localizados en errores o advertencias.
• Observabilidad avanzada: Tiempo de procesamiento en meta, integración con Prometheus o Grafana.
• Functional Endpoints: Adaptando la solución a APIs basadas en RouterFunction en lugar de anotaciones tradicionales.

Con esta base, la envoltura de respuestas deja de ser solo un detalle de formato y se convierte en una capa estratégica para consistencia, trazabilidad y mantenimiento a largo plazo.

En el desarrollo de APIs, el manejo de errores suele ser un ciudadano de segunda clase. Con frecuencia, nos conformamos con respuestas de error genéricas, inconsistentes o, en el peor de los casos, con trazas de stack trace en HTML que no aportan valor al consumidor de la API. Un buen contrato de API no solo define las rutas de éxito, sino que también establece un lenguaje claro y predecible para cuando las cosas van mal.

El objetivo de este artículo es construir, paso a paso, una estrategia de manejo de excepciones que sea robusta, escalable y centralizada. Dejaremos atrás los bloques try-catch dispersos por el código de negocio para dar paso a un sistema que produce respuestas JSON consistentes y enriquecidas para cualquier tipo de error, ya sea una validación de negocio, un recurso no encontrado o un fallo inesperado del sistema. Para ello, nos apoyaremos en principios de diseño sólidos como el Patrón Strategy, el Principio de Abierto/Cerrado y un enfoque que mantiene nuestro dominio limpio de preocupaciones de infraestructura.

Definiendo un Lenguaje Común para el Error

Antes de manejar cualquier error, debemos definir cómo queremos comunicarlo. En lugar de depender de estructuras volátiles como Map<String, Object>, estableceremos un contrato sólido mediante Data Transfer Objects (DTOs). Esto nos proporciona seguridad de tipos, autocompletado en el IDE y una excelente base para la documentación automática con herramientas como OpenAPI.

Nuestra estructura de respuesta de error estándar será la siguiente:

{
  "meta": {
    "timestamp": "2025-08-28T19:12:58.123Z",
    "path": "/api/users",
    "status": 409,
    "requestId": "a1b2c3d4e5"
  },
  "errors": [
    {
      "code": "409-001",
      "message": "EMAIL ALREADY EXISTS",
      "payload": {
        "email": "[email protected]"
      }
    }
  ]
}

Para modelar esto, definimos tres clases principales. ApiErrorResponse es el contenedor principal, que incluye una sección de metadatos (Meta) y una lista de errores. El ApiError en sí mismo es flexible, con un código, un mensaje y un payload opcional para datos contextuales.

// Modelo de respuesta genérico y estandarizado
@Data
@Builder
public class ApiErrorResponse<T> {
    private Meta meta;
    private List<T> errors;

    @Data
    @Builder
    public static class Meta {
        private String timestamp;
        private String path;
        private int status;
        private String requestId;
    }
}

// DTO que representa un único error de la API
@JsonInclude(JsonInclude.Include.NON_NULL)
public record ApiError(String code, String message, Object payload) {
    public ApiError(String code, String message) {
        this(code, message, null);
    }
}

Finalmente, un pequeño DTO para encapsular el contexto de la petición que se pasará a través de nuestro sistema.

// Encapsula la información del contexto de la request
@Data
@Builder
public class RequestContextApi {
    private String path;
    private String requestId;
}

Manteniendo el Dominio Puro: La BusinessException

Una de las claves de una buena arquitectura es la separación de conceptos. La lógica de negocio no debería saber nada sobre códigos de estado HTTP o la estructura de una respuesta JSON. Para lograrlo, definimos una excepción base para nuestro dominio, BusinessException.

Esta clase abstracta es simple pero poderosa. Contiene un errorCode único para la aplicación y un payload opcional. Cualquier excepción de negocio específica (ej. InsufficientFundsException) heredará de ella, manteniendo el dominio completamente agnóstico a la tecnología.

@Getter
public abstract class BusinessException extends RuntimeException {

    private final String errorCode;
    private final Object payload;

    protected BusinessException(String message, String errorCode, Object payload) {
        super((message != null) ? message.toUpperCase() : "");
        this.errorCode = errorCode;
        this.payload = payload;
    }

    protected BusinessException(String message, String errorCode) {
        super((message != null) ? message.toUpperCase() : "");
        this.errorCode = errorCode;
        this.payload = null;
    }
}

El Cerebro de la Operación: El Patrón Strategy

Con los modelos definidos, es hora de diseñar el mecanismo central. En lugar de un gran bloque if-else o un switch para manejar diferentes tipos de excepciones, utilizaremos el Patrón Strategy. Esto nos permitirá encapsular la lógica para manejar cada tipo de excepción en su propia clase, haciendo el sistema increíblemente fácil de extender.

La piedra angular es la interfaz ExceptionHandlerStrategy. Define un contrato que cada manejador debe cumplir:

1. supports(Class<? extends Throwable> exceptionType): Determina si el manejador es capaz de procesar un tipo de excepción dado.
2. getStatus(Throwable ex): Define el HttpStatus que corresponde a la excepción. Esto nos permite devolver códigos más precisos que un simple 400 o 500.
3. handle(Throwable ex, ...): El método que procesa la excepción. Lo interesante aquí es que proveemos una implementación default que cubre los casos más comunes, de modo que muchos de nuestros manejadores serán puramente declarativos.

public interface ExceptionHandlerStrategy {

    boolean supports(Class<? extends Throwable> exceptionType);

    default HttpStatus getStatus(Throwable ex) {
        return HttpStatus.INTERNAL_SERVER_ERROR;
    }

    default ResponseEntity<ApiErrorResponse<?>> handle(Throwable ex, RequestContextApi context) {
        HttpStatus status = getStatus(ex);
        Object error = new ApiError(String.valueOf(status.value()), "INTERNAL_SERVER_ERROR");
        return buildErrorResponse(status, context, (error instanceof List<?>) ? (List<?>) error : List.of(error));
    }
    
    static ResponseEntity<ApiErrorResponse<?>> buildErrorResponse(
            HttpStatus status, RequestContextApi context, List<?> errors) {
        // ... Lógica para construir la respuesta final ...
    }
}

Estrategias en Acción: El Manejador Específico y el Genérico

Con la interfaz lista, crear manejadores es trivial. Para nuestras BusinessException, creamos un BusinessExceptionHandler. Este manejador sobreescribe getStatus para implementar una lógica ingeniosa que deriva el código de estado HTTP a partir del errorCode de la excepción (ej. "409-001" se convierte en HttpStatus.CONFLICT). También sobreescribe handle para asegurarse de que el payload se incluya en la respuesta.

@Component
public class BusinessExceptionHandler implements ExceptionHandlerStrategy {

    @Override
    public boolean supports(Class<? extends Throwable> exceptionType) {
        return BusinessException.class.isAssignableFrom(exceptionType);
    }

    @Override
    public HttpStatus getStatus(Throwable ex) {
        BusinessException businessException = (BusinessException) ex;
        String codeHttp = businessException.getErrorCode().split("-")[0];
        try {
            int codigo = Integer.parseInt(codeHttp);
            return HttpStatus.valueOf(codigo);
        } catch (Exception e) {
            return HttpStatus.BAD_REQUEST;
        }
    }

    @Override
    public ResponseEntity<ApiErrorResponse<?>> handle(Throwable ex, RequestContextApi context) {
        BusinessException exception = (BusinessException) ex;
        HttpStatus status = getStatus(exception);
        Object error = new ApiError(exception.getErrorCode(), exception.getMessage(), exception.getPayload());
        return ExceptionHandlerStrategy.buildErrorResponse(status, context, (error instanceof List<?>) ? (List<?>) error : List.of(error));
    }
}

Para cualquier otra excepción no controlada, tenemos el GenericExceptionStrategyHandler. Gracias a la anotación @Order(Ordered.LOWEST_PRECEDENCE) de Spring, esta estrategia solo se ejecutará si ninguna otra más específica puede manejar la excepción. Es nuestra red de seguridad, y gracias a la implementación default de la interfaz, su código es mínimo.

@Component
@Order(Ordered.LOWEST_PRECEDENCE)
public class GenericExceptionStrategyHandler implements ExceptionHandlerStrategy {

    @Override
    public boolean supports(Class<? extends Throwable> exceptionType) {
        return true;
    }
}

El Orquestador: Poniendo Todo en Marcha

Las estrategias individuales son útiles, pero necesitamos un director de orquesta. Aquí es donde entran el GlobalExceptionHandlerStrategyRegistry y el GlobalExceptionTranslator.

El Registry es una clase simple que se inyecta con una lista de todas las implementaciones de ExceptionHandlerStrategy disponibles en el contexto de Spring. Su única misión es iterar sobre ellas (respetando el @Order) y delegar el control a la primera que declare que puede manejar la excepción.

@Component
public class GlobalExceptionHandlerStrategyRegistry {

    private final List<ExceptionHandlerStrategy> strategies;

    public GlobalExceptionHandlerStrategyRegistry(List<ExceptionHandlerStrategy> strategies) {
        this.strategies = strategies;
    }

    public ResponseEntity<ApiErrorResponse<?>> handle(Throwable ex, RequestContextApi context) {
        return strategies.stream()
                .filter(s -> s.supports(ex.getClass()))
                .findFirst()
                .map(s -> s.handle(ex, context))
                .orElseThrow(() -> new IllegalStateException("No suitable exception handler found.", ex));
    }
}

Finalmente, el Translator es el punto de entrada. Es una clase anotada con @RestControllerAdvice que captura cualquier Throwable que escape de nuestros controladores. Su responsabilidad es mínima y crucial: crear el RequestContextApi y pasarle la excepción al Registry. No contiene ninguna lógica de negocio, lo que lo mantiene limpio y enfocado.

@RestControllerAdvice
@RequiredArgsConstructor
public class GlobalExceptionTranslator {

    private final GlobalExceptionHandlerStrategyRegistry registry;

    @ExceptionHandler(Throwable.class)
    public final ResponseEntity<ApiErrorResponse<?>> handleAnyException(
            Throwable ex, ServerWebExchange exchange) {

        RequestContextApi context = RequestContextApi.builder()
                .path(exchange.getRequest().getURI().getPath())
                .requestId(UUID.randomUUID().toString().substring(0, 10))
                .build();

        return registry.handle(ex, context);
    }
}

Con todas las piezas en su lugar, podemos visualizar la arquitectura completa y el flujo de una excepción a través de nuestro sistema. El siguiente diagrama ilustra cómo estos componentes colaboran, desde la captura inicial hasta la selección de la estrategia adecuada y la construcción de la respuesta final.

        classDiagram
            class DatabaseConnectionPool {
                -DatabaseEngineFactory engineFactory
                +dataSourceFromSecret(String, DatabaseConnectionPropertiesFactory) DataSource
            }
            class DatabaseConnectionPropertiesFactory {
                -GenericManager secretsManager
                +getDatabaseConnectionProperties(String) DatabaseConnectionProperties
            }
            class DatabaseConnectionProperties {
                -String dbname
                -String username
                -String password
                -String engine
                ...
            }
            class DatabaseEngineFactory {
                -Map~String, DatabaseEngineStrategy~ strategies
                +getStrategy(String) DatabaseEngineStrategy
            }
            class DatabaseEngineStrategy {
                <>
                +getName() String
                +buildJdbcUrl(...) String
                +getValidationQuery() String
            }
            class PostgresqlStrategy {
                +getName() String
                ...
            }
            class MysqlStrategy {
                +getName() String
                ...
            }
            DatabaseConnectionPool ..> DatabaseConnectionPropertiesFactory : uses
            DatabaseConnectionPool ..> DatabaseEngineFactory : uses
            DatabaseConnectionPropertiesFactory ..> DatabaseConnectionProperties : creates
            DatabaseEngineFactory ..> DatabaseEngineStrategy : uses
            PostgresqlStrategy --|> DatabaseEngineStrategy : implements
            MysqlStrategy --|> DatabaseEngineStrategy : implements
  

Conclusión y Futuras Mejoras

Hemos construido un sistema de manejo de excepciones que es a la vez potente y elegante. Todas las respuestas de error de nuestra API son ahora consistentes, informativas y se generan a través de un flujo centralizado y predecible. La belleza de este diseño radica en su escalabilidad: añadir soporte para un nuevo tipo de excepción es tan simple como crear una nueva clase Strategy, sin necesidad de modificar el código existente, adhiriéndonos así al Principio de Abierto/Cerrado.

Este sistema, sin embargo, es una base sólida sobre la cual se puede seguir construyendo. Algunas líneas futuras de mejora podrían incluir:

• Integración con Logging: Centralizar el registro de las excepciones completas dentro de los manejadores para un monitoreo más efectivo.
• Internacionalización (i18n): Modificar el ApiError y los manejadores para que puedan devolver mensajes de error en diferentes idiomas según las cabeceras de la petición.
• Manejadores Específicos de Framework: Crear estrategias para excepciones comunes de frameworks como Spring Security (ej. AccessDeniedException) para traducirlas a respuestas 403 Forbidden con un formato consistente.

En el desarrollo de aplicaciones reactivas modernas, especialmente bajo paradigmas como la Arquitectura Hexagonal, surgen desafíos que nos obligan a repensar cómo aplicamos conceptos transversales. Uno de los interrogantes más comunes es: ¿dónde y cómo gestionamos las transacciones de base de datos sin contaminar nuestra lógica de negocio? Este artículo documenta un viaje desde esa pregunta inicial hasta una solución robusta y elegante, utilizando el poder de la Programación Orientada a Aspectos (AOP) en un entorno Spring WebFlux con R2DBC.

La Arquitectura como Punto de Partida

Antes de sumergirnos en el código, es fundamental visualizar la estructura del proyecto. Una organización clara de paquetes, que refleje las capas de la Arquitectura Hexagonal, es la base sobre la que construiremos nuestra solución. El dominio permanece en el centro, puro y sin dependencias externas, mientras que la aplicación y la infraestructura se organizan a su alrededor.

ms_auth/
├── applications/app-service/      # Módulo principal de la aplicación Spring Boot
│   ├── build.gradle
│   └── src/
│       ├── main/java/com/app247/
│       │   ├── MainApplication.java
│       │   └── config/aop/
│       │       └── TransactionalUseCaseAspect.java  # Nuestro Aspecto AOP
│       └── test/java/com/app247/config/aop/
│           ├── TransactionalUseCaseAspectTest.java  # Test unitario del Aspecto
│           └── TransactionalRollbackSelfContainedTest.java # Test de Integración
│
├── domain/
│   ├── model/
│   └── usecase/                     # Módulo de la lógica de negocio pura
│       └── src/main/java/com/app247/usecase/shared/core/usecase/
│           ├── TransactionalWrapperUseCase.java # Anotación personalizada
│           └── UseCase.java                     # Interfaz genérica
│
└── infrastructure/
    ├── r2dbc-postgresql/          # Módulo adaptador para la base de datos
    └── reactive-web/              # Módulo adaptador para los controladores REST

El Dilema Inicial: La Transacción y la Unidad de Trabajo

Todo comienza con una necesidad fundamental: asegurar la atomicidad de las operaciones. Imaginemos un caso de uso de negocio, como procesar una compra, que implica modificar el inventario de productos y crear un registro de orden. Ambas acciones deben tener éxito, o ninguna debe persistir. Esta es la definición de una unidad de trabajo, y la herramienta para garantizarla es la transacción.

La primera intuición podría ser colocar la anotación @Transactional de Spring en los métodos del repositorio. Sin embargo, esto es incorrecto. Una transacción en el repositorio solo cubriría una única operación de base de datos, rompiendo la unidad de trabajo del negocio. La transacción debe envolver la ejecución completa del caso de uso.

Esto nos lleva a la capa de servicio o caso de uso. Pero aquí nos encontramos con el primer gran obstáculo arquitectónico. En una Arquitectura Hexagonal, la capa de dominio (donde residen los casos de uso) debe ser pura. No puede, ni debe, tener dependencias de frameworks externos como Spring. Anotar un caso de uso del dominio con @Transactional viola este principio fundamental, acoplando nuestra lógica de negocio más preciada a un detalle de infraestructura.

La Solución Emerge: Programación Orientada a Aspectos

Si no podemos modificar el dominio, debemos aplicar el comportamiento transaccional desde afuera, de una manera no invasiva. Aquí es donde la Programación Orientada a Aspectos (AOP) brilla. AOP nos permite interceptar la ejecución de nuestros métodos para añadir funcionalidades transversales (como transacciones, seguridad o logging) sin alterar el código original.

La estrategia que emerge es crear un mecanismo declarativo y reutilizable que nos permita "marcar" qué casos de uso deben ser transaccionales, dejando que la magia de AOP haga el resto.

Una Anotación para Declarar la Intención

El primer paso es crear una anotación personalizada. Su único propósito es servir como una señal o marcador. Al ser parte de nuestro código de dominio (usecase), no introduce una dependencia directa de Spring, sino que define un contrato interno.

package com.app247.usecase.shared.core.usecase;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Anotación para marcar clases de Casos de Uso que deben ser
 * envueltas en una transacción reactiva de forma automática.
 */
@Target(ElementType.TYPE) // Se aplica a nivel de clase
@Retention(RetentionPolicy.RUNTIME) // Disponible en tiempo de ejecución para que Spring la lea
public @interface TransactionalWrapperUseCase {
}

Junto a esta, podemos definir una interfaz genérica para estandarizar nuestros casos de uso, promoviendo un diseño limpio y consistente.

package com.app247.usecase.shared.core.usecase;

// Interfaz genérica (opcional pero recomendada)
public interface UseCase<Request, Response> {
    Response execute(Request request);
}

El Aspecto: El Motor de la Transacción

Con la anotación en su lugar, construimos el componente que buscará esta marca y aplicará la lógica transaccional. Este es nuestro Aspecto, una clase de infraestructura que vive en la capa de aplicación.

Este Aspecto tiene dos partes clave:

1. Pointcut: Una expresión que actúa como un selector. Le dice a Spring: "Encuentra todos los métodos públicos en cualquier clase que esté anotada con @TransactionalWrapperUseCase".
2. Advice: La lógica que se ejecuta cuando el Pointcut encuentra una coincidencia. Usaremos un advice de tipo @Around, que nos permite envolver completamente la ejecución del método original.

La lógica del advice es simple pero poderosa: toma el Mono o Flux devuelto por el caso de uso y lo compone con el TransactionalOperator reactivo de Spring. Este operador se encarga de iniciar la transacción antes de la suscripción y de realizar commit o rollback al finalizar.

package com.app247.config.aop;

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Pointcut;
import org.springframework.stereotype.Component;
import org.springframework.transaction.reactive.TransactionalOperator;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

@Aspect
@Component
public class TransactionalUseCaseAspect {

    private final TransactionalOperator transactionalOperator;

    public TransactionalUseCaseAspect(TransactionalOperator transactionalOperator) {
        this.transactionalOperator = transactionalOperator;
    }
    
    @Pointcut("@within(com.app247.usecase.shared.core.usecase.TransactionalWrapperUseCase) && execution(public * *(..))")
    public void transactionalUseCase() {
        // Método vacío para nombrar el pointcut.
    }

    @Around("transactionalUseCase()")
    public Object wrapInTransaction(ProceedingJoinPoint joinPoint) throws Throwable {
        Object result = joinPoint.proceed();

        if (result instanceof Mono) {
            return ((Mono<?>) result).as(transactionalOperator::transactional);
        } else if (result instanceof Flux) {
            return ((Flux<?>) result).as(transactionalOperator::transactional);
        }

        return result;
    }
}

Con estos dos elementos, hemos creado un sistema donde simplemente anotando una clase de caso de uso con @TransactionalWrapperUseCase, garantizamos que su ejecución será atómica, sin haber escrito una sola línea de código transaccional dentro del propio caso de uso.

Probando la Solución: De la Confianza a la Certeza

Una solución no está completa hasta que se prueba rigurosamente. Para este mecanismo, necesitamos dos niveles de prueba para tener una confianza total.

Nivel 1: El Test de Cableado (Unitario)

El primer test debe responder a la pregunta: ¿Nuestro aspecto AOP está correctamente configurado para interceptar la llamada y usar el TransactionalOperator? Este test valida tanto respuestas Mono como Flux.

Este test no necesita una base de datos. Utiliza un contexto de Spring para activar el mecanismo AOP, pero reemplaza todas las dependencias externas (TransactionalOperator, repositorios) con Mocks. El objetivo no es probar el rollback, sino verificar la interacción: que el método transactional() del operador sea invocado.

package com.app247.config.aop;

import com.app247.usecase.shared.core.usecase.TransactionalWrapperUseCase;
import org.junit.jupiter.api.Test;
import org.mockito.InjectMocks;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.EnableAspectJAutoProxy;
import org.springframework.context.annotation.Import;
import org.springframework.test.context.bean.override.mockito.MockitoBean;
import org.springframework.transaction.reactive.TransactionalOperator;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
import reactor.test.StepVerifier;

import static org.assertj.core.api.AssertionsForClassTypes.assertThat;
import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.*;


@SpringBootTest(classes = TransactionalUseCaseAspectTest.TestConfig.class)
class TransactionalUseCaseAspectTest {

    @Autowired
    private PurchaseProductUseCasePort purchaseUseCase;
    @Autowired
    private FindProductsUseCasePort findProductsUseCase; // Caso de uso que devuelve Flux
    @Autowired
    private NonReactiveUseCasePort nonReactiveUseCase;

    @MockitoBean
    private ProductRepository productRepository;
    @MockitoBean
    private OrderRepository orderRepository;
    @MockitoBean
    private TransactionalOperator transactionalOperator;
    @InjectMocks
    private TransactionalUseCaseAspect transactionalUseCaseAspect;

    @Test
    void whenUseCaseReturnsMono_thenItShouldBeWrappedInTransaction() {
        // ARRANGE
        Product fakeProduct = new Product("prod-123", 10);
        Order fakeOrder = new Order("user-007", "prod-123");

        when(productRepository.findById(any())).thenReturn(Mono.just(fakeProduct));
        when(orderRepository.save(any())).thenReturn(Mono.just(fakeOrder));
        when(productRepository.updateStock(any(), any(Integer.class))).thenReturn(Mono.empty());
        when(transactionalOperator.transactional(any(Mono.class)))
                .thenAnswer(invocation -> invocation.getArgument(0));

        // ACT
        Mono<Order> result = purchaseUseCase.execute("user-007", "prod-123");

        // ASSERT
        StepVerifier.create(result).expectNext(fakeOrder).verifyComplete();
        verify(transactionalOperator).transactional(any(Mono.class));
        verify(productRepository).updateStock("prod-123", 9);
    }

    @Test
    void whenUseCaseReturnsFlux_thenItShouldBeWrappedInTransaction() {
        // ARRANGE
        Product fakeProduct1 = new Product("prod-001", 5);
        Product fakeProduct2 = new Product("prod-002", 3);

        when(productRepository.findAll()).thenReturn(Flux.just(fakeProduct1, fakeProduct2));
        // Configuramos el mock para que el operador transaccional simplemente devuelva el Flux original
        when(transactionalOperator.transactional(any(Flux.class)))
                .thenAnswer(invocation -> invocation.getArgument(0));

        // ACT
        Flux<Product> result = findProductsUseCase.execute(null); // `null` porque no requiere parámetros

        // ASSERT
        StepVerifier.create(result)
                .expectNext(fakeProduct1)
                .expectNext(fakeProduct2)
                .verifyComplete();

        // La verificación clave: ¿Se llamó al operador con un Flux?
        verify(transactionalOperator).transactional(any(Flux.class));
    }

    /**
     * Test para el caso no reactivo.
     */
    @Test
    void whenUseCaseIsNotReactive_thenItShouldNotBeWrappedInTransaction() {
        // --- ARRANGE (Preparar) ---
        String expectedResult = "Este es un resultado síncrono";

        // --- ACT (Actuar) ---
        // Ejecutamos el caso de uso que devuelve un String simple.
        String actualResult = nonReactiveUseCase.execute(null);

        // --- ASSERT (Verificar) ---

        // 1. Verificamos que el resultado devuelto es el original, sin cambios.
        assertThat(actualResult).isEqualTo(expectedResult);

        // 2. La verificación MÁS IMPORTANTE: nos aseguramos de que el operador transaccional
        //    NUNCA fue invocado, ya que la respuesta no era ni Mono ni Flux.
        verify(transactionalOperator, never()).transactional(any(Mono.class));
        verify(transactionalOperator, never()).transactional(any(Flux.class));
    }

    @Test
    void transactionalUseCasePointcut_shouldExecuteForCoverage() {
        // --- ACT ---
        // Simplemente llamamos al método vacío.
        // La herramienta de cobertura registrará que se ha entrado en este método.

        // --- ASSERT ---
        // Como el método no hace nada, la única aserción posible es
        // que la llamada no lance ninguna excepción.
        assertDoesNotThrow(() -> {
            transactionalUseCaseAspect.transactionalUseCase();
        });
    }


    @Configuration
    @EnableAspectJAutoProxy
    @Import(TransactionalUseCaseAspect.class)
    static class TestConfig {
        @Bean
        public PurchaseProductUseCasePort purchaseProductUseCase(ProductRepository productRepo, OrderRepository orderRepo) {
            return new PurchaseProductUseCase(productRepo, orderRepo);
        }

        @Bean
        public FindProductsUseCasePort findProductsUseCase(ProductRepository productRepo) {
            return new FindProductsUseCase(productRepo);
        }
        @Bean
        public NonReactiveUseCasePort nonReactiveUseCase() {
            return new NonReactiveUseCase();
        }
    }

    // --- Definiciones Fakes ---
    record Product(String id, int stock) {}
    record Order(String userId, String productId) {}

    interface ProductRepository {
        Mono<Product> findById(String productId);
        Flux<Product> findAll(); // Añadido para el test de Flux
        Mono<Void> updateStock(String productId, int newStock);
    }
    interface OrderRepository { Mono<Order> save(Order order); }

    interface PurchaseProductUseCasePort { Mono<Order> execute(String userId, String productId); }
    interface FindProductsUseCasePort { Flux<Product> execute(Void request); } // Nuevo caso de uso para Flux

    interface NonReactiveUseCasePort { String execute(Void request); }

    @TransactionalWrapperUseCase
    static class PurchaseProductUseCase implements PurchaseProductUseCasePort {
        private final ProductRepository productRepository;
        private final OrderRepository orderRepository;
        public PurchaseProductUseCase(ProductRepository p, OrderRepository o) { this.productRepository = p; this.orderRepository = o; }
        public Mono<Order> execute(String userId, String productId) {
            return productRepository.findById(productId)
                    .flatMap(product -> productRepository.updateStock(product.id(), product.stock() - 1)
                            .then(orderRepository.save(new Order(userId, productId))));
        }
    }

    @TransactionalWrapperUseCase
    static class FindProductsUseCase implements FindProductsUseCasePort {
        private final ProductRepository productRepository;
        public FindProductsUseCase(ProductRepository p) { this.productRepository = p; }
        public Flux<Product> execute(Void request) {
            return productRepository.findAll();
        }
    }

    @TransactionalWrapperUseCase
    static class NonReactiveUseCase implements NonReactiveUseCasePort {
        @Override
        public String execute(Void request) {
            return "Este es un resultado síncrono";
        }
    }
}

Nivel 2: El Test de Comportamiento (Integración)

El segundo test debe responder a una pregunta más importante: si una operación falla, ¿la transacción realmente hace rollback?

Para esto, necesitamos un test de integración que utilice una base de datos real (en memoria, como H2, para velocidad y aislamiento) y el TransactionalOperator real de Spring. La clave aquí es usar @SpyBean para envolver un repositorio real y forzar un fallo en una de sus operaciones. La validación final consiste en consultar la base de datos después del fallo y verificar que el estado de los datos ha sido revertido a su estado original.

Este test es completamente autocontenido: define su propia configuración, su esquema de base de datos y sus implementaciones de dominio e infraestructura, pero lo más importante es que importa y prueba el Aspecto de AOP de producción real.

package com.app247.config.aop;

import com.app247.usecase.shared.core.usecase.TransactionalWrapperUseCase;
import io.r2dbc.spi.ConnectionFactory;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.TestInstance;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.ImportAutoConfiguration;
import org.springframework.boot.autoconfigure.context.PropertyPlaceholderAutoConfiguration;
import org.springframework.boot.autoconfigure.r2dbc.R2dbcAutoConfiguration;
import org.springframework.boot.autoconfigure.transaction.TransactionAutoConfiguration;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.EnableAspectJAutoProxy;
import org.springframework.context.annotation.Import;
import org.springframework.data.annotation.Id;
import org.springframework.data.r2dbc.core.R2dbcEntityTemplate;
import org.springframework.data.relational.core.mapping.Table;
import org.springframework.r2dbc.connection.R2dbcTransactionManager;
import org.springframework.r2dbc.core.DatabaseClient;
import org.springframework.stereotype.Repository;
import org.springframework.test.annotation.DirtiesContext;
import org.springframework.test.context.TestPropertySource;
import org.springframework.test.context.bean.override.mockito.MockitoSpyBean;
import reactor.core.publisher.Mono;
import reactor.test.StepVerifier;

import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.doReturn;
import static org.springframework.data.relational.core.query.Criteria.where;
import static org.springframework.data.relational.core.query.Query.query;

@SpringBootTest(classes = TransactionalRollbackSelfContainedTest.TestConfig.class)
@ImportAutoConfiguration({
        R2dbcAutoConfiguration.class,
        TransactionAutoConfiguration.class,
        PropertyPlaceholderAutoConfiguration.class
})
@TestPropertySource(properties = {
        "spring.r2dbc.url=r2dbc:h2:mem:///finaltestdb;DB_CLOSE_DELAY=-1;",
        "spring.r2dbc.username=sa",
        "spring.r2dbc.password=",
        "spring.sql.init.mode=never"
})
@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_CLASS)
@TestInstance(TestInstance.Lifecycle.PER_CLASS)
class TransactionalRollbackSelfContainedTest {

    @Autowired private PurchaseProductUseCasePort purchaseUseCase;
    @Autowired private DatabaseClient databaseClient;
    @Autowired private R2dbcEntityTemplate template;
    @MockitoSpyBean
    private OrderRepository orderRepository;

    private final String PRODUCT_ID = "prod-123";
    private final int INITIAL_STOCK = 10;

    @BeforeAll
    void setupDatabaseSchema() {
        String createProductsTable = "CREATE TABLE PRODUCTS (id VARCHAR(255) PRIMARY KEY, name VARCHAR(255), stock INT);";
        String createOrdersTable = "CREATE TABLE ORDERS (id INT AUTO_INCREMENT PRIMARY KEY, user_id VARCHAR(255), product_id VARCHAR(255));";
        databaseClient.sql(createProductsTable).then().block();
        databaseClient.sql(createOrdersTable).then().block();
    }

    @BeforeEach
    void setupTestData() {
        databaseClient.sql("DELETE FROM PRODUCTS").then().block();
        template.insert(new ProductEntity(PRODUCT_ID, "Test Product", INITIAL_STOCK)).block();
    }

    @Test
    void whenSecondOperationFails_thenRealAspectRollsBackTransaction() {
        doReturn(Mono.error(new RuntimeException("DB Error"))).when(orderRepository).save(any());
        Mono<Void> result = purchaseUseCase.execute("user-007", PRODUCT_ID);
        StepVerifier.create(result).expectError(RuntimeException.class).verify();
        ProductEntity productAfter = template.selectOne(query(where("id").is(PRODUCT_ID)), ProductEntity.class).block();
        assertThat(productAfter.stock()).isEqualTo(INITIAL_STOCK);
    }

    @Configuration
    @EnableAspectJAutoProxy
    @Import(TransactionalUseCaseAspect.class)
    static class TestConfig {
        @Bean
        public R2dbcEntityTemplate r2dbcEntityTemplate(ConnectionFactory connectionFactory) {
            return new R2dbcEntityTemplate(connectionFactory);
        }

        @Bean
        public R2dbcTransactionManager transactionManager(ConnectionFactory connectionFactory) {
            return new R2dbcTransactionManager(connectionFactory);
        }

        @Bean
        public PurchaseProductUseCasePort purchaseProductUseCase(ProductRepository productRepo, OrderRepository orderRepo) {
            return new PurchaseProductUseCase(productRepo, orderRepo);
        }
        @Bean
        public ProductRepository productRepository(R2dbcEntityTemplate template) {
            return new R2dbcProductRepositoryAdapter(template);
        }
        @Bean
        public OrderRepository orderRepository(R2dbcEntityTemplate template) {
            return new R2dbcOrderRepositoryAdapter(template);
        }
    }

    record Product(String id, int stock) {}
    record Order(String userId, String productId) {}
    interface ProductRepository { Mono<Product> findById(String id); Mono<Void> updateStock(String id, int stock); }
    interface OrderRepository { Mono<Order> save(Order order); }
    interface PurchaseProductUseCasePort { Mono<Void> execute(String userId, String productId); }

    @Table("PRODUCTS")
    record ProductEntity(@Id String id, String name, int stock) {}
    @Table("ORDERS")
    record OrderEntity(@Id Integer id, String userId, String productId) {}

    @Repository
    static class R2dbcProductRepositoryAdapter implements ProductRepository {
        private final R2dbcEntityTemplate template;
        public R2dbcProductRepositoryAdapter(R2dbcEntityTemplate t) { this.template = t; }
        public Mono<Product> findById(String id) { return template.selectOne(query(where("id").is(id)),ProductEntity.class).map(e -> new Product(e.id(), e.stock())); }
        public Mono<Void> updateStock(String id, int stock) { return template.getDatabaseClient().sql("UPDATE PRODUCTS SET stock = :s WHERE id = :i").bind("s", stock).bind("i", id).fetch().rowsUpdated().then(); }
    }
    @Repository
    static class R2dbcOrderRepositoryAdapter implements OrderRepository {
        private final R2dbcEntityTemplate template;
        public R2dbcOrderRepositoryAdapter(R2dbcEntityTemplate t) { this.template = t; }
        public Mono<Order> save(Order o) { return template.insert(new OrderEntity(null, o.userId(), o.productId())).map(e -> o); }
    }

    @TransactionalWrapperUseCase
    static class PurchaseProductUseCase implements PurchaseProductUseCasePort {
        private final ProductRepository pRepo;
        private final OrderRepository oRepo;
        public PurchaseProductUseCase(ProductRepository p, OrderRepository o) { this.pRepo = p; this.oRepo = o; }
        public Mono<Void> execute(String userId, String productId) {
            return pRepo.findById(productId).flatMap(p -> pRepo.updateStock(p.id(), p.stock() - 1)).then(oRepo.save(new Order(userId, productId))).then();
        }
    }
}

Conclusión y Próximos Pasos

Hemos construido una solución completa, limpia y robusta para un problema complejo. Al mantener nuestro dominio puro y delegar las responsabilidades transversales a la capa de aplicación mediante AOP, logramos un código desacoplado, mantenible y altamente testeable. Las dependencias del proyecto reflejan esta arquitectura limpia, utilizando starters de Spring Boot para AOP y R2DBC, y librerías de prueba para H2 y ArchUnit.

// build.gradle
dependencies {
    implementation 'org.reactivecommons.utils:object-mapper:0.1.0'
    implementation project(':r2dbc-postgresql')
    implementation project(':reactive-web')
    implementation project(':model')
    implementation project(':usecase')
    implementation 'org.springframework.boot:spring-boot-starter'
    implementation 'org.springframework.boot:spring-boot-starter-aop'
    implementation 'org.springframework.boot:spring-boot-starter-data-r2dbc'
    runtimeOnly('org.springframework.boot:spring-boot-devtools')
    testImplementation 'com.tngtech.archunit:archunit:1.4.1'
    testImplementation 'com.fasterxml.jackson.core:jackson-databind'
    testImplementation 'com.h2database:h2'
    testImplementation 'io.r2dbc:r2dbc-h2'
}

Este patrón no se limita a las transacciones. El mismo mecanismo de anotación y aspecto puede extenderse para manejar otras responsabilidades, como la autorización de seguridad, la auditoría o el registro de métricas, consolidándose como una base sólida para el desarrollo de futuras funcionalidades en cualquier aplicación reactiva que aspire a una arquitectura limpia y escalable.

En el vertiginoso universo del desarrollo de software, donde la seguridad es un pilar innegociable y la agilidad es la moneda de cambio, nos enfrentamos a desafíos que van más allá de la simple lógica de negocio. Uno de los más recurrentes y críticos es la gestión de las conexiones a bases de datos. ¿Cómo construimos un sistema que no solo proteja sus credenciales como si fueran las joyas de la corona, sino que también sea lo suficientemente flexible para "hablar" con distintos motores de bases de datos sin despeinarse?

La respuesta no reside en un truco de magia, sino en la elegancia de la buena arquitectura. Este artículo te llevará en un viaje a través de una solución sofisticada en Spring Boot, donde desvelaremos cómo obtener credenciales de forma segura desde un gestor de secretos y, a la vez, emplear el ingenioso patrón de diseño Strategy para crear DataSources que se adaptan dinámicamente a su entorno. Prepárate para transformar una tarea mundana en una pieza de ingeniería de software.

El Mapa de la Arquitectura

Toda gran solución comienza con un plan. Antes de sumergirnos en el código, visualicemos nuestro ecosistema. No se trata de un monolito de lógica enrevesada, sino de un conjunto de componentes especializados que colaboran en perfecta armonía, como una orquesta bien afinada.

Antes de desgranar el código, un buen mapa visual nos ayudará a navegar la solución. El siguiente diagrama de clases ilustra las relaciones y dependencias entre nuestros componentes clave. Observa cómo las fábricas (Factory) orquestan la creación de objetos, mientras que la interfaz DatabaseEngineStrategy actúa como un contrato para sus diferentes implementaciones.

        classDiagram
            class DatabaseConnectionPool {
                -DatabaseEngineFactory engineFactory
                +dataSourceFromSecret(String, DatabaseConnectionPropertiesFactory) DataSource
            }
            class DatabaseConnectionPropertiesFactory {
                -GenericManager secretsManager
                +getDatabaseConnectionProperties(String) DatabaseConnectionProperties
            }
            class DatabaseConnectionProperties {
                -String dbname
                -String username
                -String password
                -String engine
                ...
            }
            class DatabaseEngineFactory {
                -Map~String, DatabaseEngineStrategy~ strategies
                +getStrategy(String) DatabaseEngineStrategy
            }
            class DatabaseEngineStrategy {
                <>
                +getName() String
                +buildJdbcUrl(...) String
                +getValidationQuery() String
            }
            class PostgresqlStrategy {
                +getName() String
                ...
            }
            class MysqlStrategy {
                +getName() String
                ...
            }
            DatabaseConnectionPool ..> DatabaseConnectionPropertiesFactory : uses
            DatabaseConnectionPool ..> DatabaseEngineFactory : uses
            DatabaseConnectionPropertiesFactory ..> DatabaseConnectionProperties : creates
            DatabaseEngineFactory ..> DatabaseEngineStrategy : uses
            PostgresqlStrategy --|> DatabaseEngineStrategy : implements
            MysqlStrategy --|> DatabaseEngineStrategy : implements
  

El flujo de nuestra sinfonía es el siguiente:

1. El director de orquesta (DatabaseConnectionPool) necesita la partitura: las propiedades de conexión. Para ello, acude a nuestro "bibliotecario" (DatabaseConnectionPropertiesFactory).
2. El bibliotecario viaja a una bóveda segura (el gestor de secretos) para recuperar la partitura (DatabaseConnectionProperties).
3. La partitura indica qué tipo de instrumento principal se necesita (el engine, ej. "postgres"). Con esta clave, el director consulta a un "maestro de instrumentos" (DatabaseEngineFactory).
4. Este maestro selecciona al músico virtuoso adecuado (DatabaseEngineStrategy) para ese instrumento.
5. El músico, con su maestría, interpreta la partitura y genera la melodía única: la URL JDBC.
6. Finalmente, con todos los elementos en su lugar, el director da la señal y se forma la orquesta completa: un pool de conexiones HikariDataSource listo para actuar.

Ahora, conozcamos a cada uno de los protagonistas de esta obra.

1. El Molde de Nuestros Secretos: DatabaseConnectionProperties

Todo sistema necesita un lenguaje común. Antes de poder manejar nuestros secretos, debemos definir su forma. Aquí es donde entra en juego DatabaseConnectionProperties, nuestro DTO (Data Transfer Object). No es más que el plano que define qué información esperamos encontrar en esa bóveda segura. Con la ayuda de Lombok, su definición es pura simpleza y elegancia.

package com.app247.mecrblog.jpa.config.datasource;

import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class DatabaseConnectionProperties {

    private String dbname;
    private String schema;
    private String username;
    private String password;
    private String host;
    private Integer port;
    private String engine; // La pieza clave que define nuestra estrategia.
    private String dbClusterIdentifier;

}

Esta clase es nuestro contrato: cualquier secreto que recuperemos deberá poder amoldarse a esta estructura.

2. El Guardián de los Secretos: DatabaseConnectionPropertiesFactory

La misión de esta fábrica es simple pero crucial: aventurarse en el mundo exterior, dialogar con el gestor de secretos y volver con el botín, ya transformado en nuestro DatabaseConnectionProperties.

package com.app247.mecrblog.jpa.config.datasource;

import org.springframework.stereotype.Component;
// ... (otros imports)
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;

@Slf4j
@RequiredArgsConstructor
@Component
public class DatabaseConnectionPropertiesFactory {

    private static final String DATABASE_SCHEMA = "schema";

    // Un detalle brillante: no depende de un cliente de AWS o Vault,
    // sino de nuestra propia interfaz 'GenericManager'. Pura abstracción.
    private final GenericManager secretsManager;

    public DatabaseConnectionProperties getDatabaseConnectionProperties(String key) throws SecretException {
        var props = secretsManager.getSecret(key, DatabaseConnectionProperties.class);
        props.setSchema(DATABASE_SCHEMA);

        log.info("Creando DataSource para el motor={} en host: {}...",
                   props.getEngine(), props.getHost());

        return props;
    }
}

La verdadera magia aquí es la dependencia de GenericManager. Esta interfaz es nuestro pasaporte universal, permitiéndonos cambiar de proveedor de secretos (de AWS a HashiCorp Vault, por ejemplo) con solo cambiar una implementación, sin que el resto de nuestra aplicación se inmute. Es el arte del desacoplamiento en su máxima expresión.

3. El Arte de la Poliglotía: Adaptabilidad con el Patrón Strategy

Aquí es donde la trama se pone interesante. ¿Qué sucede cuando nuestra aplicación necesita conversar fluidamente con PostgreSQL y, mañana, con MySQL? Podríamos caer en la tentación de un pantanoso bloque if-else o switch, un camino seguro hacia un código frágil y una deuda técnica creciente.

Pero nosotros elegimos un camino más elegante: el patrón Strategy.

El Contrato del Traductor: DatabaseEngineStrategy

Primero, definimos un contrato, una serie de reglas que cualquier "traductor" de dialectos de bases de datos debe seguir.

package com.app247.mecrblog.jpa.config.datasource;

public interface DatabaseEngineStrategy {
    // ¿Cómo te llamas? (ej: "postgres", "mysql")
    String getName();

    // ¿Cómo construyes una URL de conexión en tu idioma?
    String buildJdbcUrl(String host, int port, String dbname, String schema);

    // ¿Cuál es tu forma de verificar que estás vivo? (Validation Query)
    String getValidationQuery();
}

Los Especialistas en Dialectos

Con el contrato en mano, contratamos a nuestros especialistas. Cada uno es un maestro en su propio idioma y se registra como un bean de Spring (@Component).

El experto en PostgreSQL:

package com.app247.mecrblog.jpa.config.datasource.strategy;

import org.springframework.stereotype.Component;
// ...

@Component
public class PostgresqlStrategy implements DatabaseEngineStrategy {
    @Override
    public String getName() { return "postgres"; }

    @Override
    public String buildJdbcUrl(String host, int port, String dbname, String schema) {
        return String.format("jdbc:postgresql://%s:%d/%s%s", host, port, dbname,
                ((schema != null) && (!schema.isEmpty())) ? ("?currentSchema=" + schema) : "");
    }

    @Override
    public String getValidationQuery() { return "SELECT 1"; }
}

El experto en MySQL:

package com.app247.mecrblog.jpa.config.datasource.strategy;

import org.springframework.stereotype.Component;
// ...

@Component
public class MysqlStrategy implements DatabaseEngineStrategy {
    @Override
    public String getName() { return "mysql"; }

    @Override
    public String buildJdbcUrl(String host, int port, String dbname, String schema) {
        return String.format("jdbc:mysql://%s:%d/%s?useSSL=false&serverTimezone=UTC", host, port, dbname);
    }

    @Override
    public String getValidationQuery() { return "SELECT 1"; }
}

Esta estructura es liberadora. ¿Necesitamos soportar Oracle mañana? Simplemente creamos un OracleStrategy sin tocar una sola línea del código existente. Nuestro sistema ha aprendido a crecer.

4. El Maestro de Ceremonias: DatabaseEngineFactory

Ya tenemos a nuestros músicos especialistas, pero necesitamos a alguien que sepa a quién llamar en cada momento. Ese es el rol de DatabaseEngineFactory, nuestro maestro de ceremonias.

package com.app247.mecrblog.jpa.config.datasource;

import java.util.Map;
import java.util.function.Function;
import java.util.stream.Collectors;
// ...

@Slf4j
@Service
public class DatabaseEngineFactory {

    private final Map<String, DatabaseEngineStrategy> strategies;

    // Gracias a la magia de Spring, el constructor recibe un mapa con todos
    // nuestros especialistas (beans de DatabaseEngineStrategy) disponibles.
    public DatabaseEngineFactory(Map<String, DatabaseEngineStrategy> strategiesMap) {
        this.strategies = strategiesMap.values().stream()
                .collect(Collectors.toMap(DatabaseEngineStrategy::getName, Function.identity()));
        log.info("Motores de base de datos soportados: {}", this.strategies.keySet());
    }

    // Dada una clave ("postgres"), devuelve al especialista correcto.
    public DatabaseEngineStrategy getStrategy(String engineName) {
        DatabaseEngineStrategy strategy = strategies.get(engineName.toLowerCase());
        if (strategy == null) {
            throw new IllegalArgumentException("Motor de BD no soportado: " + engineName);
        }
        return strategy;
    }
}

Esta fábrica es un ejemplo sublime de cómo el framework Spring puede simplificar nuestro código. En lugar de registrar manualmente cada estrategia, Spring las descubre y nos las entrega listas para usar. La fábrica simplemente las organiza en un mapa para un acceso instantáneo.

5. La Gran Orquesta: Sincronizando Todo en DatabaseConnectionPool

Hemos llegado al acto final. Es hora de que el director suba al podio y una todas las piezas en una sinfonía funcional. La clase DatabaseConnectionPool es nuestro @Configuration principal, el lugar donde la magia realmente ocurre.

package com.app247.mecrblog.jpa.config.datasource;

import javax.sql.DataSource;
// ...
import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
// ...

@Slf4j
@Configuration
@RequiredArgsConstructor
@Profile({ "local", "qa", "dev", "pdn" }) // Actuamos solo en los escenarios indicados
public class DatabaseConnectionPool {

    // ... (Constantes de configuración de HikariCP)

    private final DatabaseEngineFactory engineFactory;

    @Bean
    public DataSource dataSourceFromSecret(
            @Value("${aws.secrets.credentials.db-write}") String secretName,
            DatabaseConnectionPropertiesFactory connectionPropertiesFactory) throws SecretException {

        // Acto 1: El bibliotecario trae la partitura.
        var props = connectionPropertiesFactory.getDatabaseConnectionProperties(secretName);

        // Acto 2: El maestro de ceremonias elige al virtuoso.
        DatabaseEngineStrategy engine = engineFactory.getStrategy(props.getEngine());

        // Acto 3: El virtuoso crea la melodía (la URL JDBC).
        String jdbcUrl = engine.buildJdbcUrl(props.getHost(), props.getPort(), props.getDbname(), props.getSchema());
        log.info("Creando DataSource con URL: {}", jdbcUrl);

        // Gran final: Se forma la orquesta (el pool de conexiones).
        return buildHikariDataSource(jdbcUrl, props.getUsername(), props.getPassword(), engine);
    }

    private DataSource buildHikariDataSource(String jdbcUrl, String username, String password,
                                             DatabaseEngineStrategy engine) {
        var config = new HikariConfig();
        config.setJdbcUrl(jdbcUrl);
        config.setUsername(username);
        config.setPassword(password);
        config.setPoolName("jpa-" + engine.getName() + "-hikari-pool");
        config.setConnectionTestQuery(engine.getValidationQuery()); // Usamos la frase del especialista
        // ... (resto de la configuración del pool)

        return new HikariDataSource(config);
    }
}

El método dataSourceFromSecret es el corazón palpitante de nuestra aplicación. Orquesta la secuencia de llamadas de una manera tan limpia y declarativa que su lógica se lee casi como prosa.

Telón Final y Futuras Funciones

Lo que hemos creado es más que un simple configurador de DataSource. Es un testimonio de cómo los buenos principios de diseño pueden dar como resultado un sistema que respira:

• Seguro: Las credenciales viven en su fortaleza, lejos de miradas indiscretas.
• Adaptable: Es un políglota de bases de datos, listo para aprender nuevos dialectos en cualquier momento.
• Robusto y Mantenible: Cada componente tiene su lugar y su propósito, haciendo que el sistema sea un placer de mantener y extender.

¿Y qué nos depara el futuro? Esta arquitectura no es un final, sino un punto de partida para nuevas aventuras:

1. Mundos Paralelos: Extender la lógica para manejar réplicas de lectura, creando un DataSource para escritura y otro para lectura.
2. Nuevos Talentos: Incorporar estrategias para Oracle, SQL Server o incluso bases de datos NoSQL con drivers JDBC.
3. Inteligencia Dinámica: Hacer que la selección del schema sea tan dinámica como el resto de la configuración.

Hemos transformado un requisito técnico en una solución elegante, demostrando que el código, en sus mejores momentos, se acerca más al arte que a la ciencia.

En el desarrollo de software moderno, escribir código que funciona perfectamente en escenarios ideales es solo el primer paso. La verdadera fortaleza de un sistema se manifiesta cuando debe enfrentar situaciones imprevistas, errores y desviaciones del comportamiento esperado. En este contexto, el manejo adecuado de excepciones se convierte en una disciplina fundamental.

Sin embargo, no todas las excepciones son iguales. Mientras que errores como NullPointerException o IOException señalan problemas técnicos o de infraestructura, existe una categoría más rica y expresiva: las Excepciones de Dominio. Estas no representan fallos técnicos, sino violaciones específicas de las reglas, políticas y restricciones del negocio.

Las excepciones de dominio son especialmente valiosas en arquitecturas que siguen los principios de Domain-Driven Design (DDD), ya que permiten que nuestro código comunique directamente en el lenguaje del negocio, encapsulando la lógica de forma explícita y comprensible.

Este artículo establece una base documental completa sobre el tema, explorando un catálogo exhaustivo de excepciones de dominio y presentando un patrón de implementación que mantiene la separación de responsabilidades entre las capas de dominio e infraestructura.

El Corazón del Asunto: Un Catálogo de Excepciones de Dominio

Una arquitectura robusta requiere identificar y nombrar los conceptos con precisión. Para los errores de negocio, esto significa crear una jerarquía de excepciones que comunique exactamente qué regla específica ha sido violada. El siguiente catálogo cubre una amplia gama de escenarios de negocio comunes:

Patrón de Implementación: De la Pureza del Dominio a la Realidad de la Infraestructura 💡

Tener una rica jerarquía de excepciones es valioso, pero el verdadero desafío está en manejarlas de forma elegante. El objetivo es que nuestra capa de dominio lance una InsufficientBalanceException sin conocimiento alguno sobre HTTP, mientras que nuestra capa de API REST la traduzca apropiadamente a una respuesta 422 Unprocessable Entity con formato JSON.

La solución combina el Principio de Inversión de Dependencias con el patrón Strategy, creando un sistema flexible y escalable.

1. La Base de Todo: DomainException

Creamos una clase base abstracta de la que heredarán todas nuestras excepciones de dominio. Es un POJO puro, sin dependencias de frameworks:

package com.tuempresa.dominio.excepciones;

/**
 * Excepción base del dominio.
 * 
 * Todas las excepciones específicas del dominio deben heredar de esta clase.
 * No contiene ninguna referencia a frameworks ni tecnologías (HTTP, DB, etc.)
 * 
 * Permite mantener un "errorCode" que facilita el mapeo en las capas de
 * aplicación/infraestructura.
 */
public abstract class DomainException extends RuntimeException {
    
    private final String errorCode;
    
    protected DomainException(String message, String errorCode) {
        super(message);
        this.errorCode = errorCode;
    }
    
    public String getErrorCode() {
        return errorCode;
    }
}

2. Una Excepción Concreta: EntityNotFoundException

Cada excepción de dominio es una clase simple que extiende DomainException, proporcionando sus propios códigos y mensajes por defecto:

package com.tuempresa.dominio.excepciones;

/**
 * Se lanza cuando una entidad no puede ser encontrada en el dominio.
 */
public class EntityNotFoundException extends DomainException {
    
    private static final String DEFAULT_MESSAGE = "ENTITY_NOT_FOUND";
    private static final String DEFAULT_CODE = "404-001";
    
    public EntityNotFoundException() {
        super(DEFAULT_MESSAGE, DEFAULT_CODE);
    }
    
    // Constructor opcional para mayor flexibilidad
    public EntityNotFoundException(String message, String errorCode) {
        super(message, errorCode);
    }
}

3. El Traductor: Patrón Strategy para el Manejo de Excepciones

En lugar de un gigantesco bloque if-else o switch, creamos una "estrategia" de manejo para cada excepción. Esto respeta el Principio de Abierto/Cerrado: podemos añadir nuevos manejadores sin modificar código existente.

3.1. La Interfaz Común (DomainExceptionHandlerStrategy)

Define el contrato que todos nuestros manejadores deben cumplir:

package com.tuempresa.infraestructura.excepciones;

import com.tuempresa.dominio.excepciones.DomainException;
import org.springframework.http.ResponseEntity;

public interface DomainExceptionHandlerStrategy<T extends DomainException> {
    
    /**
     * Devuelve el tipo de excepción que este manejador puede procesar.
     */
    Class<T> getExceptionType();
    
    /**
     * Procesa la excepción y la convierte en una respuesta HTTP.
     */
    ResponseEntity<ApiError> handle(T ex);
}

3.2. Un Manejador Específico (EntityNotFoundHandler)

Implementación concreta para EntityNotFoundException. Su única responsabilidad es traducir esta excepción de dominio en un HTTP 404 Not Found:

package com.tuempresa.infraestructura.excepciones;

import com.tuempresa.dominio.excepciones.EntityNotFoundException;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Component;

@Component
public class EntityNotFoundHandler 
    implements DomainExceptionHandlerStrategy<EntityNotFoundException> {
    
    @Override
    public Class<EntityNotFoundException> getExceptionType() {
        return EntityNotFoundException.class;
    }
    
    @Override
    public ResponseEntity<ApiError> handle(EntityNotFoundException ex) {
        ApiError error = new ApiError(ex.getErrorCode(), ex.getMessage());
        return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
    }
}

4. El Orquestador: DomainExceptionHandlerRegistry 🔨

Este componente central actúa como director de orquesta. Mediante inyección de dependencias de Spring, recibe un Map donde las claves son tipos de excepción y los valores son las estrategias correspondientes:

package com.tuempresa.infraestructura.excepciones;

import com.tuempresa.dominio.excepciones.DomainException;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Component;
import java.util.Map;
import java.util.function.Function;
import java.util.stream.Collectors;

@Component
public class DomainExceptionHandlerRegistry {
    
    private final Map<Class<? extends DomainException>, DomainExceptionHandlerStrategy> strategies;
    
    // Spring inyectará una lista de todos los beans que implementen la interfaz
    // y nosotros la convertimos en un Map para un acceso rápido.
    public DomainExceptionHandlerRegistry(
        java.util.List<DomainExceptionHandlerStrategy> strategyList) {
        
        this.strategies = strategyList.stream()
            .collect(Collectors.toMap(
                DomainExceptionHandlerStrategy::getExceptionType, 
                Function.identity()
            ));
    }
    
    @SuppressWarnings("unchecked")
    public ResponseEntity<ApiError> handle(DomainException ex) {
        // Buscamos la estrategia específica para el tipo de excepción
        DomainExceptionHandlerStrategy<DomainException> strategy = 
            strategies.get(ex.getClass());
        
        if (strategy != null) {
            return strategy.handle(ex);
        }
        
        // Fallback para excepciones de dominio no mapeadas explícitamente
        return ResponseEntity
            .status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(new ApiError("500-000", "UNEXPECTED_DOMAIN_ERROR"));
    }
}

5. La Estructura de Respuesta: ApiError DTO

Un record de Java para estandarizar el formato de nuestras respuestas de error:

package com.tuempresa.infraestructura.excepciones;

// Usamos un record de Java para una clase de datos inmutable y concisa.
public record ApiError(String code, String message) {}

6. La Puerta de Entrada: @RestControllerAdvice

Finalmente, usamos @RestControllerAdvice de Spring para crear un traductor global que intercepta cualquier DomainException no capturada anteriormente:

package com.tuempresa.infraestructura.excepciones;

import com.tuempresa.dominio.excepciones.DomainException;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

@RestControllerAdvice
public class GlobalExceptionTranslator extends ResponseEntityExceptionHandler {
    
    private final DomainExceptionHandlerRegistry registry;
    
    public GlobalExceptionTranslator(DomainExceptionHandlerRegistry registry) {
        this.registry = registry;
    }
    
    @ExceptionHandler(DomainException.class)
    public final ResponseEntity<ApiError> handleDomainException(DomainException ex) {
        // Toda la lógica compleja está en el registry, aquí solo delegamos.
        return registry.handle(ex);
    }
}

Beneficios del Patrón Implementado

Este enfoque proporciona múltiples ventajas significativas:

Separación de Responsabilidades: La capa de dominio permanece completamente aislada de las preocupaciones de infraestructura como códigos HTTP o formatos de respuesta.

Extensibilidad: Añadir nuevas excepciones de dominio requiere únicamente crear la excepción y su manejador correspondiente, sin modificar código existente.

Testabilidad: Cada componente puede ser probado independientemente, facilitando la escritura de pruebas unitarias y de integración.

Mantenibilidad: La lógica de manejo de errores está centralizada pero distribuida de forma lógica, evitando el antipatrón de "God Objects".

Reutilización: El mismo patrón puede adaptarse a diferentes protocolos y tecnologías más allá de HTTP/REST.

Conclusión y Futuras Líneas de Trabajo

Hemos establecido una base sólida y documentada para el manejo de errores de negocio. Las excepciones de dominio trascienden la simple gestión de errores para convertirse en una herramienta de modelado que enriquece nuestro código, haciéndolo más expresivo y alineado con las reglas del negocio.

El patrón presentado, fundamentado en Strategy y un Registro central, ofrece una solución elegante que mantiene la pureza de la capa de dominio mientras proporciona un mecanismo extensible para traducir errores de negocio en respuestas concretas de infraestructura.

En el desarrollo de aplicaciones empresariales modernas, la seguridad es un pilar fundamental. Sin embargo, lograr una arquitectura de seguridad que sea reutilizable, desacoplada y, al mismo tiempo, compatible con los estándares de la industria (como JWT y Spring Security) puede ser un reto. Este artículo explora una solución basada en la arquitectura hexagonal, que permite centralizar la lógica de autorización en el dominio, sin perder la integración con las capacidades avanzadas de Spring Security, como el uso de anotaciones (@PreAuthorize) y la inyección del usuario autenticado en los controladores.

Contexto y Desafío

La mayoría de los frameworks modernos, como Spring Boot, ofrecen mecanismos de seguridad robustos y listos para usar. Sin embargo, estos suelen acoplar la lógica de autenticación y autorización a la infraestructura, dificultando la reutilización y el testeo independiente del dominio. Por otro lado, la arquitectura hexagonal promueve la separación de responsabilidades, permitiendo que la lógica de negocio (incluida la autorización) permanezca independiente de los detalles tecnológicos.

El desafío surge cuando se requiere que la lógica de autorización, implementada en el dominio, pueda interactuar con el ecosistema de Spring Security, permitiendo el uso de anotaciones como @PreAuthorize y la inyección del usuario autenticado en los controladores. La solución propuesta en este artículo aborda este reto, permitiendo una integración fluida y flexible.

Dependencias Requeridas

Para implementar esta solución, se requieren las siguientes dependencias en el archivo build.gradle:

dependencies {
    // Spring Boot Core
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'org.springframework.boot:spring-boot-configuration-processor'
    
    // Lombok para reducir boilerplate
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
    
    // JWT (opcional, para parsing de tokens)
    implementation 'io.jsonwebtoken:jjwt-api:0.11.5'
    runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.11.5'
    runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.11.5'
    
    // Testing
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'org.springframework.security:spring-security-test'
}

Estructura de Directorios

La librería sigue una estructura de directorios que respeta los principios de la arquitectura hexagonal:

src/
├── main/
│   ├── java/
│   │   └── com/
│   │       └── tuempresa/
│   │           ├── dominio/
│   │           │   └── autorizacion/
│   │           │       ├── AuthorizationContext.java
│   │           │       ├── AuthorizationException.java
│   │           │       ├── AuthorizationService.java
│   │           │       └── AuthorizationServiceImpl.java
│   │           └── infraestructura/
│   │               ├── config/
│   │               │   ├── AuthorizationConfig.java
│   │               │   └── AuthorizationFilterConfig.java
│   │               └── filtros/
│   │                   └── StandardAuthorizationFilter.java
│   └── resources/
│       └── META-INF/
│           └── spring.factories (para auto-configuración)
└── test/
    └── java/
        └── com/
            └── tuempresa/
                ├── dominio/
                │   └── autorizacion/
                │       └── AuthorizationServiceTest.java
                └── infraestructura/
                    └── filtros/
                        └── StandardAuthorizationFilterTest.java

Solución: Librería de Seguridad Hexagonal Integrada

La solución se basa en una serie de clases y componentes que pueden ser empaquetados como una librería reutilizable. Esta librería permite:

• Centralizar la lógica de autorización en el dominio, desacoplada de la infraestructura.
• Configurar rutas excluidas, parámetros y comportamiento desde archivos de configuración.
• Integrar con Spring Security para habilitar anotaciones y acceso al usuario autenticado.
• Validar JWT y extraer roles/claims para el contexto de seguridad.

A continuación, se presentan las clases clave de la solución.

1. Contexto de Autorización (Dominio)

package com.tuempresa.dominio.autorizacion;

import lombok.Builder;
import lombok.Value;
import java.util.Map;

@Value
@Builder
public class AuthorizationContext {
    String method;
    String uri;
    Map<String, String> headers;
    Map<String, String> queryParams;
    String body;
    String remoteAddress;
}

2. Excepción de Dominio

package com.tuempresa.dominio.autorizacion;

public class AuthorizationException extends RuntimeException {
    public AuthorizationException(String message) {
        super(message);
    }
}

3. Puerto de Dominio (Interface)

package com.tuempresa.dominio.autorizacion;

public interface AuthorizationService {
    void authorize(AuthorizationContext context) throws AuthorizationException;
}

4. Implementación Base del Servicio de Dominio

package com.tuempresa.dominio.autorizacion;

public class AuthorizationServiceImpl implements AuthorizationService {
    @Override
    public void authorize(AuthorizationContext context) {
        String token = context.getHeaders().get("authorization");
        if (token == null || !token.startsWith("Bearer ")) {
            throw new AuthorizationException("Token inválido o ausente");
        }
        // Más lógica de dominio...
    }
}

5. Configuración del Filtro

package com.tuempresa.infraestructura.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import java.util.Set;
import java.util.HashSet;

@Data
@Component
@ConfigurationProperties(prefix = "app.security.authorization")
public class AuthorizationFilterConfig {
    
    private Set<String> excludedPaths = new HashSet<>();
    private boolean enabled = true;
    private int order = 1;
    private boolean includeQueryParams = true;
    private boolean includeBody = false;
    private boolean enableSpringSecurityIntegration = true;
    
    public AuthorizationFilterConfig() {
        excludedPaths.add("/actuator/health");
        excludedPaths.add("/actuator/info");
        excludedPaths.add("/swagger-ui");
        excludedPaths.add("/v3/api-docs");
        excludedPaths.add("/error");
    }
}

6. Filtro Principal Consolidado

package com.tuempresa.infraestructura.filtros;

import com.tuempresa.dominio.autorizacion.AuthorizationContext;
import com.tuempresa.dominio.autorizacion.AuthorizationService;
import com.tuempresa.dominio.autorizacion.AuthorizationException;
import com.tuempresa.infraestructura.config.AuthorizationFilterConfig;

import lombok.RequiredArgsConstructor;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.core.annotation.Order;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import org.springframework.web.util.ContentCachingRequestWrapper;

import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.*;

@Component
@Order(1)
@ConditionalOnProperty(name = "app.security.authorization.enabled", havingValue = "true", matchIfMissing = true)
@RequiredArgsConstructor
public class StandardAuthorizationFilter extends OncePerRequestFilter {

    private final AuthorizationFilterConfig config;
    private final AuthorizationService authorizationService;

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain) throws ServletException, IOException {

        if (isExcludedPath(request.getRequestURI())) {
            filterChain.doFilter(request, response);
            return;
        }

        try {
            HttpServletRequest requestToUse = request;
            if (config.isIncludeBody()) {
                requestToUse = new ContentCachingRequestWrapper(request);
            }

            Map<String, String> headers = extractHeaders(requestToUse);
            Map<String, String> queryParams = config.isIncludeQueryParams() ? extractQueryParams(requestToUse) : Collections.emptyMap();
            String requestBody = (config.isIncludeBody() && requestToUse instanceof ContentCachingRequestWrapper)
                    ? extractRequestBody((ContentCachingRequestWrapper) requestToUse)
                    : null;

            AuthorizationContext context = AuthorizationContext.builder()
                    .method(requestToUse.getMethod())
                    .uri(requestToUse.getRequestURI())
                    .headers(headers)
                    .queryParams(queryParams)
                    .body(requestBody)
                    .remoteAddress(requestToUse.getRemoteAddr())
                    .build();

            authorizationService.authorize(context);

            // Integración con Spring Security (si está habilitada)
            if (config.isEnableSpringSecurityIntegration()) {
                setSpringSecurityContext(context);
            }

            filterChain.doFilter(requestToUse, response);

        } catch (AuthorizationException e) {
            handleSecurityException(response, e);
        } catch (Exception e) {
            logger.error("Error in authorization filter", e);
            handleGenericError(response);
        }
    }

    private Map<String, String> extractHeaders(HttpServletRequest request) {
        Map<String, String> headers = new HashMap<>();
        Enumeration<String> headerNames = request.getHeaderNames();
        while (headerNames.hasMoreElements()) {
            String headerName = headerNames.nextElement();
            String headerValue = request.getHeader(headerName);
            headers.put(headerName.toLowerCase(), headerValue);
        }
        return headers;
    }

    private Map<String, String> extractQueryParams(HttpServletRequest request) {
        Map<String, String> queryParams = new HashMap<>();
        Enumeration<String> paramNames = request.getParameterNames();
        while (paramNames.hasMoreElements()) {
            String paramName = paramNames.nextElement();
            String paramValue = request.getParameter(paramName);
            queryParams.put(paramName, paramValue);
        }
        return queryParams;
    }

    private String extractRequestBody(ContentCachingRequestWrapper request) throws IOException {
        byte[] content = request.getContentAsByteArray();
        if (content.length > 0) {
            return new String(content, StandardCharsets.UTF_8);
        }
        return null;
    }

    private void setSpringSecurityContext(AuthorizationContext context) {
        try {
            String authHeader = context.getHeaders().get("authorization");
            if (authHeader != null && authHeader.startsWith("Bearer ")) {
                String username = extractUsernameFromToken(authHeader);
                List<String> roles = extractRolesFromToken(authHeader);
                List<SimpleGrantedAuthority> authorities = roles.stream()
                        .map(role -> new SimpleGrantedAuthority("ROLE_" + role.toUpperCase()))
                        .toList();

                UsernamePasswordAuthenticationToken authentication =
                        new UsernamePasswordAuthenticationToken(username, null, authorities);

                SecurityContextHolder.getContext().setAuthentication(authentication);
            }
        } catch (Exception e) {
            logger.warn("Could not set Spring Security context", e);
        }
    }

    private String extractUsernameFromToken(String authHeader) {
        // Implementar parsing del JWT aquí
        return "user_from_jwt"; // Placeholder
    }

    private List<String> extractRolesFromToken(String authHeader) {
        // Implementar parsing del JWT aquí
        return List.of("USER"); // Placeholder
    }

    private boolean isExcludedPath(String requestURI) {
        return config.getExcludedPaths().stream()
                .anyMatch(excluded -> requestURI.startsWith(excluded));
    }

    private void handleSecurityException(HttpServletResponse response, AuthorizationException e) throws IOException {
        response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
        response.setContentType("application/json");
        response.getWriter().write(String.format(
                "{\"error\":\"Unauthorized\",\"message\":\"%s\",\"timestamp\":\"%s\"}",
                e.getMessage(), new Date()
        ));
    }

    private void handleGenericError(HttpServletResponse response) throws IOException {
        response.setStatus(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
        response.setContentType("application/json");
        response.getWriter().write(String.format(
                "{\"error\":\"Internal Server Error\",\"message\":\"Authorization check failed\",\"timestamp\":\"%s\"}",
                new Date()
        ));
    }
}

7. Configuración de Beans

package com.tuempresa.infraestructura.config;

import com.tuempresa.dominio.autorizacion.AuthorizationService;
import com.tuempresa.dominio.autorizacion.AuthorizationServiceImpl;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class AuthorizationConfig {
    @Bean
    public AuthorizationService authorizationService() {
        return new AuthorizationServiceImpl();
    }
}

8. Configuración en application.yml

app:
  security:
    authorization:
      enabled: true
      order: 1
      include-query-params: true
      include-body: false
      enable-spring-security-integration: true
      excluded-paths:
        - "/actuator/health"
        - "/actuator/info"
        - "/swagger-ui"
        - "/v3/api-docs"
        - "/public"
        - "/auth/login"

9. Ejemplo de Uso en el Proyecto Cliente

@Service
public class MyCustomAuthorizationService implements AuthorizationService {

    @Override
    public void authorize(AuthorizationContext context) throws AuthorizationException {
        String token = context.getHeaders().get("authorization");
        if (!isValidJWT(token)) {
            throw new AuthorizationException("JWT inválido");
        }
        if (context.getUri().startsWith("/admin") && !hasAdminRole(token)) {
            throw new AuthorizationException("Acceso denegado a área administrativa");
        }
    }

    private boolean isValidJWT(String token) {
        // Implementar validación JWT
        return true;
    }

    private boolean hasAdminRole(String token) {
        // Verificar roles en el JWT
        return false;
    }
}

10. Uso en Controllers

@RestController
public class MyController {

    @GetMapping("/protected")
    @PreAuthorize("hasRole('USER')")
    public String protectedEndpoint(@AuthenticationPrincipal String username) {
        return "Hello " + username + "! You are authenticated.";
    }

    @GetMapping("/admin")
    @PreAuthorize("hasRole('ADMIN')")
    public String adminEndpoint() {
        return "Admin area";
    }
}

Consideraciones Finales

• Separación de responsabilidades: El dominio se mantiene puro y desacoplado de la infraestructura.
• Integración total: Se habilita el uso de anotaciones y la inyección del usuario autenticado gracias a la integración con el contexto de Spring Security.
• Configurabilidad: La solución es fácilmente adaptable a distintos proyectos mediante configuración externa.
• Reutilización: El diseño modular permite empaquetar la solución como una librería para múltiples aplicaciones.

Conclusión

La estandarización de la seguridad bajo una arquitectura hexagonal, combinada con la integración de Spring Security y JWT, permite construir aplicaciones robustas, mantenibles y alineadas con las mejores prácticas de la industria. Esta aproximación no solo facilita la reutilización y el testeo, sino que también habilita la evolución futura del sistema, permitiendo incorporar nuevas estrategias de autenticación o autorización sin comprometer la arquitectura.

En el diseño de bases de datos, la normalización ha sido durante mucho tiempo sinónimo de integridad, eficiencia y orden. Sin embargo, los tiempos cambian, y con ellos, las necesidades de los sistemas modernos. Los datos semi-estructurados ganan terreno, y PostgreSQL ha sabido adaptarse integrando soporte robusto para los tipos JSON y JSONB. Esta evolución plantea una pregunta crucial: ¿seguir apostando por la rigidez de las tablas normalizadas o abrazar la elasticidad del modelo documental?

El Dilema: Estructura vs. Flexibilidad

La decisión entre un modelo relacional rígido y uno dinámico basado en documentos tiene implicaciones profundas en rendimiento, mantenibilidad y escalabilidad. Entender sus ventajas y límites es clave para construir sistemas sólidos y adaptables.

Tablas Normalizadas: Precisión con Disciplina

La normalización organiza datos para evitar duplicidades y asegurar integridad, a través de estructuras bien definidas y relaciones explícitas.

Ventajas:

• Integridad de Datos: Claves foráneas, restricciones UNIQUE y validaciones CHECK aseguran coherencia.
• Eficiencia en Escrituras: Modificaciones atómicas reducen el riesgo de anomalías.
• Ahorro de Espacio: La minimización de redundancia optimiza el almacenamiento.
• Consultas Optimizadas: Los JOIN son eficientemente resueltos por el planificador de PostgreSQL.

Desventajas:

• Cambios Costosos: Alterar la estructura requiere migraciones.
• Complejidad en Consultas: Obtener una visión completa puede implicar múltiples JOIN.
• Lecturas Pesadas: Agregaciones sobre muchas tablas pueden degradar el rendimiento.

Cuándo Usarlas: Cuando los datos tienen una estructura estable y la integridad es prioritaria. Casos típicos incluyen sistemas contables, gestión de inventarios y aplicaciones bancarias.

JSON/JSONB: Flexibilidad sin Esquema

PostgreSQL permite almacenar JSON de dos maneras:

• json: Mantiene el texto original. Más rápido al insertar, pero más lento en consultas.
• jsonb: Almacena en formato binario. Un poco más lento al insertar, pero mucho más eficiente al consultar y permite indexación avanzada. En la mayoría de los casos, es la opción recomendada.

Ventajas:

• Esquema Dinámico: Atributos variables sin necesidad de alterar el modelo.
• Consultas Directas: Datos relacionados pueden vivir en un único documento.
• Prototipado Rápido: Ideal para iterar sin fricciones durante el desarrollo.

Desventajas:

• Sin Integridad Referencial: Las relaciones deben ser gestionadas manualmente.
• Redundancia y Consistencia: Datos duplicados son comunes, lo que implica riesgos si no se sincronizan.
• Actualizaciones Complejas: Modificar datos anidados no es tan directo como un UPDATE.

Cuando destaca: Para casos con estructuras cambiantes, como configuraciones, eventos, integración de APIs externas o metadata variable

JSONB: Consultas, Índices y Más

Consultas y Proyecciones

PostgreSQL ofrece operadores intuitivos para navegar por estructuras JSONB:

• ->: Accede a un campo, devuelve jsonb.
• ->>: Accede y devuelve texto.
• #>: Navega rutas anidadas, devuelve jsonb.
• #>>: Igual que #>, pero como texto.

Ejemplo de Uso:

CREATE TABLE productos (
    id SERIAL PRIMARY KEY,
    nombre TEXT NOT NULL,
    detalles JSONB
);

INSERT INTO productos (nombre, detalles) VALUES
('Laptop Pro', '{"precio": 1500, "fabricante": "TechCorp", "especs": {"cpu": "i7", "ram": 16, "almacenamiento": 512}}'),
('Smartphone X', '{"precio": 800, "fabricante": "MobileFirst", "especs": {"cpu": "Snapdragon 8", "ram": 8, "almacenamiento": 256}}');

Proyecciones:

SELECT nombre, detalles->>'precio' AS precio FROM productos;

SELECT nombre, detalles#>'{especs, ram}' AS ram FROM productos;

Filtrado y Búsquedas

Operadores potentes permiten extraer información fácilmente:

• @>: Contiene.
• <@: Está contenido.
• ?: Existe clave.
• ?|: Existe alguna.
• ?&: Existen todas.

Ejemplos:

SELECT * FROM productos WHERE detalles @> '{"fabricante": "TechCorp"}';

SELECT * FROM productos WHERE detalles @> '{"especs": {"ram": 16}}';

SELECT * FROM productos WHERE detalles ? 'precio';

Indexación

Las consultas sobre JSONB pueden volverse lentas sin índices adecuados. PostgreSQL ofrece:

• GIN (Generalized Inverted Index): El más recomendado. Optimiza búsquedas con @>, ?, ?|, ?&.
• GiST: Más versátil, pero menos eficiente en general.

Ejemplo:

CREATE INDEX idx_productos_detalles_gin ON productos USING GIN (detalles);

También es posible crear índices B-tree sobre campos específicos:

CREATE INDEX idx_productos_fabricante ON productos ((detalles->>'fabricante'));

Actualizaciones Parciales

Con jsonb_set, es posible modificar datos sin reescribir todo el documento:

UPDATE productos
SET detalles = jsonb_set(detalles, '{precio}', '1450')
WHERE nombre = 'Laptop Pro';

UPDATE productos
SET detalles = jsonb_set(detalles, '{especs, ram}', '32')
WHERE nombre = 'Laptop Pro';

Modelo Híbrido: Lo Mejor de Dos Mundos

Combinar estructuras relacionales con campos JSONB permite construir sistemas flexibles, sin sacrificar integridad.

Ventajas del enfoque mixto:

• Datos críticos viven en columnas estructuradas.
• Atributos variables residen en campos JSONB.
• Menos JOINs, más velocidad.
• Menos migraciones con cada cambio de requisitos.

Casos Prácticos

1. E-commerce: Productos con atributos diversos

CREATE TABLE productos (
    id SERIAL PRIMARY KEY,
    nombre TEXT NOT NULL,
    precio DECIMAL(10, 2),
    categoria_id INT REFERENCES categorias(id),
    especificaciones JSONB
);

CREATE INDEX idx_especificaciones_gin ON productos USING GIN (especificaciones);

SELECT * FROM productos 
WHERE categoria_id = 1 
AND especificaciones @> '{"ram": "16GB", "almacenamiento": "SSD"}';

2. SaaS: Preferencias de usuario

ALTER TABLE usuarios ADD COLUMN preferencias JSONB DEFAULT '{}';

UPDATE usuarios 
SET preferencias = jsonb_set(preferencias, '{tema}', '"claro"')
WHERE id = 123;

3. Logs y eventos con estructuras variables

CREATE INDEX idx_eventos_detalles_ip ON eventos ((detalles->>'ip'));

SELECT * FROM eventos 
WHERE tipo = 'login' 
AND detalles->>'ip' = '192.168.1.1';

Claves del Modelo Híbrido

1. Desarrollo Ágil: Sin necesidad de migrar con cada cambio menor.
2. Rendimiento: Índices GIN aceleran búsquedas complejas.
3. Mantenibilidad: Las estructuras centrales permanecen estables.
4. Integración Sencilla: Ideal para microservicios y respuestas JSON de APIs externas.

Conclusión: El Futuro es Híbrido

No se trata de elegir entre rigidez o flexibilidad, sino de combinarlas inteligentemente. PostgreSQL permite construir arquitecturas donde:

• Los datos estables viven en tablas relacionales.
• Los atributos cambiantes se encapsulan en JSONB.
• El SQL moderno los une con potencia y elegancia.

La evolución de jsonb —junto con el soporte creciente para SQL/JSON path— abre nuevas puertas. El enfoque híbrido no es una moda, es una estrategia para diseñar sistemas duraderos, escalables y listos para adaptarse a lo que viene.

🔗 Recursos Recomendados

• Documentación oficial de PostgreSQL sobre JSONB
• Índices GIN vs. GiST
• Funciones SQL/JSON

En el dinámico mundo del desarrollo de software, la complejidad es el enemigo silencioso. Las aplicaciones crecen, los requisitos cambian y, sin una guía clara, el código puede convertirse rápidamente en un laberinto frágil y costoso de mantener. ¿La solución? No es un framework de moda, sino una filosofía de diseño sólida. Esta guía ofrece un mapa detallado para construir software robusto, escalable y, sobre todo, alineado con el negocio, fusionando los principios del Diseño Guiado por el Dominio (DDD), la Arquitectura Limpia (Clean Architecture) y la Arquitectura Hexagonal (Puertos y Adaptadores).

Olvídate de las capas anémicas y el acoplamiento tecnológico. Aquí aprenderás a colocar el corazón de tu negocio —el dominio— en el centro del universo, protegido y aislado de los detalles mundanos de la tecnología. Prepárate para diseñar sistemas donde la lógica de negocio es la reina, la infraestructura es un sirviente intercambiable y el cambio es una oportunidad, no una amenaza.

🎯 Capa de Dominio: El Corazón del Negocio

Esta es la capa más sagrada y protegida de la arquitectura. Su único propósito es encapsular la lógica y las reglas de negocio puras, utilizando el Lenguaje Ubicuo (Ubiquitous Language) del problema que se está resolviendo. Es completamente agnóstica a la tecnología; no debe existir ninguna referencia a frameworks, bases de datos o APIs. En Arquitectura Hexagonal, esta capa es el "hexágono" central, y en Arquitectura Limpia, corresponde a los círculos internos de Entidades y Casos de Uso.

Aquí residen los componentes que modelan el negocio: Agregados, Entidades, Objetos de Valor, Eventos de Dominio, Servicios de Dominio, las interfaces de los Repositorios (que actúan como Puertos) y los Casos de Uso que orquestan toda la lógica.

🔌 Capa de Infraestructura: El Mundo de la Tecnología

Esta capa contiene todos los detalles técnicos y las implementaciones concretas. Su finalidad es servir como un conjunto de adaptadores que traducen las interacciones del mundo exterior al lenguaje del dominio, y viceversa. Implementa los puertos definidos en la Capa de Dominio, cumpliendo con la sagrada Regla de la Dependencia: la infraestructura siempre depende del dominio. Aquí residen los frameworks web, las conexiones a bases de datos, los clientes de servicios externos y cualquier otra dependencia del mundo real.

Los componentes clave son los Entry-Points (adaptadores que invocan los casos de uso, como controladores de API REST) y los Driven-Adapters (implementaciones de los puertos del dominio, como un repositorio JPA), junto con sus artefactos de apoyo como DTOs, Modelos de Persistencia y Mappers.

🚀 Capa de Aplicación: El Ensamblador

Esta es la capa más externa y conceptualmente simple. Su única finalidad es ensamblar la aplicación y ponerla en marcha. No contiene lógica de negocio. Es responsable de inicializar el sistema, configurar el contenedor de Inyección de Dependencias (IoC) para conectar las implementaciones de la infraestructura (Driven-Adapters) con las abstracciones del dominio (Puertos), y leer configuraciones externas.

📂 Estructura de Módulos Sugerida

Una representación visual de una estructura de módulos (por ejemplo, en Gradle o Maven) que materializa esta arquitectura de forma limpia.

mi-proyecto-escalable/
├── build.gradle.kts
├── settings.gradle.kts      # Define los módulos del proyecto
│
├── applications/
│   └── app-service/         # Capa de Aplicación: Ensambla y corre la app
│       └── src/main/java/com/miempresa/app/MainApplication.java
│       └── build.gradle.kts # Depende de 'domain' e 'infrastructure'
│
├── domain/                  # Capa de Dominio: Lógica de negocio pura
│   ├── model/               # El modelo: agregados, entidades, VOs, eventos...
│   │   └── src/main/java/com/miempresa/domain/model/producto/Producto.java
│   │   └── src/main/java/com/miempresa/domain/model/producto/gateways/ProductoRepository.java # Puerto (Interfaz)
│   │   └── build.gradle.kts # No tiene dependencias de otras capas
│   └── usecase/             # Los casos de uso que orquestan el modelo
│       └── src/main/java/com/miempresa/domain/usecase/producto/ListarProductosUseCase.java
│       └── build.gradle.kts # Depende de 'domain/model'
│
└── infrastructure/          # Capa de Infraestructura: Detalles tecnológicos
    ├── entry-points/        # Adaptadores de entrada (ej. API REST)
    │   └── rest-api/
    │       └── src/main/java/com/miempresa/infrastructure/entrypoints/producto/ProductoController.java
    │       └── build.gradle.kts # Depende de 'domain/usecase'
    │
    └── driven-adapters/     # Adaptadores de salida (ej. Repositorio JPA)
        └── jpa-repository/
        │   └── src/main/java/com/miempresa/infrastructure/drivenadapters/producto/ProductoData.java # Entidad JPA
        │   └── src/main/java/com/miempresa/infrastructure/drivenadapters/producto/ProductoRepositoryAdapter.java # Adaptador
        │   └── build.gradle.kts # Depende de 'domain/model'

🗺️ Diagrama de Flujo y Dependencias

Este diagrama ilustra la Regla de la Dependencia (flechas sólidas de dependencia ->) y el Flujo de Control (flechas punteadas de ejecución ...> ). Observa cómo las dependencias siempre apuntan hacia el interior, hacia el dominio, mientras que el flujo de control atraviesa las capas.

+-------------------------------------------------------------------------------------------------+
| Capa de Aplicación (Ensamblador, main)                                                          |
+-------------------------------------------------------------------------------------------------+
       |
       | Inicia y configura
       V
+-------------------------------------------------------------------------------------------------+
| Capa de Infraestructura (Adaptadores: REST, DB, etc.)   <-- Las flechas de DEPENDENCIA apuntan aquí |
|                                                                                                 |
|  +---------------+      FLUJO DE CONTROL ...>      +--------------------+                       |
|  |  Entry-Point  |                                 |   Driven-Adapter   |                       |
|  | (Controller)  | ... ... ... ... ... ... ... ... | (JPA Repository)   |                       |
|  +---------------+   .                             +--------------------+                       |
|      |       ^       .                                  ^          |                           |
| (Llama) | (Retorna DTO) .                             (Implementa) | (Habla con DB)            |
|      |       . . . . .                                    |          V                           |
|      V                                                    |      +---------------+             |
|  <DEPENDENCIA>                                        <DEPENDENCIA> | Mundo Externo |             |
+------+------------------------------------------------------+----------+---------------+-------------+
       |                                                      |
       V                                                      V
+-------------------------------------------------------------------------------------------------+
| Capa de Dominio (Lógica de Negocio Pura)            <-- TODAS las DEPENDENCIAS apuntan aquí     |
|                                                                                                 |
|  +---------------+      FLUJO DE CONTROL ...>      +--------------------+                       |
|  |  Caso de Uso  |                                 | Repositorio (Port) |                       |
|  | (Orquestador) | ... ... ... ... ... ... ... ... |     (Interfaz)     |                       |
|  +---------------+   .                             +--------------------+                       |
|      ^       |       .                                                                         |
|      |       V       .                                                                         |
|      |   +----------+                                                                          |
|      +-> | Agregado | <... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...|
|          +----------+                                                                          |
+-------------------------------------------------------------------------------------------------+

💡 Ejemplo Avanzado: POST /orders (Crear un Pedido)

Veamos cómo fluyen las interacciones en un proceso de negocio real y complejo, como la creación de un nuevo pedido.

1. La Petición del Cliente (Capa de Infraestructura)

• Componente: OrderController (Entry-Point).
• Acción: Recibe una petición POST en /orders. Su rol es validar el formato de la petición (usando un PlaceOrderRequestDTO) y delegar inmediatamente al caso de uso correspondiente. No sabe cómo se procesa un pedido, solo a quién llamar.
• Artefacto: PlaceOrderRequestDTO (DTO). Modela el JSON de entrada (customerId, items, etc.). Usa validaciones de framework (@NotNull, @Size) para un rechazo temprano.

2. La Orquestación Central (Capa de Dominio)

• Componente: PlaceOrderUseCase (Caso de Uso).
• Acción: Este es el director de orquesta. No contiene lógica de negocio en sí mismo, pero coordina los pasos en el orden correcto. Su constructor recibe, mediante inyección de dependencias, varios puertos (interfaces): CustomerRepository, ProductRepository, OrderPricingService, PaymentGateway, y OrderRepository.

3. Recolección y Validación de Negocio (Dominio interactuando con Infraestructura)

• Paso 3.1: Validar Cliente: El caso de uso invoca customerRepository.findById(customerId). El CustomerRepositoryAdapter (en infraestructura) lo buscará en la base de datos. Si no existe, el dominio lanza una excepción de negocio (CustomerNotFoundException).
• Paso 3.2: Validar Productos y Stock: Para cada ítem, invoca productRepository.findById(productId). El Agregado Product recuperado es responsable de validar sus propias reglas, como product.hasSufficientStock(quantity).

4. Ejecución de Lógica de Negocio Compleja (Dominio)

• Componente: OrderPricingService (Servicio de Dominio).
• Acción: El caso de uso le pasa el cliente y los productos. Este servicio, cuya lógica no encaja en un único agregado, calcula el precio total, aplicando descuentos por lealtad o promociones. Devuelve un Objeto de Valor Money.

5. Creación del Nuevo Agregado (Dominio)

• Componente: Order (Agregado Raíz).
• Acción: Con todos los datos validados y el precio calculado, el caso de uso invoca un método de fábrica estático: Order.create(customer, items, totalPrice). El agregado Order se crea en un estado inicial válido y registra un evento, OrderPlacedEvent.

6. Interacción con Servicios Externos (Infraestructura)

• Componente: PaymentGateway (Puerto en el dominio) y StripePaymentAdapter (Driven-Adapter en infraestructura).
• Acción: El caso de uso llama a paymentGateway.processPayment(...). El dominio solo conoce la interfaz. La infraestructura proporciona la implementación concreta (StripePaymentAdapter) que se comunica con la API de Stripe. Si el pago falla, se lanza una excepción que aborta el caso de uso.

7. Persistencia y Efectos Secundarios (Dominio y Infraestructura)

• Paso 7.1: Guardar el Pedido: Si el pago es exitoso, el caso de uso llama a orderRepository.save(order). El OrderRepositoryAdapter, usando un OrderDataMapper para convertir el agregado a un OrderData (entidad JPA), persiste el pedido en la base de datos de forma transaccional.
• Paso 7.2: Publicar Evento de Dominio: Tras guardar exitosamente, el caso de uso (o un decorador del repositorio) invoca a un DomainEventPublisher. Esto despacha el OrderPlacedEvent registrado previamente. Otros módulos del sistema, como Notifications o Inventory, pueden escuchar este evento y reaccionar de forma totalmente desacoplada (enviar un email, actualizar el stock).

8. La Respuesta Final (Infraestructura)

• Componente: OrderController (de nuevo).
• Acción: Recibe el resultado exitoso del caso de uso (el agregado Order recién creado), lo mapea a un PlaceOrderResponseDTO y devuelve una respuesta 201 Created con el ID del nuevo pedido.

🏁 Conclusión: Más Allá del Código

Adoptar una arquitectura basada en DDD y Hexagonal no es simplemente organizar carpetas; es un cambio de mentalidad. Nos obliga a dialogar con los expertos del negocio, a modelar la complejidad del mundo real y a proteger esa lógica invaluable de los detalles efímeros de la tecnología.

Los beneficios clave son innegables:

1. Testabilidad Superior: La lógica de negocio pura en el dominio puede ser probada unitariamente sin necesidad de frameworks, bases de datos o servidores web.
2. Mantenibilidad y Evolución: Cambiar de una base de datos PostgreSQL a MongoDB, o de una API REST a gRPC, se convierte en la tarea de escribir un nuevo adaptador, sin tocar el núcleo del negocio.
3. Enfoque en el Negocio: El equipo se centra en resolver problemas de negocio reales, ya que el código refleja directamente el lenguaje y los procesos de la empresa.
4. Escalabilidad Organizacional: Diferentes equipos pueden trabajar en distintos adaptadores o módulos del dominio de forma paralela con un bajo riesgo de conflictos.

Esta arquitectura sienta las bases para patrones aún más avanzados como CQRS (Command Query Responsibility Segregation) y Event Sourcing, permitiendo que tus sistemas no solo respondan a las necesidades actuales, sino que estén preparados para prosperar ante los desafíos del futuro.

En el desarrollo de aplicaciones Java, el manejo de respuestas a solicitudes —especialmente aquellas que involucran operaciones asincrónicas, procesamiento de datos o comunicación con servicios externos— requiere estructuras robustas, claras y reutilizables. Aunque Optional<T> de Java es útil para representar valores potencialmente ausentes, su semántica está limitada a la presencia o ausencia de un valor, sin ofrecer un contexto de estado (como éxito, error, pendiente) ni información adicional como mensajes de error.

Este artículo tiene como objetivo presentar una implementación técnica detallada de una clase ResponseWrapper<T> en Java. Esta clase encapsula un valor de respuesta, un estado (Status) y una lista de errores, replicando y extendiendo las capacidades de Optional<T>. A través de esta herramienta, se busca proveer una estructura genérica que mejore la expresividad, manejabilidad y trazabilidad de las respuestas dentro de aplicaciones Java, especialmente en contextos de desarrollo backend, servicios REST, o flujos de validación de datos.

El contenido está orientado a desarrolladores de software, arquitectos de aplicaciones y diseñadores de APIs que deseen integrar una solución flexible y extensible para el manejo de respuestas estructuradas.

Implementación Técnica de ResponseWrapper

Motivación y Limitaciones de Optional<T>

El uso de Optional<T> es común para evitar null y sus efectos colaterales. Sin embargo, presenta limitaciones:

• No permite almacenar información contextual sobre por qué el valor está ausente.
• No diferencia entre un valor ausente por error y uno ausente por diseño (por ejemplo, un valor aún no calculado).
• No soporta transporte de metadatos como mensajes de error, códigos de estado, o indicadores de transición.