El tramo en cascada que todo proyecto ágil necesita (y casi ninguno tiene)

Mauricio ECR
Gestion
02 Aug, 2026

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

Ver página completa

Observabilidad sin Ruido: Diseñando un Sistema de Logs con AOP en Arquitecturas DDD — Parte III

Mauricio ECR
Arquitectura
07 Jun, 2026

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 l

Ver página completa

Observabilidad sin Ruido: Diseñando un Sistema de Logs con AOP en Arquitecturas DDD — Parte III

Mauricio ECR
Arquitectura
07 Jun, 2026

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 markdown - Código fuente completo


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

Ver página completa →

Cuando el sistema nuevo tiene que hablarle al sistema viejo en su idioma

Mauricio ECR
Arquitectura
31 May, 2026

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 clara

Ver página completa

Cuando el sistema nuevo tiene que hablarle al sistema viejo en su idioma

Mauricio ECR
Arquitectura
31 May, 2026

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:

Característica	Enfoque A: COPY TO STDOUT	Enfoque B: Procesos en paralelo
Volumen de datos	Acotado y predecible	Grande o impredecible
Tamaño del CSV por ciclo	Menor a 5MB	Mayor a 5MB
Procesamiento por registro	Vive en SQL	Requiere lógica fuera de la DB
Número de procesos	Un solo proceso	Múltiples procesos en paralelo
Trazabilidad por registro	No requerida	Requerida
Errores parciales	No se toleran	Se toleran y gestionan
Reintentos individuales	Reintentos individuales	No necesarios
Tipos de archivo	Pocos y fijos	Dinámicos según los datos
Escalabilidad futura	No se contempla	Se contempla o es necesaria

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.

Elemento	Detalle
Tabla de exportación	Estructura idéntica al CSV destino, con campo de estado
Campo de estado	`PENDING`, `COMPLETED`
Alimentación	Sistema origen o disparador en PostgreSQL
Lambda en S3	Solo para la variante de tipos dependientes

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.

Elemento	Detalle
Campo de estado en tabla de jobs	`PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `DEAD`
Campo `locked_at` en tabla de jobs	Timestamp para detectar registros huérfanos
Tabla temporal de líneas CSV	Línea formateada, peso en bytes, tipo y estado de subida
Tabla de auditoría	Referencia al registro, número de intento, error y timestamp
Tabla de sesión	Ventana de procesamiento (`min_id`, `max_id`) y estado (`OPEN`, `DONE`)
Tabla de partes por tipo	Tipo, `uploadId` de S3 y estado (`OPEN`, `DONE`)
Tabla de exportación	Opcional, recomendada como buena práctica para simplificar el procesamiento por lote

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.

Ver página completa →

Cuando un sistema debe ejecutar lo mismo siempre y algo distinto cada vez

Mauricio ECR
Arquitectura
24 May, 2026

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 disti

Ver página completa

Cuando un sistema debe ejecutar lo mismo siempre y algo distinto cada vez

Mauricio ECR
Arquitectura
24 May, 2026

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:

Comando	Propósito	Quién resuelve la lógica
Consulta de pasos	Obtiene el total de pasos y el nombre de cada uno	Núcleo, usando el dato declarado en el registro del módulo
Consulta de progreso	Retorna el total de pasos, el paso actual y el último paso completado	Núcleo. Cuando el control está delegado, consulta al módulo por el paso actual
Siguiente	Avanza al siguiente paso lógico	Núcleo si el paso es transversal, módulo si el paso es del módulo
Atrás	Retrocede al paso anterior	Núcleo si el paso es transversal, módulo si el paso es del módulo
Salto	Navega a un paso específico, siempre que no supere el último paso alcanzado	Núcleo si el destino es transversal, módulo si el destino es del módulo
Cancelar	Termina el flujo completamente	Núcleo

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.

Ver página completa →

Observabilidad sin Ruido: Diseñando un Sistema de Logs con AOP en Arquitecturas DDD — Parte II

Mauricio ECR
Arquitectura
18 May, 2026

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

Ver página completa

Observabilidad sin Ruido: Diseñando un Sistema de Logs con AOP en Arquitecturas DDD — Parte II

Mauricio ECR
Arquitectura
18 May, 2026

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.

Ver página completa →

Cuando todo falla, ¿Quién decide?

Mauricio ECR
Gestion
05 May, 2026

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

Ver página completa

El fin de la 'Jaula de Oro': recuperar el control de tu infraestructura

Mauricio ECR
DevOps
22 Mar, 2026

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

Ver página completa

El fin de la 'Jaula de Oro': recuperar el control de tu infraestructura

Mauricio ECR
DevOps
22 Mar, 2026

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:

Herramienta	Reemplaza a	Uso	RAM Mínima (1-5 usuarios)	RAM Equipo (20+)	Desafío Honesto
Supabase	Firebase	Backend Pro	4 GB RAM	8 GB+	Arquitectura compleja (Docker).
PocketBase	Firebase	MVP / Personal	512 MB RAM	2 GB	SQLite (límite de concurrencia).
Coolify	Vercel	PaaS / Despliegue	2 GB RAM	4 GB	Consume recursos al compilar apps.
Insomnia / Bruno	Postman	API Testing	Local	-	La colaboración es vía Git.
AppFlowy	Notion	Notas	1 GB RAM	2 GB	Todavía puliendo integraciones.
Plane	Jira	Proyectos	4 GB RAM	8 GB	Múltiples servicios corriendo.
NocoDB	Airtable	DB Visual	1 GB RAM	4 GB	Depende del volumen de datos.
Mattermost	Slack	Chat	2 GB RAM	4 GB	Búsquedas en tiempo real.
Jitsi	Zoom	Video	4 GB / 4 vCPU	8 GB+	Muy sensible a la CPU y red.
Odoo / ERPNext	SAP / Oracle	ERP	2 GB RAM	8 GB	Curva de aprendizaje técnica.

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.

Ver página completa →

Arquitectura Modular por Contexto: Cuando la Teoría se Encuentra con la Realidad

Mauricio ECR
Arquitectura
21 Mar, 2026

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 encontr

Ver página completa

Observabilidad sin Ruido: Diseñando un Sistema de Logs con AOP en Arquitecturas DDD

Mauricio ECR
Arquitectura
01 Mar, 2026

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

Ver página completa

Estándar de Arquitectura: Transacciones Distribuidas (Patrón Saga)

Mauricio ECR
Arquitectura
14 Feb, 2026

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 bloque

Ver página completa

Arquitectura distribuida y el abandono consciente de ACID

Mauricio ECR
Arquitectura
14 Feb, 2026

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 tranquiliz

Ver página completa

Arquitectura de Base de Datos para Identidad, Autenticación y Autorización (IAM)

Mauricio ECR
Arquitectura
01 Feb, 2026

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 aute

Ver página completa

Arquitectura de Base de Datos para Identidad, Autenticación y Autorización (IAM)

Mauricio ECR
Arquitectura
01 Feb, 2026

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.

Ver página completa →

Arquitectura de Confianza Cero en Docker Compose: Estrategias de Aislamiento y Segmentación de Redes

Mauricio ECR
DevOps
10 Jan, 2026

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 list

Ver página completa

Arquitectura de Confianza Cero en Docker Compose: Estrategias de Aislamiento y Segmentación de Redes

Mauricio ECR
DevOps
10 Jan, 2026

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:

Reducción de la Superficie de Ataque: Limitamos drásticamente qué contenedores son accesibles desde el exterior.
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.
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.

codigo mermaid


   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

Ver página completa →

Entrega de Valor en Arquitecturas de Microservicios. Una reinterpretación pragmática de Scrum para sistemas distribuidos

Mauricio ECR
Gestion
27 Dec, 2025

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

Ver página completa

Entrega de Valor en Arquitecturas de Microservicios. Una reinterpretación pragmática de Scrum para sistemas distribuidos

Mauricio ECR
Gestion
27 Dec, 2025

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.

Ver página completa →

El Arte de la Consistencia: Creando Respuestas API Predecibles en Spring MVC

Mauricio ECR
Snippets
24 Sep, 2025

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

Ver página completa

El Arte de la Consistencia: Creando Respuestas API Predecibles en Spring MVC

Mauricio ECR
Snippets
24 Sep, 2025

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.

Ver página completa →

El Arte del Contexto: Diseño Flexible en Arquitecturas DDD con Java y Spring Boot

Mauricio ECR
Snippets
23 Sep, 2025

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

Ver página completa

El Arte del Contexto: Diseño Flexible en Arquitecturas DDD con Java y Spring Boot

Mauricio ECR
Snippets
23 Sep, 2025

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:

Inicializar el contexto al empezar.
Poblarlo con datos de la petición, como cabeceras.
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.

Ver página completa →

Respuestas API Consistentes: Un Wrapper Transversal con Spring WebFlux y `WebFilter`

Mauricio ECR
Snippets
30 Aug, 2025

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

Ver página completa

Respuestas API Consistentes: Un Wrapper Transversal con Spring WebFlux y `WebFilter`

Mauricio ECR
Snippets
30 Aug, 2025

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:

Respetar el modelo reactivo: no bloquear el flujo ni forzar materializaciones tempranas.
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.

Ver página completa →

Más Allá del `try-catch`: Diseñando un Sistema de Excepciones Robusto y Escalable 🎯

Mauricio ECR
Snippets
28 Aug, 2025

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, co

Ver página completa

Más Allá del `try-catch`: Diseñando un Sistema de Excepciones Robusto y Escalable 🎯

Mauricio ECR
Snippets
28 Aug, 2025

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:

supports(Class<? extends Throwable> exceptionType): Determina si el manejador es capaz de procesar un tipo de excepción dado.
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.
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.

codigo mermaid


        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.

Ver página completa →

Transacciones Declarativas en Arquitecturas Hexagonales con Spring WebFlux y AOP

Mauricio ECR
Snippets
27 Aug, 2025

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

Ver página completa

Transacciones Declarativas en Arquitecturas Hexagonales con Spring WebFlux y AOP

Mauricio ECR
Snippets
27 Aug, 2025

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:

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

Ver página completa →

El Arte de Conectar: Forjando un DataSource Dinámico en Spring Boot

Mauricio ECR
Snippets
23 Aug, 2025

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

Ver página completa

El Arte de Conectar: Forjando un DataSource Dinámico en Spring Boot

Mauricio ECR
Snippets
23 Aug, 2025

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.

codigo mermaid


        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:

El director de orquesta (DatabaseConnectionPool) necesita la partitura: las propiedades de conexión. Para ello, acude a nuestro "bibliotecario" (DatabaseConnectionPropertiesFactory).
El bibliotecario viaja a una bóveda segura (el gestor de secretos) para recuperar la partitura (DatabaseConnectionProperties).
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).
Este maestro selecciona al músico virtuoso adecuado (DatabaseEngineStrategy) para ese instrumento.
El músico, con su maestría, interpreta la partitura y genera la melodía única: la URL JDBC.
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:

Mundos Paralelos: Extender la lógica para manejar réplicas de lectura, creando un DataSource para escritura y otro para lectura.
Nuevos Talentos: Incorporar estrategias para Oracle, SQL Server o incluso bases de datos NoSQL con drivers JDBC.
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.

Ver página completa →

Manejando el Caos: Una Guía Definitiva sobre Excepciones de Dominio 🎯

Mauricio ECR
Snippets
20 Aug, 2025

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

Ver página completa

Manejando el Caos: Una Guía Definitiva sobre Excepciones de Dominio 🎯

Mauricio ECR
Snippets
20 Aug, 2025

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:

Excepción	Descripción	Ejemplo de Uso	Código HTTP	DEFAULT_MESSAGE	DEFAULT_CODE
EntityNotFoundException	La entidad o recurso solicitado no existe	Buscar un usuario con `id=99` que no está en la base de datos	404 Not Found	`ENTITY_NOT_FOUND`	`404-001`
DuplicateEntityException	Ya existe una entidad con un identificador único	Crear un usuario con un email ya registrado	409 Conflict	`DUPLICATE_ENTITY`	`409-001`
InvalidIdentifierException	El identificador no cumple con el formato requerido	Consultar un producto con ID esperado como UUID usando valor `"ABC-###"`	400 Bad Request	`INVALID_IDENTIFIER`	`400-001`
BusinessRuleViolationException	Violación de una regla de negocio fundamental	Retiro bancario que excede el saldo disponible	422 Unprocessable Entity	`BUSINESS_RULE_VIOLATION`	`422-001`
OperationNotAllowedException	Operación no permitida en el estado actual del recurso	Intentar cancelar un pedido ya entregado	403 Forbidden	`OPERATION_NOT_ALLOWED`	`403-001`
InconsistentStateException	Estado internamente incoherente en el modelo de dominio	Pedido marcado como "pagado" sin transacciones asociadas	500 Internal Server Error	`INCONSISTENT_STATE`	`500-001`
ValidationException	Error genérico de validación de datos de entrada	Petición a la API sin campo obligatorio	400 Bad Request	`VALIDATION_FAILED`	`400-002`
InvalidValueException	Valor de campo fuera de rango o inválido	Crear usuario con `edad = -5`	400 Bad Request	`INVALID_VALUE`	`400-003`
MissingMandatoryValueException	Ausencia de valor obligatorio para la operación	Crear factura sin número de serie	400 Bad Request	`MISSING_MANDATORY_VALUE`	`400-004`
ConcurrencyException	Conflicto al modificar un recurso en paralelo	Dos usuarios editando el mismo producto simultáneamente	409 Conflict	`CONCURRENCY_CONFLICT`	`409-002`
OptimisticLockingException	Discordancia en versión de entidad (bloqueo optimista)	Guardar cliente con `version=2` cuando la BD tiene `version=3`	409 Conflict	`OPTIMISTIC_LOCK_ERROR`	`409-003`
ReferentialIntegrityException	Violación de restricción de integridad referencial	Eliminar cliente que tiene facturas asociadas	409 Conflict	`REFERENTIAL_INTEGRITY_VIOLATION`	`409-004`
AuthenticationException	Fallo en proceso de autenticación	Iniciar sesión con contraseña incorrecta	401 Unauthorized	`AUTHENTICATION_FAILED`	`401-001`
AuthorizationException	Usuario sin permisos necesarios para la operación	Usuario "cliente" intentando acceder a panel de administración	403 Forbidden	`AUTHORIZATION_FAILED`	`403-002`
SessionExpiredException	Sesión expirada o token inválido	Petición con JWT expirado a endpoint protegido	401 Unauthorized	`SESSION_EXPIRED`	`401-002`
WorkflowViolationException	Transición inválida en flujo o proceso	Intentar "aprobar" orden de compra no "validada"	422 Unprocessable Entity	`WORKFLOW_VIOLATION`	`422-002`
TimeoutException	Operación excedió tiempo de espera máximo	Pago en pasarela externa sin respuesta a tiempo	504 Gateway Timeout	`OPERATION_TIMEOUT`	`504-001`
ExternalSystemUnavailableException	Sistema externo dependiente no disponible	Servicio de inventario caído durante procesamiento de venta	503 Service Unavailable	`EXTERNAL_SYSTEM_UNAVAILABLE`	`503-001`
InsufficientBalanceException	Fondos o saldo insuficientes	Pagar compra de 200€ con saldo de 100€	422 Unprocessable Entity	`INSUFFICIENT_BALANCE`	`422-003`
CurrencyMismatchException	Mezcla de monedas incompatibles	Pagar en USD desde cuenta que opera solo en EUR	400 Bad Request	`CURRENCY_MISMATCH`	`400-005`
LimitExceededException	Superación de límite definido	Transferir 10.000€ con límite diario de 5.000€	429 Too Many Requests	`LIMIT_EXCEEDED`	`429-001`
ConfigurationException	Error o falta de configuración en el dominio	Sistema sin tipo de IVA definido para país específico	500 Internal Server Error	`CONFIGURATION_ERROR`	`500-002`
UnsupportedOperationException	Operación no soportada o implementada	Exportar reporte a formato obsoleto no desarrollado	501 Not Implemented	`UNSUPPORTED_OPERATION`	`501-001`

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.

Ver página completa →

Una Propuesta para Estandarizar la Seguridad en APIs REST con Arquitectura Hexagonal y Spring Security

Mauricio ECR
Snippets
03 Aug, 2025

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 t

Ver página completa

Una Propuesta para Estandarizar la Seguridad en APIs REST con Arquitectura Hexagonal y Spring Security

Mauricio ECR
Snippets
03 Aug, 2025

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.

Ver página completa →

Tablas Normalizadas vs. JSON/JSONB en PostgreSQL

Mauricio ECR
Persistencia
11 Jul, 2025

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

Ver página completa

Tablas Normalizadas vs. JSON/JSONB en PostgreSQL

Mauricio ECR
Persistencia
11 Jul, 2025

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

Desarrollo Ágil: Sin necesidad de migrar con cada cambio menor.
Rendimiento: Índices GIN aceleran búsquedas complejas.
Mantenibilidad: Las estructuras centrales permanecen estables.
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

Ver página completa →

Arquitectura DDD y Hexagonal: Construyendo Software para el Futuro

Mauricio ECR
Arquitectura
05 Jul, 2025

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

Ver página completa

Arquitectura DDD y Hexagonal: Construyendo Software para el Futuro

Mauricio ECR
Arquitectura
05 Jul, 2025

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.

Componente	Rol y Responsabilidad Clave
Agregado (Aggregate)	Unidad de consistencia transaccional. Agrupa entidades y objetos de valor bajo una raíz (`Aggregate Root`) que protege las reglas de negocio del clúster.
Entidad (Entity)	Objeto con una identidad única que perdura en el tiempo y un ciclo de vida definido. Su identidad es lo que lo define, no sus atributos.
Objeto de Valor (VO)	Objeto inmutable definido por sus atributos, sin una identidad propia. Se utiliza para medir, cuantificar o describir cosas (ej. `Dinero`, `FechaRango`).
Evento de Dominio	Representa un suceso de negocio relevante que ya ha ocurrido. Sirve para comunicar cambios y desacoplar la lógica entre diferentes partes del sistema.
Servicio de Dominio	Encapsula lógica de negocio sin estado que no pertenece de forma natural a ninguna entidad u objeto de valor, a menudo coordinando varios de ellos.
Repositorio (Puerto)	Define el contrato para persistir y recuperar agregados. Es una interfaz que dicta las necesidades del dominio sin conocer la tecnología subyacente.
Caso de Uso	Orquesta el flujo de una operación. Es el punto de entrada a la lógica de dominio, recibiendo datos de entrada y utilizando los puertos para ejecutar la acción.

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

Componente	Rol y Responsabilidad Clave
Entry-Point	Adaptador que recibe una señal externa (ej. una petición HTTP, un mensaje de una cola) y la traduce en una llamada a un Caso de Uso.
DTO (Data Transfer Object)	Define la estructura de datos para la comunicación externa. Se usa en los `Entry-Points` para modelar peticiones y respuestas, aislando el dominio.
Driven-Adapter	Implementación de un puerto del dominio. Por ejemplo, un repositorio que usa JPA para hablar con una base de datos o un cliente HTTP para consumir otra API.
Modelo de Persistencia	Clase que mapea a una estructura de base de datos (ej. una tabla). Es un detalle de implementación del adaptador de persistencia, no es la entidad de dominio.
Mapper / Traductor	Utilidad para convertir datos entre capas: `DTO` ↔ `Entidad`, `Modelo de Persistencia` ↔ `Entidad`. Es el pegamento que permite el desacoplamiento.

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

Componente	Rol y Responsabilidad Clave
Contenedor IoC	Configuración de la Inyección de Dependencias. Define "recetas" para construir los objetos, especificando qué `Driven-Adapter` se debe usar para un `Puerto`.
Configuración	Gestiona los parámetros externos de la aplicación (URLs, credenciales, etc.) a través de archivos (`.yml`, `.properties`) o variables de entorno.
Punto de Entrada	La clase que contiene el método `public static void main(String[] args)`. Su única función es arrancar el framework y, con él, toda la aplicación.

📂 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:

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

Ver página completa →

Diseñando un Wrapper de Respuesta en Java con Funcionalidades de Optional y Gestión de Estado

Mauricio ECR
Snippets
30 Jun, 2025

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 extern

Ver página completa

Diseñando un Wrapper de Respuesta en Java con Funcionalidades de Optional y Gestión de Estado

Mauricio ECR
Snippets
30 Jun, 2025

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.

Por tanto, es útil extender su concepto en una clase personalizada que mantenga las siguientes características:

Presencia opcional de un valor
Estado de la operación (SUCCESS, FAILURE, PENDING)
Listado de errores informativos o técnicos
Soporte para operaciones tipo map, flatMap, orElse y ifPresent

Estructura de Código

La clase ResponseWrapper y el enum Status pueden definirse como sigue:

Archivo `Status.java`

public enum Status {
    SUCCESS,
    FAILURE,
    PENDING
}

Archivo `ResponseWrapper.java`

import java.util.ArrayList;
import java.util.List;
import java.util.NoSuchElementException;
import java.util.function.Consumer;
import java.util.function.Function;
import java.util.function.Supplier;

public class ResponseWrapper<T> {
    private final T value;
    private final Status status;
    private final List<String> errors;

    private ResponseWrapper(T value, Status status, List<String> errors) {
        this.value = value;
        this.status = status;
        this.errors = errors != null ? new ArrayList<>(errors) : new ArrayList<>();
    }

    public static <T> ResponseWrapper<T> of(T value) {
        return new ResponseWrapper<>(value, Status.SUCCESS, null);
    }

    public static <T> ResponseWrapper<T> empty() {
        return new ResponseWrapper<>(null, Status.PENDING, null);
    }

    public static <T> ResponseWrapper<T> ofError(List<String> errors) {
        return new ResponseWrapper<>(null, Status.FAILURE, errors);
    }

    public boolean isPresent() {
        return value != null;
    }

    public T get() {
        if (value == null) {
            throw new NoSuchElementException("No value present");
        }
        return value;
    }

    public T orElse(T other) {
        return value != null ? value : other;
    }

    public T orElseGet(Supplier<? extends T> other) {
        return value != null ? value : other.get();
    }

    public <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws X {
        if (value != null) {
            return value;
        } else {
            throw exceptionSupplier.get();
        }
    }

    public void ifPresent(Consumer<? super T> consumer) {
        if (value != null) {
            consumer.accept(value);
        }
    }

    public <U> ResponseWrapper<U> map(Function<? super T, ? extends U> mapper) {
        if (!isPresent()) {
            return empty();
        }
        return ResponseWrapper.of(mapper.apply(value));
    }

    public <U> ResponseWrapper<U> flatMap(Function<? super T, ResponseWrapper<U>> mapper) {
        if (!isPresent()) {
            return empty();
        }
        return mapper.apply(value);
    }

    public Status getStatus() {
        return status;
    }

    public List<String> getErrors() {
        return new ArrayList<>(errors);
    }

    public boolean isSuccess() {
        return status == Status.SUCCESS;
    }

    public boolean isFailure() {
        return status == Status.FAILURE;
    }

    public boolean isPending() {
        return status == Status.PENDING;
    }

    @Override
    public String toString() {
        return value != null
            ? String.format("ResponseWrapper[%s, %s, %s]", value, status, errors)
            : String.format("ResponseWrapper.empty[%s, %s]", status, errors);
    }
}

Aplicaciones Prácticas

Caso de Uso 1: Servicio RESTful

En una API REST, ResponseWrapper puede encapsular una respuesta sin tener que lanzar excepciones para errores esperados:

@GetMapping("/usuarios/{id}")
public ResponseEntity<ResponseWrapper<Usuario>> obtenerUsuario(@PathVariable Long id) {
    Optional<Usuario> usuario = usuarioService.buscarPorId(id);
    if (usuario.isPresent()) {
        return ResponseEntity.ok(ResponseWrapper.of(usuario.get()));
    } else {
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
            .body(ResponseWrapper.ofError(List.of("Usuario no encontrado")));
    }
}

Caso de Uso 2: Validación de datos

public ResponseWrapper<String> validarEntrada(String input) {
    if (input == null || input.isBlank()) {
        return ResponseWrapper.ofError(List.of("Entrada vacía o nula"));
    }
    return ResponseWrapper.of(input.trim());
}

Caso de Uso 3: Procesamiento Encadenado

ResponseWrapper<String> resultado = validarEntrada("   hola   ")
    .map(String::toUpperCase)
    .flatMap(this::procesarTexto);

if (resultado.isFailure()) {
    log.warn("Errores: {}", resultado.getErrors());
}

Conclusiones

El patrón ResponseWrapper representa una evolución práctica del uso de Optional<T> en Java, permitiendo no solo modelar valores opcionales, sino también asociar metainformación esencial como estado y errores. Esta estructura permite escribir código más legible, declarativo y resiliente ante fallos predecibles.

Su versatilidad lo hace útil en diversos escenarios: servicios web, validaciones, transformaciones funcionales y pruebas. Además, su diseño extensible admite futuras adaptaciones como códigos de error tipados, trazabilidad de auditoría o integración con frameworks de serialización JSON.

Referencias y Recursos Adicionales

Ver página completa →

Auditoría: Un Enfoque Auto-Declarativo

Mauricio ECR
Auditoria
28 Jun, 2025

La Necesidad de Logs que Cuentan Historias En el ciclo de vida de cualquier plataforma digital, llega un momento crucial en el que responder a la pregunta "¿Quién hizo qué y cuándo?" deja de ser u

Ver página completa

Auditoría: Un Enfoque Auto-Declarativo

Mauricio ECR
Auditoria
28 Jun, 2025

La Necesidad de Logs que Cuentan Historias

En el ciclo de vida de cualquier plataforma digital, llega un momento crucial en el que responder a la pregunta "¿Quién hizo qué y cuándo?" deja de ser una opción y se convierte en una necesidad. Los logs de auditoría son la crónica de nuestra aplicación, un registro inmutable de las acciones significativas.

Esta guía presenta la versión 0.1 de nuestros lineamientos de auditoría, un enfoque diseñado con un objetivo primordial: la legibilidad inmediata. Partimos de un principio fundamental que guiará todas las decisiones en esta fase inicial:

Principio Fundamental V0.1: Cada entrada de log debe ser una historia completa y comprensible por sí misma, sin requerir consultas a sistemas externos o la decodificación de identificadores (ID) opacos.

El alcance de esta versión se centra deliberadamente en registrar acciones realizadas por usuarios autenticados (logueados). Los eventos anónimos o puramente sistémicos (ej. "base de datos iniciada") quedan fuera de este marco inicial para mantener la simplicidad y el enfoque.

2. ⚠️ El Compromiso Central de la V0.1: Legibilidad vs. Exposición de Datos

Para alcanzar la meta de logs auto-declarativos, la V0.1 adopta una postura de diseño que representa un compromiso consciente. Nos desviamos temporalmente de la práctica de seguridad estándar de minimizar la exposición de datos para maximizar la utilidad inmediata.

Al implementar esta guía, la organización acepta y gestiona conscientemente el siguiente riesgo:

Aceptación de Riesgo: Para facilitar la identificación inequívoca del actor sin consultas externas, se registrará información de identificación personal (PII), como el nombre completo y el correo electrónico del usuario, en texto plano dentro de los logs de auditoría. Esta decisión aumenta el riesgo inherente en caso de una brecha de seguridad que exponga dicho sistema de logs.

En consecuencia, el acceso a los repositorios de logs de auditoría debe ser considerado un privilegio extremadamente elevado. Dicho acceso debe estar protegido por múltiples capas de seguridad, ser rigurosamente controlado mediante listas de acceso explícitas y ser monitoreado de forma continua.

3. Anatomía del Evento de Auditoría (`UserAuditEvent`)

Cada evento de auditoría generado debe ser una instancia del siguiente modelo JSON. La estructura está optimizada para la descriptividad humana, favoreciendo campos claros sobre códigos crípticos.

{
  "eventTimestamp": "2025-06-27T17:22:35.123Z",
  "user": {
    "email": "[email protected]",
    "name": "Carlos Pérez",
    "role": "Administrador"
  },
  "action": {
    "type": "DOCUMENT_DOWNLOADED",
    "description": "El usuario descargó el reporte financiero correspondiente al Q2 2025."
  },
  "resource": {
    "type": "Reporte Financiero",
    "name": "Reporte Financiero Q2 2025.pdf"
  },
  "context": {
    "clientIp": "203.0.113.55",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...",
    "details": {
      "pageUrl": "/dashboard/reports",
      "downloadId": "b1b2a38c-1e24-4a2b-8c6c-a9e9e1f2f3f4"
    }
  }
}

3.1. Desglose de Campos

Campo	Descripción y Contenido Esperado	Razón de Ser
`eventTimestamp`	Fecha y hora UTC del evento en formato ISO 8601. Obligatorio.	Establece una línea de tiempo universal e inequívoca para todos los eventos.
`user`	Objeto que describe al actor. Prohibido el uso de IDs internos en esta V0.1.	Identifica al "quién" de la historia de forma inmediata.
`user.email`	Correo electrónico principal del usuario que realizó la acción.	Es el identificador humano único más común en sistemas digitales.
`user.name`	Nombre completo del usuario para una rápida identificación visual.	Aporta contexto humano y reduce la carga cognitiva del revisor.
`user.role`	El rol o perfil del usuario en el instante de la acción (ej. "Cliente", "Admin").	Ayuda a evaluar si la acción era apropiada para el nivel de permisos del actor.
`action`	Objeto que describe la acción realizada, el "qué" de la historia.	Es el verbo de la narrativa del log.
`action.type`	Clasificador de la acción según la taxonomía definida. Obligatorio.	Permite la búsqueda, el filtrado y la creación de alertas automatizadas.
`action.description`	Descripción legible por humanos. Debe ser clara, concisa y completa. Obligatorio.	Es el corazón del principio auto-declarativo. Debe contar la historia.
`resource`	Objeto que describe el recurso o entidad afectada, el "sobre qué".	Aporta el objeto directo de la acción, completando la frase narrativa.
`resource.type`	Tipo de recurso en lenguaje natural (ej. "Factura", "Proyecto", "Usuario").	Clasifica el objeto afectado para facilitar el análisis.
`resource.name`	Nombre o identificador legible del recurso (ej. "Factura #12345", "Proyecto Alpha").	Especifica la instancia exacta del recurso que fue alterada.
`context`	Información técnica y ambiental para entender el "cómo" y el "dónde".	Proporciona pistas cruciales para investigaciones de seguridad o depuración.
`context.clientIp`	Dirección IP de origen de la solicitud. Esencial para análisis de seguridad.	Permite geolocalizar el origen de la acción y detectar patrones anómalos.
`context.userAgent`	Cadena del agente de usuario del cliente (navegador, app móvil, etc.).	Ayuda a identificar el tipo de dispositivo o software utilizado.
`context.details`	Objeto flexible para datos de contexto adicionales que completen la historia.	Un "cajón de sastre" para información valiosa que no encaja en otros campos.

4. Taxonomía de Acciones: Un Vocabulario Controlado (`action.type`)

Para garantizar la consistencia y permitir un análisis de datos efectivo, todas las acciones deben clasificarse utilizando la siguiente taxonomía plana. La elección de un action.type correcto es fundamental.

`action.type`	Cuándo Usarlo
`USER_LOGIN_SUCCESS`	Un usuario se autentica exitosamente en la plataforma.
`USER_LOGIN_FAILURE`	Falla un intento de inicio de sesión (por contraseña incorrecta, usuario inexistente, etc.).
`USER_LOGOUT`	Un usuario finaliza su sesión de forma explícita.
`PROFILE_DATA_UPDATED`	El usuario modifica la información de su propio perfil (ej. nombre, teléfono).
`PASSWORD_UPDATED`	El usuario completa exitosamente un cambio de su propia contraseña.
`DOCUMENT_VIEWED`	Se visualiza o se accede al contenido de un documento, archivo o reporte.
`DOCUMENT_DOWNLOADED`	Se inicia la descarga de un documento o archivo a un dispositivo local.
`ENTITY_CREATED`	Creación de un nuevo recurso de negocio (ej. un proyecto, una tarea, un cliente).
`ENTITY_UPDATED`	Modificación de un recurso de negocio existente.
`ENTITY_DELETED`	Eliminación (lógica o física) de un recurso de negocio.
`ADMIN_ACTION`	Acción privilegiada que afecta a otros usuarios o a la configuración global del sistema.

5. El Arte de la Descripción: Creando Logs que Cuentan Historias

El campo action.description es el pilar de la legibilidad. Su propósito es verbalizar el evento de una manera que sea inmediatamente comprensible para un ser humano. Los demás campos actúan como datos estructurados que apoyan y enriquecen esta narrativa.

Ejemplo 1: Un administrador reasigna un rol.

La descripción debe ser la protagonista, explicando la acción de forma concisa.

{
  "eventTimestamp": "2025-06-27T18:10:00Z",
  "user": { "email": "[email protected]", "name": "Admin General", "role": "Superadmin" },
  "action": {
    "type": "ADMIN_ACTION",
    "description": "El administrador reasignó el rol del usuario '[email protected]' de 'Editor' a 'Administrador'."
  },
  "resource": { "type": "Cuenta de Usuario", "name": "[email protected]" },
  "context": {
    "clientIp": "203.0.113.100",
    "userAgent": "Mozilla/5.0...",
    "details": { "adminPanelUrl": "/admin/users/edit/ana.gomez" }
  }
}

Ejemplo 2: Un cliente actualiza campos específicos de su perfil.

Note cómo details enriquece la descripción sin sobrecargarla.

{
  "eventTimestamp": "2025-06-27T19:30:15Z",
  "user": { "email": "[email protected]", "name": "Juan Rodríguez", "role": "Cliente" },
  "action": {
    "type": "PROFILE_DATA_UPDATED",
    "description": "El usuario actualizó su dirección de facturación personal."
  },
  "resource": { "type": "Perfil de Usuario", "name": "Juan Rodríguez" },
  "context": {
    "clientIp": "198.51.100.20",
    "userAgent": "Mozilla/5.0...",
    "details": { "changedFields": ["addressLine1", "city", "postalCode"] }
  }
}

6. Disciplinas y Anti-Patrones de la V0.1

Incluso en una primera versión simplificada, la disciplina es clave para no generar ruido en lugar de señales.

Protección de Credenciales Sensibles: Categóricamente Prohibido. Nunca, bajo ninguna circunstancia, se deben registrar contraseñas, tokens de sesión, claves de API o cualquier otro secreto en texto plano. La descripción debe indicar el evento ("El usuario cambió su contraseña"), no el valor del secreto.
Principio de Concisión Selectiva: Evitar el Vuelco de Datos. El campo context.details es para añadir contexto, no para volcar objetos enteros de la base de datos o payloads de API completos. Seleccione manualmente 2 o 3 piezas de información clave que realmente aporten valor a la historia del log.
La Plaga de la Generalidad: Exigir Descripciones Específicas. Una action.description como "Entidad actualizada" o "Registro modificado" es inaceptable por su inutilidad. Debe ser específica: "El usuario actualizó el número de teléfono del contacto 'Juan Pérez'" o "Se cambió el estado del proyecto 'Alpha' a 'Completado'".

7. Conclusión: La Hoja de Ruta hacia la V1.0

La versión 0.1 de estos lineamientos es un paso táctico y deliberado. Su objetivo es entregar valor inmediato a los equipos de seguridad, soporte y producto, proporcionando una trazabilidad clara y legible desde el primer día. Es un fundamento sólido sobre el cual construir.

La evolución natural hacia una versión 1.0, más robusta y segura, debe contemplar la siguiente hoja de ruta:

Minimizar la Exposición de PII: El paso más crítico será reemplazar los datos personales explícitos (user.email, user.name) por identificadores únicos y estables (user.id). Esta transición es fundamental para alinearse con las mejores prácticas de seguridad y requerirá el desarrollo de una herramienta interna segura que permita a personal autorizado resolver estos IDs.
Industrializar la Generación de Logs: Introducir un SDK de Auditoría o una librería centralizada. Esto estandarizará la creación de eventos, reducirá errores de implementación en los distintos servicios y facilitará futuras actualizaciones del formato del log.
Enriquecer el Contexto para la Observabilidad: Incorporar identificadores de correlación (traceId, requestId) en el context. Esto permitirá vincular un evento de auditoría específico con los logs de aplicación, métricas y trazas correspondientes, creando una visión de 360 grados de cada solicitud.
Formalizar y Escalar la Taxonomía: A medida que la plataforma crezca, la taxonomía plana actual deberá evolucionar. Un modelo jerárquico (ej. Domain.Resource.Action como USER_MANAGEMENT.ACCOUNT.ROLE_CHANGED) permitirá una organización más granular y potente de los miles de eventos futuros.

Estos lineamientos V0.1 no son el destino final, sino el primer y más importante paso en el camino hacia una cultura de auditoría y responsabilidad madura.

Ver página completa →

Del Dicho al Hecho: Generando Proyectos Java con Plantillas y FreeMarker

Mauricio ECR
DevOps
25 Jun, 2025

En el artículo anterior, alcanzamos un hito crucial: construimos un plugin binario funcional en Java, completo con su propia configuración y tarea. Nuestro plugin "saludador" demostró que dominamos la

Ver página completa

Del Dicho al Hecho: Generando Proyectos Java con Plantillas y FreeMarker

Mauricio ECR
DevOps
25 Jun, 2025

En el artículo anterior, alcanzamos un hito crucial: construimos un plugin binario funcional en Java, completo con su propia configuración y tarea. Nuestro plugin "saludador" demostró que dominamos la estructura, pero su utilidad era meramente académica. Hoy, transformamos ese esqueleto en una herramienta de productividad real. Vamos a convertir nuestro plugin en un generador de proyectos.

El objetivo de este capítulo es tomar la configuración del usuario (como el nombre del proyecto y el paquete base) y, con una sola tarea de Gradle, materializar un esqueleto de proyecto Java completamente funcional. Para lograr esto, dejaremos atrás la simple impresión en consola y nos adentraremos en dos áreas clave: la manipulación del sistema de archivos y, lo más importante, el uso de un motor de plantillas. Presentamos a nuestro nuevo mejor amigo: Apache FreeMarker.

1. La Herramienta Adecuada: ¿Por qué un Motor de Plantillas?

Podríamos generar archivos concatenando String en Java, pero eso sería increíblemente frágil, difícil de leer y casi imposible de mantener. Un motor de plantillas separa el "qué" (la estructura y el contenido de un archivo) del "cómo" (los datos específicos que lo rellenan).

Elegimos FreeMarker por varias razones:

Madurez y Potencia: Es una biblioteca robusta y probada en batalla.
Diseñado para la Generación de Texto: A diferencia de otros motores más enfocados en HTML, FreeMarker es excelente para generar cualquier tipo de archivo de texto: .java, .xml, .properties, o nuestro build.gradle.
Lógica en Plantillas: Permite usar condicionales, bucles y otras lógicas directamente en los archivos de plantilla, algo que será vital cuando generemos código más complejo.

2. Integrando FreeMarker en Nuestro Plugin

El primer paso es hacer que nuestro plugin conozca FreeMarker.

a) Añadir la Dependencia

Abre el archivo build.gradle de nuestro plugin (nuestro-generador/plugin/build.gradle) y añade la dependencia de FreeMarker.

// nuestro-generador/plugin/build.gradle

plugins {
    id 'java-gradle-plugin'
}

repositories {
    mavenCentral()
}

// AÑADIMOS ESTE BLOQUE
dependencies {
    // Añadimos la implementación de FreeMarker
    implementation 'org.freemarker:freemarker:2.3.32'
}

gradlePlugin {
    plugins {
        // Renombraremos el plugin para que refleje su nuevo propósito
        projectGeneratorPlugin {
            id = 'com.miempresa.project-generator'
            implementationClass = 'com.miempresa.ProjectGeneratorPlugin'
        }
    }
}

b) Creación de las Plantillas

Las plantillas son el corazón de nuestro generador. Por convención, las colocaremos en src/main/resources/templates dentro de nuestro proyecto de plugin. Gradle las empaquetará automáticamente en el .jar final, haciéndolas accesibles desde el classpath.

Crea el directorio nuestro-generador/plugin/src/main/resources/templates/. Ahora, creemos algunas plantillas básicas. Nota el uso de la sintaxis ${...} para las variables.

templates/build.gradle.ftl:

plugins {
    id 'java'
    id 'application'
}

group = '${basePackage}'
version = '1.0-SNAPSHOT'

repositories {
    mavenCentral()
}

dependencies {
    testImplementation 'org.junit.jupiter:junit-jupiter:5.10.0'
}

application {
    mainClass = '${basePackage}.Application'
}

templates/Application.java.ftl:

package ${basePackage};

public class Application {
    public static void main(String[] args) {
        System.out.println("¡Hola desde el proyecto '${projectName}'!");
    }
}

3. Expandiendo la Configuración

Nuestra extensión actual es demasiado simple. Necesitamos que el usuario nos proporcione la información necesaria para la generación. Vamos a renombrar y expandir nuestra clase de extensión.

Renombra GreeterExtension.java a GeneratorExtension.java.
Añade las nuevas propiedades.

plugin/src/main/java/com/miempresa/GeneratorExtension.java:

package com.miempresa;

public class GeneratorExtension {
    private String projectName = "mi-proyecto-generado";
    private String basePackage = "com.ejemplo.proyecto";

    public String getProjectName() {
        return projectName;
    }

    public void setProjectName(String projectName) {
        this.projectName = projectName;
    }

    public String getBasePackage() {
        return basePackage;
    }

    public void setBasePackage(String basePackage) {
        this.basePackage = basePackage;
    }
}

4. La Tarea de Generación: El Corazón de la Lógica

Aquí es donde ocurre la magia. Reemplazaremos nuestra antigua tarea greet por una nueva y potente tarea generateProject.

Renombra GreetingPlugin.java a ProjectGeneratorPlugin.java.
Actualiza la lógica para que use FreeMarker y cree los archivos.

plugin/src/main/java/com/miempresa/ProjectGeneratorPlugin.java:

package com.miempresa;

import freemarker.template.Configuration;
import freemarker.template.Template;
import freemarker.template.TemplateException;
import freemarker.template.TemplateExceptionHandler;
import org.gradle.api.Plugin;
import org.gradle.api.Project;

import java.io.File;
import java.io.FileWriter;
import java.io.IOException;
import java.io.Writer;
import java.util.HashMap;
import java.util.Map;

public class ProjectGeneratorPlugin implements Plugin<Project> {

    @Override
    public void apply(Project project) {
        final GeneratorExtension extension = project.getExtensions().create("generator", GeneratorExtension.class);

        project.getTasks().register("generateProject", task -> {
            task.setGroup("Generacion");
            task.setDescription("Genera un nuevo esqueleto de proyecto Java.");
            task.doLast(t -> {
                try {
                    generate(project, extension);
                } catch (IOException | TemplateException e) {
                    // Lanzamos una excepción para que el build falle si algo va mal
                    throw new RuntimeException("Fallo al generar el proyecto", e);
                }
            });
        });
    }

    private void generate(Project project, GeneratorExtension extension) throws IOException, TemplateException {
        String projectName = extension.getProjectName();
        String basePackage = extension.getBasePackage();
        project.getLogger().lifecycle("Iniciando generación del proyecto: {}", projectName);

        // 1. Configurar FreeMarker
        Configuration cfg = new Configuration(Configuration.VERSION_2_3_32);
        cfg.setClassForTemplateLoading(ProjectGeneratorPlugin.class, "/templates");
        cfg.setDefaultEncoding("UTF-8");
        cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);

        // 2. Crear el modelo de datos para las plantillas
        Map<String, Object> model = new HashMap<>();
        model.put("projectName", projectName);
        model.put("basePackage", basePackage);

        // 3. Crear directorios
        File projectDir = new File(project.getProjectDir(), projectName);
        File packageDir = new File(projectDir, "src/main/java/" + basePackage.replace('.', '/'));
        if (!packageDir.mkdirs()) {
            throw new IOException("No se pudieron crear los directorios base.");
        }
        new File(projectDir, "src/test/java").mkdirs();

        // 4. Procesar plantillas y generar archivos
        generateFile(cfg, model, "build.gradle.ftl", new File(projectDir, "build.gradle"));
        generateFile(cfg, model, "Application.java.ftl", new File(packageDir, "Application.java"));
        
        project.getLogger().lifecycle("Proyecto '{}' generado exitosamente en: {}", projectName, projectDir.getAbsolutePath());
    }

    private void generateFile(Configuration cfg, Map<String, Object> model, String templateName, File output) throws IOException, TemplateException {
        Template template = cfg.getTemplate(templateName);
        try (Writer writer = new FileWriter(output)) {
            template.process(model, writer);
        }
    }
}

5. Probándolo Todo Junto

Ya estamos listos para la prueba final.

Actualiza el build.gradle del proyecto de prueba para usar el nuevo ID del plugin y la nueva extensión generator.

nuestro-generador/proyecto-de-prueba/build.gradle:

plugins {
    // Usamos el nuevo ID del plugin
    id 'com.miempresa.project-generator'
}

// Usamos la nueva extensión 'generator'
generator {
    projectName = 'mi-primera-app'
    basePackage = 'com.acme.app'
}

Ejecuta la tarea de generación desde el directorio raíz (nuestro-generador/).
```
./gradlew :proyecto-de-prueba:generateProject
```

Si todo fue correcto, verás los mensajes de log en tu consola y, lo más importante, ¡un nuevo directorio llamado mi-primera-app habrá aparecido! Dentro, encontrarás un proyecto Gradle funcional, listo para ser importado en tu IDE y ejecutado.

nuestro-generador/
├── mi-primera-app/
│   ├── build.gradle
│   └── src/main/java/com/acme/app/Application.java
├── plugin/
└── ...

Conclusión y Siguientes Pasos

¡Hemos dado un salto cuántico! Nuestro plugin ha pasado de ser un juguete a una herramienta de productividad. Ahora puede tomar una configuración declarativa y generar un proyecto Java completo y funcional. Hemos aprendido a integrar una biblioteca de terceros, a gestionar y procesar archivos de plantillas desde el classpath y a escribir una lógica de tarea compleja que interactúa con el sistema de archivos.

Nuestro generador es potente, pero su estructura es estática. Siempre genera el mismo tipo de proyecto. ¿Y si pudiéramos llevarlo más allá? ¿Y si pudiéramos describir una entidad de negocio —como "Producto" o "Cliente"— y el plugin generara automáticamente todo el código CRUD (Crear, Leer, Actualizar, Borrar) para ella, siguiendo las mejores prácticas de la industria?

En el próximo artículo, nos adentraremos en el fascinante mundo del Domain-Driven Design (DDD) y la arquitectura hexagonal. Haremos que nuestro plugin lea una definición de modelo y genere dinámicamente todas las capas necesarias, desde la entidad de dominio hasta el controlador REST, llevando nuestra capacidad de automatización a un nivel completamente nuevo.

Ver página completa →

Estándar de Codificación y Gestión de Errores en Arquitecturas de Microservicios

Mauricio ECR
Convenciones
18 Jun, 2025

En el ecosistema de aplicaciones web modernas, la arquitectura de microservicios distribuidos se ha consolidado como un paradigma dominante. Su flexibilidad, escalabilidad y resiliencia son innegables

Ver página completa

Estándar de Codificación y Gestión de Errores en Arquitecturas de Microservicios

Mauricio ECR
Convenciones
18 Jun, 2025

En el ecosistema de aplicaciones web modernas, la arquitectura de microservicios distribuidos se ha consolidado como un paradigma dominante. Su flexibilidad, escalabilidad y resiliencia son innegables. Sin embargo, esta distribución introduce una complejidad significativa en la gestión de estados y, especialmente, en el manejo de errores. Cuando una operación involucra a múltiples servicios, identificar la causa raíz de un fallo puede convertirse en una tarea titánica, afectando la experiencia del usuario, los tiempos de resolución y la mantenibilidad del sistema.

Este documento establece un estándar completo y directamente aplicable para la codificación, documentación y gestión de errores visibles al usuario final. El objetivo es crear un marco de trabajo robusto que, aunque inicialmente se implementará en un entorno de backend con Java (Spring Boot) y frontend con Angular, ha sido diseñado con un enfoque agnóstico al lenguaje para garantizar su longevidad y adaptabilidad a futuras tecnologías.

Adoptar este estándar permitirá no solo presentar mensajes de error claros y útiles al usuario, sino también establecer una base documental sólida que facilite la observabilidad, la trazabilidad y la colaboración entre equipos de desarrollo, QA y soporte técnico.

El Estándar Detallado

1. Filosofía y Principios Fundamentales

Antes de detallar la implementación, es crucial entender los principios que guían este estándar:

El Error como Ciudadano de Primera Clase: Los errores no son un caso excepcional, sino una parte inherente del flujo de una aplicación. Deben ser diseñados, documentados y probados con el mismo rigor que las funcionalidades exitosas.
Claridad para el Usuario, Detalle para el Desarrollador: La información presentada al usuario final debe ser concisa, clara, traducible y orientada a la acción. Por el contrario, la información registrada para los equipos técnicos debe ser rica en detalles para permitir un diagnóstico rápido y preciso.
Seguridad por Opacidad: Los códigos y mensajes de error públicos nunca deben revelar detalles de la infraestructura interna, nombres de clases, trazas de pila (stack traces) o cualquier información que pueda ser explotada por un actor malicioso.
Trazabilidad Extrema: Cada error debe ser unívocamente identificable y correlacionable a través de los distintos servicios y sistemas de observabilidad (logs, métricas, trazas distribuidas).

2. Formato del Código de Error

Todo error visible al usuario final o que cruce los límites de un microservicio deberá ser identificado por un código único y opaco. Este código actúa como una clave inmutable que desacopla el error en sí de su representación (el mensaje).

La estructura propuesta es: MSS-ECNNN[-EXTCODE]

MSS (MicroService Short-identifier): Identificador numérico único de 3 dígitos asignado a cada microservicio. Esta asignación debe ser gestionada en un registro centralizado para evitar colisiones.
- Ejemplo: 101 para "Servicio de Autenticación", 205 para "Servicio de Pedidos".
EC (Error Category): Código alfabético de 2 letras que clasifica la naturaleza del error. Esto permite un filtrado y análisis rápido. (Ver sección 3 para el catálogo de categorías).
- Ejemplo: IV para "Validación de Entrada", BR para "Regla de Negocio".
NNN (Numeric Sequence): Secuencia numérica de 3 dígitos, única dentro del microservicio para esa categoría. Se recomienda iniciar en 001 y aumentar de forma secuencial.
- Ejemplo: 001, 002, 047.
[EXTCODE] (External Code - Opcional): Componente opcional para encapsular errores originados en servicios de terceros. Proporciona una correlación directa sin exponer el formato original del tercero.
- Formato: EXT_<ID_SERVICIO>_<CODIGO_ERROR_ORIGINAL>
- ID_SERVICIO: Un identificador corto y predefinido para el servicio externo (ej. STRIPE, SENDGRID, AWS_S3).
- CODIGO_ERROR_ORIGINAL: El código de error devuelto por el servicio externo, sanitizado para ser compatible con la URL (ej. reemplazando espacios o caracteres especiales por _).
- Ejemplo: 205-DP003-EXT_STRIPE_card_declined

Ejemplo completo: 205-BR001 representa el primer error de "Regla de Negocio" definido en el microservicio "Pedidos" (ID 205).

3. Clasificación de Errores Comunes

La estandarización de categorías (EC) es fundamental para la observabilidad y la generación de métricas. El catálogo inicial es el siguiente:

Código	Categoría	Descripción
`IV`	Input Validation	Errores relacionados con la validación de datos de entrada (formato, rango, campos obligatorios). Suelen ser errores del tipo `400 Bad Request`.
`AU`	Authentication & Authorization	Fallos de autenticación (token inválido, credenciales incorrectas) o autorización (sin permisos para la acción). Errores `401 Unauthorized` o `403 Forbidden`.
`BR`	Business Rule	Violación de una regla de negocio específica. La solicitud es sintácticamente correcta pero semánticamente inválida en el contexto actual (ej. stock insuficiente). Suele ser un `409 Conflict` o `422 Unprocessable Entity`.
`DP`	Dependency Failure	Un servicio externo del que depende el microservicio no está disponible o ha devuelto un error (otra API interna, base de datos, sistema de colas). Errores del tipo `502 Bad Gateway` o `503 Service Unavailable`.
`SY`	System Error	Errores inesperados o no controlados en el servidor (excepciones `RuntimeException`, `NullPointerException`, etc.). Siempre deben ser investigados. Corresponden a un `500 Internal Server Error`.
`NT`	Network & Timeout	Errores de comunicación, ya sea porque una dependencia no respondió a tiempo o por problemas en la red. Corresponde a un `504 Gateway Timeout`.
`CF`	Configuration Error	El servicio no puede iniciarse o funcionar correctamente debido a una configuración faltante o incorrecta (variables de entorno, secretos, etc.).
`NF`	Not Found	El recurso solicitado no existe. Corresponde a un `440 Not Found`.

4. Catálogo Inicial de Códigos de Error

A continuación, se presenta un catálogo de ejemplo con 10 códigos para dos microservicios hipotéticos: Gestión de Usuarios (ID: 101) y Procesamiento de Pedidos (ID: 205).

Código	Mensaje usuario	Descripción técnica	Severidad	Estado	Acción esperada	Servicio externo (si aplica)
101-IV001	El correo electrónico proporcionado no tiene un formato válido. Por favor, revísalo.	El campo `email` en el DTO de registro de usuario no supera la validación de la expresión regular `^(.+)@(.+)$`.	Baja	Activo	Usuario: Corregir el formato del email. Frontend: Realizar validación en cliente para prevenir el error.	N/A
101-AU001	Tu sesión ha expirado. Por favor, inicia sesión de nuevo.	El JWT recibido en la cabecera `Authorization` ha caducado. La fecha de expiración (`exp`) es anterior a la fecha actual.	Media	Activo	Sistema: Redirigir al usuario a la página de login. Usuario: Volver a introducir sus credenciales.	N/A
101-AU002	No tienes permisos para realizar esta acción. Contacta al administrador si crees que es un error.	El usuario autenticado, extraído del token, no posee el rol requerido (`ROLE_ADMIN`) para acceder al endpoint.	Media	Activo	Frontend: Ocultar o deshabilitar la opción que provoca el error. Soporte: Verificar los roles del usuario si este levanta un ticket.	N/A
101-BR001	El correo electrónico ya está registrado en nuestra plataforma. Intenta iniciar sesión.	Se intentó crear un usuario con un email que ya existe en la tabla `users` de la base de datos (violación de `UNIQUE constraint`).	Baja	Activo	Usuario: Usar la opción "recuperar contraseña" o iniciar sesión. Frontend: Ofrecer un enlace directo a la página de login.	N/A
205-IV001	El identificador del producto no es válido. Debe ser un número positivo.	El `productId` recibido en la línea de un pedido es nulo, cero o negativo. La validación `@Positive` falló en el DTO.	Baja	Activo	Usuario: Informar del error. Es un caso raro que indica un bug en el frontend. Desarrollo: Investigar cómo se pudo enviar un ID inválido desde el cliente.	N/A
205-BR001	No hay suficiente stock para el producto 'Nombre del Producto'. Solo quedan X unidades.	La cantidad solicitada de un producto es mayor que el `stock` disponible registrado en la base de datos para ese `productId`.	Media	Activo	Usuario: Reducir la cantidad del producto o eliminarlo del carrito. Sistema: El mensaje debe incluir el stock actual para ser útil.	N/A
205-BR002	No se pueden añadir productos de diferentes vendedores en un mismo pedido.	La lógica de negocio impide mezclar productos de `sellerId` distintos en una sola transacción para simplificar la logística.	Media	Activo	Usuario: Finalizar la compra actual y crear un nuevo pedido para los otros productos. Frontend: Mostrar una advertencia al intentar añadir un producto incompatible.	N/A
205-DP001	El servicio de inventario no está respondiendo. Por favor, inténtalo de nuevo en unos minutos.	La llamada HTTP al microservicio de Inventario (ID `310`) para verificar el stock ha resultado en un timeout o error 5xx.	Alta	Activo	Sistema: Implementar un reintento con exponential backoff. Si persiste, activar un circuit breaker. Soporte: Revisar el estado del servicio de Inventario.	N/A
205-DP002	Tu pago no pudo ser procesado por el proveedor. Razón: Fondos insuficientes.	La pasarela de pagos (Stripe) devolvió un error `402 Request Failed` con el código `card_declined` y el motivo `insufficient_funds`.	Media	Activo	Usuario: Intentar con otro método de pago o verificar los fondos de su tarjeta. Sistema: No reintentar automáticamente. Invalidar el pedido.	`EXT_STRIPE_insufficient_funds`
205-SY001	Ha ocurrido un error inesperado al procesar tu pedido. Nuestro equipo ya ha sido notificado.	Se ha capturado una `NullPointerException` no esperada en la clase `OrderProcessingService` al calcular los impuestos. Se ha creado una alerta en Sentry/Datadog.	Alta	Activo	Sistema: Registrar el `trace_id` y toda la información de la petición. Desarrollo: Priorizar la corrección de este bug. Usuario: Reintentar más tarde o contactar a soporte con el `trace_id` si se le muestra.	N/A

5. Documentación y Centralización

La documentación es lo que transforma este estándar de una idea a una herramienta útil.

Estructura de Archivos: Cada microservicio debe incluir en su repositorio un archivo docs/errors/errors.md. Este archivo contendrá la tabla completa de errores que el servicio puede generar.
Control de Versiones: El archivo errors.md debe ser versionado junto con el código fuente del microservicio. Cualquier adición o modificación de un código de error debe formar parte de un Pull Request, permitiendo su revisión.
Formato de Documentación: Se utilizará la tabla Markdown definida en la sección anterior. Este formato es fácil de leer para humanos y de parsear por máquinas.

Ejemplo de `microservice-orders/docs/errors/errors.md`:

Catálogo de Errores - Servicio de Pedidos

Nombre Lógico: Servicio de Procesamiento de Pedidos
ID del Microservicio: 205

Código	Mensaje usuario	Descripción técnica	Severidad	Estado	Acción esperada	Servicio externo (si aplica)
205-IV001	El identificador del producto no es válido. Debe ser un número positivo.	El `productId` recibido en la línea de un pedido es nulo, cero o negativo. La validación `@Positive` falló en el DTO.	Baja	Activo	Usuario: Informar del error. Desarrollo: Investigar cómo se pudo enviar un ID inválido.	N/A
...	...	...	...	...	...	...

6. Recomendaciones para Centralización y Escalabilidad

Para que el estándar sea efectivo en una organización grande, se recomienda:

Repositorio Central de Errores: Un pipeline de CI/CD debería agregar los archivos errors.md de todos los microservicios tras cada release exitosa en un repositorio central o una página de Confluence/Wiki. Esto crea un único punto de verdad para que los equipos de QA, Soporte y Frontend puedan consultar cualquier código de error sin necesidad de acceder a los repositorios individuales.
Automatización y Linters: El pipeline de CI/CD debe incluir pasos para:
- Validar la Unicidad: Asegurar que no existan códigos MSS-ECNNN duplicados dentro del mismo microservicio.
- Validar el Formato: Comprobar que todos los nuevos códigos sigan la estructura definida.
- Detectar Nuevos Servicios Externos: Lanzar una advertencia si se añade un EXTCODE con un <ID_SERVICIO> no registrado previamente, para asegurar que se documente centralmente.
Generación de Artefactos: Se pueden crear scripts que lean estos archivos .md para generar automáticamente artefactos útiles, como:
- Enums de TypeScript para el frontend, permitiendo un manejo de errores tipado (case ErrorCodes.USER_EMAIL_EXISTS:).
- Clases de constantes en Java para el backend.
- Plantillas para sistemas de tickets (Jira, Zendesk).

Conclusión

Este estándar de codificación y gestión de errores proporciona un marco de trabajo unificado y resiliente, diseñado para escalar con la complejidad de una arquitectura de microservicios. Al tratar los errores como un componente central del diseño de software, logramos múltiples beneficios:

Mejora la Experiencia del Usuario (UX): Los mensajes son claros, consistentes y orientados a la acción.
Agiliza la Resolución de Incidencias: Los códigos únicos y la documentación detallada permiten a los equipos de soporte y desarrollo identificar y solucionar problemas rápidamente.
Potencia la Observabilidad: La estructura de códigos y categorías facilita la creación de dashboards, alertas y métricas significativas sobre la salud del sistema.
Aumenta la Seguridad: La opacidad de los códigos previene la fuga de información sensible de la infraestructura.

Futuras Líneas de Aplicación:

Integración con Plataformas de Observabilidad: Enriquecer automáticamente las trazas distribuidas (ej. en Jaeger o Datadog) con la "Descripción Técnica" del error a partir de su código.
Desarrollo de un "Servicio de Errores": Una pequeña API central que, dado un código de error, devuelva su documentación completa, incluyendo el mensaje de usuario localizado en diferentes idiomas.
Generación de SDKs de Cliente: Automatizar la creación de librerías para diferentes lenguajes (JS/TS, Python, Go) que encapsulen la lógica de manejo de estos códigos de error estandarizados.

La adopción disciplinada de este estándar no es una carga adicional, sino una inversión estratégica en la calidad, mantenibilidad y escalabilidad a largo plazo de la plataforma.

Ver página completa →

De Consumidor a Creador: Construyendo tu Primer Plugin Binario de Gradle

Mauricio ECR
DevOps
16 Jun, 2025

En nuestro artículo anterior, desmitificamos Gradle y sentamos las bases para entender su funcionamiento. Aprendimos a crear proyectos, ejecutar tareas y comprendimos el rol fundamental de los plugins

Ver página completa

De Consumidor a Creador: Construyendo tu Primer Plugin Binario de Gradle

Mauricio ECR
DevOps
16 Jun, 2025

En nuestro artículo anterior, desmitificamos Gradle y sentamos las bases para entender su funcionamiento. Aprendimos a crear proyectos, ejecutar tareas y comprendimos el rol fundamental de los plugins como consumidores. Hoy, damos el salto más emocionante: pasaremos de ser meros usuarios a ser creadores. Vamos a construir nuestro propio plugin binario desde cero, utilizando Java para la lógica y el Groovy DSL para nuestros scripts de build.

¿Por qué un plugin binario? Porque es el estándar profesional. A diferencia de los scripts sueltos, un plugin binario es un artefacto compilado (.jar), versionable, fácilmente distribuible y, sobre todo, mucho más robusto y testeable. Es el vehículo perfecto para encapsular la lógica compleja que nuestro futuro generador de código necesitará.

En este capítulo, construiremos un plugin "saludador" (Greeter). Será sencillo en su función —mostrar un mensaje configurable— pero nos enseñará la anatomía completa de un plugin en un entorno Java: su estructura, su punto de entrada, cómo hacerlo configurable y, finalmente, cómo probarlo. ¡Es hora de arremangarse y empezar a programar nuestro build!

1. La Anatomía de un Plugin: Estructura del Proyecto

Para empezar, necesitamos un entorno de trabajo. La mejor manera de desarrollar y probar un plugin es con un build multi-proyecto. Crearemos una estructura que contenga tanto la lógica del plugin como un proyecto de ejemplo que lo consumirá.

Abre tu terminal y crea la siguiente estructura de directorios:

nuestro-generador/
├── plugin/                # Directorio para el código de nuestro plugin
└── proyecto-de-prueba/    # Un proyecto simple para aplicar y probar el plugin

Ahora, configuremos cada parte.

a) Configurando el Proyecto del Plugin (`/plugin`)

Este es el corazón de nuestro trabajo. Dentro del directorio plugin, crea un archivo build.gradle y un settings.gradle.

plugin/settings.gradle:

rootProject.name = 'mi-plugin-saludador'

plugin/build.gradle: Este archivo es crucial. Le dice a Gradle que estamos construyendo un plugin de Gradle con código Java.

plugins {
    // Plugin esencial para desarrollar plugins de Gradle en Java
    id 'java-gradle-plugin'
}

repositories {
    mavenCentral()
}

// Este bloque configura los detalles de nuestro plugin
gradlePlugin {
    plugins {
        // "greeterPlugin" es el nombre que le damos a nuestra configuración
        greeterPlugin {
            id = 'com.miempresa.greeter' // El ID único que los usuarios usarán
            implementationClass = 'com.miempresa.GreetingPlugin' // La clase Java que implementa la lógica
        }
    }
}

b) El Código Fuente del Plugin

Gradle necesita saber dónde está el código. Con el plugin java-gradle-plugin, asumirá la estructura estándar de Java.

Crea la clase del Plugin: Dentro de plugin/, crea la ruta de directorios src/main/java/com/miempresa/. Dentro, crea el archivo GreetingPlugin.java.
El archivo de propiedades: El plugin java-gradle-plugin y el bloque gradlePlugin se encargan de generar automáticamente el archivo de propiedades necesario (META-INF/gradle-plugins/com.miempresa.greeter.properties). ¡Magia!

2. El Punto de Entrada: La Interfaz `Plugin<Project>`

Todo plugin binario debe implementar la interfaz Plugin<Project>. Su método apply(Project project) es la puerta de entrada, el equivalente al main de una aplicación. Es aquí donde toda nuestra lógica se conectará al proyecto que use el plugin.

Edita tu archivo plugin/src/main/java/com/miempresa/GreetingPlugin.java:

package com.miempresa;

import org.gradle.api.Plugin;
import org.gradle.api.Project;

public class GreetingPlugin implements Plugin<Project> {
    @Override
    public void apply(Project project) {
        // El objeto "project" es nuestra puerta de acceso al build del consumidor.
        // Aquí registraremos tareas, extensiones, etc.
        project.getLogger().lifecycle("¡Plugin 'greeter' aplicado con éxito!");
    }
}

Ya tenemos un esqueleto funcional. ¡Pero un plugin que no hace nada no es muy útil!

3. Haciendo tu Plugin Configurable con Extensiones

Rara vez querremos que un plugin se comporte siempre igual. Necesitamos una forma de que el usuario lo configure. En lugar de pasar parámetros de forma engorrosa, Gradle nos ofrece un mecanismo elegante: las Extensiones.

Una extensión no es más que un POJO (Plain Old Java Object) cuyas propiedades serán configurables desde el build.gradle del consumidor a través de sus getters y setters.

Crea la clase de la Extensión: Dentro de com.miempresa, crea un nuevo archivo GreeterExtension.java.

package com.miempresa;

public class GreeterExtension {
    // En Java, las propiedades se modelan con campos privados y getters/setters públicos.
    private String message = "Hola por defecto desde el plugin Java";

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

Registra la Extensión: Ahora, volvamos a GreetingPlugin.java y registremos la extensión en el método apply.

// ... en GreetingPlugin.java
@Override
public void apply(Project project) {
    // Registramos una extensión llamada "greeter" que usa nuestra clase POJO.
    // El usuario la configurará con un bloque `greeter { ... }` en su build.gradle
    GreeterExtension extension = project.getExtensions().create("greeter", GreeterExtension.class);

    // ... más lógica vendrá aquí
}

4. Dando Vida al Plugin: Tareas Personalizadas

El objetivo final de un plugin es, generalmente, añadir nuevas tareas. Vamos a crear una tarea greet que use el mensaje de nuestra extensión.

Registra la Tarea: Dentro del método apply de GreetingPlugin.java, después de registrar la extensión, registraremos la tarea.

// ... en GreetingPlugin.java, dentro del método apply()
@Override
public void apply(Project project) {
    // La variable debe ser final (o efectivamente final) para ser usada en la lambda
    final GreeterExtension extension = project.getExtensions().create("greeter", GreeterExtension.class);

    // Registramos una nueva tarea llamada "greet"
    project.getTasks().register("greet", task -> {
        task.setGroup("Saludos"); // Agrupa la tarea en la lista de `./gradlew tasks`
        task.setDescription("Muestra un saludo configurable");

        // La acción que se ejecutará cuando se llame a la tarea
        task.doLast(t -> {
            // Usamos la extensión capturada del scope exterior
            project.getLogger().lifecycle(extension.getMessage());
        });
    });
}

Hemos conectado todo: El plugin registra una extensión para recibir configuración y una tarea que lee esa configuración para ejecutar una acción.

5. ¡A Probar! Aplicando y Verificando el Plugin Localmente

Es el momento de la verdad. Vamos a usar nuestro proyecto-de-prueba para consumir el plugin que acabamos de crear.

Modifica el settings.gradle principal: Necesitamos decirle a Gradle que nuestro build tiene dos subproyectos y que uno (plugin) es un "build incluido" que provee plugins. Crea un archivo settings.gradle en el directorio raíz (nuestro-generador/).
```
// nuestro-generador/settings.gradle
rootProject.name = 'generador-completo'

// Incluye el proyecto que usará el plugin
include 'proyecto-de-prueba'

// Incluye el build que contiene nuestro plugin
includeBuild 'plugin'
```

Configura el proyecto-de-prueba: Ahora, crea un archivo build.gradle dentro de proyecto-de-prueba/.

// nuestro-generador/proyecto-de-prueba/build.gradle

plugins {
    // ¡Aplicamos nuestro plugin usando el ID que definimos!
    id 'com.miempresa.greeter'
}

// Configuramos la extensión que creamos en el plugin.
// El Groovy DSL llama a setMessage() automáticamente.
greeter {
    message = '¡Mi primer plugin en Java funciona! 🎉'
}

Ejecuta la Tarea: Vuelve a la raíz (nuestro-generador/) en tu terminal y ejecuta la tarea, especificando la ruta completa del proyecto:
```
gradle :proyecto-de-prueba:greet
```

Si todo ha ido bien, deberías ver la salida:

Task :proyecto-de-prueba:greet ¡Mi primer plugin en Java funciona! 🎉

Y si ejecutas gradle :proyecto-de-prueba:tasks verás tu tarea listada bajo el grupo "Saludos".

Conclusión y Siguientes Pasos

¡Lo has conseguido! Has trascendido la barrera de simple usuario para convertirte en un desarrollador de plugins de Gradle usando Java. Hoy has aprendido el ciclo de vida completo de la creación de un plugin: desde la estructura del proyecto y el uso del plugin java-gradle-plugin, pasando por la implementación de la interfaz Plugin<Project>, la creación de una extensión POJO para hacerlo configurable, y el registro de una tarea personalizada que materializa su lógica.

Ya tenemos una base robusta y profesional. Nuestro plugin puede ser configurado y puede ejecutar acciones. Ahora que dominamos la estructura, el siguiente paso es hacerlo realmente útil.

En la próxima entrega de esta serie, tomaremos este esqueleto y le añadiremos músculos. Integraremos un motor de plantillas como FreeMarker, y modificaremos nuestra tarea para que, en lugar de imprimir un simple mensaje, genere una estructura completa de directorios y archivos. La aventura de nuestro generador de código está a punto de dar su paso más importante.

Ver página completa →

Desmitificando Gradle: El Primer Paso para Automatizar tu Mundo Java

Mauricio ECR
DevOps
14 Jun, 2025

En el vertiginoso universo del desarrollo de software, la eficiencia no es un lujo, es una necesidad. Dedicar tiempo a tareas repetitivas como compilar código, ejecutar pruebas, empaquetar la aplicaci

Ver página completa

Desmitificando Gradle: El Primer Paso para Automatizar tu Mundo Java

Mauricio ECR
DevOps
14 Jun, 2025

En el vertiginoso universo del desarrollo de software, la eficiencia no es un lujo, es una necesidad. Dedicar tiempo a tareas repetitivas como compilar código, ejecutar pruebas, empaquetar la aplicación y gestionar dependencias es un lastre para la productividad. Aquí es donde entran en juego los sistemas de automatización de construcción, y hoy, nos enfocaremos en uno de los más potentes y flexibles del ecosistema Java: Gradle.

Este artículo es el punto de partida de una serie en la que no solo aprenderemos a usar Gradle, sino que construiremos nuestra propia herramienta avanzada: un plugin capaz de generar esqueletos de proyectos Java y módulos CRUD completos bajo la filosofía de Domain-Driven Design (DDD). Pero antes de correr, debemos aprender a caminar. ¡Acompáñanos en este primer paso para sentar unas bases sólidas y duraderas con Gradle!

¿Qué es Gradle y por qué Debería Importarte?

Imagina a Gradle como el director de orquesta de tu proyecto. Es un sistema de automatización de construcción de código abierto que toma tu código fuente, las librerías de las que depende, y una serie de instrucciones, y produce un artefacto final (como un archivo .jar o .war).

Si vienes del mundo de Java, es probable que hayas oído hablar de Maven o incluso del venerable Ant. ¿Qué hace diferente a Gradle?

Frente a Maven: Mientras que Maven se rige por la "convención sobre configuración" con una estructura rígida definida en archivos pom.xml, Gradle ofrece una flexibilidad inmensa. Su filosofía se basa en un DSL (Domain Specific Language), un lenguaje específico para el dominio de la construcción de software, que se escribe en Groovy o Kotlin. Esto transforma tus scripts de construcción de simples archivos de configuración a potentes programas.
Frente a Ant: Ant también usa scripts (XML), pero es mucho más imperativo. Le dices qué hacer y cómo hacerlo. Gradle es más declarativo; describes qué quieres lograr, y Gradle, con su modelo de grafos de dependencias, se encarga de la manera más eficiente de lograrlo.

Conceptos Clave para Empezar

Para hablar el idioma de Gradle, necesitas conocer su vocabulario esencial:

Proyectos (Projects): Un proyecto es cualquier componente que quieres construir. Puede ser una librería (.jar) o una aplicación web completa. Un repositorio puede contener un único proyecto o múltiples subproyectos.
Tareas (Tasks): Son las unidades de trabajo en Gradle. Una tarea puede ser compilar código (compileJava), ejecutar pruebas (test), crear un archivo (build) o cualquier acción que definas.
Plugins: Son extensiones que añaden nuevas capacidades y tareas a tu proyecto. Por ejemplo, el plugin de Java añade tareas para compilar y probar código Java. Son el corazón de la reusabilidad en Gradle.
Dependencias (Dependencies): Son las librerías o módulos externos que tu proyecto necesita para funcionar. Gradle se encarga de descargarlas de repositorios (como Maven Central) y hacerlas disponibles en tu proyecto.

Preparando el Terreno: Tu Entorno de Desarrollo 🛠️

Antes de escribir una sola línea, asegúrate de tener las herramientas adecuadas.

JDK (Java Development Kit): Gradle se ejecuta sobre la JVM, por lo que necesitas un JDK instalado. La versión 17 o superior es una excelente elección para proyectos modernos.
Instalación de Gradle: Aunque puedes descargarlo manualmente, la forma más recomendada es usar un gestor de versiones como SDKMAN! (para Linux/macOS) o simplemente usar el Gradle Wrapper, una pequeña utilidad que se incluye en los proyectos Gradle y que descarga la versión correcta automáticamente. ¡No te preocupes, lo veremos en acción ahora mismo!
IDE (Entorno de Desarrollo Integrado): IntelliJ IDEA ofrece una integración con Gradle que es simplemente espectacular. Visual Studio Code, con la extensión "Gradle for Java", es también una alternativa fantástica y ligera.

¡Manos a la Obra! Tu Primer Proyecto con Gradle

La teoría está muy bien, pero la magia sucede en la práctica. Vamos a crear un proyecto Java desde cero. Abre tu terminal en una carpeta vacía y ejecuta:

gradle init

Gradle te hará algunas preguntas:

Select type of project to generate: Elige 2: application.
Select implementation language: Elige 3: Java.
Split functionality across multiple subprojects?: Elige 1: no.
Select build script DSL: Elige 1: Groovy (es un excelente punto de partida, aunque también podrías elegir Kotlin).
Generate build using new APIs and behavior?: Elige no por ahora para mantenerlo simple.
Select test framework: Elige 4: JUnit Jupiter.
Project name y Source package: Presiona Enter para aceptar los valores por defecto.

¡Y listo! 🎉 Gradle ha creado una estructura de proyecto funcional:

.
├── build.gradle         // El script de construcción principal
├── gradle
│   └── wrapper
├── gradlew              // El ejecutable del Wrapper para Linux/macOS
├── gradlew.bat          // El ejecutable del Wrapper para Windows
├── settings.gradle      // Configuración de proyectos/subproyectos
└── src
    ├── main             // Código fuente de la aplicación
    │   └── java
    └── test             // Código fuente de las pruebas

El archivo más importante aquí es build.gradle. Ábrelo y verás algo así:

// build.gradle

plugins {
    id 'java'
    id 'application'
}

repositories {
    mavenCentral()
}

dependencies {
    testImplementation 'org.junit.jupiter:junit-jupiter:5.10.0'
    implementation 'com.google.guava:guava:32.1.3-jre' // Guava ya viene incluido
}

application {
    mainClass = 'org.example.App'
}

Puedes ver los conceptos en acción: se aplican los plugins java y application, se declara el repositorio mavenCentral() para buscar dependencias y se especifica la dependencia de JUnit para las pruebas.

Ahora, ejecutemos algunas tareas básicas desde la terminal:

./gradlew build: Compila, prueba y empaqueta tu aplicación.
./gradlew run: Ejecuta la aplicación.
./gradlew clean: Borra el directorio build con todos los artefactos generados.

El Corazón de Gradle: Un Vistazo a las Tareas

Todo lo que hace Gradle es a través de tareas. Puedes definir las tuyas de forma muy sencilla. Añade esto al final de tu build.gradle:

// Tarea personalizada
task miPrimeraTarea {
    doLast {
        println '¡Hola desde mi primera tarea en Gradle!'
    }
}

Ahora ejecuta ./gradlew miPrimeraTarea y verás tu mensaje. Las tareas tienen un ciclo de vida, siendo doFirst y doLast las acciones que puedes añadir al principio o al final de su ejecución.

Más importante aún es cómo las tareas se relacionan. Puedes hacer que una tarea dependa de otra:

task tareaB {
    doLast { println 'Soy la tarea B' }
}

task tareaA(dependsOn: tareaB) {
    doLast { println 'Soy la tarea A, y me ejecuto después de la B' }
}

Esta capacidad de crear un grafo de dependencias es lo que permite a Gradle ser tan eficiente. Además, gracias a los inputs y outputs de las tareas, Gradle sabe si el trabajo ya está hecho (UP-TO-DATE) y puede saltarse la ejecución, ahorrando un tiempo valiosísimo.

El Poder de la Reutilización: Introducción a los Plugins

Escribir la misma lógica de construcción en cada proyecto es tedioso. Los plugins son la solución para encapsular y reutilizar esta lógica. Ya los has usado (id 'java'). Existen tres tipos principales:

Script Plugins: Un script de Gradle (otro.gradle) que importas en tu build.gradle. Útil para lógicas simples dentro de un mismo proyecto.
Precompiled Script Plugins: Scripts .gradle.kts o .gradle que se compilan y empaquetan, permitiendo una mejor organización.
Binary Plugins: El enfoque profesional. Son clases (en Java, Groovy o Kotlin) que implementan la interfaz Plugin. Se distribuyen como archivos .jar y son el objetivo final de nuestra serie de artículos.

Conclusión y Próximos Pasos

¡Felicidades! Has dado un paso gigante. Ahora entiendes que Gradle es un sistema de construcción programable y altamente flexible, has configurado tu entorno, has creado y ejecutado tu primer proyecto Java y has escarbado en la superficie de sus conceptos más importantes: las tareas y los plugins.

Esta base sólida es el cimiento sobre el que construiremos nuestro conocimiento. Hemos sentado las bases teóricas y prácticas para entender no solo qué hace Gradle, sino cómo piensa.

En nuestra próxima entrega, daremos el siguiente paso lógico y emocionante: comenzaremos a construir nuestro propio plugin binario desde cero. Exploraremos la estructura de un proyecto de plugin, aprenderemos a crear configuraciones personalizadas para que los usuarios puedan ajustarlo y definiremos nuestras primeras tareas encapsuladas. ¡La verdadera aventura de la automatización está a punto de comenzar!

Ver página completa →

Microsoft 365 Copilot: Tu Aliado Estratégico en la Era de la Inteligencia Artificial

En el dinámico panorama laboral actual, la optimización del rendimiento y la eficiencia son claves. Aquí es donde Microsoft 365 Copilot emerge como una herramienta transformadora . Al integrar la inte

Ver página completa

Microsoft 365 Copilot: Tu Aliado Estratégico en la Era de la Inteligencia Artificial

Mauricio ECR
Productividad
13 Jun, 2025

En el dinámico panorama laboral actual, la optimización del rendimiento y la eficiencia son claves. Aquí es donde Microsoft 365 Copilot emerge como una herramienta transformadora . Al integrar la inteligencia artificial directamente en tus aplicaciones cotidianas de Microsoft como Word, Excel, Outlook y Teams, Copilot se convierte en un asistente dedicado, diseñado para automatizar las tareas mecánicas y repetitivas . Su propósito fundamental es liberar tu tiempo y tu capacidad cognitiva para que puedas concentrarte en el pensamiento crítico, la creatividad y la toma de decisiones estratégicas, elevando tu rol profesional a un nuevo nivel .

Desglosando la Potencia de Copilot

Microsoft 365 Copilot no es solo una promesa futurista, sino una realidad operativa para quienes buscan optimizar su manera de trabajar . Esta herramienta va más allá de la mera automatización, transformando cada aplicación de Microsoft en un asistente especializado que puede ahorrarte horas de trabajo por semana.

¿Qué es Microsoft 365 Copilot y en qué se diferencia?

Microsoft 365 Copilot está adaptado específicamente para el entorno empresarial, ofreciendo funcionalidades avanzadas como el acceso y la edición de archivos corporativos . Se diferencia de Copilot para Windows, que está diseñado fundamentalmente para responder a solicitudes personales . Las funcionalidades destacadas de Microsoft 365 Copilot incluyen una barra lateral completa con herramientas especializadas, un historial de conversaciones para registro y consulta rápida, y una integración directa con archivos empresariales para una mayor productividad .

Copilot facilita una amplia gama de tareas repetitivas y cotidianas, como redactar informes precisos, resumir y simplificar correos electrónicos, analizar grandes volúmenes de datos y preparar presentaciones claras y efectivas .

Los Componentes Fundamentales de Copilot a Nivel Empresarial

El funcionamiento eficaz de Microsoft Copilot se basa en tres componentes clave:

LLMs (Large Language Models): Estos modelos extensivos de lenguaje son la base que permite a la inteligencia artificial comprender y responder preguntas con precisión .
Graph: Constituye el sistema de seguridad de Copilot. Permite autenticar usuarios y restringe el acceso a la información exclusivamente a lo permitido para cada usuario dentro de una organización . Graph asegura el acceso protegido a la información, limita la interacción de Copilot únicamente con documentos autorizados para cada persona y protege la información empresarial manteniéndola dentro de la compañía . La herramienta Graph Explorer, que emplea credenciales corporativas, permite profundizar en el conocimiento sobre Graph .
NLP (Procesamiento de Lenguaje Natural): Esta capacidad es lo que permite a Copilot entender y responder en el idioma que se le pregunte, facilitando una interacción fluida y natural .

Seguridad y Privacidad: Un Pilar Fundamental

La privacidad y la seguridad son prioridades clave para Microsoft 365 Copilot . Microsoft asegura que tus datos corporativos siempre permanecerán seguros, ya que no utiliza datos personales para entrenar modelos de inteligencia artificial y mantiene la información dentro de rigurosos límites de seguridad y cumplimiento normativo . Si actualmente utilizas Microsoft 365, la privacidad ya forma parte del acuerdo establecido . Un aspecto crucial es que todos los datos procesados por Copilot se mantienen exclusivamente dentro del entorno empresarial, sin riesgo de ser copiados o utilizados indebidamente .

Inversión y Beneficios Reales: Transformando la Eficiencia Operacional

La inversión en Microsoft 365 Copilot, con un costo aproximado de 30 dólares mensuales por usuario, puede traducirse en ahorros significativos para las empresas . Reduce la necesidad de grandes equipos dedicados al análisis, escritura, respuesta y presentación . Empresas como BOW ya reportan ahorros millonarios gracias al impacto directo en su eficiencia operacional . Copilot no solo optimiza tareas, sino que también transforma tu enfoque laboral, permitiéndote ser más rápido y enfocado, facilitando decisiones estratégicas al eliminar tareas operativas y potenciando tu rol profesional al convertir la tecnología en un verdadero socio laboral .

Puntos de Acceso y Funcionalidades en Aplicaciones Microsoft 365

Copilot se integra de manera fluida y práctica en múltiples puntos de tu equipo corporativo .

Acceso General: La Barra de Tareas

El punto de acceso más común es el pequeño ícono identificado con M365 Copilot en la barra de tareas de Windows, que despliega una interfaz clara e intuitiva . Desde aquí, puedes acceder rápidamente a páginas previamente creadas, abrir documentos específicos, visitar organizaciones vinculadas directamente y realizar búsquedas relacionadas con actividades o calendario personal .

Copilot en Excel: Análisis y Visualización de Datos con IA

En Excel, el ícono de Copilot aparece en las herramientas superiores al abrir una hoja nueva . Al activarlo, puedes iniciar conversaciones en su ventana de chat, cuya interacción influye en tiempo real sobre las celdas y el contenido de tu documento . El ícono permanece disponible para su uso constante .

Las funciones clave de Copilot en Excel incluyen:

Generar resúmenes instantáneos .
Crear gráficos interactivos de manera automatizada .
Realizar preguntas específicas con lenguaje natural para obtener resultados precisos .

Ejemplos de `prompts` en Excel:
*   "Solicita un resumen general del conjunto de datos." 
*   "Pide gráficos específicos: barras, líneas, etc." 
*   "Consultas por períodos específicos, por ejemplo, ventas durante el verano."

Si la respuesta o el gráfico no son los esperados, puedes agregar la información a una nueva hoja para verificar el formato o reformular el prompt . Además, Copilot no solo genera gráficos, sino que también ofrece fórmulas automáticas ajustadas a tu consulta, simplificando la extracción y presentación organizada de resultados .

Copilot en Word: Resúmenes y Traducciones Automáticas

En Word, el ícono de Copilot aparece en la esquina superior derecha al abrir un documento nuevo, con accesos rápidos para extraer documentos guardados en la nube privada o editar directamente . Copilot ofrece tres funciones esenciales para la productividad:

Insights o puntos clave: Permite identificar rápidamente las ideas más importantes .
Generación automática de resumen: Puedes solicitar un resumen breve y pertinente, ahorrando tiempo de lectura extensa . Para generarlo, seleccionas la categoría de información y presionas Enter .
Traducción integrada al español: Al generar un prompt, tienes la opción de traducir el resumen al español con un simple comando como "tradúcelo español" .

Una ventaja esencial son las referencias precisas que Copilot adjunta a los resúmenes, permitiéndote verificar cada dato en el documento original . También puedes insertar estos resúmenes directamente en tus documentos .

Copilot en PowerPoint: Creación Automática de Presentaciones

PowerPoint integra Copilot en cada diapositiva y en la barra superior de actividades . Ambas vías habilitan la ventana de chat para personalizar y facilitar el desarrollo de tus presentaciones .

El proceso para generar una presentación automática es sencillo:

Abre un proyecto nuevo en blanco en PowerPoint .
Desde la ventana de chat de Copilot, selecciona "Crea una presentación a partir de un documento" .
Selecciona el archivo de referencia (por ejemplo, un documento de Word) .
Copilot creará automáticamente las diapositivas .

Si el contenido está en inglés y lo necesitas en español, puedes usar la instrucción "Traduce mis slides al español" en el chat de Copilot . La facilidad y rapidez de Copilot en PowerPoint se potencian con la familiaridad del usuario con la plataforma .

Copilot en OneNote: Creación de Temarios y Guiones

OneNote, combinado con Copilot, facilita la creación, estructuración y administración de contenidos educativos, siendo eficaz en la planificación de cursos, generación rápida de guiones y estructuración de temarios .

Para elaborar guiones breves:

Selecciona la sección pertinente en OneNote .
Escribe un prompt claro y conciso, como: "Crea un guión de no más de 100 palabras que explique la diferencia entre Git y GitHub y sirva como introducción al curso."
Copilot genera la descripción al instante .

Para estructurar temarios de cursos:

Activa Copilot desde la barra de herramientas .
Escoge el prompt necesario: "Prepara un temario para hablar de un curso introductorio de Git y GitHub con máximo 25 clases."
Se genera automáticamente un listado base de temas relevantes, que facilita discusiones y es fácilmente convertible en una lista de tareas .

Convertir un temario en lista de tareas optimiza la coordinación y el seguimiento del trabajo, favoreciendo un seguimiento claro del proceso, comunicación fluida con equipos y gestión eficiente del avance .

ACOPILOT en Outlook: Gestión Eficiente de Correos

El correo electrónico puede ser complejo de manejar, pero ACOPILOT en Outlook permite gestionar eficientemente largas cadenas . Ubicado directamente en la interfaz, puede generar un breve resumen de conversaciones extensas en segundos, especialmente útil cuando un hilo crece rápidamente . ACOPILOT analiza el contenido y brinda puntos clave que resumen el intercambio .

Además, con ACOPILOT, puedes redactar respuestas rápidas y claras sin mucho esfuerzo: escribes una respuesta corta, y ACOPILOT la reformula automáticamente con un tono diplomático y adecuado, ahorrando tiempo en la lectura y redacción manual de correos extensos .

Automatización de Análisis Financieros con Copilot

La automatización del análisis financiero con Copilot mejora la eficiencia en el procesamiento de información económica crucial . Mediante prompts sencillos, puedes obtener rápidamente una comparativa actualizada de resultados fiscales y precios accionarios de compañías tecnológicas importantes .

Un `prompt` específico puede dar un desglose claro que incluye:
*   Precios actuales de acciones .
*   Resultados fiscales recientes de compañías tecnológicas líderes .
*   Breves resúmenes explicativos relacionados con estos datos .

También es posible solicitar visualizaciones gráficas como "Genera una gráfica donde se muestre el comportamiento de sus acciones" para interpretar tendencias financieras, y perfeccionar el prompt para otros formatos como gráficos de columnas . Copilot facilita el manejo integral de la información financiera, permitiendo crear documentos automatizados de Word en OneDrive, generar enlaces para compartir y automatizar el envío de correos electrónicos a través de Outlook, agilizando la comunicación y colaboración .

Visual Creator en Microsoft 365 Copilot: Contenido Multimedia Profesional

Microsoft 365 Copilot integra Visual Creator, una herramienta poderosa para elaborar rápidamente contenido multimedia como videos e imágenes . Permite crear videos específicos (ej. sobre lenguajes de programación para IA) e imágenes libres de derechos .

El proceso de creación es sencillo:

Escribe un prompt claro y detallado en español .
Selecciona el tipo de contenido (video o imagen) .
Especifica detalles relevantes (duración, idioma, voz para narración) .
Visual Creator interpreta tu lenguaje y produce resultados coherentes .

Puedes modificar tu producción fácilmente con una interfaz manual para gestionar videos, música de fondo, editar textos y audios, y ajustar elementos multimedia en tiempo real desde la línea de tiempo . También puedes refactorizar tu prompt inicial para optimizar resultados . Las opciones para compartir incluyen guardar en tu galería de documentos corporativos o exportar para público externo .

Optimizando tus Interacciones con Copilot: La Clave de los Prompts

Dominar la habilidad de escribir prompts claros y efectivos es clave para aprovechar al máximo Copilot, ya que la calidad de los resultados depende notablemente de cómo formulas tus consultas . La práctica mejora la precisión .

Tipos de Prompts y Galería de Prompts

Microsoft Copilot permite consultas recurrentes y útiles como visualizar tu lista de actividades semanales, saber cuándo fue tu última reunión con una persona específica, o obtener información de contacto de compañeros . Cada solicitud genera resultados prácticos, como enlaces a detalles de juntas o perfiles corporativos . Copilot facilita la organización de prompts frecuentemente utilizados: puedes guardar cualquier prompt asignándole un nombre personalizado . La opción "Prompt Gallery" ofrece tres categorías: Microsoft Prompts (sugerencias directas), tus propios prompts guardados y prompts compartidos por compañeros o a nivel organizacional, dependiendo de los permisos . Usar prompts guardados simplifica enormemente tareas repetitivas .

Prompt Coach: Perfeccionando tus Instrucciones

Dado que Copilot no incluye un manual específico, el aprendizaje de prompts puede ser un reto . Para esto, Copilot integra Prompt Coach, una funcionalidad diseñada para ayudarte a perfeccionar tu interacción con la IA mediante prompts más eficientes . El Prompt Coach se encuentra en la sección "Agentes" de Copilot y brinda guía efectiva . Al ingresar tu prompt inicial, recibirás retroalimentación que incluye el prompt original, una versión mejorada con cambios y detalles sobre las modificaciones y sus razones . Esta herramienta puede unificar tareas que requerían varios prompts individuales en un solo mensaje eficiente (ej. un resumen financiero, un documento en Word y un correo electrónico) . Para aprovecharla al máximo, copia el prompt recomendado, úsalo en el chat y guárdalo en tu galería para reutilizarlo .

Agentes Especializados: Ampliando las Funciones de Copilot

Microsoft 365 Copilot ofrece una funcionalidad adicional que amplía considerablemente su potencial: los agentes especializados . Estos actúan como pequeñas aplicaciones descargables desde un mercado interno, similares a las tiendas de apps móviles . Al instalarlos, puedes optimizar tareas o funciones específicas, simplificando procesos tediosos . La disponibilidad de agentes puede variar según los permisos de los administradores de tu suscripción .

Un ejemplo notable es el agente Bookings, que simplifica significativamente el proceso de organizar reuniones . Permite configurar agendas o reuniones con plantillas preestablecidas (para juntas de 15 o 30 minutos) o crear tus propias plantillas personalizadas para reuniones recurrentes . Una vez integradas, Copilot puede usarlas directamente para concretar reuniones específicas sin necesidad de prompts detallados . La incorporación de agentes especializados como Bookings te libera de comandos complejos, promueve acciones más rápidas y focalizadas, y asegura respuestas más eficientes mediante prompts simples, promoviendo un entorno de trabajo ágil y especializado .

Conclusión

Microsoft 365 Copilot representa una evolución significativa en la forma en que interactuamos con la tecnología y gestionamos nuestras responsabilidades laborales. Al integrarse profundamente en las aplicaciones cotidianas de Microsoft, desde la redacción de documentos en Word y el análisis de datos en Excel hasta la gestión de correos en Outlook y la creación de presentaciones en PowerPoint, Copilot se establece como un asistente de IA indispensable . Su capacidad para automatizar tareas repetitivas, como la generación de resúmenes o la creación de gráficos interactivos, no solo ahorra tiempo valioso sino que también permite a los profesionales redirigir su energía hacia el pensamiento estratégico y la toma de decisiones críticas .

La seguridad y la privacidad de los datos corporativos son pilares inquebrantables, asegurando que la información se mantenga dentro del entorno empresarial y no se utilice para entrenar modelos de IA con datos personales . Además, la inversión en Copilot se traduce en ahorros millonarios para las empresas, mejorando la eficiencia operacional .

La potencia de Copilot reside también en sus componentes fundamentales: los LLMs para la comprensión del lenguaje, Graph para la seguridad y el control de acceso, y NLP para una interacción natural . Herramientas como Prompt Coach y la galería de prompts empoderan a los usuarios para maximizar la eficacia de sus instrucciones, mientras que los agentes especializados, como Bookings, amplían aún más sus funcionalidades, adaptando Copilot a necesidades específicas y promoviendo un entorno de trabajo más ágil .

En un futuro cercano, la evolución de Copilot probablemente incluirá una mayor especialización de agentes, la integración con nuevas plataformas y una adaptabilidad aún más profunda a los flujos de trabajo personalizados. La investigación futura podría explorar su impacto a largo plazo en la creatividad humana y la redefinición de roles laborales en diversas industrias, consolidando a Copilot no solo como una herramienta, sino como un verdadero socio en el desarrollo profesional y empresarial .

Ver página completa →

Kafka 7: Patrones Avanzados y Anti-Patrones con Kafka

Mauricio ECR
Arquitectura
08 Jun, 2025

Hemos recorrido un camino considerable en nuestra serie sobre Apache Kafka. Desde sus fundamentos y arquitectura interna hasta la interacción con productores y consumidores, las herramientas de proces

Ver página completa

Kafka 7: Patrones Avanzados y Anti-Patrones con Kafka

Mauricio ECR
Arquitectura
08 Jun, 2025

Hemos recorrido un camino considerable en nuestra serie sobre Apache Kafka. Desde sus fundamentos y arquitectura interna hasta la interacción con productores y consumidores, las herramientas de procesamiento de stream y los aspectos críticos de despliegue, seguridad y optimización. Ahora que comprendemos cómo funciona Kafka y cómo operarlo, es momento de elevar la conversación a un nivel más estratégico: cómo diseñar sistemas robustos y resilientes utilizando Kafka y, quizás igual de importante, qué errores comunes debemos evitar.

Kafka, como cualquier tecnología potente, puede ser mal utilizado. Comprender los patrones de diseño que aprovechan sus fortalezas y los anti-patrones que conducen a problemas es crucial para construir arquitecturas basadas en eventos exitosas. Este artículo explorará algunas de las estrategias de diseño más efectivas que los profesionales usan con Kafka y destacará las trampas comunes en las que es fácil caer.

Patrones Avanzados: Aprovechando el Poder de Kafka

Integrar Kafka en arquitecturas de software modernas abre la puerta a patrones de diseño muy potentes que promueven el desacoplamiento, la escalabilidad y la resiliencia.

Event Sourcing + CQRS

Estos dos patrones a menudo van de la mano y encuentran en Kafka un aliado natural:

Event Sourcing: En lugar de almacenar solo el estado actual de una entidad (como una fila en una base de datos tradicional), el Event Sourcing almacena la secuencia completa de eventos que llevaron a ese estado. Cada cambio en la entidad se registra como un evento inmutable. Kafka, con su naturaleza de log de eventos inmutable y persistente, es el almacén ideal para estos "logs de eventos". Almacenar todos los eventos permite reconstruir el estado de la entidad en cualquier punto del tiempo y proporciona una auditoría completa.
CQRS (Command Query Responsibility Segregation): Separa el modelo utilizado para actualizar la información (Command side) del modelo utilizado para leer la información (Query side). Los comandos generan eventos que se escriben en Kafka (Event Sourcing). Estos eventos son luego consumidos y procesados por diferentes proyecciones (listeners) para actualizar modelos de lectura optimizados para consultas específicas (ej: una base de datos relacional para reportes, un almacén de documentos para búsqueda). Esta separación permite escalar y optimizar cada lado de forma independiente y responder a diferentes necesidades de lectura y escritura.

Saga Pattern para Microservicios

En una arquitectura de microservicios, las transacciones de negocio a menudo se extienden a través de múltiples servicios. A diferencia de las transacciones ACID en una base de datos monolítica, las transacciones distribuidas en microservicios son complejas y a menudo implican compensaciones. El Saga Pattern es una forma de gestionar la consistencia de datos en transacciones distribuidas.

Una Saga es una secuencia de transacciones locales, donde cada transacción local actualiza la base de datos de un servicio participante y publica un evento. Si una transacción local falla, la Saga ejecuta transacciones de compensación para deshacer los cambios realizados por las transacciones locales anteriores. Kafka sirve como el bus de eventos para coordinar la Saga, publicando eventos de éxito o fallo de las transacciones locales para que otros servicios puedan reaccionar y avanzar o compensar la Saga.

Dead Letter Queues (DLQ) para Manejo de Errores

En sistemas distribuidos, los errores son inevitables. Un consumidor de Kafka puede fallar al procesar un mensaje debido a datos corruptos, un error de lógica en la aplicación, o una dependencia externa no disponible. Si un consumidor simplemente reintenta el mismo mensaje fallido en un bucle, puede detener el procesamiento de la partición (conocido como "poison pill").

Las Dead Letter Queues (DLQ) son un patrón para manejar estos mensajes fallidos de forma elegante. Cuando un consumidor encuentra un mensaje que no puede procesar después de varios reintentos, en lugar de bloquearse, publica ese mensaje (quizás con información adicional sobre el error) en un Topic dedicado a mensajes fallidos: el DLQ. Esto permite:

El consumidor principal puede continuar procesando otros mensajes de la partición.
Los mensajes en el DLQ pueden ser inspeccionados manualmente, depurados y, si es posible, reprocesados o descartados.

Anti-Patrones Comunes: Errores a Evitar

Aunque Kafka es muy potente, usarlo incorrectamente puede llevar a problemas de rendimiento, complejidad operativa y fiabilidad. Reconocer y evitar estos anti-patrones es tan importante como aplicar los patrones correctos.

Too Many Partitions (Demasiadas Particiones)

Un error común, especialmente para los recién llegados, es crear un número excesivo de particiones para un Topic, pensando que "más es mejor" para el paralelismo. Sin embargo, un número excesivo de particiones puede:

Aumentar la Latencia: Más particiones significan más ficheros de log a gestionar por broker, más conexiones TCP, más metadatos para el clúster (ZooKeeper/KRaft), y un mayor impacto durante los rebalanceos.
Aumentar el Consumo de Recursos: Cada partición tiene un coste de memoria y CPU asociado en los brokers.
Sobrecarga de Rebalanceo: Un Consumer Group con un gran número de particiones experimentará rebalanceos más lentos y más intensivos en recursos cuando los consumidores se unan o salgan.
Limitar el Paralelismo del Consumidor: Aunque las particiones permiten paralelismo, un consumidor solo puede leer de una partición a la vez. Si el procesamiento de un solo mensaje es muy rápido, puede que no necesites tantas particiones para saturar a tus consumidores.

// Ejemplo de creación de un topic con un número excesivo de particiones (anti-patrón)
Properties props = new Properties();
props.put("bootstrap.servers", "localhost:9092");
AdminClient adminClient = AdminClient.create(props);

// ¡NO HACER ESTO EN PRODUCCIÓN SIN UNA RAZÓN MUY SÓLIDA!
NewTopic newTopic = new NewTopic("mi-topic-con-demasiadas-particiones", 1000, (short) 3);
adminClient.createTopics(Collections.singleton(newTopic));

Regla General: Empieza con un número de particiones que se ajuste a tus requisitos de paralelismo iniciales y a la capacidad de tus brokers (ej: 10-20 particiones por broker). Puedes añadir más particiones más tarde (aunque no eliminarlas fácilmente).

Ignorar el Rebalanceo

El rebalanceo de Consumer Groups es una parte normal del funcionamiento de Kafka, pero ignorar sus implicaciones es un anti-patrón. Un rebalanceo ocurre cuando:

Un consumidor se une o sale del grupo.
Un consumidor deja de enviar "heartbeats" (latidos) al broker (por ejemplo, debido a un fallo o una pausa GC prolongada).
Se añade una nueva partición a un Topic al que el grupo está suscrito.

Durante un rebalanceo, los consumidores dejan de procesar mensajes mientras se reasignan las particiones. Un rebalanceo frecuente o de larga duración puede:

Impactar la Latencia: Introducir pausas en el procesamiento de mensajes.
Aumentar la Complejidad Operacional: Dificultar la depuración de problemas.
Causar Problemas de Disponibilidad: Si el rebalanceo es inestable, los consumidores pueden estar constantemente en proceso de reasignación.

// Configuración de un consumidor de Kafka para manejar el rebalanceo
Properties props = new Properties();
props.put("bootstrap.servers", "localhost:9092");
props.put("group.id", "mi-grupo-consumidor");
props.put("enable.auto.commit", "false"); // Mejor control del commit de offsets
props.put("session.timeout.ms", "10000"); // Aumentar si las pausas GC son un problema
props.put("heartbeat.interval.ms", "3000"); // Debe ser menor que session.timeout.ms
// props.put("group.instance.id", "instancia-unica-1"); // Para static membership

KafkaConsumer<String, String> consumer = new KafkaConsumer<>(props);
consumer.subscribe(Collections.singletonList("mi-topic"));

// Implementar un ConsumerRebalanceListener para manejar el rebalanceo
consumer.subscribe(Collections.singletonList("my-topic"), new ConsumerRebalanceListener() {
    @Override
    public void onPartitionsRevoked(Collection<TopicPartition> partitions) {
        // Commitear offsets antes de que las particiones sean revocadas
        consumer.commitSync();
    }

    @Override
    public void onPartitionsAssigned(Collection<TopicPartition> partitions) {
        // Opcional: buscar un offset específico si es necesario
    }
});

Solución: Monitoriza la frecuencia y duración de los rebalanceos. Ajusta el session.timeout.ms y heartbeat.interval.ms de los consumidores. Considera usar Static Membership (group.instance.id) para consumidores que se reinician con frecuencia, como vimos en el Artículo 3. Asegúrate de que los consumidores commiteen offsets de forma manual y atómica para evitar duplicados masivos o pérdida de datos durante los rebalanceos.

No Planear la Retención de Datos

Kafka es un log de eventos persistente, no una base de datos eterna por defecto. Un anti-patrón es no planificar adecuadamente la política de retención de datos en los Topics (log.retention.ms o log.retention.bytes).

Si no se configura la retención o se establece a un valor muy alto (ej: infinito), los datos se acumularán indefinidamente en los brokers, lo que puede llevar a:

Agotamiento de Espacio en Disco: Una causa común de fallos en el clúster.
Impacto en el Rendimiento: Más datos en disco pueden ralentizar operaciones como la recuperación de brokers.
Aumento de Costos: Especialmente en la nube.

# Ejemplo de configuración de retención en un Topic (Kafka CLI)
# Retención de 7 días (604800000 ms)
kafka-topics.sh --bootstrap-server localhost:9092 \
                --alter --topic mi-topic \
                --config retention.ms=604800000

# Retención de 10 GB
kafka-topics.sh --bootstrap-server localhost:9092 \
                --alter --topic mi-topic \
                --config retention.bytes=10737418240

# Para Topics compactados (log.cleanup.policy=compact)
kafka-topics.sh --bootstrap-server localhost:9092 \
                --alter --topic mi-topic-compactado \
                --config cleanup.policy=compact

Solución: Entiende los requisitos de tu aplicación para la retención de datos. La mayoría de los Topics pueden tener una retención corta (días o semanas). Si necesitas datos históricos a largo plazo, considera transferirlos a un almacén de datos más adecuado (data lake, data warehouse) utilizando Kafka Connect o Kafka Streams. Para Topics compactados (donde solo se mantiene el último valor por clave), asegúrate de que tus claves de mensajes sean apropiadas para la compactación.

Conclusión

Hemos llegado al final de nuestra exploración de los patrones avanzados y anti-patrones comunes en el uso de Apache Kafka. Entender cómo implementar patrones como Event Sourcing, CQRS y Saga Pattern con Kafka te permite construir sistemas distribuidos mucho más potentes y resilientes. Al mismo tiempo, reconocer y evitar errores como el exceso de particiones, la negligencia del rebalanceo o la falta de planificación de la retención, te ayudará a mantener un clúster de Kafka saludable y eficiente.

La clave para el éxito con Kafka no solo reside en comprender sus componentes, sino en aplicarlos con sabiduría de diseño. Con estos patrones y anti-patrones en mente, estás mejor equipado para tomar decisiones arquitectónicas sólidas y evitar escollos comunes. En nuestro artículo final, miraremos hacia el horizonte: las tendencias y el futuro de Kafka, incluyendo el impacto de KRaft, la integración con otras tecnologías de procesamiento de stream y su papel emergente en el edge computing.

Ver página completa →

Spring WebFlux 4: Comunicación Avanzada, Pruebas y Producción

Mauricio ECR
Arquitectura
31 May, 2025

La serie Spring WebFlux nos ha llevado a través de un viaje fascinante por el mundo de la programación reactiva, desde sus fundamentos y el poder de Project Reactor hasta la construcción de arquit

Ver página completa

Spring WebFlux 4: Comunicación Avanzada, Pruebas y Producción

Mauricio ECR
Arquitectura
31 May, 2025

La serie Spring WebFlux nos ha llevado a través de un viaje fascinante por el mundo de la programación reactiva, desde sus fundamentos y el poder de Project Reactor hasta la construcción de arquitecturas altamente concurrentes y la gestión de la comunicación con servicios externos y bases de datos. En esta cuarta parte, profundizaremos en aspectos más avanzados y críticos para el desarrollo y despliegue de aplicaciones WebFlux robustas y eficientes. Exploraremos desde la comunicación en tiempo real con Server-Sent Events y WebSockets, hasta la crucial gestión de la contrapresión, el contexto reactivo, las estrategias de testing y, por supuesto, la seguridad y las buenas prácticas en producción.

1. Server-Sent Events (SSE): Flujos de Eventos Unidireccionales

Los Server-Sent Events (SSE) son una tecnología web que permite a un servidor enviar actualizaciones automáticamente a un cliente a través de una conexión HTTP persistente y unidireccional. A diferencia de los WebSockets, que son bidireccionales y más complejos, los SSE están diseñados específicamente para escenarios donde el cliente solo necesita recibir datos del servidor. Piensa en ellos como un flujo continuo de noticias, actualizaciones de cotizaciones bursátiles o notificaciones en tiempo real.

¿Cómo funcionan los SSE?

El cliente establece una conexión HTTP normal con el servidor. Sin embargo, en lugar de cerrar la conexión después de enviar la respuesta inicial, el servidor la mantiene abierta y envía datos de forma continua. Cada "evento" se envía como un bloque de texto formateado de una manera específica, seguido de un salto de línea. El navegador o cliente (usando la API EventSource de JavaScript) interpreta estos bloques como eventos individuales.

SSE con Spring WebFlux

En Spring WebFlux, implementar SSE es sorprendentemente sencillo gracias a la naturaleza reactiva de Flux. Dado que un Flux puede emitir 0 a N elementos de forma asíncrona, es la elección natural para representar un flujo de eventos.

Para enviar eventos, simplemente necesitas devolver un Flux desde tu controlador. Spring WebFlux se encargará automáticamente de configurar los encabezados HTTP (Content-Type: text/event-stream) y formatear los datos para que el cliente los reciba como SSE.

import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Flux;

import java.time.Duration;
import java.time.LocalDateTime;

@RestController
public class SseController {

    @GetMapping(value = "/eventos", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> getEvents() {
        return Flux.interval(Duration.ofSeconds(1)) // Emite un elemento cada segundo
                   .map(sequence -> "Evento #" + sequence + " a las " + LocalDateTime.now());
    }

    @GetMapping(value = "/data-stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<MyData> streamMyData() {
        return Flux.interval(Duration.ofSeconds(2))
                   .map(sequence -> new MyData("Item " + sequence, Math.random() * 100))
                   .take(5); // Limita el número de elementos
    }
}

En este ejemplo:

getEvents() envía una cadena de texto cada segundo.
streamMyData() envía objetos MyData (que se serializarán a JSON automáticamente) cada dos segundos, limitando la emisión a 5 elementos.

Del lado del cliente (JavaScript):

const eventSource = new EventSource('/eventos');

eventSource.onmessage = function(event) {
    console.log("Mensaje recibido:", event.data);
};

eventSource.onerror = function(error) {
    console.error("Error en el flujo de eventos:", error);
    eventSource.close();
};

// Si el servidor envía eventos con un 'event' type específico:
// eventSource.addEventListener('nombreDeEvento', function(event) {
//     console.log("Evento con nombre específico:", event.data);
// });

Los SSE son ideales para dashboards en tiempo real, feeds de actividad o cualquier escenario donde se necesiten actualizaciones push del servidor sin la complejidad de una conexión bidireccional completa.

2. Backpressure: Gestionando el Flujo de Datos

El concepto de backpressure (contrapresión) es fundamental en la programación reactiva y, en particular, en Project Reactor y Spring WebFlux. Se refiere a la capacidad de un suscriptor (consumidor) de señalar a un publicador (productor) qué tan rápido o cuántos elementos puede procesar. En un flujo reactivo, si el productor es mucho más rápido que el consumidor, los datos se acumularán en el buffer del consumidor, lo que puede llevar a problemas de memoria o a la caída del sistema. La contrapresión resuelve esto permitiendo que el consumidor "tire" de los datos solo cuando está listo para manejarlos.

¿Por qué es crucial la contrapresión?

Imagina un río (el publicador) que fluye muy rápido hacia un balde (el suscriptor) que solo puede contener una pequeña cantidad de agua a la vez. Sin contrapresión, el balde se desbordaría rápidamente. Con contrapresión, el balde puede indicarle al río que disminuya el caudal o que le envíe agua solo cuando haya espacio.

En el contexto de Spring WebFlux, la contrapresión es vital para la estabilidad y eficiencia del sistema. Evita que un servicio backend sobrecargue a un cliente más lento (como un navegador o una API externa con límites de tasa) o que una base de datos reactiva inunde el servicio con resultados que no puede procesar a tiempo.

Implementación en Reactor

Project Reactor implementa la contrapresión según las especificaciones de Reactive Streams. Esto significa que los operadores de Mono y Flux manejan la contrapresión de forma nativa. Cuando un Subscriber se suscribe a un Publisher, lo primero que hace es solicitar un número inicial de elementos. Luego, a medida que procesa esos elementos, puede solicitar más (request(n)).

import reactor.core.publisher.Flux;
import org.reactivestreams.Subscription;
import org.reactivestreams.Subscriber;

public class BackpressureExample {

    public static void main(String[] args) {
        Flux.range(1, 100) // Publicador que emite 100 números
            .subscribe(new Subscriber<Integer>() {
                private Subscription s;
                private int count = 0;

                @Override
                public void onSubscribe(Subscription s) {
                    this.s = s;
                    System.out.println("Suscrito. Solicitando 2 elementos.");
                    s.request(2); // Solicita inicialmente 2 elementos
                }

                @Override
                public void onNext(Integer integer) {
                    System.out.println("Procesando: " + integer);
                    count++;
                    if (count % 2 == 0) { // Después de procesar 2 elementos, solicita 2 más
                        System.out.println("Procesados 2. Solicitando 2 más.");
                        s.request(2);
                    }
                }

                @Override
                public void onError(Throwable t) {
                    System.err.println("Error: " + t);
                }

                @Override
                public void onComplete() {
                    System.out.println("Completado.");
                }
            });
    }
}

En este ejemplo simplificado, el Subscriber controla la velocidad de emisión al solicitar solo dos elementos a la vez. Este mecanismo es transparente en la mayoría de los casos cuando usas operadores de Reactor, pero es crucial entender que está ocurriendo "bajo el capó" para un comportamiento predecible y robusto.

3. Contexto Reactivo: Compartiendo Información

En la programación tradicional, ThreadLocal se utiliza comúnmente para compartir información a través de diferentes métodos en el mismo hilo de ejecución, como el contexto de seguridad o un ID de correlación para logging. Sin embargo, en un entorno reactivo y no bloqueante como Spring WebFlux, donde las operaciones pueden cambiar de hilo de forma asíncrona, ThreadLocal ya no es una opción viable porque la información se perdería entre los cambios de hilo.

Aquí es donde entra el Contexto Reactivo (Context) de Project Reactor. El Context es una característica que permite adjuntar datos a un flujo reactivo, haciéndolos disponibles para cualquier operador o suscriptor a lo largo de la cadena, independientemente de qué hilo esté ejecutando la operación.

¿Cómo funciona el Contexto Reactivo?

Cada flujo Mono o Flux tiene asociado un Context. Este Context es una estructura de datos inmutable (similar a un Map) que se propaga a lo largo de la cadena de operadores. Cuando un operador necesita acceder a información del contexto, puede hacerlo a través de métodos como contextWrite().

import reactor.core.publisher.Mono;
import reactor.core.publisher.Flux;
import reactor.util.context.Context;

public class ReactiveContextExample {

    public static void main(String[] args) {
        String correlationId = "corr-123";

        Mono<String> dataMono = Mono.just("Hello")
                .doOnNext(s -> {
                    // Acceder al contexto para obtener el correlationId
                    Mono.deferContextual(ctx -> {
                        String id = ctx.get("correlationId");
                        System.out.println("doOnNext: Data = " + s + ", Correlation ID from Context = " + id);
                        return Mono.empty();
                    }).subscribe(); // Suscribirse para activar el deferContextual
                })
                .contextWrite(Context.of("correlationId", correlationId)); // Escribir en el contexto

        dataMono.subscribe(
                data -> System.out.println("Subscriber: Data = " + data),
                error -> System.err.println("Subscriber Error: " + error),
                () -> System.out.println("Subscriber: Completed")
        );

        System.out.println("\n--- Otro ejemplo con Flux y múltiples valores ---");

        Flux.just("Item A", "Item B")
                .contextWrite(Context.of("traceId", "trace-xyz")) // Escribir en el contexto
                .flatMap(item ->
                        Mono.deferContextual(ctx -> {
                            String traceId = ctx.get("traceId");
                            return Mono.just("Procesando " + item + " con Trace ID: " + traceId);
                        })
                )
                .subscribe(
                        result -> System.out.println("Subscriber: " + result),
                        error -> System.err.println("Subscriber Error: " + error)
                );
    }
}

Aplicaciones Comunes del Contexto Reactivo

Propagación de IDs de Correlación/Traza: Esencial para el logging distribuido y la observabilidad. Puedes insertar un ID de correlación al inicio del flujo y que esté disponible en cada operador y en la capa de persistencia.
Contexto de Seguridad: Información del usuario autenticado, roles, permisos.
Parámetros de Configuración Dinámicos: Valores que pueden variar por solicitud pero que no son parte de la carga útil principal.
Datos Transaccionales: Si bien Spring Data R2DBC maneja las transacciones reactivas, el contexto podría usarse para almacenar metadatos relacionados con la transacción.

El Context proporciona una forma segura y reactiva de pasar información a través de los límites de los hilos, manteniendo la integridad del flujo de datos.

4. Testing Reactivo: Garantizando la Robustez

Probar aplicaciones reactivas requiere un enfoque ligeramente diferente al de las aplicaciones síncronas debido a la naturaleza asíncrona y no bloqueante de los flujos. Spring WebFlux y Project Reactor ofrecen herramientas poderosas para facilitar este proceso, asegurando que tus flujos de datos se comporten como esperas.

TestUtils de Reactor: StepVerifier

La herramienta más importante para probar flujos Mono y Flux es StepVerifier de Project Reactor. Permite probar secuencias reactivas de manera determinista, verificando los valores emitidos, los errores y la finalización, e incluso simulando el tiempo para probar operadores basados en tiempo.

import org.junit.jupiter.api.Test;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
import reactor.test.StepVerifier;
import java.time.Duration;

class ReactiveTestingExample {

    // Prueba de un Mono simple
    @Test
    void testMono() {
        Mono<String> mono = Mono.just("Hello Reactive!");

        StepVerifier.create(mono)
                .expectNext("Hello Reactive!") // Espera un valor específico
                .expectComplete()             // Espera que el flujo se complete
                .verify();                    // Inicia la verificación
    }

    // Prueba de un Flux con múltiples elementos
    @Test
    void testFlux() {
        Flux<Integer> flux = Flux.just(1, 2, 3);

        StepVerifier.create(flux)
                .expectNext(1)
                .expectNext(2)
                .expectNext(3)
                .expectComplete()
                .verify();
    }

    // Prueba de un Flux con un error
    @Test
    void testFluxWithError() {
        Flux<String> flux = Flux.just("data1", "data2")
                .concatWith(Mono.error(new RuntimeException("Oops!")));

        StepVerifier.create(flux)
                .expectNext("data1", "data2")
                .expectError(RuntimeException.class) // Espera un error de tipo RuntimeException
                .verify();
    }

    // Prueba de un Flux con retardo (simulando tiempo)
    @Test
    void testFluxWithDelay() {
        Flux<Long> flux = Flux.interval(Duration.ofSeconds(1)).take(3);

        StepVerifier.withVirtualTime(() -> flux) // Usa tiempo virtual para acelerar la prueba
                .expectSubscription()
                .expectNoEvent(Duration.ofSeconds(1)) // No espera eventos por 1 segundo
                .expectNext(0L)
                .thenAwait(Duration.ofSeconds(1)) // Avanza el tiempo virtual 1 segundo
                .expectNext(1L)
                .thenAwait(Duration.ofSeconds(1))
                .expectNext(2L)
                .expectComplete()
                .verify();
    }
}

StepVerifier ofrece una API fluida y encadenable para definir las expectativas sobre el flujo. withVirtualTime() es particularmente útil para probar operadores basados en tiempo sin tener que esperar el tiempo real, acelerando significativamente las pruebas.

Testing de Controladores WebFlux

Para probar controladores WebFlux, puedes usar WebTestClient. Este cliente no bloqueante permite realizar solicitudes HTTP simuladas a tu aplicación WebFlux y verificar las respuestas reactivas. Es ideal para pruebas de integración o de slice.

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.boot.test.mock.mockito.MockBean;
import org.springframework.test.web.reactive.server.WebTestClient;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import static org.mockito.Mockito.when;

@WebFluxTest(MyReactiveController.class) // Especifica el controlador a probar
class MyReactiveControllerTest {

    @Autowired
    private WebTestClient webTestClient; // Cliente para realizar solicitudes HTTP

    @MockBean // Simula dependencias del controlador
    private MyReactiveService myReactiveService;

    @Test
    void testGetHello() {
        when(myReactiveService.getHelloMessage()).thenReturn(Mono.just("Hello from Service!"));

        webTestClient.get().uri("/hello")
                .exchange() // Realiza la solicitud
                .expectStatus().isOk() // Verifica el código de estado HTTP
                .expectBody(String.class).isEqualTo("Hello from Service!"); // Verifica el cuerpo de la respuesta
    }

    @Test
    void testGetAllItems() {
        when(myReactiveService.getAllItems()).thenReturn(Flux.just("Item1", "Item2"));

        webTestClient.get().uri("/items")
                .exchange()
                .expectStatus().isOk()
                .expectBodyList(String.class).containsExactly("Item1", "Item2"); // Verifica una lista de elementos
    }
}

En este ejemplo:

@WebFluxTest configura un contexto de aplicación limitado para probar solo el controlador especificado.
@MockBean permite simular las dependencias del controlador, lo que es crucial para aislar la lógica del controlador.
WebTestClient simula las solicitudes HTTP y permite verificar la respuesta de manera reactiva.

Combinando StepVerifier para la lógica reactiva de negocio y WebTestClient para las interacciones HTTP, puedes construir un conjunto de pruebas robusto para tus aplicaciones Spring WebFlux.

5. Seguridad en Aplicaciones WebFlux (Spring Security Reactivo)

La seguridad es un pilar fundamental en cualquier aplicación, y las aplicaciones reactivas no son la excepción. Spring Security Reactivo proporciona una integración fluida con Spring WebFlux, ofreciendo un modelo de seguridad no bloqueante que se adapta perfectamente al paradigma reactivo. A diferencia del Spring Security tradicional, que se basa en ThreadLocal y filtros de Servlet, la versión reactiva opera con Mono y Flux para mantener la reactividad de principio a fin.

Componentes Clave de Spring Security Reactivo

SecurityWebFilterChain: Reemplaza al FilterChain de Servlets y define la cadena de filtros de seguridad reactivos.
ReactiveUserDetailsService: Para cargar detalles del usuario de forma reactiva.
ReactiveAuthenticationManager: Para autenticar usuarios de forma reactiva.
SecurityContextRepository: Para guardar y cargar el contexto de seguridad (ej. para sesiones o JWT).

Configuración Básica

Para habilitar Spring Security Reactivo, necesitas añadir la dependencia spring-boot-starter-security y configurar tu SecurityWebFilterChain.

// build.gradle
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-webflux'
    implementation 'org.springframework.boot:spring-boot-starter-security'
    // ...
}

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.reactive.EnableWebFluxSecurity;
import org.springframework.security.config.web.server.ServerHttpSecurity;
import org.springframework.security.core.userdetails.MapReactiveUserDetailsService;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.server.SecurityWebFilterChain;

@Configuration
@EnableWebFluxSecurity
public class SecurityConfig {

    @Bean
    public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
        return http
                .csrf(ServerHttpSecurity.CsrfSpec::disable) // Deshabilita CSRF para APIs sin estado
                .authorizeExchange(exchanges -> exchanges
                        .pathMatchers("/public/**").permitAll() // Rutas públicas accesibles sin autenticación
                        .pathMatchers("/admin/**").hasRole("ADMIN") // Rutas solo para ADMIN
                        .anyExchange().authenticated() // Todas las demás rutas requieren autenticación
                )
                .httpBasic(httpBasic -> httpBasic.init(http)) // Habilita autenticación HTTP Basic
                .formLogin(formLogin -> formLogin.disable()) // Deshabilita el formulario de login por defecto
                .build();
    }

    @Bean
    public MapReactiveUserDetailsService userDetailsService(PasswordEncoder passwordEncoder) {
        UserDetails user = User.withUsername("user")
                .password(passwordEncoder.encode("password"))
                .roles("USER")
                .build();
        UserDetails admin = User.withUsername("admin")
                .password(passwordEncoder.encode("adminpass"))
                .roles("ADMIN")
                .build();
        return new MapReactiveUserDetailsService(user, admin);
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

En este ejemplo:

Deshabilitamos CSRF (común para APIs RESTful sin estado).
Definimos reglas de autorización para diferentes rutas (/public es accesible por todos, /admin solo por usuarios con rol ADMIN).
Configuramos HTTP Basic para la autenticación simple.
Se define un MapReactiveUserDetailsService para usuarios en memoria, aunque en un entorno real se usaría una base de datos reactiva.

Accediendo al Usuario Autenticado

En Spring WebFlux, puedes acceder al usuario autenticado usando Mono<Principal> o Mono<Authentication> en tus controladores o servicios.

import org.springframework.security.core.Authentication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Mono;

import java.security.Principal;

@RestController
public class SecuredController {

    @GetMapping("/secure/user-info")
    public Mono<String> getUserInfo(Mono<Principal> principalMono) {
        return principalMono.map(principal -> "Hola, " + principal.getName() + "! Eres un usuario autenticado.");
    }

    @GetMapping("/admin/dashboard")
    public Mono<String> getAdminDashboard(Mono<Authentication> authenticationMono) {
        return authenticationMono.map(auth -> "Bienvenido al Dashboard de Admin, " + auth.getName() + "! Roles: " + auth.getAuthorities());
    }
}

Uso de JWT (JSON Web Tokens)

Para aplicaciones sin estado, el uso de JWT es una práctica común. Spring Security Reactivo facilita la implementación de autenticación basada en JWT. Generalmente, esto implica:

Un endpoint de login que recibe credenciales y devuelve un JWT.
Un filtro de seguridad que intercepta las solicitudes, valida el JWT en el encabezado Authorization y construye un Authentication reactivo.

Puedes crear tu propio ServerWebExchangeMatcher y ServerAuthenticationConverter para procesar el token y autenticar al usuario sin necesidad de sesiones.

Spring Security Reactivo se integra perfectamente con el modelo de programación reactiva, asegurando que tus mecanismos de seguridad no introduzcan bloqueos o cuellos de botella en tus aplicaciones de alto rendimiento.

6. WebSockets con WebFlux: Comunicación Bidireccional en Tiempo Real

Mientras que Server-Sent Events (SSE) son excelentes para la comunicación unidireccional del servidor al cliente, las aplicaciones que requieren comunicación bidireccional en tiempo real, como chats, juegos en línea o herramientas de colaboración, necesitan WebSockets. WebSockets proporcionan un canal de comunicación dúplex completo a través de una única conexión TCP. Spring WebFlux ofrece un soporte robusto y reactivo para WebSockets.

¿Cómo funcionan los WebSockets?

A diferencia de HTTP, que es de corta duración y sin estado, los WebSockets comienzan con un handshake HTTP. Una vez que este handshake es exitoso, la conexión se "actualiza" a un protocolo WebSocket, permaneciendo abierta indefinidamente. Esto permite que tanto el cliente como el servidor envíen mensajes de forma asíncrona en cualquier momento.

WebSockets con Spring WebFlux

Spring WebFlux proporciona una API funcional para manejar WebSockets, aprovechando Flux y Mono para la gestión de mensajes reactivos.

WebSocketHandler: Es la interfaz principal que implementas para manejar la lógica de la conexión WebSocket. El método handle recibe un WebSocketSession que te permite enviar y recibir mensajes.
WebSocketHandlerAdapter y SimpleUrlHandlerMapping: Estos beans son necesarios para mapear las URLs a tus WebSocketHandlers específicos.

Configuración de WebSocket

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.handler.SimpleUrlHandlerMapping;
import org.springframework.web.reactive.socket.WebSocketHandler;
import org.springframework.web.reactive.socket.server.WebSocketService;
import org.springframework.web.reactive.socket.server.support.HandshakeWebSocketService;
import org.springframework.web.reactive.socket.server.support.WebSocketHandlerAdapter;
import org.springframework.web.reactive.socket.server.upgrade.ReactorNettyRequestUpgradeStrategy;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.time.Duration;
import java.util.HashMap;
import java.util.Map;

@Configuration
public class WebSocketConfig {

    @Bean
    public SimpleUrlHandlerMapping webSocketHandlerMapping(WebSocketHandler echoHandler) {
        Map<String, WebSocketHandler> map = new HashMap<>();
        map.put("/echo", echoHandler); // Mapea /echo a nuestro handler
        map.put("/time-stream", new TimeStreamWebSocketHandler()); // Otro handler
        return new SimpleUrlHandlerMapping(map);
    }

    @Bean
    public WebSocketHandlerAdapter handlerAdapter(WebSocketService webSocketService) {
        return new WebSocketHandlerAdapter(webSocketService);
    }

    @Bean
    public WebSocketService webSocketService() {
        // Usa Reactor Netty por defecto, que es el servidor webflux por defecto
        return new HandshakeWebSocketService(new ReactorNettyRequestUpgradeStrategy());
    }

    @Bean
    public WebSocketHandler echoHandler() {
        return session -> session.send(
                session.receive() // Recibe mensajes del cliente
                        .doOnNext(message -> System.out.println("Received: " + message.getPayloadAsText()))
                        .map(message -> session.textMessage("ECHO: " + message.getPayloadAsText())) // Eco de vuelta
        ).and(session.receive()
                .doOnError(throwable -> System.err.println("Error en la conexión WebSocket: " + throwable.getMessage()))
                .then()); // Mantener la conexión abierta hasta que se complete o haya un error
    }
}

Creando un `WebSocketHandler`

Aquí tienes un ejemplo de un WebSocketHandler que envía la hora actual cada segundo:

// En un archivo separado o como inner class
import org.springframework.web.reactive.socket.WebSocketHandler;
import org.springframework.web.reactive.socket.WebSocketMessage;
import org.springframework.web.reactive.socket.WebSocketSession;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.time.Duration;
import java.time.LocalDateTime;

public class TimeStreamWebSocketHandler implements WebSocketHandler {

    @Override
    public Mono<Void> handle(WebSocketSession session) {
        // Envía un mensaje cada segundo al cliente
        Flux<WebSocketMessage> output = Flux.interval(Duration.ofSeconds(1))
                .map(value -> session.textMessage("Current Time: " + LocalDateTime.now()));

        // Mantén la conexión abierta para recibir mensajes (aunque este handler no los procese)
        // La conexión se cierra cuando el Mono<Void> retornado se completa
        return session.send(output)
                .and(session.receive() // Esto es importante para mantener la conexión abierta
                        .doOnNext(message -> System.out.println("Received from client on time stream: " + message.getPayloadAsText()))
                        .then()); // No hacemos nada con los mensajes recibidos aquí, solo los logueamos
    }
}

Cliente JavaScript para WebSockets

const ws = new WebSocket('ws://localhost:8080/echo'); // Para el handler de eco

ws.onopen = function(event) {
    console.log("Conectado al WebSocket!");
    ws.send("Hola desde el cliente!");
};

ws.onmessage = function(event) {
    console.log("Mensaje recibido del servidor:", event.data);
};

ws.onclose = function(event) {
    console.log("Conexión WebSocket cerrada:", event.code, event.reason);
};

ws.onerror = function(error) {
    console.error("Error WebSocket:", error);
};

// Para enviar más mensajes:
// ws.send("Otro mensaje...");

// Para el handler de tiempo:
// const wsTime = new WebSocket('ws://localhost:8080/time-stream');
// wsTime.onmessage = function(event) {
//     console.log("Tiempo recibido:", event.data);
// };

WebSockets con WebFlux te permiten construir aplicaciones de comunicación en tiempo real altamente eficientes, aprovechando la capacidad de Spring para manejar flujos de datos reactivos de forma nativa.

7. Buenas Prácticas en Producción para Aplicaciones WebFlux

Desarrollar una aplicación WebFlux es solo una parte del desafío; desplegarla y mantenerla en producción requiere atención a varias buenas prácticas para asegurar su rendimiento, estabilidad y observabilidad.

1. Monitoreo y Observabilidad

Las aplicaciones reactivas pueden ser más difíciles de depurar sin las herramientas adecuadas debido a la naturaleza asíncrona y la transición de hilos.

Métricas (Micrometer/Prometheus): Spring Boot Actuator, combinado con Micrometer, facilita la exposición de métricas (JVM, WebFlux, Reactor, etc.) que pueden ser recolectadas por sistemas como Prometheus y visualizadas en Grafana. Monitorea la latencia, el rendimiento del Event Loop, el uso de memoria y el número de conexiones activas.
Logging (Structured Logging): Utiliza un sistema de logging que soporte logging estructurado (ej. SLF4J con Logback configurado para JSON) para facilitar el análisis con herramientas como ELK Stack (Elasticsearch, Logstash, Kibana) o Grafana Loki.
APM (Application Performance Monitoring): Herramientas como Dynatrace, New Relic o AppDynamics pueden proporcionar visibilidad profunda en el rendimiento de tu aplicación, incluyendo la trazabilidad de transacciones a través de hilos y servicios.
Tracing (Brave/OpenTelemetry): Implementa Distributed Tracing (ej. con Spring Cloud Sleuth y Zipkin/Jaeger) para seguir el rastro de una solicitud a través de múltiples servicios, especialmente crucial en arquitecturas de microservicios reactivos.

2. Gestión de Recursos

Connection Pooling: Asegúrate de que tus conexiones a bases de datos reactivas (R2DBC, MongoDB reactive drivers) o a otros servicios externos (WebClient) utilicen connection pooling para evitar la sobrecarga y el agotamiento de recursos.
Timeouts: Configura timeouts apropiados en WebClient y en tus servidores para evitar que las solicitudes de larga duración o los servicios externos lentos bloqueen los recursos del Event Loop.
Límites de Conexión: Establece límites de conexión adecuados en tus servidores (Netty, Undertow) para prevenir la sobrecarga.

3. Contrapresión Efectiva

Aunque Reactor maneja la contrapresión de forma nativa, es crucial entender cuándo y cómo se aplica, especialmente al integrar con sistemas que no son reactivos o que no la soportan. Asegúrate de que tus flujos de datos estén diseñados para manejar el backpressure correctamente para evitar la sobrecarga del consumidor.

4. Seguridad

Principio de Mínimo Privilegio: Asegúrate de que tu aplicación solo tenga los permisos necesarios para realizar sus funciones.
Secret Management: No guardes credenciales directamente en el código o en archivos de configuración. Utiliza soluciones de gestión de secretos como HashiCorp Vault, AWS Secrets Manager o Kubernetes Secrets.
Actualizaciones y Parches: Mantén tus dependencias de Spring Boot, Spring Security y Reactor actualizadas para beneficiarte de las últimas correcciones de seguridad.
HTTPS: Siempre utiliza HTTPS en producción para asegurar la comunicación cliente-servidor.

5. Configuración y Despliegue

Externalización de la Configuración: Utiliza Spring Cloud Config Server, o simplemente application.properties/application.yml con perfiles, y variables de entorno para gestionar la configuración de forma externa al artefacto de despliegue.
Contenedores (Docker/Kubernetes): Empaquetar tu aplicación en un contenedor Docker facilita el despliegue, la escalabilidad y la gestión de dependencias en entornos como Kubernetes.
Liveness y Readiness Probes: En Kubernetes, configura Liveness y Readiness Probes para que el orquestador pueda saber cuándo tu aplicación está saludable y lista para recibir tráfico. Spring Boot Actuator proporciona endpoints /actuator/health que son perfectos para esto.
Escalabilidad: Las aplicaciones WebFlux son inherentemente escalables horizontalmente. Asegúrate de que tu infraestructura de despliegue (Kubernetes, balanceadores de carga) pueda escalar tu aplicación de manera eficiente.

6. Pruebas de Carga y Rendimiento

Realiza pruebas de carga exhaustivas para simular escenarios de alto tráfico y verificar cómo se comporta tu aplicación WebFlux bajo presión. Esto te ayudará a identificar cuellos de botella y a optimizar la configuración.

7. Manejo de Errores Robustos

ErrorWebExceptionHandler: Asegúrate de tener un ErrorWebExceptionHandler global bien configurado para manejar excepciones no capturadas y proporcionar respuestas de error consistentes y amigables para el cliente, sin exponer detalles internos.
Circuit Breakers: Implementa patrones de Circuit Breaker (ej. con Resilience4j) al interactuar con servicios externos para evitar cascadas de fallos cuando un servicio dependiente no está disponible o es lento.

Al seguir estas buenas prácticas, puedes asegurar que tus aplicaciones Spring WebFlux no solo sean rápidas y eficientes en desarrollo, sino también robustas, seguras y fáciles de operar en producción.

Conclusión

En esta cuarta entrega de nuestra serie sobre Spring WebFlux, hemos explorado características avanzadas y cruciales que elevan el desarrollo de aplicaciones reactivas. Desde la implementación de Server-Sent Events (SSE) para flujos de datos unidireccionales hasta la robusta comunicación WebSocket para interacciones bidireccionales en tiempo real, hemos visto cómo Spring WebFlux simplifica la construcción de aplicaciones de tiempo real.

Hemos profundizado en la importancia de la contrapresión (backpressure), un mecanismo vital para garantizar la estabilidad del sistema al permitir que los consumidores controlen el flujo de datos. La gestión del contexto reactivo se ha revelado como una solución elegante para compartir información a través de los límites de los hilos en un entorno asíncrono, mientras que las herramientas de testing reactivo como StepVerifier y WebTestClient demuestran ser indispensables para asegurar la corrección de nuestros flujos. Finalmente, abordamos la integración de Spring Security Reactivo para asegurar nuestras aplicaciones de forma no bloqueante y delineamos un conjunto de buenas prácticas para la producción, fundamentales para el monitoreo, la estabilidad y la escalabilidad de nuestras aplicaciones WebFlux.

Esta serie ha cubierto los pilares esenciales para construir aplicaciones reactivas de alto rendimiento con Spring WebFlux. Con una base sólida en fundamentos, arquitectura, comunicación de datos, seguridad, pruebas y consideraciones de producción, estás bien preparado para enfrentar desafíos reales y llevar tus aplicaciones reactivas al siguiente nivel.

Como continuación natural de este camino, te recomendamos explorar algunas áreas complementarias que potenciarán aún más tus habilidades en entornos reactivos:

R2DBC a profundidad: Explora la integración con bases de datos relacionales reactivas, optimización de consultas y rendimiento en entornos de alta demanda.
Spring Cloud Gateway: Descubre cómo usar esta herramienta basada en WebFlux para implementar enrutamiento, seguridad y resiliencia en arquitecturas de microservicios.
Programación Reactiva en el Frontend: Investiga cómo frameworks como React, Angular o Vue pueden conectarse eficientemente con backends WebFlux en escenarios de tiempo real.
WebFlux y GraalVM Native Image: Evalúa las ventajas de empaquetar tus aplicaciones como imágenes nativas para mejorar el rendimiento y reducir el consumo de recursos.
Patrones de resiliencia con WebFlux: Profundiza en técnicas como Circuit Breaker, Retry, Timeout y Rate Limiting mediante el uso de Resilience4j en entornos reactivos.

Explorar estos temas no solo ampliará tu dominio técnico, sino que también te permitirá diseñar soluciones más eficientes, resilientes y adaptadas a los retos actuales del desarrollo moderno. La programación reactiva, bien aplicada, abre la puerta a aplicaciones verdaderamente escalables y sensibles a la demanda del usuario.

Ver página completa →

Spring WebFlux 3: Comunicación, Datos y Errores Reactivos

Mauricio ECR
Arquitectura
24 May, 2025

¡Continuemos nuestro viaje por el fascinante mundo de Spring WebFlux! En la Parte 1, sentamos las bases de la programación reactiva y exploramos Project Reactor, el corazón de WebFlux. En la **Pa

Ver página completa

Spring WebFlux 3: Comunicación, Datos y Errores Reactivos

Mauricio ECR
Arquitectura
24 May, 2025

¡Continuemos nuestro viaje por el fascinante mundo de Spring WebFlux!

En la Parte 1, sentamos las bases de la programación reactiva y exploramos Project Reactor, el corazón de WebFlux. En la Parte 2, nos adentramos en la arquitectura de WebFlux y aprendimos a construir endpoints utilizando tanto anotaciones como el enfoque funcional.

Ahora, en esta Parte 3, nos enfocaremos en cómo las aplicaciones WebFlux interactúan con el mundo exterior: cómo consumen otros servicios de manera reactiva, cómo persisten y recuperan datos en bases de datos reactivas, y, crucialmente, cómo gestionamos los errores que inevitablemente surgen en estos flujos asíncronos.

Comunicación con Servicios Externos (WebClient)

En el ecosistema de microservicios actual, es muy común que nuestras aplicaciones necesiten consumir APIs externas. Spring WebFlux nos proporciona una herramienta poderosa y reactiva para esto: WebClient. Es la contraparte no bloqueante de RestTemplate y la forma recomendada de hacer llamadas HTTP en un contexto reactivo.

WebClient

WebClient es un cliente HTTP no bloqueante que forma parte del módulo spring-webflux. Está diseñado para aprovechar la pila reactiva de principio a fin, lo que significa que no bloqueará hilos mientras espera respuestas de servicios externos, maximizando la eficiencia de tu aplicación WebFlux.

Su API es fluida y declarativa, similar a la forma en que construyes flujos con Mono y Flux.

Configuración Básica:

Puedes configurar WebClient de diversas maneras. La forma más común es inyectarlo como un bean en tu clase, o construir una instancia en línea. Puedes especificar una URL base, encabezados comunes, timeouts, filtros y más.

// Configuración como Bean (ejemplo en una clase @Configuration)
@Configuration
public class WebClientConfig {

    @Bean
    public WebClient externalApiClient(WebClient.Builder webClientBuilder) {
        return webClientBuilder
                .baseUrl("https://api.example.com") // URL base para todas las peticiones
                .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE) // Encabezado por defecto
                .clientConnector(new ReactorClientHttpConnector(
                        HttpClient.create().responseTimeout(Duration.ofSeconds(5)) // Timeout de 5 segundos
                ))
                .build();
    }
}

Consumo de Respuestas Reactivas:

Después de definir la petición (GET, POST, PUT, DELETE, etc.), usas métodos como:

.retrieve(): Inicia la recuperación de la respuesta.
.bodyToMono(Class<T> type): Convierte el cuerpo de la respuesta en un Mono de un objeto de tipo T. Útil cuando esperas una única respuesta (ej., un objeto JSON).
.bodyToFlux(Class<T> type): Convierte el cuerpo de la respuesta en un Flux de objetos de tipo T. Útil para listas o streams de datos (ej., una lista de objetos JSON).
.bodyToMono(ParameterizedTypeReference<T> typeRef) / .bodyToFlux(ParameterizedTypeReference<T> typeRef): Útil para tipos genéricos (ej., List<MyObject>).
.toEntity(Class<T> type) / .toEntityList(Class<T> type) / .toEntityFlux(Class<T> type): Devuelve un Mono<ResponseEntity<T>> o Mono<ResponseEntity<List<T>>> para acceder a la respuesta completa (estado HTTP, cabeceras, cuerpo).

Casos Típicos/Práctica

Llamada GET a un servicio externo y procesar la respuesta reactivamente:

Asumiendo que externalApiClient es un WebClient bean inyectado.

public Mono<MyObject> getObjectById(String id) {
    return externalApiClient.get() // Inicia una petición GET
            .uri("/objects/{id}", id) // Define la URI con PathVariable
            .retrieve() // Recupera la respuesta
            .bodyToMono(MyObject.class); // Convierte el cuerpo a Mono<MyObject>
}

Llamada POST enviando un Mono<?> como body:

public Mono<MyObject> createObject(Mono<MyObject> newObjectMono) {
    return externalApiClient.post() // Inicia una petición POST
            .uri("/objects")
            .body(newObjectMono, MyObject.class) // Envía el Mono<MyObject> como cuerpo
            .retrieve()
            .bodyToMono(MyObject.class); // Espera la respuesta como Mono<MyObject>
}

Manejar múltiples llamadas a servicios externos en paralelo (Mono.zip, Flux.merge, flatMap):

Mono.zip: Combina los resultados de múltiples Monos (o Fluxs que emiten un solo elemento) en un solo Mono que contiene una tupla de sus resultados. Las operaciones se ejecutan en paralelo. Ideal para combinar resultados de diferentes tipos que son necesarios simultáneamente.

public Mono<CombinedData> getCombinedData(String id) {
    Mono<User> userMono = externalApiClient.get().uri("/users/{id}", id).retrieve().bodyToMono(User.class);
    Mono<Order> orderMono = externalApiClient.get().uri("/orders/{id}", id).retrieve().bodyToMono(Order.class);

    return Mono.zip(userMono, orderMono, (user, order) -> {
        // Aquí se combinan los resultados cuando ambos Monos han completado
        return new CombinedData(user, order);
    });
}

Flux.merge: Combina múltiples Publishers (Mono o Flux) en un único Flux, entrelazando sus elementos tan pronto como son emitidos. Las operaciones se ejecutan en paralelo, y el orden de los elementos resultantes no está garantizado.

public Flux<Item> getItemsFromMultipleSources() {
    Flux<Item> source1 = externalApiClient.get().uri("/items/source1").retrieve().bodyToFlux(Item.class);
    Flux<Item> source2 = externalApiClient.get().uri("/items/source2").retrieve().bodyToFlux(Item.class);

    return Flux.merge(source1, source2); // Los ítems de source1 y source2 se entrelazan
}

flatMap: (Ya cubierto en Parte 1, pero clave aquí) Úsalo cuando la transformación de un elemento inicial te lleva a realizar otra operación asíncrona que devuelve un Mono o Flux. Permite encadenar operaciones secuenciales asíncronas.

public Mono<OrderDetail> getOrderDetails(String orderId) {
    return externalApiClient.get().uri("/orders/{id}", orderId).retrieve().bodyToMono(Order.class) // 1. Obtener la orden
            .flatMap(order -> externalApiClient
                                .get()
                                .uri("/products/{id}", order.getProductId()).retrieve().bodyToMono(Product.class) // 2. Obtener el producto de la orden
                    .map(product -> new OrderDetail(order, product))); // 3. Combinar y devolver OrderDetail
}

Manejar errores de un servicio externo llamado con WebClient:

WebClient lanza WebClientResponseException (o subclases como WebClientResponseException.NotFound) si la respuesta HTTP es un error (4xx, 5xx). Puedes usar operadores de manejo de errores de Reactor como onErrorResume o onErrorReturn.

public Mono<MyObject> getObjectByIdHandlingError(String id) {
    return externalApiClient.get()
            .uri("/objects/{id}", id)
            .retrieve()
            .onStatus(HttpStatus.NOT_FOUND::equals, // Si el estado es 404
                      response -> Mono.error(new MyCustomNotFoundException("Object not found: " + id))) // Mapea a una excepción personalizada
            .onStatus(HttpStatus::is5xxServerError, // Si es un error 5xx
                      response -> Mono.error(new RuntimeException("External service error"))) // Mapea a otra excepción
            .bodyToMono(MyObject.class)
            .onErrorResume(MyCustomNotFoundException.class, e -> {
                // Si es MyCustomNotFoundException, devuelve un Mono.empty() o un default
                System.err.println("Handling not found: " + e.getMessage());
                return Mono.empty(); // O Mono.just(new MyObject("Default object"));
            })
            .onErrorReturn(RuntimeException.class, new MyObject("Error occurred, returning default")); // Si es RuntimeException, devuelve un objeto por defecto
}

Manejo de Datos Reactivos

Una aplicación reactiva es más eficiente si toda su pila es no bloqueante, y esto incluye la capa de persistencia de datos. Acceder a bases de datos de forma reactiva es crucial para evitar cuellos de botella por I/O bloqueante.

Integración de WebFlux con Bases de Datos Reactivas

Para bases de datos relacionales, la API estándar para acceso reactivo es R2DBC (Reactive Relational Database Connectivity). Es el equivalente reactivo de JDBC, pero diseñado desde cero para ser no bloqueante y asíncrono. Spring Data ha adoptado R2DBC, proporcionando integraciones para bases de datos como PostgreSQL, H2, MySQL (con driver de terceros) y SQL Server.

Para bases de datos NoSQL, muchos de los drivers ya están diseñados para ser reactivos. Por ejemplo, Spring Data tiene módulos reactivos para:

MongoDB: spring-data-mongodb-reactive
Cassandra: spring-data-cassandra-reactive
Redis: spring-data-redis-reactive

Repositorios Reactivos:

Spring Data extiende sus interfaces de repositorio para el contexto reactivo. En lugar de extender CrudRepository, extiendes interfaces como ReactiveCrudRepository, ReactiveMongoRepository, ReactiveCassandraRepository, etc. Los métodos de estas interfaces devuelven Mono<?> o Flux<?>.

Casos Típicos/Práctica

Asumiendo una entidad User y un repositorio UserRepository que extiende ReactiveCrudRepository<User, Long> (para R2DBC) o ReactiveMongoRepository<User, String> (para MongoDB).

Guardar (save):

// En un servicio
@Autowired
private UserRepository userRepository;

public Mono<User> saveUser(User user) {
    return userRepository.save(user); // Devuelve Mono<User>
}

Encontrar por ID (findById):

public Mono<User> findUserById(Long id) {
    return userRepository.findById(id); // Devuelve Mono<User>
}

Encontrar todos (findAll):

public Flux<User> findAllUsers() {
    return userRepository.findAll(); // Devuelve Flux<User>
}

Manejo de Transacciones en un Contexto Reactivo: Este es un tema un poco más avanzado y complejo. En un contexto bloqueante, las transacciones se manejan con @Transactional, que delega a un ThreadLocal. Sin embargo, los ThreadLocal no funcionan en un contexto reactivo porque los elementos pueden pasar por diferentes hilos en diferentes momentos.

Para transacciones reactivas, Spring Data proporciona la anotación @Transactional en combinación con la infraestructura de transacciones reactivas de Spring (por ejemplo, ReactiveTransactionManager para R2DBC). Cuando usas @Transactional en un método reactivo, Spring se asegura de que todas las operaciones reactivas dentro de ese método (que interactúan con la misma base de datos) se ejecuten dentro de la misma transacción.

Es importante entender que una transacción se "adjunta" al Mono o Flux que se crea, no al hilo. Es decir, las operaciones dentro del flujo reactivo, si son parte de la misma transacción, se aseguran de comprometerse o revertirse juntas.
```
@Service
public class UserServiceImpl implements UserService {

    @Autowired
    private UserRepository userRepository;

    @Transactional // Esta anotación ahora trabaja con ReactiveTransactionManager
    public Mono<User> createUserAndAudit(User user) {
        return userRepository.save(user) // Guarda el usuario
                .flatMap(savedUser -> {
                    // Simula una operación de auditoría que debe ser parte de la misma transacción
                    // Si AuditRepository fuera reactivo y manejara transacciones.
                    // return auditRepository.save(new AuditLog(savedUser.getId(), "User created"));
                    System.out.println("User saved, attempting audit for: " + savedUser.getUsername());
                    return Mono.just(savedUser); // Devolver el usuario guardado
                })
                .doOnError(e -> System.err.println("Transaction rolled back due to: " + e.getMessage())); // Manejo de error de transacción
    }
}
```
El desafío es que todas las operaciones dentro de la transacción deben ser reactivas y deben usar la misma conexión transaccional. Es un área donde la depuración puede ser más compleja que con las transacciones síncronas.

Manejo de Errores en Streams Reactivos

El manejo de errores es crucial en cualquier aplicación, y en los flujos reactivos tiene sus propias particularidades. Como ya mencionamos, cuando un error es emitido (onError), la secuencia se termina. Para evitar que toda la aplicación se caiga o para proporcionar una recuperación elegante, Reactor ofrece operadores específicos.

Operadores de Manejo de Errores

onErrorReturn(T fallbackValue): Cuando el Publisher emite un error, este operador intercepta el error, emite un valor de respaldo (fallbackValue), y luego completa la secuencia normalmente (onComplete). El error original es consumido.

// Si ocurre un error, devuelve el valor por defecto "Default Message"
Mono.error(new RuntimeException("Simulated error"))
    .onErrorReturn("Default Message")
    .subscribe(System.out::println, System.err::println); // Imprime "Default Message"

onErrorResume(Function<Throwable, Mono<T>> fallbackMonoProvider): Si ocurre un error, este operador intercepta el error y cambia a un Publisher alternativo (fallbackMonoProvider). Es útil cuando necesitas ejecutar una lógica asíncrona para recuperarte del error.

// Si ocurre un error, cambia a un Mono que simula una recuperación
Mono.error(new RuntimeException("Simulated error"))
    .onErrorResume(e -> {
        System.err.println("Error caught, resuming with alternative: " + e.getMessage());
        return Mono.just("Recovered from error!");
    })
    .subscribe(System.out::println, System.err::println); // Imprime "Recovered from error!"

onErrorMap(Function<Throwable, Throwable> errorMapper): Transforma un tipo de excepción en otro. Esto es útil para encapsular excepciones internas en excepciones más significativas para tu dominio de negocio.

// Transforma RuntimeException en CustomBusinessException
Mono.error(new RuntimeException("Database error"))
    .onErrorMap(RuntimeException.class, e -> new MyCustomBusinessException("Failed to process data: " + e.getMessage()))
    .subscribe(System.out::println, System.err::println); // Lanza MyCustomBusinessException

doOnError(Consumer<Throwable> errorConsumer): Ejecuta una acción de efecto secundario cuando un error ocurre, pero no consume el error. El error continúa propagándose por el stream. Útil para logging o métricas sin alterar el flujo de error.

// Logea el error, pero el error sigue propagándose
Mono.error(new RuntimeException("Another simulated error"))
    .doOnError(e -> System.err.println("Logging error before propagation: " + e.getMessage()))
    .subscribe(System.out::println, System.err::println); // Imprime el log y luego lanza RuntimeException

retry(long numRetries) / retryWhen(Function<Flux<Throwable>, Publisher<?>> retrySignal): Intenta re-suscribirse al Publisher original un número de veces o bajo ciertas condiciones.

Manejo Global de Errores en WebFlux (`ErrorWebExceptionHandler`)

Para centralizar el manejo de errores y proporcionar respuestas HTTP consistentes (ej. JSON con un formato de error estándar), WebFlux proporciona la interfaz ErrorWebExceptionHandler. Puedes implementar esta interfaz y registrarla como un bean para manejar todas las excepciones no capturadas por los operadores en tus flujos.

@Component
@Order(-1) // Asegura que este handler sea el primero en la cadena
public class GlobalErrorWebExceptionHandler implements ErrorWebExceptionHandler {

    @Override
    public Mono<Void> handle(ServerWebExchange exchange, Throwable ex) {
        HttpStatus status;
        String errorMessage;

        if (ex instanceof MyCustomNotFoundException) {
            status = HttpStatus.NOT_FOUND;
            errorMessage = ex.getMessage();
        } else if (ex instanceof IllegalArgumentException) {
            status = HttpStatus.BAD_REQUEST;
            errorMessage = "Invalid input: " + ex.getMessage();
        } else {
            status = HttpStatus.INTERNAL_SERVER_ERROR;
            errorMessage = "An unexpected error occurred: " + ex.getMessage();
            // Considerar logear la excepción aquí
        }

        // Construir la respuesta de error JSON
        ErrorResponse errorResponse = new ErrorResponse(status.value(), errorMessage);
        DataBufferFactory bufferFactory = exchange.getResponse().bufferFactory();
        DataBuffer buffer = bufferFactory.wrap(toJson(errorResponse).getBytes()); // Convierte el objeto a JSON

        exchange.getResponse().setStatusCode(status);
        exchange.getResponse().getHeaders().setContentType(MediaType.APPLICATION_JSON);
        return exchange.getResponse().writeWith(Mono.just(buffer));
    }

    private String toJson(Object obj) {
        // Implementa la lógica para convertir el objeto a JSON (ej. con ObjectMapper de Jackson)
        try {
            return new ObjectMapper().writeValueAsString(obj);
        } catch (JsonProcessingException e) {
            return "{\"status\":500, \"message\":\"Error converting error response to JSON\"}";
        }
    }

    // Clase auxiliar para la respuesta de error
    private static class ErrorResponse {
        public int status;
        public String message;
        public ErrorResponse(int status, String message) { this.status = status; this.message = message; }
    }
}

Casos Típicos/Práctica

Manejo de un error específico dentro de una cadena de operadores: Supongamos un servicio que busca un usuario, pero puede lanzar UserNotFoundException si no lo encuentra.

public Mono<User> getUserProfile(String userId) {
    return userRepository.findById(userId) // Simula buscar en DB
            .switchIfEmpty(Mono.error(new UserNotFoundException("User not found with ID: " + userId))) // Si Mono.empty(), lanza excepción
            .onErrorResume(UserNotFoundException.class, e -> {
                System.err.println("Handled specific UserNotFoundException: " + e.getMessage());
                return Mono.just(new User("defaultUser", "Default User")); // Devuelve un usuario por defecto
            });
}

Centralizar el manejo de errores para devolver respuestas HTTP consistentes: Como se mostró en el ejemplo de GlobalErrorWebExceptionHandler arriba.
- 404 Not Found: Mapear MyCustomNotFoundException a HttpStatus.NOT_FOUND.
- 500 Internal Server Error: Para excepciones inesperadas, mapear a HttpStatus.INTERNAL_SERVER_ERROR.
- 400 Bad Request: Para errores de validación o entrada incorrecta, mapear a HttpStatus.BAD_REQUEST.
El GlobalErrorWebExceptionHandler es el lugar ideal para definir el formato JSON estándar de tus mensajes de error y sus códigos de estado HTTP asociados, asegurando que todos los errores que atraviesan tu aplicación sean presentados de manera uniforme al cliente.

Conclusión

En esta tercera entrega, hemos cubierto pilares fundamentales para construir aplicaciones WebFlux robustas: la comunicación reactiva con servicios externos utilizando WebClient, la persistencia de datos con bases de datos reactivas a través de Spring Data R2DBC o drivers NoSQL, y el vital manejo de errores en los flujos reactivos, tanto a nivel de operador como de forma global con ErrorWebExceptionHandler.

Estos conocimientos son esenciales para construir aplicaciones que no solo sean rápidas y escalables, sino también resilientes y fáciles de mantener. En la Parte 4 y final de nuestra serie, abordaremos temas más avanzados como Server-Sent Events, el concepto de Backpressure y el Contexto Reactivo, y, por supuesto, cómo probar eficazmente nuestras aplicaciones WebFlux.

¡Nos vemos en la última parte para solidificar aún más tu conocimiento en WebFlux!

Ver página completa →

Guía Completa: Implementando Azure DevOps para la Gestión Integral del Ciclo de Desarrollo de Software

Mauricio ECR
CI CD
15 May, 2025

El desarrollo de software moderno exige agilidad, colaboración y automatización. En este contexto, contar con una plataforma que unifique las diversas etapas del ciclo de vida se vuelve fundamental. M

Ver página completa

Kafka 6: Despliegue, Seguridad y Optimización

Mauricio ECR
Arquitectura
14 May, 2025

Hemos explorado la arquitectura fundamental de Apache Kafka, la dinámica entre productores y consumidores, sus potentes capacidades para el procesamiento de flujos de datos y las herramientas que enri

Ver página completa

Spring WebFlux 2: Alta Concurrencia sin Más Hilos

Mauricio ECR
Arquitectura
12 May, 2025

¡Bienvenido de nuevo a nuestra inmersión en Spring WebFlux! 👋 En la primera parte de esta serie, exploramos el "por qué" de la programación reactiva, entendiendo los problemas del bloqueo y descubri

Ver página completa

Spring WebFlux 2: Alta Concurrencia sin Más Hilos

Mauricio ECR
Arquitectura
12 May, 2025

¡Bienvenido de nuevo a nuestra inmersión en Spring WebFlux! 👋

En la primera parte de esta serie, exploramos el "por qué" de la programación reactiva, entendiendo los problemas del bloqueo y descubriendo a Project Reactor como el motor que impulsa los flujos de datos asíncronos. Ahora que tenemos una base sólida sobre los principios reactivos y los tipos Mono/Flux, es momento de subir un nivel y entender cómo Spring WebFlux aplica estos conceptos para construir aplicaciones web eficientes y escalables.

En esta segunda entrega, nos centraremos en la arquitectura que diferencia a WebFlux de su predecesor, Spring MVC, y aprenderemos las dos formas principales de definir los endpoints de nuestra API reactiva.

3. Arquitectura de Spring WebFlux

Si Spring MVC se construyó sobre la API de Servlets (diseñada originalmente para un modelo síncrono de un hilo por petición), Spring WebFlux se construye sobre una pila completamente reactiva y no bloqueante. Esta diferencia fundamental es la clave de su capacidad para manejar alta concurrencia.

Teoría: Componentes Clave

La arquitectura de WebFlux se basa en:

Servidores No Bloqueantes: A diferencia de depender de un Contenedor de Servlets (como Tomcat, Jetty) configurado de forma tradicional, WebFlux utiliza servidores web diseñados para manejar I/O no bloqueante. El servidor por defecto integrado con Spring Boot WebFlux es Netty, un framework asíncrono basado en eventos muy popular en la industria por su rendimiento. Sin embargo, WebFlux es flexible y también soporta otros servidores reactivos como Undertow o incluso Servlets 3.1+ API en modo no bloqueante (aunque el uso de Netty o Undertow es más común y eficiente para aprovechar plenamente el potencial reactivo).
EventLoop: El corazón del procesamiento no bloqueante. En lugar de asignar un hilo por petición, WebFlux (y los servidores como Netty) utilizan un pequeño número de hilos llamados "Event Loop threads". Estos hilos no realizan operaciones de I/O bloqueantes directamente. En cambio, delegan la operación al sistema operativo y quedan libres para procesar otras tareas o peticiones. Cuando la operación de I/O se completa (por ejemplo, llega la respuesta de una base de datos o un servicio externo), el sistema operativo notifica al Event Loop, que entonces toma el resultado y continúa el procesamiento del flujo reactivo asociado a esa petición.
Reactor Core: Como vimos en la Parte 1, Project Reactor proporciona los tipos Mono y Flux y los operadores para componer la lógica asíncrona. WebFlux se integra estrechamente con Reactor.
Spring Web Reactive Framework: Capas por encima de Reactor y el servidor para proporcionar la funcionalidad web: manejo de peticiones, ruteo, serialización/deserialización, manejo de errores, etc.

Cómo WebFlux Maneja las Peticiones (El Pipeline Reactivo)

Cuando una petición HTTP llega a un servidor WebFlux:

Uno de los Event Loop threads del servidor la recibe.
La petición pasa a través de la cadena de procesamiento de WebFlux (filtros, ruteo).
La petición llega al Handler (controlador o función manejadora) correspondiente.
El Handler ejecuta la lógica de negocio, que típicamente involucra operaciones que devuelven Mono o Flux (ej: llamar a un servicio, acceder a una base de datos reactiva).
Estas operaciones, al ser reactivas y no bloqueantes, no detienen el Event Loop thread. El thread delega la tarea (ej: consulta a DB) y queda libre.
Cuando la operación asíncrona finaliza (ej: la DB devuelve resultados), uno de los Event Loop threads recibe la notificación.
Los resultados fluyen de vuelta a través de la cadena de operadores definida en el Mono/Flux.
El resultado final del Mono/Flux se convierte en una respuesta HTTP y se envía de vuelta al cliente, de nuevo, utilizando los Event Loop threads de forma no bloqueante.

Todo el procesamiento, desde la recepción de la petición hasta el envío de la respuesta, se maneja sin bloquear los hilos principales, permitiendo que un pequeño número de hilos gestione una alta concurrencia.

Diferencias Arquitectónicas Fundamentales con Spring MVC

Característica	Spring MVC (Tradicional)	Spring WebFlux (Reactivo)
Modelo de Hilos	Thread-per-request (Bloqueante)	Event Loop (No Bloqueante)
Contenedor/Servidor	Basado en Servlet API (Tomcat, Jetty, etc.)	Basado en servidores reactivos (Netty, Undertow) o Servlet 3.1+ no bloqueante
Manejo de I/O	Bloqueante (por defecto)	No Bloqueante
Dependencies Base	`spring-webmvc`	`spring-webflux`
Tipos de Retorno	Objetos POJO, `ResponseEntity`, `ModelAndView`, etc.	`Mono<?>`, `Flux<?>`, `ResponseEntity<Mono<?>>`, etc.
Backpressure	No aplica directamente	Soportado nativamente a través de Reactive Streams

¿Puedes usar Spring MVC y Spring WebFlux en el mismo proyecto?

Generalmente no. Aunque es técnicamente posible tener ambas dependencias en el classpath, Spring Boot configurará automáticamente solo una de las dos pilas web (MVC o WebFlux) basándose en la que encuentre primero o una configuración explícita. Son dos arquitecturas de manejo de peticiones fundamentalmente diferentes que no están diseñadas para coexistir y procesar la misma petición dentro del mismo contexto de aplicación Spring de forma híbrida y coherente. Debes elegir una u otra para tu aplicación web principal.

Casos Típicos/Práctica

Flujo de una Petición Típica en WebFlux:
1. Llega petición HTTP a Netty (Event Loop thread A la recibe).
2. WebFlux la rutea a un HandlerFunction (el mismo thread A).
3. El Handler llama a un UserService.findById(id) que devuelve Mono<User>.
4. UserService usa un ReactiveUserRepository.findById(id) (que usa un driver R2DBC no bloqueante).
5. El Event Loop thread A delega la consulta a la DB y queda libre.
6. Cuando la DB responde, otro Event Loop thread (B) recibe la notificación.
7. El thread B retoma el flujo del Mono<User>.
8. El resultado User fluye de regreso al Handler.
9. El Handler devuelve el Mono<User>, que WebFlux serializa a JSON.
10. El Event Loop thread B envía la respuesta HTTP de vuelta al cliente.
Modelo de Hilos de Spring MVC vs. WebFlux:
- MVC: Un pico de 1000 peticiones concurrentes esperando por una DB lenta podría requerir 1000 hilos (o el tamaño máximo del pool), muchos de ellos inactivos.
- WebFlux: Esas mismas 1000 peticiones podrían ser manejadas por 4-8 Event Loop threads, que nunca esperan, simplemente gestionan el estado de las operaciones asíncronas pendientes. Esto libera recursos para otras tareas.

4. Creación de Endpoints (Controladores y Endpoints Funcionales)

Spring WebFlux ofrece dos enfoques principales para definir los puntos finales de tu API: el modelo tradicional basado en anotaciones y un modelo más funcional.

Teoría: Dos Enfoques

Basado en Anotaciones: Similar a Spring MVC, usas anotaciones como @RestController, @RequestMapping, @GetMapping, @PostMapping, @RequestBody, etc. La diferencia clave es que los métodos del controlador deben devolver tipos reactivos (Mono<?> o Flux<?>).
Endpoints Funcionales: Un enfoque más funcional y declarativo. Defines las rutas usando RouterFunction y los manejadores de peticiones usando HandlerFunction. No hay anotaciones a nivel de método o clase; es todo código Java.

Uso de Anotaciones con Tipos Reactivos

Es el enfoque más familiar si vienes de Spring MVC. Simplemente creas clases con @RestController y métodos con anotaciones de mapeo HTTP. La diferencia crucial es el tipo de retorno:

Devuelve Mono<T> si esperas 0 o 1 objeto T en la respuesta.
Devuelve Flux<T> si esperas 0 a N objetos T en la respuesta (esto puede ser un array JSON o un stream de datos, por ejemplo, en Server-Sent Events).
Puedes envolver el tipo reactivo en ResponseEntity para tener control sobre el estado HTTP, cabeceras, etc.: Mono<ResponseEntity<T>> o ResponseEntity<Flux<T>>.

Recibir datos en el cuerpo de la petición también se hace reactivamente: usas @RequestBody con Mono<T>.

Uso de Endpoints Funcionales

Este enfoque desacopla completamente la definición de la ruta de la lógica de manejo de la petición.

RouterFunction<ServerResponse>: Define cómo las peticiones se rutean a los HandlerFunction basándose en predicados (métodos HTTP, rutas, cabeceras, etc.). Usas la clase RouterFunctions para construirlas (route(RequestPredicate, HandlerFunction)).
HandlerFunction<ServerResponse>: Contiene la lógica de negocio para manejar una petición. Recibe un ServerRequest como entrada y devuelve un Mono<ServerResponse>. La clase ServerResponse se usa para construir la respuesta (estado HTTP, cuerpo, cabeceras).

Ventajas del Enfoque Funcional:

Mayor separación de preocupaciones (ruteo vs. manejo).
Más fácil de testear unitariamente (HandlerFunction es solo una función pura).
Permite una construcción de rutas más programática y dinámica.
Evita el uso de reflexion asociado a las anotaciones (micro-optimización).

Desventajas del Enfoque Funcional:

Puede ser menos conciso y legible para APIs REST simples comparado con las anotaciones.
Menos familiar para desarrolladores acostumbrados al modelo de anotaciones.

Casos Típicos/Práctica

Endpoint GET que devuelva un Mono<MyObject> (Anotaciones):

Asumiendo una clase MyObject { String message; }

@RestController
@RequestMapping("/api/greeting")
public class GreetingController {

    @GetMapping("/{name}")
    public Mono<MyObject> getGreeting(@PathVariable String name) {
        // Simula una operación asíncrona que devuelve un solo objeto
        return Mono.just(new MyObject("Hello, " + name))
                   .delayElement(Duration.ofMillis(500)); // Simula latencia
    }
}

Endpoint GET que devuelva un Flux<MyObject> (Stream de datos) (Anotaciones):

@RestController
@RequestMapping("/api/numbers")
public class NumberStreamController {

    @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) // Importante: MediaType.TEXT_EVENT_STREAM_VALUE para SSE
    public Flux<String> streamNumbers() {
        // Emite un número cada segundo indefinidamente
        return Flux.interval(Duration.ofSeconds(1))
                   .map(sequence -> "Event: " + sequence);
    }

    @GetMapping("/list") // Devuelve como JSON array
    public Flux<MyObject> getObjectsList() {
        return Flux.just(new MyObject("one"), new MyObject("two"), new MyObject("three"))
                   .delayElements(Duration.ofMillis(100));
    }
}

Endpoint POST que reciba un Mono<MyObject> en el body (Anotaciones):

@RestController
@RequestMapping("/api/objects")
public class ObjectController {

    @PostMapping
    public Mono<String> createObject(@RequestBody Mono<MyObject> objectMono) {
        // Recibe un Mono<MyObject> del cuerpo de la petición
        // flatMap es necesario porque objectMono es un Publisher y save es otro Publisher
        return objectMono
                .flatMap(obj -> {
                    System.out.println("Recibido objeto: " + obj.getMessage());
                    // Simula guardar el objeto asíncronamente y devolver un ID
                    return Mono.just("Object saved with ID: " + obj.getMessage().hashCode())
                               .delayElement(Duration.ofMillis(300));
                });
    }
}

Definir una ruta y su manejador usando el enfoque funcional:

Primero, el HandlerFunction:

// En un archivo separado, por ejemplo, src/main/java/com/example/demo/handler/GreetingHandler.java
@Component // Spring lo detecta como un Bean
public class GreetingHandler {

    public Mono<ServerResponse> getGreeting(ServerRequest request) {
        String name = request.pathVariable("name");
        return Mono.just(new MyObject("Hello, " + name))
                   .delayElement(Duration.ofMillis(500)) // Simula latencia
                   .flatMap(obj -> ServerResponse.ok() // Construye la respuesta HTTP 200
                                                 .contentType(MediaType.APPLICATION_JSON) // Define el tipo de contenido
                                                 .bodyValue(obj)); // Pone el objeto en el cuerpo de la respuesta
    }

     public Mono<ServerResponse> createObject(ServerRequest request) {
         return request.bodyToMono(MyObject.class) // Extrae el cuerpo a un Mono<MyObject>
                .flatMap(obj -> {
                    System.out.println("Recibido objeto (Funcional): " + obj.getMessage());
                     // Simula guardar
                    return Mono.just("Object saved (Funcional) with ID: " + obj.getMessage().hashCode())
                               .delayElement(Duration.ofMillis(300));
                })
                .flatMap(responseString -> ServerResponse.status(HttpStatus.CREATED) // Construye respuesta 201 Created
                                                          .contentType(MediaType.TEXT_PLAIN)
                                                          .bodyValue(responseString));
     }
}

Luego, el RouterFunction (en una clase de configuración, por ejemplo):

// En una clase de configuración, por ejemplo, src/main/java/com/example/demo/config/RoutingConfig.java
@Configuration
public class RoutingConfig {

    @Bean
    public RouterFunction<ServerResponse> route(GreetingHandler greetingHandler) {
        return RouterFunctions.route(GET("/api/functional/greeting/{name}").and(accept(MediaType.APPLICATION_JSON)), greetingHandler::getGreeting)
               .andRoute(POST("/api/functional/objects").and(contentType(MediaType.APPLICATION_JSON)), greetingHandler::createObject); // Combina con otras rutas
    }
}

¿Cuándo elegirías anotaciones vs. endpoints funcionales?
- Anotaciones: Ideal para proyectos que migran de Spring MVC, equipos familiarizados con el modelo de anotaciones, o APIs REST con estructuras estándar. Es a menudo más rápido de implementar para casos simples o CRUDs.
- Funcionales: Preferible para APIs con lógica de ruteo compleja o dinámica, si buscas una mayor separación de preocupaciones para facilitar el testing unitario de la lógica del manejador, o si simplemente prefieres un estilo más funcional y programático. Puede tener una curva de aprendizaje inicial si no estás acostumbrado.

Conclusión

En esta segunda entrega, hemos explorado la arquitectura fundamental de Spring WebFlux, entendiendo cómo su modelo no bloqueante basado en EventLoop y servidores como Netty le permite manejar eficientemente la alta concurrencia, a diferencia del modelo tradicional de Spring MVC. También hemos aprendido las dos vías principales para construir endpoints: el familiar enfoque basado en anotaciones (adaptado para devolver tipos reactivos) y el modelo más programático y funcional de RouterFunction y HandlerFunction, comprendiendo las fortalezas de cada uno y cuándo considerar usarlos.

Con la arquitectura y la creación de endpoints cubiertas, estamos listos para abordar la interacción de nuestra aplicación WebFlux con el mundo exterior y el manejo de datos y errores. En la próxima parte, nos sumergiremos en el uso de WebClient para consumir servicios externos reactivamente, la integración con bases de datos reactivas (R2DBC, drivers NoSQL) y las estrategias para gestionar errores en los flujos reactivos.

¡Hasta la próxima entrega de nuestra serie sobre WebFlux!

Ver página completa →

Kafka 5: Más Allá del Core, Explorando el Ecosistema de Apache Kafka

Mauricio ECR
Arquitectura
10 May, 2025

Hemos navegado por las entrañas de Apache Kafka, comprendiendo su funcionamiento interno, la interacción entre productores y consumidores, e incluso cómo procesar datos en tiempo real con Kafka Stream

Ver página completa

Kafka 5: Más Allá del Core, Explorando el Ecosistema de Apache Kafka

Mauricio ECR
Arquitectura
10 May, 2025

Hemos navegado por las entrañas de Apache Kafka, comprendiendo su funcionamiento interno, la interacción entre productores y consumidores, e incluso cómo procesar datos en tiempo real con Kafka Streams y ksqlDB. Sin embargo, en un entorno de producción, Kafka rara vez opera de forma aislada. Para construir pipelines de datos completas, robustas y fáciles de gestionar a escala, se necesita un conjunto de herramientas y componentes que complementen sus capacidades fundamentales.

Este artículo se sumerge en el vibrante ecosistema que rodea a Kafka, destacando herramientas clave que simplifican tareas críticas como la gestión de esquemas de datos, la integración con sistemas externos y la monitorización del clúster. Una parte significativa de estas herramientas ha sido desarrollada por Confluent, la empresa fundada por los creadores originales de Kafka, aunque también exploraremos alternativas open-source relevantes. Entender este ecosistema es crucial para llevar tus proyectos de Kafka de una prueba de concepto a una operación a escala en producción.

La Confluent Platform y el Ecosistema Kafka

Si bien Apache Kafka es el corazón del sistema de streaming de eventos, la Confluent Platform es un conjunto de herramientas y servicios, que incluyen componentes tanto open-source como comerciales, diseñados para extender las capacidades de Kafka y facilitar su uso en entornos empresariales. Exploraremos algunos de los componentes más relevantes de este ecosistema.

Confluent Schema Registry: El Guardián de Tus Datos

En arquitecturas basadas en eventos donde múltiples aplicaciones interactúan con Kafka (leyendo y escribiendo datos), la gestión de los formatos o esquemas de esos datos es fundamental. Sin una gestión centralizada, un productor podría enviar datos en un formato inesperado, causando fallos en los consumidores que esperan un formato diferente. Aquí es donde el Schema Registry se vuelve indispensable.

El Confluent Schema Registry es un almacén centralizado y distribuido diseñado específicamente para gestionar esquemas de datos. Funciona especialmente bien con formatos de serialización basados en esquema como Avro, Protobuf o JSON Schema. Los productores pueden registrar el esquema de los mensajes que publican en el Registry, y los consumidores, al leer estos mensajes, pueden obtener el esquema correspondiente del Registry para deserializar los datos correctamente.

Los beneficios clave del Schema Registry son varios:

Gestión Centralizada: Todos los esquemas se almacenan en un único lugar, lo que simplifica su descubrimiento y gestión.
Validación de Esquemas: Los productores pueden configurarse para validar los mensajes contra el esquema registrado antes de publicarlos, lo que previene que datos mal formados lleguen a los topics de Kafka.
Evolución de Esquemas con Compatibilidad: Permite definir reglas de compatibilidad (como BACKWARD, FORWARD, FULL) para controlar cómo los esquemas pueden cambiar con el tiempo. Si se intenta registrar una nueva versión de un esquema que rompe la compatibilidad según la regla definida, el Registry lo impide. Esto es crucial para garantizar que los consumidores existentes puedan seguir procesando datos producidos con esquemas nuevos o viceversa, facilitando que las aplicaciones evolucionen de forma independiente.

Ejemplo Práctico de Evolución de Esquemas

Consideremos un esquema inicial para un usuario (User_v1) con campos id (entero) y name (cadena).

{
  "type": "record",
  "name": "User",
  "fields": [
    {"name": "id", "type": "int"},
    {"name": "name", "type": "string"}
  ]
}

Si queremos añadir un campo opcional email, creamos User_v2 con la regla BACKWARD. Un consumidor usando User_v1 aún podrá leer mensajes de User_v2 ignorando el nuevo campo email, mientras que los consumidores nuevos podrán usarlo.

{
  "fields": [
    {"name": "id", "type": "int"},
    {"name": "name", "type": "string"},
    {"name": "email", "type": ["null", "string"], "default": null}
  ]
}

Sin embargo, intentar eliminar el campo name en User_v3 con una regla FULL (que requiere compatibilidad bidireccional) sería rechazado por el Schema Registry porque rompería a los consumidores antiguos que esperan el campo name. Esto demuestra cómo el Registry previene errores en producción.

Mejores Prácticas para Schema Registry:

Es recomendable usar Avro para la serialización debido a su eficiencia binaria y excelente soporte para la evolución de esquemas.
Define reglas de compatibilidad según el ciclo de vida de tus datos y despliegues. BACKWARD es ideal si los consumidores se actualizan gradualmente después de los productores.
Valida la compatibilidad de los esquemas en tus procesos de Integración Continua/Despliegue Continuo (CI/CD) para detectar problemas antes de llegar a producción.
Considera usar "subjects" con sufijos de entorno (ej: user-dev, user-prod) para aislar versiones de esquemas en diferentes entornos.
Existe una alternativa open-source al Confluent Schema Registry llamada Apicurio Registry.

Caso de Uso Real:

Plataformas de pagos que necesitan evolucionar sus modelos de transacciones añadiendo nuevos campos (ej: tipo de divisa) sin romper los sistemas de conciliación o antifraude que usan esquemas más antiguos.

Kafka Connect: El Puente hacia Otros Sistemas

Kafka Connect es un framework open-source (parte de Apache Kafka) diseñado para conectar Kafka con otros sistemas de datos de forma escalable y fiable. Permite importar datos a Kafka (conectores fuente o Source Connectors) o exportar datos desde Kafka (conectores sumidero o Sink Connectors) sin necesidad de escribir código de integración personalizado.

Kafka Connect se ejecuta como un clúster separado de workers que gestionan el ciclo de vida de los conectores. Cada conector es una instancia de una tarea de integración específica, configurada para leer o escribir datos de un sistema particular.

Modos de Implementación:

Standalone: Ideal para desarrollo o pruebas. Un solo proceso maneja todas las tareas del conector. La configuración es simple usando un archivo .properties.
Distribuido: Para entornos de producción. Múltiples workers se coordinan a través de una REST API. Este modo es escalable y tolerante a fallos; si un worker falla, otro retoma sus tareas. Se recomienda usar al menos 3 workers en producción para tolerancia a fallos.

Gestión de Offsets:

Una de las grandes ventajas de Kafka Connect es su gestión automática de offsets. Los conectores fuente almacenan su progreso (el último offset leído del sistema de origen) en topics internos de Kafka (llamados connect-offsets). En caso de fallo o reinicio, el conector puede retomar la ingesta de datos exactamente desde el último offset guardado, garantizando la entrega "at least once" o "exactly once" dependiendo del conector y la configuración.

Ejemplos Populares de Conectores:

Debezium: Un conjunto de Source Connectors open-source para Change Data Capture (CDC). Debezium monitoriza bases de datos (como MySQL, PostgreSQL, MongoDB) a nivel de log transaccional y publica todos los cambios (inserciones, actualizaciones, eliminaciones) como flujos de eventos en topics de Kafka. Esto permite reaccionar a los cambios en la base de datos en tiempo real y construir arquitecturas basadas en eventos.
JDBC Connector: Un conector genérico que puede funcionar como Source (lee datos de bases de datos relacionales vía JDBC y los publica en Kafka) o como Sink (lee datos de Kafka y los escribe en bases de datos relacionales).
Otros conectores populares incluyen los de S3, Elasticsearch, HDFS, GCS, y muchos más. Puedes descubrir y probar cientos de conectores listos para usar en Confluent Hub.

Mejores Prácticas para Kafka Connect:

Prioriza el uso de conectores oficiales o aquellos mantenidos activamente por comunidades robustas (verifica en Confluent Hub).
Monitoriza métricas clave por conector, como source-record-poll-rate (ritmo de lectura del origen) y sink-record-send-rate (ritmo de escritura al destino) para evaluar su rendimiento.

Caso de Uso Real:

Sincronización en tiempo real entre bases de datos transaccionales y data warehouses. Por ejemplo, usando Debezium para capturar cambios en una base de datos MySQL/PostgreSQL y publicarlos en Kafka, y luego un JDBC Sink Connector para exportar esos datos a un data warehouse como Snowflake o BigQuery. Esto moderniza arquitecturas legacy convirtiendo bases de datos en streams de eventos sin código personalizado.

Otras Herramientas de Confluent Platform (Comerciales y Open-Source)

REST Proxy: Expone la API de Kafka a través de HTTP, lo que puede ser ideal para microservicios ligeros o entornos con restricciones de librerías cliente.
MirrorMaker 2: Una herramienta para sincronizar topics entre clústeres de Kafka. Es invaluable para replicación multi-datacenter, migraciones o estrategias de recuperación ante desastres (DR - Disaster Recovery).

Monitorización y Gestión: Mantén el Control

Conforme un clúster de Kafka crece en tamaño y complejidad (más topics, particiones, productores, consumidores), monitorizar su salud, rendimiento y el flujo de datos se vuelve absolutamente esencial.

Confluent Control Center:

Control Center es una herramienta de interfaz gráfica que forma parte de la Confluent Platform comercial (no es open-source Apache Kafka). Proporciona una visibilidad integral del clúster. Permite:

Visualizar la topología del clúster, incluyendo brokers, topics y consumidores.
Monitorizar métricas clave de rendimiento como throughput, latencia, y tasa de errores para brokers, productores y consumidores.
Inspeccionar datos dentro de los topics (ver mensajes).
Gestionar topics (crear, eliminar, modificar).
Monitorizar y gestionar aplicaciones de Kafka Connect y Kafka Streams.
Visualizar el flujo de datos de extremo a extremo a través de la función "Data Lineage" (rastreo del origen y destino de los datos). Control Center puede alertar sobre problemas como el consumer lag (retraso de los consumidores).

Alternativas Open-Source para Monitorización:

Existen potentes alternativas open-source para la monitorización y gestión.

Prometheus + Grafana: Una combinación muy común para el scraping y visualización de métricas. Puedes exportar métricas JMX de Kafka usando herramientas como el JMX Exporter y crear dashboards personalizados en Grafana para métricas clave (throughput, latencia, consumer lag, uso de disco, etc.). Prometheus permite configurar alertas basadas en estas métricas.
Kafdrop: Una interfaz web ligera y fácil de usar para explorar topics, particiones, líderes y ver mensajes en tiempo real. Es útil para inspecciones rápidas sin configuración compleja. Se puede desplegar fácilmente con Docker.
Kafka Manager: Una herramienta de gestión de clústeres que permite tareas como la creación y modificación de topics.
Cruise Control: Desarrollado por LinkedIn, es una herramienta open-source para el balanceo automático de particiones y la optimización de clústeres. Ayuda a optimizar la distribución de réplicas para evitar "nodos calientes" (hotspots) y puede ayudar en la autorrecuperación de brokers.

Operadores Kubernetes para Despliegues Cloud-Native

Para entornos que utilizan Kubernetes (K8s), los operadores simplifican enormemente el despliegue, escalado, y operaciones de Kafka.

Strimzi: Un operador muy popular para desplegar, escalar y gestionar Kafka sobre K8s.
Banzaicloud Kafka Operator: Similar a Strimzi, con un enfoque en multitenancy y GitOps.

Estos operadores aseguran alta disponibilidad y portabilidad de tu clúster Kafka en la nube.

Ecosistema Alternativo: Más Allá de Apache Kafka Core

Aunque Apache Kafka es el líder indiscutible en el espacio del streaming de eventos distribuidos open-source, es importante saber que existen otras plataformas con arquitecturas diferentes que podrían ser más adecuadas para casos de uso específicos. Dos alternativas open-source notables son:

Redpanda: Una plataforma de streaming de datos compatible con la API de Kafka, escrita en C++. Su objetivo es ser más simple de operar, más rápida y sin la dependencia de ZooKeeper (utiliza un motor Raft integrado, similar a KRaft en las versiones recientes de Kafka). Se posiciona como una opción de alto rendimiento y menor latencia (1-10 ms frente a 10-50 ms de Kafka), especialmente atractiva en entornos de edge computing o donde la simplicidad operativa y baja latencia son primordiales. La comunidad es aún más pequeña que la de Kafka.
Apache Pulsar: Una plataforma de mensajería y streaming distribuida con una arquitectura desacoplada de almacenamiento y servicio. A diferencia de Kafka, donde los brokers almacenan los datos, Pulsar utiliza una capa de almacenamiento separada basada en Apache BookKeeper (un log de commits distribuido). Esta separación permite escalar la capacidad de almacenamiento y servicio de forma independiente y ofrece características avanzadas como "tiered storage" nativo (mover datos antiguos a almacenamiento más barato). Pulsar también soporta múltiples modelos de suscripción (exclusivo, compartido, failover), a diferencia de los Consumer Groups de Kafka. Tiene un concepto nativo de "multi-tenancy". Es una alternativa potente con un conjunto de características diferente, aunque con potencialmente mayor complejidad de operación. Su latencia es baja (5-20 ms).

Comparativa Rápida: Kafka vs Redpanda vs Pulsar

Característica	Apache Kafka	Redpanda	Apache Pulsar
Arquitectura	Broker + ZooKeeper/KRaft	Single binary, Raft (sin ZK)	Broker + BookKeeper (almac. sep.)
Latencia	Moderada (10-50 ms)	Muy baja (1-10 ms)	Baja (5-20 ms)
Tiered Storage	Sí (vía extensiones/Confluent)	No	Sí (nativo)
Modelos Consumer	Consumer Groups	Consumer Groups	Suscripciones (exclusivo, compartido, failover)
Escalabilidad	Alta	Alta	Muy Alta (por desacoplamiento)
Caso de Uso Ideal	Ecosistema maduro, procesamiento	Edge computing, baja latencia, simplicidad	Multi-tenancy, escalabilidad extrema

Es importante notar que las alternativas (Redpanda/Pulsar) pueden no ser 100% compatibles con todas las APIs de Kafka.

Flujo de Datos de Extremo a Extremo (Ejemplo Integrado)

Para ilustrar cómo encajan estas piezas, consideremos un pipeline típico:

┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐    ┌─────────────────┐
│   Database  │──▶│Debezium (CDC)│──▶│ Kafka Topic (Avro)  │──▶│Kafka Streams App│
└─────────────┘    └─────────────┘    └─────────────────────┘    └─────────────────┘
      ▲              ▲                  ▲                          │
      │ Schema Registry │                  │ (Validation)             │ (Processing)
      ▼              │                  │                          ▼
┌────────────────┐    ┌─────────────────┐    ┌────────────────┐    ┌────────────────┐
│Monitorización  │◀──│ Kafka Connect   │◀──│ Kafka Topic    │◀── │ Kafka Streams  │
│(Control Center,│    │ (JDBC Sink)     │    │ (Enriched Data)│    │    (Results)   │
│Prometheus)     │    └─────────────────┘    └────────────────┘    └────────────────┘
└────────────────┘                                   │
                                                     │ (Export)
                                                     ▼
                                               ┌────────────────┐
                                               │Data Warehouse  │
                                               └────────────────┘

Ingesta: Debezium captura cambios de una tabla PostgreSQL (users) y los publica en un topic de Kafka (postgres.public.users). El Schema Registry valida que los mensajes Avro cumplan con el esquema esperado (User_v2).
Procesamiento: Una aplicación Kafka Streams consume datos del topic de origen, los enriquece (ej: agrega geolocalización) y escribe los resultados en un nuevo topic (users-enriched).
Exportación: Un JDBC Sink Connector consume los datos enriquecidos del topic users-enriched y los inserta en un Data Warehouse como BigQuery. El conector gestiona automáticamente sus offsets.
Monitorización: Confluent Control Center o una combinación de Prometheus + Grafana monitoriza el rendimiento de todo el pipeline. Se pueden configurar alertas si el consumer lag del Sink Connector excede un umbral o si la latencia de los brokers aumenta significativamente.

Este ejemplo demuestra cómo el ecosistema completo transforma una base de datos estática en un flujo de eventos dinámico que alimenta procesamiento en tiempo real y analítica.

Checklist Rápido de Herramientas por Necesidad

Necesidad	Herramienta Recomendada	Alternativa Open-Source
Gestión de esquemas	Confluent Schema Registry	Apicurio Registry
CDC (Bases de datos)	Debezium	No hay equivalente directo
Integración genérica	Kafka Connect (Source/Sink)	-
Acceso vía HTTP	Confluent REST Proxy	-
Sincronización clúster	MirrorMaker 2	-
Monitorización/Gestión	Confluent Control Center	Prometheus + Grafana, Kafdrop, Kafka Manager
Balanceo/Optimización	Cruise Control	-
Despliegue en K8s	Strimzi, Banzaicloud Operator	-
Plataforma simplificada	Redpanda	-
Multi-tenancy, tiered	Apache Pulsar	-

⚠ Importante (Advertencias Comunes) ⚠

No intentes usar Schema Registry con formatos como JSON genérico; úsalo con Avro, Protobuf o JSON Schema para beneficiarte de la validación y compatibilidad.
Kafka Connect requiere tuning de los workers y la configuración de los conectores para lograr un alto throughput y eficiencia.
Si bien Redpanda y Pulsar son alternativas potentes, no son 100% compatibles con todas las APIs y herramientas del ecosistema de Kafka. Investiga si tus librerías o herramientas específicas son compatibles antes de elegirlas.

Conclusión: El Poder del Ecosistema

Hemos ampliado nuestra perspectiva más allá del núcleo de Apache Kafka para explorar el valioso ecosistema de herramientas y componentes que lo rodean. Vimos cómo Schema Registry resuelve el desafío crítico de la gestión de esquemas en un entorno dinámico, cómo Kafka Connect simplifica enormemente la integración con sistemas externos a través de una rica variedad de conectores (como Debezium para CDC). Exploramos cómo herramientas de monitorización y gestión como Control Center (comercial) o las alternativas open-source como Prometheus+Grafana y Kafdrop proporcionan la visibilidad necesaria para operar Kafka en producción a escala. También echamos un vistazo a alternativas open-source como Redpanda y Apache Pulsar, reconociendo la diversidad en el paisaje del streaming de datos.

El verdadero poder de Kafka emerge cuando se integra con un sólido ecosistema. Schema Registry garantiza la integridad y evolución controlada de tus datos. Kafka Connect y el REST Proxy facilitan la ingesta y exposición de eventos. MirrorMaker 2 y los operadores nativos de Kubernetes aseguran alta disponibilidad y portabilidad. Y un adecuado stack de monitorización te dará la visibilidad total necesaria para operar sistemas de misión crítica.

La selección de herramientas dependerá de las necesidades específicas de tu proyecto. Para entornos cloud o donde buscas reducir la carga operativa, considera Confluent Cloud (que integra Schema Registry, Connect y Control Center) o Redpanda Cloud. Si trabajas con arquitecturas legacy que usan bases de datos, Kafka Connect + Debezium es ideal para modernizar con CDC. Equipos pequeños pueden beneficiarse de la simplicidad operativa de Redpanda o soluciones gestionadas. Y para escenarios de multi-tenancy, Apache Pulsar ofrece capacidades nativas robustas.

Con un conocimiento sólido de Kafka, sus componentes clave, la interacción entre productores/consumidores, las capacidades de procesamiento de stream y las herramientas que lo complementan, estamos listos para abordar aspectos prácticos y críticos de su despliegue y operación.

En el próximo artículo, profundizaremos precisamente en el Despliegue, la Seguridad y la Optimización de un clúster de Kafka. Cubriremos temas como opciones de despliegue (incluyendo Strimzi en K8s), cómo asegurar tu clúster con TLS y ACLs, y técnicas para ajustar su rendimiento (tuning de particiones, GC de JVM). También exploraremos herramientas emergentes como Flink (procesamiento avanzado con estado) o Quarkus (construir aplicaciones Kafka nativas en Kubernetes).

Con estas piezas colocadas, estarás listo para transformar tus pruebas de concepto en pipelines de datos robustos y listos para producción de misión crítica. ¡Nos vemos allí!

Ver página completa →

Spring WebFlux 1: Fundamentos Reactivos y el Corazón de Reactor

Mauricio ECR
Arquitectura
08 May, 2025

¡Hola, entusiasta del desarrollo moderno! 👋 En el vertiginoso mundo de las aplicaciones web, donde la escalabilidad y la eficiencia son reyes, ha surgido un paradigma que desafía el modelo tradicion

Ver página completa

Spring WebFlux 1: Fundamentos Reactivos y el Corazón de Reactor

Mauricio ECR
Arquitectura
08 May, 2025

¡Hola, entusiasta del desarrollo moderno! 👋

En el vertiginoso mundo de las aplicaciones web, donde la escalabilidad y la eficiencia son reyes, ha surgido un paradigma que desafía el modelo tradicional de solicitud-respuesta síncrono: la Programación Reactiva. Y si trabajas con Spring, inevitablemente te encontrarás con Spring WebFlux, la respuesta de este popular framework a este emocionante cambio.

Prepararte para una entrevista sobre WebFlux implica comprender no solo cómo usarlo, sino por qué existe y cómo funciona por dentro. En esta primera entrega de nuestra serie, sentaremos las bases, explorando los principios reactivos y conociendo a Project Reactor, la biblioteca que impulsa WebFlux.

1. Fundamentos de Programación Reactiva y el "Por Qué" de WebFlux

Imagínate un restaurante. En el modelo tradicional (síncrono), un camarero toma una orden (petición), va a la cocina y espera a que el plato esté listo para llevarlo a la mesa. Mientras espera, no puede atender a nadie más. Si el restaurante se llena, necesitas más camareros (hilos) esperando. Esto escala, pero llega un punto en que tener demasiados camareros se vuelve ineficiente (consumo de memoria, sobrecarga del planificador de hilos).

Ahora, imagina un modelo diferente. El camarero toma la orden, la lleva a la cocina y, en lugar de esperar, vuelve a tomar más órdenes. Cuando un plato está listo, el cocinero avisa, y el camarero que esté libre lo recoge y lo lleva. Este es el modelo reactivo/asíncrono/no bloqueante. Los camareros (hilos) no se quedan inactivos esperando; están constantemente haciendo algo útil.

Teoría: ¿Qué es la Programación Reactiva?

La Programación Reactiva es un paradigma de programación que se centra en trabajar con flujos de datos asíncronos que reaccionan a cambios. No es solo sobre asincronía; es sobre gestionar la propagación de cambios y el manejo de "eventos" de manera eficiente y no bloqueante.

Aunque existe un "Reactive Manifesto" que define los principios de sistemas reactivos (responsivos, resilientes, elásticos y basados en mensajes), en el contexto de la programación reactiva a nivel de código, nos enfocamos más en cómo manejamos esos flujos de datos asíncronos.

Programación Síncrona vs. Asíncrona vs. No Bloqueante vs. Reactiva

Es crucial entender estas diferencias:

Síncrona: Las operaciones se ejecutan secuencialmente. Una operación debe completarse antes de que la siguiente pueda comenzar. Un hilo realiza una tarea de principio a fin.
Asíncrona: Una operación se inicia y el programa continúa ejecutando otras tareas sin esperar a que la primera termine. Cuando la operación asíncrona finaliza, a menudo notifica al programa (por ejemplo, a través de un callback o una promesa).
No Bloqueante: Un subconjunto importante de la programación asíncrona. Una llamada a una función no bloqueante regresa inmediatamente, incluso si la operación solicitada no se ha completado. Si el resultado no está disponible, a menudo devuelve un valor especial (como null o un indicador de "pendiente"). No bloquea el hilo llamador.
Reactiva: Un estilo de programación que utiliza flujos de datos asíncronos y no bloqueantes. Se basa en el patrón Observer, donde un "Publisher" emite elementos y un "Subscriber" los consume reaccionando a ellos. Permite componer operaciones complejas sobre estos flujos de manera declarativa.

El Problema del Bloqueo (Thread per Request):

En las arquitecturas web tradicionales (como Spring MVC sobre Servlet API), el modelo común es "un hilo por petición". Cuando una petición llega, se le asigna un hilo del pool. Si esa petición necesita interactuar con algo lento (una base de datos, un servicio externo, una espera de I/O), el hilo asignado se bloquea esperando. Mientras está bloqueado, no puede atender otras peticiones. En escenarios de alto tráfico o latencia, esto lleva a:

Agotamiento del pool de hilos.
Alta demanda de recursos del sistema (memoria, CPU por el cambio de contexto entre muchos hilos).
Disminución del rendimiento y la capacidad de respuesta.

La programación reactiva y WebFlux resuelven esto utilizando un modelo basado en eventos y no bloqueante. Un pequeño número de hilos (a menudo llamados Event Loop threads) maneja muchas peticiones concurrentemente. Cuando una operación de I/O es necesaria, el hilo no espera; delega la operación al sistema operativo y se libera para manejar otras peticiones. Cuando el resultado de la operación de I/O está listo, el sistema operativo notifica a uno de los hilos del Event Loop, que entonces procesa la respuesta.

Ventajas de Usar WebFlux

Escalabilidad: Maneja un gran número de conexiones concurrentes con un número reducido de hilos, lo que se traduce en una mejor utilización de recursos y mayor capacidad para escalar horizontalmente.
Uso Eficiente de Recursos: Menos hilos significan menos consumo de memoria y menos sobrecarga del planificador de hilos.
Manejo de Latencia: Al no bloquear hilos en operaciones de I/O, la aplicación sigue siendo receptiva incluso cuando depende de servicios lentos o tiene alta latencia.
Composición de Flujos Asíncronos: El modelo reactivo basado en operadores facilita la construcción de lógica compleja que involucra múltiples operaciones asíncronas.

¿Cuándo NO Usar WebFlux?

WebFlux no es una bala de plata para todos los casos. Hay situaciones donde Spring MVC tradicional puede ser más adecuado:

Aplicaciones CPU-Bound: Si tu aplicación realiza principalmente cálculos intensivos que consumen mucha CPU, un modelo reactivo no te dará grandes beneficios en términos de escalabilidad, ya que los hilos estarán ocupados computando, no esperando I/O. De hecho, la sobrecarga del modelo reactivo podría ser detrimental.
Aplicaciones Simples con Bajo Tráfico: Para APIs sencillas o aplicaciones internas con poca carga, la complejidad adicional de la programación reactiva puede no justificarse. El modelo síncrono de Spring MVC es a menudo más rápido de desarrollar en estos casos.
Ecosistema Bloqueante: Si dependes fuertemente de bibliotecas o tecnologías que son inherentemente bloqueantes y no tienen alternativas reactivas, adoptar WebFlux implicará wrappers o adaptadores que pueden complicar el código.

Casos Típicos/Práctica

Hilo Bloqueado vs. Hilo No Bloqueado:
- Hilo Bloqueado: Imagina un hilo pidiendo datos a una base de datos y esperando pasivamente hasta que todos los datos llegan. Durante ese tiempo, el hilo no puede hacer nada más.
- Hilo No Bloqueado: El hilo pide los datos y, en lugar de esperar, le dice a la base de datos "avísame cuando tengas los datos". Luego, el hilo queda libre para procesar otra petición. Cuando la base de datos termina, notifica a un hilo disponible para que procese los resultados.
Escenario donde WebFlux Brilla: Una API Gateway que recibe miles de peticiones por segundo, cada una de las cuales necesita hacer varias llamadas a microservicios internos (con latencia variable) y a bases de datos antes de agregar y devolver la respuesta. En este escenario, un modelo tradicional agotaría rápidamente los hilos, mientras que WebFlux, al no bloquear, puede manejar la concurrencia eficientemente con muchos menos hilos.
¿Por qué Spring creó WebFlux si ya existía Spring MVC? Spring MVC se basa en la API de Servlets, que es fundamentalmente síncrona y bloqueante en su diseño original (aunque ha evolucionado). Para ofrecer una solución de programación reactiva y no bloqueante de extremo a extremo que pudiera competir con frameworks como Node.js o Vert.x en escenarios de alta concurrencia y I/O-bound, Spring necesitaba una arquitectura desde cero que no dependiera del modelo Servlet. WebFlux nació para llenar ese vacío, proporcionando una pila web completamente reactiva construida sobre bibliotecas como Reactor y servidores no bloqueantes como Netty.

2. Project Reactor: El Corazón de WebFlux

WebFlux no implementa la programación reactiva desde cero; se apoya en una biblioteca especializada para ello: Project Reactor. Reactor es una biblioteca de programación reactiva para JVM, basada en la especificación Reactive Streams, que define un estándar para el procesamiento de flujos de datos asíncronos con "backpressure".

Teoría: Conceptos Clave de Reactor

Reactor proporciona dos tipos principales para representar flujos de datos asíncronos:

Mono: Representa un flujo reactivo que emite 0 o 1 elemento y luego se completa (o emite un error). Ideal para operaciones que devuelven un único resultado o ninguna (como guardar un registro, buscar por ID si existe, o una operación de borrado).
Flux: Representa un flujo reactivo que emite 0 a N elementos y luego se completa (o emite un error). Ideal para operaciones que pueden devolver múltiples resultados (como buscar todos los usuarios, un stream de eventos, o resultados de una consulta paginada).

Estos tipos implementan la interfaz Publisher de Reactive Streams.

El modelo de Reactor (y Reactive Streams) se basa en cuatro interfaces principales:

Publisher: Produce elementos (eventos). Es el origen de la secuencia. Solo tiene un método: subscribe(Subscriber s).
Subscriber: Consume elementos emitidos por el Publisher. Define métodos de callback:
- onSubscribe(Subscription s): Se invoca una vez cuando el Subscriber se suscribe exitosamente al Publisher. Recibe un objeto Subscription.
- onNext(T t): Se invoca para cada elemento emitido por el Publisher.
- onError(Throwable t): Se invoca si el Publisher encuentra un error. La secuencia termina.
- onComplete(): Se invoca cuando el Publisher ha terminado de emitir elementos exitosamente. La secuencia termina.
Subscription: Representa la relación entre un Publisher y un Subscriber. Permite al Subscriber gestionar el flujo de datos (pedir más elementos - backpressure) o cancelar la suscripción. Métodos clave: request(long n) y cancel().
Operator: Son funciones puras que transforman, filtran, combinan o manipulan flujos. Reciben un Publisher como entrada y devuelven un nuevo Publisher. Encadenar operadores crea un pipeline reactivo.

El Ciclo de Vida de un Stream Reactivo

El ciclo de vida es fundamental:

Un Subscriber se suscribe a un Publisher llamando a publisher.subscribe(subscriber).
El Publisher, si acepta la suscripción, llama a subscriber.onSubscribe(subscription), pasándole un objeto Subscription.
El Subscriber utiliza el objeto Subscription para solicitar elementos llamando a subscription.request(n). Esto es backpressure: el consumidor le dice al productor cuántos elementos está listo para manejar.
El Publisher emite elementos llamando a subscriber.onNext(element) hasta que se alcanzan los n elementos solicitados o se agotan los elementos disponibles.
Este proceso de request(n) y onNext(element) se repite.
Eventualmente, el Publisher terminará la secuencia llamando a subscriber.onComplete() o subscriber.onError(error). Una vez que onComplete o onError son llamados, la secuencia termina y no se emitirán más eventos. El Subscriber también puede cancelar la suscripción prematuramente llamando a subscription.cancel().

Importante: La ejecución real del flujo (el pushing de datos a través del pipeline) solo comienza cuando hay un Subscriber. Esto se conoce como lazy execution.

Operadores: ¿Qué son y por qué son importantes?

Los operadores son el poder de Reactor. Permiten construir lógica compleja sobre flujos de datos de manera declarativa y componible. Cada operador toma un Publisher de entrada y devuelve un nuevo Publisher modificado. Puedes encadenar múltiples operadores para construir una secuencia de procesamiento.

Ejemplos de categorías de operadores:

Transformación: map, flatMap, concatMap.
Filtrado: filter, take, skip.
Combinación: merge, zip, concat.
Manejo de Errores: onErrorReturn, onErrorResume, doOnError.
Utilidad: doOnNext, doOnComplete, delayElements.

Casos Típicos/Práctica

Diferencia entre Mono y Flux con ejemplos:

// Mono: Representa 0 o 1 elemento
Mono<String> greeting = Mono.just("Hola Mundo"); // Emite "Hola Mundo"
Mono<String> noValue = Mono.empty(); // Emite 0 elementos

// Flux: Representa 0 a N elementos
Flux<Integer> numbers = Flux.just(1, 2, 3, 4, 5); // Emite 1, 2, 3, 4, 5
Flux<String> greetings = Flux.fromIterable(Arrays.asList("Hello", "World", "Reactor")); // Emite "Hello", "World", "Reactor"
Flux<Long> infinite = Flux.interval(Duration.ofSeconds(1)); // Emite un número cada segundo (infinito)

Ejemplo de Uso: Usarías un Mono<User> para obtener los detalles de un usuario por su ID, y un Flux<Product> para obtener una lista de productos de una categoría.

Demostrar el uso de operadores comunes:

Flux.just(1, 2, 3, 4, 5)
    .filter(n -> n % 2 == 0) // Filtra solo números pares
    .map(n -> "Número par: " + n) // Transforma cada número en un String
    .subscribe(System.out::println); // Suscriptor que imprime cada elemento
// Salida:
// Número par: 2
// Número par: 4

Mono.just("spring")
    .map(String::toUpperCase) // Transforma a mayúsculas
    .subscribe(System.out::println); // Suscriptor
// Salida:
// SPRING

Entender bien flatMap vs map: ¡Crucial!

map: Transforma cada elemento emitido por el origen sincrónicamente en otro elemento. Si la función de mapeo devuelve un tipo reactivo (Mono o Flux), el resultado será un Flux de Monos o Fluxs anidados (un Flux<Mono<T>> o Flux<Flux<T>>), lo cual rara vez es lo que quieres.
flatMap: Transforma cada elemento emitido por el origen en un nuevo Publisher (Mono o Flux) y luego aplana (fusiona) los elementos de estos Publishers resultantes en un único Flux. Es ideal para operaciones asíncronas. El orden de los elementos resultantes no está garantizado con flatMap si las operaciones internas tardan tiempos variables.
concatMap: Similar a flatMap, pero garantiza que los Publishers internos se suscriban y emitan sus elementos en el mismo orden en que llegaron los elementos originales. Esto es útil cuando el orden es importante, pero puede ser menos eficiente que flatMap ya que espera a que cada Publisher interno termine antes de procesar el siguiente.

// Ejemplo flatMap vs map
Flux.just("Alpha", "Beta")
    .flatMap(word -> Mono.just(word.length()) // Crea un Mono con la longitud de la palabra (asíncrono o síncrono envuelto en Mono)
                       .delayElement(Duration.ofMillis(word.length() * 100))) // Simula una operación asíncrona con retraso
    .subscribe(length -> System.out.println("flatMap - Longitud: " + length));
// Posible salida (el orden puede variar debido a delayElement y flatMap):
// flatMap - Longitud: 5
// flatMap - Longitud: 4

Flux.just("Alpha", "Beta")
    .map(word -> Mono.just(word.length()) // Crea un Mono con la longitud
                       .delayElement(Duration.ofMillis(word.length() * 100)))
    .subscribe(monoLength -> monoLength.subscribe(length -> System.out.println("map - Longitud: " + length))); // Necesitas suscribirte al Mono interno!
// Salida (después de 500ms y 400ms):
// map - Longitud: 5
// map - Longitud: 4
// ¡Fíjate que map devolvió un Flux<Mono<Integer>>! Tuvimos que suscribirnos a cada Mono. flatMap lo hizo automáticamente y aplanó el resultado.

Flux.just("Alpha", "Beta")
    .concatMap(word -> Mono.just(word.length()) // Crea un Mono con la longitud
                        .delayElement(Duration.ofMillis(word.length() * 100))) // Simula operación asíncrona con retraso
    .subscribe(length -> System.out.println("concatMap - Longitud: " + length));
// Salida (el orden está garantizado por concatMap):
// concatMap - Longitud: 5  (espera 500ms)
// concatMap - Longitud: 4  (luego espera 400ms)

Secuencia que emita números y luego los transforme:

Flux.range(1, 10) // Emite números del 1 al 10
    .map(n -> n * 2) // Multiplica cada número por 2
    .filter(n -> n > 10) // Mantiene solo los resultados mayores que 10
    .subscribe(result -> System.out.println("Resultado transformado: " + result), // onNext
               error -> System.err.println("Ocurrió un error: " + error), // onError
               () -> System.out.println("Secuencia completada.")); // onComplete
// Salida:
// Resultado transformado: 12
// Resultado transformado: 14
// Resultado transformado: 16
// Resultado transformado: 18
// Resultado transformado: 20
// Secuencia completada.

¿Qué sucede si un Flux emite un error? ¿Cómo lo manejas? Cuando un Publisher emite un error a través de onError(Throwable t), la secuencia termina inmediatamente. Ningún elemento posterior será emitido. El Subscriber recibe la notificación onError, y el flujo se detiene en ese punto. Para manejar errores de forma elegante, se usan operadores de manejo de errores (los veremos en detalle en un artículo posterior), como onErrorReturn (devuelve un valor por defecto y completa), onErrorResume (cambia a un Publisher alternativo), o retry (intenta la secuencia de nuevo).

subscribeOn vs publishOn: ¡Otro concepto fundamental! Controlan la ejecución concurrente.

subscribeOn(Scheduler scheduler): Afecta el contexto de ejecución del Publisher original y toda la cadena de operadores subsiguiente hasta que se encuentra otro publishOn. Define en qué Scheduler (un ejecutor de tareas, similar a un Thread Pool) se ejecutará el trabajo del Publisher y dónde comenzará el pipeline. Si hay múltiples subscribeOn, solo el primero (el más cercano al Publisher) tiene efecto.
publishOn(Scheduler scheduler): Afecta el contexto de ejecución de los operadores que le siguen en la cadena, no los que están antes o el Publisher original. Es útil para cambiar de contexto de ejecución en medio de un pipeline, por ejemplo, para pasar del hilo rápido de I/O a un pool de hilos de trabajo para una operación intensiva en CPU. Puede haber múltiples publishOn en una cadena, cada uno afectando a la parte del pipeline que le sigue.

Scheduler ioScheduler = Schedulers.boundedElastic(); // Scheduler adecuado para I/O
Scheduler computationScheduler = Schedulers.parallel(); // Scheduler adecuado para CPU-bound

Flux.range(1, 5)
    .map(i -> {
        System.out.println("Map 1 en hilo: " + Thread.currentThread().getName());
        return i * 2;
    })
    .publishOn(computationScheduler) // Los operadores que siguen se ejecutarán aquí
    .map(i -> {
         System.out.println("Map 2 en hilo: " + Thread.currentThread().getName());
         return i + 1;
    })
    .subscribeOn(ioScheduler) // El Publisher original y todo comienza aquí (si no hay publishOn antes)
    .subscribe(result -> System.out.println("Subscripción en hilo: " + Thread.currentThread().getName() + " - Resultado: " + result));

// Posible Salida (los nombres de hilos variarán):
// Map 1 en hilo: boundedElastic-1
// Map 1 en hilo: boundedElastic-1
// Map 1 en hilo: boundedElastic-1
// Map 1 en hilo: boundedElastic-1
// Map 1 en hilo: boundedElastic-1
// Map 2 en hilo: parallel-1
// Subscripción en hilo: parallel-1 - Resultado: 3
// Map 2 en hilo: parallel-2
// Subscripción en hilo: parallel-2 - Resultado: 5
// Map 2 en hilo: parallel-3
// Subscripción en hilo: parallel-3 - Resultado: 7
// Map 2 en hilo: parallel-4
// Subscripción en hilo: parallel-4 - Resultado: 9
// Map 2 en hilo: parallel-1
// Subscripción en hilo: parallel-1 - Resultado: 11

// Observa cómo el primer map se ejecuta en el scheduler de subscribeOn (boundedElastic),
// mientras que el segundo map y la subscripción se ejecutan en el scheduler de publishOn (parallel).

Cuándo usar cada uno:
- Usa subscribeOn cerca del origen de tu stream (el Publisher que quizás interactúa con una API bloqueante envuelta o realiza una operación de I/O inicial) para asegurar que esa parte del trabajo no bloquee tus hilos principales.
- Usa publishOn para cambiar de contexto de ejecución en medio del pipeline, por ejemplo, si después de una operación de I/O (que se ejecuta en un scheduler de I/O), necesitas realizar cálculos intensivos en CPU y quieres usar un pool de hilos diferente dedicado a la computación para no saturar los hilos de I/O.

Conclusión

En esta primera parte, hemos desempacado los conceptos fundamentales que motivaron la creación de Spring WebFlux: los desafíos del bloqueo en arquitecturas tradicionales y cómo la programación reactiva, basada en flujos de datos asíncronos y no bloqueantes, ofrece una solución elegante y escalable. Hemos introducido Project Reactor como la biblioteca clave detrás de WebFlux, explorando sus tipos principales (Mono y Flux), el modelo Publisher/Subscriber/Subscription y la importancia de los operadores. Conceptos como flatMap vs map y subscribeOn vs publishOn son esenciales para dominar la programación reactiva con Reactor.

Comprender estas bases es el primer paso crucial. En la próxima entrega de esta serie, nos adentraremos en la arquitectura específica de Spring WebFlux y cómo se construyen las aplicaciones sobre este modelo reactivo, explorando el EventLoop y las diferencias arquitectónicas con Spring MVC.

¡Mantente reactivo!

Ver página completa →

Kafka 4: Procesamiento de Datos en Tiempo Real con Kafka Streams y ksqlDB

Mauricio ECR
Arquitectura
07 May, 2025

En los artículos anteriores, hemos construido una sólida comprensión de Apache Kafka: qué es, por qué es una plataforma líder para streaming de eventos, cómo está estructurado internamente con Topic

Ver página completa

Kafka 4: Procesamiento de Datos en Tiempo Real con Kafka Streams y ksqlDB

Mauricio ECR
Arquitectura
07 May, 2025

En los artículos anteriores, hemos construido una sólida comprensión de Apache Kafka: qué es, por qué es una plataforma líder para streaming de eventos, cómo está estructurado internamente con Topics, Particiones y Brokers, y cómo Productores y Consumidores interactúan con él para enviar y recibir datos. Tenemos nuestra "tubería central de datos" funcionando y los datos fluyendo.

Pero la verdadera potencia de una plataforma de streaming de eventos no reside solo en mover datos de un punto a otro de forma fiable y escalable, sino en la capacidad de procesar esos datos a medida que llegan, es decir, en tiempo real. Aquí es donde entran en juego las herramientas de procesamiento de stream del ecosistema Kafka.

Este artículo se centra en dos componentes clave que facilitan la construcción de aplicaciones de procesamiento de datos directamente sobre Kafka: Kafka Streams, una potente biblioteca cliente para construir aplicaciones de procesamiento de stream en Java/Scala, y ksqlDB, una base de datos de streaming que permite procesar datos en Kafka utilizando una sintaxis SQL familiar. Exploraremos cómo estas herramientas te permiten transformar, agregar, enriquecer y analizar tus flujos de eventos para derivar valor de tus datos en movimiento.

Kafka Streams: Construyendo Aplicaciones de Procesamiento de Stream

Kafka Streams es una biblioteca cliente para Java y Scala que te permite construir aplicaciones que procesan datos almacenados en Kafka. No es un framework de procesamiento distribuido separado (como Spark o Flink, aunque estos también se integran bien con Kafka), sino una API que se integra directamente en tu aplicación Java/Scala estándar. Despliegas tu aplicación de Kafka Streams como cualquier otra aplicación, y se conecta al clúster de Kafka para leer datos de Topics de entrada, aplicar lógica de procesamiento y escribir resultados en Topics de salida.

La potencia de Kafka Streams radica en su capacidad para manejar la complejidad inherente del procesamiento de stream distribuido (gestión de estado, tiempo de procesamiento, tolerancia a fallos) de una manera relativamente sencilla para el desarrollador.

codigo mermaid


  graph TD
      subgraph Kafka Cluster
          B[(Broker 1)]
          B2[(Broker 2)]
          B3[(Broker 3)]
      end

  subgraph Producers
      P1[Producer App 1]
      P2[Producer App 2]
  end

  subgraph Kafka Streams Application
      ST[StreamsBuilder]
      KT[KafkaStreams]
      P[Processor API]
      S[State Stores]
  end

  subgraph Consumers
      C1[Consumer App 1]
      C2[Consumer App 2]
  end

  P1 -->|publica en| B
  P2 -->|publica en| B2
  B -->|topic1| ST
  B2 -->|topic2| ST
  ST --> KT
  KT -->|procesa| P
  P -->|escribe en| S
  KT -->|escribe en| B3
  B3 -->|topic-output| C1
  B3 -->|topic-output| C2

  classDef kafka fill:#f9f,stroke:#333;
  classDef app fill:#bbf,stroke:#333;
  classDef stream fill:#9f9,stroke:#333;
  class B,B2,B3,Z kafka;
  class P1,P2,C1,C2 app;
  class ST,KT,P,S stream;

Topologías: Streams, Tablas y State Stores

Kafka Streams introduce una abstracción fundamental para representar y procesar datos:

Stream (KStream): Representa un flujo ilimitado de eventos inmutables. Piensa en un KStream como el log de commits de Kafka que has estado leyendo: una secuencia de eventos que ocurren a lo largo del tiempo. Cuando procesas un KStream, la lógica se aplica a cada evento individual a medida que llega.
Table (KTable): Representa una vista materializada de un KStream o de un Topic. A diferencia de un KStream que representa la historia completa de eventos, una KTable representa el estado actual de la clave en el momento más reciente. Por ejemplo, un KStream podría contener todos los eventos de "actualización de saldo de cuenta", mientras que una KTable derivada de ese stream contendría el saldo actual de cada cuenta. Cuando llega un nuevo evento para una clave en un KTable, actualiza el valor existente para esa clave.
State Stores: Para realizar operaciones con estado (como agregaciones o joins) que requieren recordar información de eventos pasados, Kafka Streams utiliza State Stores. Son bases de datos clave-valor locales (a menudo RocksDB, aunque configurables) asociadas a cada instancia de la aplicación de Kafka Streams. El estado se gestiona localmente para cada tarea de procesamiento de la aplicación, se mantiene sincronizado con réplicas en Kafka para tolerancia a fallos y se reestablece automáticamente en caso de fallos o rebalanceos.

Esta dualidad Stream/Table es clave. Puedes convertir un KStream en un KTable (por ejemplo, para obtener el último valor por clave) y viceversa (por ejemplo, para ver un stream de cambios en una tabla).

Operaciones: map, filter, aggregate, join y Más

Kafka Streams proporciona una rica API funcional para definir la lógica de procesamiento como una topología de procesadores conectados. Algunas operaciones comunes incluyen:

Transformaciones sin estado: map (transforma el valor de cada registro), filter (excluye registros que no cumplen una condición), flatMap (produce cero, uno o más registros de salida por cada registro de entrada), etc.
Transformaciones con estado:
- Agregaciones: groupByKey, count, reduce, aggregate. Estas operaciones acumulan o combinan valores a lo largo del tiempo para una clave específica, manteniendo el estado en un State Store.
- Joins: join (une dos streams o un stream y una tabla basándose en una clave), leftJoin, outerJoin. Las operaciones de join a menudo requieren que uno o ambos lados del join mantengan estado (en State Stores) para poder encontrar coincidencias.
Ventanas (Windows): Las agregaciones y joins se realizan a menudo dentro de ventanas de tiempo (por ejemplo, contar eventos por minuto, unir eventos que ocurren en un lapso de 5 segundos). Kafka Streams soporta diferentes tipos de ventanas (ventanas de tiempo fijas, deslizantes, de sesión) y maneja la complejidad del tiempo de evento y tiempo de procesamiento.

Exactly-once Processing

Basándose en las capacidades transaccionales de Kafka (mencionadas en el Artículo 3), Kafka Streams puede ofrecer semántica de procesamiento exactly-once de extremo a extremo. Esto significa que cada evento se procesa exactamente una vez, y las actualizaciones de estado resultantes y los mensajes de salida se publican de forma atómica. Si una instancia de la aplicación falla, se reinicia y reanuda el procesamiento desde donde lo dejó sin perder ni duplicar datos, siempre y cuando los orígenes y destinos sean Topics de Kafka. Esto se habilita configurando processing.guarantee=exactly_once_v2.

KSQL (ahora ksqlDB): Streaming con Sintaxis SQL

ksqlDB (anteriormente KSQL) es una base de datos de streaming distribuida construida sobre Kafka. Permite a los desarrolladores definir aplicaciones de procesamiento de stream de forma interactiva utilizando una sintaxis similar a SQL, eliminando la necesidad de escribir código en Java o Scala para muchos casos de uso comunes.

codigo mermaid


    graph TD
        subgraph Kafka Cluster
            B[(Broker 1)]
            B2[(Broker 2)]
            B3[(Broker 3)]
        end

    subgraph Data Sources
        DB[(Database)]
        API[Rest API]
        IoT[IoT Devices]
    end

    subgraph ksqlDB Server
        KSQL[ksqlDB Engine]
        KQ[Queries Persistentes]
        KS[Streams]
        KT[Tables]
    end

    subgraph Consumers
        DASH[Dashboard]
        ALERTS[Alert System]
        DW[Data Warehouse]
    end

    DB -->|Debezium CDC| B
    API -->|Kafka Connect| B2
    IoT -->|MQTT Proxy| B3
    B --> KSQL
    B2 --> KSQL
    B3 --> KSQL
    KSQL -->|Crea| KS
    KSQL -->|Crea| KT
    KSQL -->|Ejecuta| KQ
    KQ -->|Escribe| B2
    B2 --> DASH
    B3 --> ALERTS
    B --> DW

    classDef kafka fill:#f9f,stroke:#333;
    classDef source fill:#f96,stroke:#333;
    classDef ksql fill:#6af,stroke:#333;
    classDef consumer fill:#6f6,stroke:#333;
    class B,B2,B3 kafka;
    class DB,API,IoT source;
    class KSQL,KQ,KS,KT ksql;
    class DASH,ALERTS,DW consumer;

ksqlDB es ideal para:

Transformación de datos (ETL ligero en tiempo real).
Enriquecimiento de datos (unir un stream de eventos con datos de referencia en una tabla).
Filtrado y enrutamiento de datos.
Agregaciones y análisis en tiempo real.
Creación de vistas materializadas (tablas) sobre streams de eventos.

Consultas Push/Pull

ksqlDB soporta dos tipos de consultas:

Consultas Push (Push Queries): Son consultas continuas que se ejecutan indefinidamente. Producen resultados en tiempo real a medida que llegan nuevos eventos a los Topics de entrada. Se usan típicamente para crear nuevos streams o tablas persistentes basadas en transformaciones, filtros o agregaciones de otros streams/tablas.
Consultas Pull (Pull Queries): Son consultas puntuales que se ejecutan una vez y retornan el estado actual de una tabla hasta el momento en que se ejecutó la consulta. Son útiles para obtener el valor actual de una clave o un agregado de una tabla (vista materializada).

Creación de Streams y Tablas

La sintaxis de ksqlDB es muy intuitiva para cualquiera familiarizado con SQL. Puedes definir STREAMS y TABLES sobre Topics de Kafka existentes y luego usar sentencias CREATE STREAM AS SELECT ... o CREATE TABLE AS SELECT ... para definir transformaciones continuas:

-- Crear un Stream a partir de un Topic existente
CREATE STREAM clicks (user_id VARCHAR, url VARCHAR, timestamp BIGINT)
  WITH (kafka_topic='user-clicks', value_format='json', timestamp='timestamp');

-- Filtrar y proyectar datos de un Stream y enviarlos a un nuevo Topic
CREATE STREAM high_value_clicks AS
  SELECT user_id, url
  FROM clicks
  WHERE user_id IN ('user123', 'user456');

-- Crear una Tabla (vista materializada) a partir de un Stream para contar clics por usuario
CREATE TABLE click_counts AS
  SELECT user_id, COUNT(*)
  FROM clicks
  GROUP BY user_id;

-- Realizar una consulta Pull sobre la Tabla
SELECT * FROM click_counts WHERE user_id = 'user789';

Uso en Tiempo Real (ej: Detección de Anomalías)

ksqlDB es excelente para casos de uso de tiempo real relativamente sencillos como la detección de anomalías. Por ejemplo, podrías definir una tabla que cuente el número de eventos sospechosos por usuario en una ventana de 5 minutos, y luego consultar esa tabla para alertar si el recuento excede un umbral. O podrías unir un stream de transacciones con una tabla de información de clientes para identificar transacciones inusualmente grandes para clientes nuevos.

Aunque no es tan flexible o potente como Kafka Streams para lógica de procesamiento muy compleja, ksqlDB permite a los desarrolladores y analistas de datos interactuar con Kafka y procesar streams de forma ágil utilizando una interfaz declarativa.

Conclusión

En este artículo, hemos explorado cómo ir más allá de la simple ingesta y distribución de datos en Kafka para procesarlos activamente en tiempo real. Introducimos Kafka Streams como una biblioteca robusta para construir aplicaciones de procesamiento de stream con manejo de estado y garantías exactly-once, y ksqlDB como una interfaz SQL-like accesible para realizar transformaciones y agregaciones sobre streams de forma interactiva.

Estas herramientas nativas del ecosistema Kafka empoderan a los desarrolladores para construir arquitecturas reactivas y basadas en eventos donde el procesamiento de datos ocurre continuamente a medida que los eventos fluyen, en lugar de depender de procesamiento por lotes retrasado. Ya sea que necesites construir pipelines ETL en tiempo real, aplicaciones de monitoreo o sistemas de detección de fraude, Kafka Streams y ksqlDB ofrecen las capacidades necesarias.

Ahora que tenemos una comprensión sólida de la arquitectura de Kafka, cómo interactuar con ella (Productores/Consumidores) y cómo procesar los datos en tiempo real, es momento de mirar las herramientas y plataformas que complementan a Kafka y amplían sus capacidades, así como algunas alternativas notables en el espacio del streaming de datos. En el próximo artículo, exploraremos Confluent Platform y otras herramientas clave del ecosistema Kafka.

Ver página completa →

Exploración Profunda de Kubernetes: Componentes Clave y Principios Fundamentales

Mauricio ECR
DevOps
06 May, 2025

En el panorama tecnológico actual, caracterizado por arquitecturas de microservicios y despliegues en la nube, la gestión efectiva de aplicaciones contenedorizadas es un desafío crítico. Kubernetes su

Ver página completa

Kafka 3: Productores y Consumidores, Configuración y Buenas Prácticas

Mauricio ECR
Arquitectura
05 May, 2025

Hemos navegado por los conceptos esenciales de Apache Kafka y desentrañado la arquitectura que reside bajo la superficie, comprendiendo cómo los Topics se dividen en Particiones distribuidas entre Bro

Ver página completa

Kafka 2: Arquitectura Profunda de Kafka, Topics, Particiones y Brokers

Mauricio ECR
Arquitectura
04 May, 2025

En nuestro primer artículo, despegamos en el mundo de Apache Kafka, sentando las bases de lo que es esta potente plataforma de streaming de eventos y diferenciándola de los sistemas de mensajería trad

Ver página completa

Kafka 2: Arquitectura Profunda de Kafka, Topics, Particiones y Brokers

Mauricio ECR
Arquitectura
04 May, 2025

En nuestro primer artículo, despegamos en el mundo de Apache Kafka, sentando las bases de lo que es esta potente plataforma de streaming de eventos y diferenciándola de los sistemas de mensajería tradicionales. Comprendimos su propósito fundamental como una “tubería central de datos” que permite desacoplar productores y consumidores, manejando flujos de eventos a gran escala con alta disponibilidad.

Ahora que tenemos esa visión general, es momento de adentrarnos en el corazón de la bestia. ¿Cómo logra Kafka esa escalabilidad masiva, esa tolerancia a fallos y ese alto rendimiento? La respuesta reside en su arquitectura interna distribuida. Este segundo artículo nos llevará a través de los componentes fundamentales que dan vida a un clúster de Kafka: los Topics donde se organizan los datos, las Particiones que permiten paralelizar la lectura y escritura, y los Brokers, los nodos servidores que almacenan y gestionan los datos. También exploraremos la evolución reciente en la gestión del clúster con la llegada de KRaft, la alternativa nativa que busca reemplazar a ZooKeeper.

Comprender la interacción entre estos elementos es crucial no solo para entender cómo funciona Kafka a bajo nivel, sino también para diseñar sistemas que lo aprovechen de manera eficiente, optimizar su rendimiento y resolver problemas comunes. Prepárate para desmontar la “tubería” y ver sus engranajes internos.

codigo mermaid


    graph TD
        %% Elementos principales con agrupaciones
        Producer[Productor] -->|envía mensajes| Cluster
        
    subgraph Cluster[Cluster Kafka]
        subgraph Broker1[Broker 1]
            subgraph TopicA1[Tópico A]
                PA0[Partición 0]
                PA1[Partición 1]
            end
            subgraph TopicB1[Tópico B]
                PB0[Partición 0]
            end
        end
        
        subgraph Broker2[Broker 2]
            subgraph TopicA2[Tópico A]
                PA2[Partición 2]
            end
            subgraph TopicB2[Tópico B]
                PB1[Partición 1]
                PB2[Partición 2]
            end
        end
        
        subgraph Broker3[Broker 3]
            subgraph TopicA3[Tópico A]
                PA3[Partición 3]
            end
        end
    end
        subgraph Grupo B[Topic B: Grupo 2]
        PB0 --> Consumer5[Consumidor 5]
        PB1 --> Consumer6[Consumidor 6]
        PB2 --> Consumer7[Consumidor 7]
    end
    subgraph Grupo A[Topic A: Grupo 1]
        %% Conexiones de consumidores
        PA0 --> Consumer1[Consumidor 1]
        PA1 --> Consumer2[Consumidor 2]
        PA2 --> Consumer3[Consumidor 3]
        PA3 --> Consumer4[Consumidor 4]
    end

    
    

    
    %% Estilos mejorados
    style Producer fill:#4CAF50,stroke:#333,color:white
    style Cluster fill:#f5f5f5,stroke:#333,stroke-width:2px
    style Broker1 fill:#E1F5FE,stroke:#0288D1
    style Broker2 fill:#E1F5FE,stroke:#0288D1
    style Broker3 fill:#E1F5FE,stroke:#0288D1
    style TopicA1 fill:#B3E5FC,stroke:#0288D1
    style TopicB1 fill:#B3E5FC,stroke:#0288D1
    style PA0 fill:#FFECB3,stroke:#FFA000

Topics y Particiones: La Organización y Paralelismo de Datos

En Kafka, los eventos no se lanzan a un pozo sin fondo. Se organizan en categorías lógicas llamadas Topics. Piensa en un Topic como una fuente de datos particular, por ejemplo, ordenes-de-compra, clicks-web o lecturas-sensores. Los productores escriben eventos en Topics específicos, y los consumidores leen eventos de Topics a los que se han suscrito.

La magia para la escalabilidad y el paralelismo ocurre dentro de cada Topic. Un Topic se divide en una o más Particiones. Cada Partición es un log de eventos secuencial, inmutable y ordenado. Cuando un productor escribe un evento en un Topic, este se añade a una de las Particiones de ese Topic.

El uso de Particiones tiene implicaciones fundamentales:

Paralelismo: Las Particiones son la unidad de paralelismo tanto para productores como para consumidores. Múltiples productores pueden escribir en diferentes particiones de un mismo Topic simultáneamente. Más importante aún, múltiples consumidores dentro de un mismo Consumer Group (que veremos en detalle en el próximo artículo) pueden leer datos de diferentes particiones en paralelo, escalando así la capacidad de consumo.
Orden: Dentro de una misma Partición, Kafka garantiza que los eventos se almacenan y se entregan a los consumidores en el orden en que fueron escritos. Sin embargo, el orden no está garantizado a través de diferentes Particiones de un Topic. Si el orden global es crítico (por ejemplo, para eventos relacionados con una misma cuenta de usuario), debes asegurarte de que todos esos eventos vayan a la misma partición.
Escalabilidad Horizontal: A medida que el volumen de datos de un Topic crece o necesitas más consumidores para procesar los datos más rápido, puedes aumentar el número de Particiones (aunque reconfigurar particiones existentes en producción puede ser complejo). Un mayor número de particiones permite que más consumidores en paralelo procesen datos.

Configuración Clave: `num.partitions` y `replication.factor`

Al crear un Topic, hay dos configuraciones esenciales que debes definir:

num.partitions: El número inicial de particiones para el Topic. Elegir el número correcto es importante; pocas particiones limitan el paralelismo, mientras que demasiadas pueden aumentar la sobrecarga de gestión tanto para Kafka como para los clientes.
replication.factor: El número de copias de cada partición que Kafka mantendrá a través de diferentes brokers. Un factor de replicación de 3 significa que cada partición tendrá 3 copias (una copia original y dos réplicas) distribuidas en el clúster. Esto es crucial para la tolerancia a fallos. Si un broker que contiene una réplica falla, las otras réplicas garantizan que los datos no se pierdan y sigan estando disponibles.

Estrategias de Particionamiento

Cuando un productor envía un mensaje a un Topic, Kafka debe decidir a qué Partición enviarlo. La estrategia de particionamiento se define en el productor. Las estrategias más comunes son:

Por Clave (Key-based): Si el mensaje incluye una clave (key), el productor por defecto utiliza un hash de esa clave para determinar la partición. Esto asegura que todos los mensajes con la misma clave (ej: un ID de usuario, un ID de producto) siempre irán a la misma partición. Esto es fundamental si necesitas procesar eventos relacionados con una entidad específica en orden.
Round-Robin: Si el mensaje no tiene clave, o si se configura explícitamente, el productor distribuirá los mensajes de forma equitativa entre todas las particiones disponibles del Topic. Esto ayuda a distribuir la carga de escritura de manera uniforme.
Personalizado: Puedes implementar tu propia lógica de particionamiento si las estrategias por defecto no se ajustan a tus necesidades.

Replicación (ISR - In-Sync Replicas)

Como mencionamos, la replicación es clave para la tolerancia a fallos. Cada partición tiene una Réplica Líder (Leader Replica) y cero o más Réplicas Seguidoras (Follower Replicas). Todas las escrituras y lecturas para una partición específica siempre pasan por la Réplica Líder. Las Réplicas Seguidoras simplemente copian los datos del Líder de forma asíncrona pero continua.

Kafka utiliza el concepto de In-Sync Replicas (ISR). El ISR es el conjunto de réplicas (incluyendo la líder) que están completamente sincronizadas con la Réplica Líder de una partición. Es decir, han replicado todos los mensajes que han sido confirmados (committed) por la líder hasta un cierto punto. Kafka garantiza que un mensaje sólo se considera “committed” (es decir, no se perderá) si ha sido replicado por todas las réplicas en el ISR.

Si la Réplica Líder falla, Kafka elegirá automáticamente una nueva Réplica Líder de entre las Réplicas que están en el ISR. Esto garantiza que la nueva líder tiene todos los datos confirmados, evitando la pérdida de datos. Si una réplica seguidora se retrasa demasiado o falla, es eliminada temporalmente del ISR hasta que se ponga al día o se recupere. Configurar adecuadamente el factor de replicación y monitorizar el estado del ISR es vital para la durabilidad de los datos y la disponibilidad del clúster.

Brokers y Clúster: Los Servidores de Kafka

Un clúster de Kafka se compone de uno o más servidores, conocidos como Brokers. Cada Broker es una instancia de la aplicación Kafka que se ejecuta en una máquina física o virtual.

Los Brokers son los nodos de almacenamiento y servicio del clúster. Cada Broker:

Almacena una o más Particiones de diferentes Topics.
Responde a las solicitudes de productores para escribir datos en particiones de las que es líder.
Responde a las solicitudes de consumidores para leer datos de particiones de las que es líder.
Sincroniza datos entre las réplicas líderes y seguidoras que aloja.

Roles: Líder y Seguidor (Leader/Follower)

Como vimos con las Particiones, los Brokers asumen roles de Líder o Seguidor para las réplicas de las particiones que albergan. Un Broker puede ser el líder para algunas particiones y el seguidor para otras. Esta distribución de liderazgo entre los brokers es lo que permite el balanceo de carga; la carga de trabajo de escritura y lectura para un Topic dado se distribuye entre los Brokers que son líderes para sus particiones.

Balanceo de Carga y Escalabilidad

La escalabilidad horizontal del clúster se logra añadiendo o eliminando Brokers. Cuando añades un nuevo Broker, Kafka puede (con ayuda de herramientas de administración o manualmente) redistribuir réplicas de particiones existentes al nuevo Broker. También puede transferir el liderazgo de algunas particiones al nuevo Broker. Esto equilibra la carga de trabajo de escritura y lectura entre los Brokers y aumenta la capacidad total del clúster.

ZooKeeper vs. KRaft (Kafka Raft): El Cerebro del Clúster

Hasta hace poco, Kafka dependía externamente de Apache ZooKeeper para gestionar el estado del clúster. ZooKeeper es un servicio de coordinación distribuida que Kafka utilizaba para:

Mantener la lista de brokers activos en el clúster.
Manejar la elección del controlador (un broker especial que gestiona el estado de particiones y réplicas).
Almacenar metadatos sobre Topics, Particiones y la asignación de réplicas a brokers.
Gestionar la elección de líderes de partición.

Sin embargo, la dependencia de ZooKeeper presentaba algunos desafíos:

Complejidad Operacional: Requería desplegar y gestionar un clúster de ZooKeeper separado, añadiendo una capa de complejidad.
Escalabilidad Limitada: ZooKeeper puede convertirse en un cuello de botella en clústeres muy grandes (miles de particiones).
Versiones Acopladas: La compatibilidad entre versiones de Kafka y ZooKeeper a veces era un problema.

Para abordar estos problemas, la comunidad de Kafka ha estado trabajando en la eliminación de la dependencia de ZooKeeper, introduciendo un nuevo modo de consenso nativo llamado KRaft (Kafka Raft).

Introducción a KRaft (modo consensus nativo)

KRaft implementa un protocolo de consenso basado en Raft (similar al que usan sistemas como etcd o Consul) directamente dentro de los brokers de Kafka. En un clúster KRaft, un subconjunto de brokers asume el rol de Controlador (Controller) y gestiona el estado del clúster utilizando el protocolo Raft. Estos brokers controladores forman un quorum. El líder del quorum se encarga de tomar decisiones sobre la gestión del clúster (elección de líderes de partición, gestión de brokers, etc.).

Los beneficios de KRaft incluyen:

Simplificación: Elimina la necesidad de un clúster de ZooKeeper separado, reduciendo la complejidad de despliegue y operación.
Mejor Escalabilidad: Diseñado para escalar a clústeres de Kafka mucho más grandes.
Arranque Más Rápido: Los clústeres KRaft generalmente se inician más rápido.
Arquitectura Unificada: La lógica de gestión del clúster reside ahora dentro de los propios brokers de Kafka.

Aunque Kafka aún soporta el modo basado en ZooKeeper por compatibilidad, KRaft es el futuro y el modo recomendado para nuevas instalaciones.

Conclusión

Hemos realizado una inmersión profunda en la arquitectura interna de Apache Kafka, explorando los conceptos fundamentales de Topics, Particiones y Brokers que son la columna vertebral de su capacidad de procesamiento de datos a gran escala. Entendimos cómo las Particiones permiten el paralelismo y la ordenación dentro de un log inmutable, cómo la replicación y el concepto de ISR garantizan la durabilidad y disponibilidad de los datos, y cómo los Brokers actúan como los servidores que alojan y gestionan estos componentes distribuidos. Finalmente, vimos la importante transición hacia KRaft, que simplifica la arquitectura al integrar la gestión del clúster dentro de los propios brokers.

Comprender esta arquitectura es fundamental para cualquier persona que trabaje con Kafka, ya que influye directamente en cómo se diseñan los sistemas, cómo se optimiza el rendimiento y cómo se garantiza la resiliencia. Con estos conocimientos arquitectónicos en mente, estamos listos para pasar al siguiente nivel: interactuar con el clúster. En el próximo artículo, exploraremos en detalle a los actores principales que se conectan a Kafka: los Productores que escriben datos y los Consumidores que los leen, así como sus configuraciones clave y buenas prácticas.

Ver página completa →

Kafka 1: Introducción a Apache Kafka, fundamentos y Casos de Uso

Mauricio ECR
Arquitectura
03 May, 2025

En el panorama tecnológico actual, los datos son el motor que impulsa la innovación. La capacidad de procesar, reaccionar y mover grandes volúmenes de datos en tiempo real se ha convertido en una nece

Ver página completa

RabbitMQ 6: Alta Disponibilidad y Escalabilidad con Clustering en RabbitMQ

Mauricio ECR
Arquitectura
01 May, 2025

Hasta ahora, hemos hablado de cómo un nodo individual de RabbitMQ maneja mensajes, gestiona colas, y cómo monitorizar su rendimiento y seguridad. Sin embargo, para aplicaciones críticas que no pueden

Ver página completa

RabbitMQ 5: Consumo de Recursos, Latencia y Monitorización de RabbitMQ

Mauricio ECR
Arquitectura
29 Apr, 2025

Hemos explorado la teoría detrás de RabbitMQ, su arquitectura, cómo enruta mensajes y cómo podemos construir sistemas robustos y seguros. Sin embargo, para operar RabbitMQ de manera efectiva en produc

Ver página completa

RabbitMQ 5: Consumo de Recursos, Latencia y Monitorización de RabbitMQ

Mauricio ECR
Arquitectura
29 Apr, 2025

Hemos explorado la teoría detrás de RabbitMQ, su arquitectura, cómo enruta mensajes y cómo podemos construir sistemas robustos y seguros. Sin embargo, para operar RabbitMQ de manera efectiva en producción, necesitamos entender cuántos recursos consume, qué esperar en términos de latencia de los mensajes y, lo más importante, cómo vigilarlo y gestionarlo activamente.

Este artículo se sumerge en estos aspectos prácticos, brindándote la información necesaria para dimensionar tu infraestructura, gestionar expectativas sobre el rendimiento y mantener tu broker funcionando sin problemas.

Consumo de Recursos e Implementación

El "costo" de ejecutar RabbitMQ, principalmente en términos de CPU, memoria RAM y espacio en disco, no es fijo. Varía significativamente en función de varios factores clave:

Factores que Influyen en el Consumo

Carga (Throughput): El factor más obvio. Un alto volumen de mensajes publicados y entregados por segundo requiere más CPU y red para procesar las operaciones.
Número de Colas y Exchanges: Aunque los recursos por cola/exchange inactivos son bajos, un gran número de ellos (miles o decenas de miles) puede aumentar la carga de gestión interna del broker y el consumo de memoria. Esto es especialmente cierto si hay muchas conexiones y bindings activos asociados a estos elementos.
Persistencia de Mensajes y Durabilidad de Colas:
- Los mensajes persistentes (en colas duraderas) requieren escrituras a disco para asegurar que no se pierdan en caso de fallo del broker. Esto consume I/O de disco y puede ser un cuello de botella importante si el volumen es alto y el disco subyacente es lento.
- Las colas duraderas requieren que su estado (configuración, mensajes en cola, estado de consumidores) sea guardado persistentemente.
- Usar mensajes persistentes aumenta significativamente la demanda de recursos de disco y puede reducir el throughput máximo comparado con mensajes no persistentes.
Número de Conexiones y Canales: Cada conexión de cliente TCP y cada canal AMQP asociado consumen memoria en el broker para mantener su estado. Un gran número de clientes conectados (cientos o miles) puede sumar un consumo notable de RAM, incluso si la tasa de mensajes no es extremadamente alta.
Tamaño de los Mensajes: Mensajes más grandes consumen más ancho de banda de red al ser transferidos entre productores/consumidores y el broker. También consumen más memoria y/o disco al ser transferidos y almacenados temporalmente en el broker o en las colas.
Uso de Características Avanzadas: Características como prioridades de mensajes (x-max-priority), TTLs (x-message-ttl), o Dead-Lettering añaden algo de overhead de procesamiento interno en el broker para gestionar la lógica asociada.

Ejemplos de Carga y Consideraciones de Dimensionamiento

No hay una "calculadora" única y precisa para dimensionar RabbitMQ que funcione en todos los casos, ya que depende mucho de los factores anteriores y del hardware subyacente. Sin embargo, aquí hay algunas pautas generales basadas en la experiencia común:

Mensajes/s	Tamaño Msg (bytes)	CPU Cores	RAM (GB)	Disco (IOPS / MB/s)	Ancho de Banda
100	512	1	1	50 IOPS / 1 MB/s	~0.4 Mbps
1,000	1,024 (1 KB)	2	2	100 IOPS / 5 MB/s	~8 Mbps
5,000	2,048 (2 KB)	4	4	200 IOPS / 20 MB/s	~80 Mbps
10,000	4,096 (4 KB)	6	6	400 IOPS / 40 MB/s	~320 Mbps
50,000	4,096 (4 KB)	8–12	12–16	1,000 IOPS / 200 MB/s	~1.6 Gbps
100,000	8,192 (8 KB)	16+	32+	2,000+ IOPS / 800 MB/s	~6.4 Gbps

🔍 Notas / Supuestos:

Se asume que la persistencia está activada (uso típico).

Uso de colas clásicas (classic queues) sin clustering.

No se consideran configuraciones con replicación (HA) o federation.

Basado en RabbitMQ 3.11+.

Los mensajes tienen TTL o se procesan rápidamente (sin grandes acumulaciones).

Red de baja latencia.

Estrategias para Optimizar el Uso de Recursos

Minimizar la Persistencia: Usa persistencia solo para los mensajes y colas donde la pérdida sea inaceptable. Los mensajes no persistentes son mucho más rápidos y consumen significativamente menos recursos de disco y CPU asociados al I/O.
Mantener las Colas Cortas: Idealmente, los consumidores deben procesar mensajes tan rápido como llegan. Colas que crecen indefinidamente son un signo de contrapresión (la tasa de producción excede la de consumo) y consumen progresivamente más RAM y eventualmente pagan a disco. Usa límites de cola (x-max-length, x-max-length-bytes) para proteger el broker de crecimientos descontrolados.
Optimizar el Prefetch (QoS): Ajusta el prefetch de los consumidores. Un prefetch muy alto puede hacer que un consumidor acapare muchos mensajes en memoria, potencialmente agotando la RAM del consumidor y reduciendo el throughput si no puede procesarlos rápido. Un prefetch muy bajo (ej. 1) puede reducir el throughput total al esperar la confirmación de cada mensaje. Encuentra un balance óptimo para tu carga, el rendimiento de tus consumidores y la latencia deseada.
Limitar Conexiones/Canales: Si es posible, reutiliza conexiones y canales en tus aplicaciones cliente en lugar de crear nuevos para cada operación. Mantener miles de conexiones efímeras puede ser costoso en recursos para el broker.
Dimensionar el Disco Correctamente: Si usas persistencia o esperas colas largas (aunque esto último es una señal de alerta), invierte en discos SSD rápidos y con suficiente espacio para manejar tanto los mensajes en cola como los archivos de paginación y logs. La velocidad del disco impacta directamente el throughput y la latencia con persistencia.
Monitorizar y Ajustar: Usa las métricas de RabbitMQ de forma constante para identificar cuellos de botella (I/O de disco alto, uso de CPU elevado, crecimiento persistente de colas, alta latencia, número excesivo de conexiones/canales) y ajusta tu configuración o escala tu infraestructura en consecuencia.

Latencia Esperada en los Mensajes

La latencia de un mensaje es el tiempo que tarda desde que un productor lo publica hasta que un consumidor lo recibe (y potencialmente lo procesa). No es cero, ya que implica varias etapas y tránsitos por la red y el broker.

La latencia total se puede conceptualizar aproximadamente como la suma de los tiempos en cada etapa:

$ Latencia_{Total} = Latencia_{Red} (Productor => Broker) + Tiempo_{Broker} (Enrutamiento, Encolamiento, Persistencia) + Latencia_{Red} (Broker => Consumidor) + Tiempo_{Procesamiento} (Consumidor) $

Nos centraremos en los factores que afectan el tiempo que el mensaje pasa dentro o viajando hacia/desde el broker. Varios factores afectan esta latencia:

Factores que Afectan la Latencia

Carga del Broker: Un broker bajo alta carga (muchos mensajes, muchas conexiones, I/O de disco saturado) tardará más en procesar mensajes y entregarlos. Las operaciones se encolan internamente.
Tamaño del Mensaje: Mensajes más grandes tardan más en viajar por la red y ser procesados por el broker y los clientes (serialización/deserialización).
Persistencia: Publicar y encolar mensajes persistentes es significativamente más lento que con mensajes no persistentes, ya que requiere que el broker espere la confirmación de escritura a disco antes de reconocer la publicación al productor (si se usan confirmaciones de editor) y antes de considerarlo seguro en la cola. Esto añade latencia.
Red: La latencia intrínseca de la red entre productores, el broker y consumidores es un componente directo y, a menudo, incontrolable si los componentes están distribuidos geográficamente. Brokers y aplicaciones en diferentes centros de datos o regiones tendrán mayor latencia de red.
QoS (Prefetch): Un prefetch bajo (ej. 1) puede aumentar la latencia percibida entre mensajes para un mismo consumidor, ya que debe confirmar cada mensaje antes de recibir el siguiente. Un prefetch más alto reduce esta latencia inter-mensaje, pero puede aumentar el tiempo que un mensaje espera en el buffer del consumidor antes de ser procesado, aumentando su latencia dentro del consumidor.
Número de Hops (Enrutamiento): Mensajes que son enrutados a través de múltiples Exchanges encadenados (topologías avanzadas con shovel o federation o simples bindings secuenciales) pueden experimentar latencia adicional en cada paso de enrutamiento interno o entre brokers.
Paginación a Disco: Si las colas crecen y los mensajes que no caben en RAM se paginan a disco, la latencia para acceder a ellos cuando un consumidor los solicita aumenta drásticamente. Acceder a disco es mucho más lento que acceder a RAM.

Latencias Típicas Esperadas

Las latencias varían ampliamente, pero aquí hay un rango esperado bajo diferentes escenarios:

Configuración Optimizada, Baja Carga, Mensajes Pequeños y No Persistentes, Red Rápida: Latencia muy baja, a menudo en el rango de pocos milisegundos. Este es el mejor escenario.
Configuración Típica, Carga Moderada, Mensajes Persistentes, Red Estándar: Latencia moderada, probablemente en el rango de decenas o cientos de milisegundos. La persistencia suele ser el factor dominante aquí.
Alta Carga, I/O de Disco Saturado, Colas Largas, Paginación Activa: Latencia puede dispararse a varios segundos o incluso más. Esto indica un problema grave de rendimiento o dimensionamiento.

Estrategias para Minimizar la Latencia Cuando es Crítico

Usar Mensajes No Persistentes: Si la pérdida ocasional de mensajes es aceptable y la latencia es crítica (ej. datos de monitorización no vitales, notificaciones efímeras), usa mensajes no persistentes. Son significativamente más rápidos.
Mantener Colas Cortas: Asegura que los consumidores procesen mensajes rápidamente para evitar que las colas se alarguen y los mensajes se paginen. Escalar el número de consumidores es la estrategia clave contra la contrapresión.
Optimizar el Prefetch: Experimenta con el prefetch para encontrar el equilibrio adecuado que mantenga a tus consumidores ocupados sin sobrecargarlos ni acaparar mensajes innecesariamente.
Hardware Rápido: Usa servidores con CPU potente (para el procesamiento interno), mucha RAM (para colas en memoria) y discos SSD muy rápidos (crítico si usas persistencia) para minimizar los tiempos de procesamiento del broker.
Red de Baja Latencia: Coloca el broker y los consumidores/productores en la misma red o lo más cerca posible geográficamente para minimizar la latencia de red.
Evitar Enrutamiento Complejo Innecesario: Si una topología de enrutamiento simple es suficiente, úsala en lugar de cadenas complejas de Exchanges, ya que cada paso añade una pequeña sobrecarga.
Monitorizar la Latencia: Mide la latencia de extremo a extremo de tus mensajes en tus aplicaciones (productor -> broker -> consumidor -> procesamiento) para identificar cuellos de botella reales. Las métricas del broker te dirán cuánto tiempo pasa dentro de RabbitMQ.

Es importante recordar que RabbitMQ está diseñado principalmente para la comunicación asíncrona, el desacoplamiento de servicios y la entrega confiable (especialmente con persistencia), optimizando el throughput (mensajes por segundo) sobre la latencia ultrabaja. Si necesitas latencias de microsegundos y comunicación estrictamente síncrona, RabbitMQ podría no ser la herramienta adecuada; la comunicación directa via RPC o protocolos especializados de baja latencia serían más apropiados.

Monitorización y Gestión de RabbitMQ

Una vez que RabbitMQ está funcionando, la monitorización activa y la gestión son vitales para asegurar su salud, rendimiento, prever problemas y solucionarlos rápidamente cuando ocurren.

Uso Exhaustivo de la Interfaz de Administración Web

La interfaz web de gestión (Management Plugin) es una herramienta invaluable para la inspección manual del estado del broker. Se accede típicamente a través del puerto 15672 (asegúrate de que esté accesible solo desde redes de administración seguras). Permite visualizar:

Overview: Métricas generales y gráficos de alto nivel como mensajes publicados/entregados por segundo, uso de memoria/disco, número de conexiones/canales, y estado del cluster.
Connections: Listado de todas las conexiones activas, desde qué host se originan, qué usuario las estableció, qué vhost están usando, etc. Puedes cerrarlas forzadamente si es necesario.
Channels: Detalles de los canales AMQP dentro de cada conexión, incluyendo el prefetch configurado y los mensajes no confirmados.
Exchanges: Listado de todos los Exchanges declarados, su tipo (direct, fanout, topic, headers), durabilidad, y a qué colas están vinculados (bindings). Puedes declarar/eliminar Exchanges.
Queues: La vista más importante para diagnosticar problemas. Muestra todas las colas, cuántos mensajes tienen listos para entregar (messages ready), cuántos mensajes están entregados pero sin confirmar (messages unacknowledged), la tasa de entrada (incoming), la tasa de salida (outgoing), el número de consumidores activos, sus propiedades (durabilidad, auto-delete, argumentos), etc. Puedes declarar/eliminar colas, purgar mensajes (vaciar la cola), publicar mensajes de prueba.
Admin: Gestionar usuarios, vhosts (entornos virtuales), permisos de usuario en vhosts, políticas (para configuración a gran escala), y el estado del cluster (si aplica).

Aprender a navegar por esta interfaz e interpretar sus métricas es fundamental para diagnosticar problemas rápidamente (ej. colas creciendo consistentemente -> contrapresión, los consumidores no dan abasto; tasas de entrega bajas pero mensajes en cola -> problemas en los consumidores; muchas conexiones -> posible fuga de recursos en una aplicación cliente; uso de disco alto -> persistencia o paginación).

Herramientas de Línea de Comandos (rabbitmqctl)

rabbitmqctl es la herramienta de línea de comandos para interactuar con RabbitMQ. Es esencial para tareas de automatización, scripting, y gestión de bajo nivel, especialmente en servidores donde no tienes acceso fácil a una UI gráfica o para realizar operaciones repetitivas. Algunos comandos esenciales incluyen (siempre especificando el vhost con -p <vhost> si no es el / por defecto):

rabbitmqctl status

Muestra el estado general del nodo RabbitMQ, versión, estado de los procesos, uso de memoria, etc.

rabbitmqctl list_queues name messages_ready messages_unacknowledged consumers memory

Lista las colas y métricas clave como el número de mensajes listos y sin confirmar, consumidores activos y uso de memoria por cola. Puedes listar otras columnas según necesites (message_stats.publish, message_stats.deliver_get, etc.).

rabbitmqctl list_exchanges name type durable

Lista los Exchanges, su tipo y si son duraderos.

rabbitmqctl list_bindings source destination destination_type routing_key arguments

Lista todas las vinculaciones (bindings) entre Exchanges y Colas/Exchanges.

rabbitmqctl add_user <username> <password>
rabbitmqctl set_permissions -p <vhost> <user> "<configure>" "<write>" "<read>"
rabbitmqctl delete_user <username>

Gestión básica de usuarios y permisos. Los permisos son expresiones regulares. "<configure>" afecta a exchanges/colas, "<write>" a la publicación, "<read>" al consumo.

rabbitmqctl delete_queue [-p <vhost>] <name>
rabbitmqctl purge_queue [-p <vhost>] <name>

Elimina una cola o elimina todos los mensajes de una cola sin borrarla. ¡Usar con precaución en producción!

rabbitmqctl tiene muchos más comandos para gestionar el cluster, políticas, parámetros de vhost, etc., siendo una herramienta muy potente para la administración avanzada.

Integración con Sistemas de Monitorización Externos

Si bien la UI web es útil para la inspección manual y rabbitmqctl para la gestión puntual, para la monitorización proactiva, la visualización histórica y las alertas necesitas integrar RabbitMQ con sistemas de monitorización centralizados.

Prometheus + Grafana: Una combinación muy popular en entornos de microservicios. El plugin de gestión de RabbitMQ expone métricas en un formato que Prometheus puede scrapear (/metrics endpoint si el plugin prometheus está habilitado, o via API si solo el plugin management está habilitado). Grafana se utiliza luego para crear dashboards visuales con estas métricas (uso de CPU/RAM, I/O de disco, longitud de colas a lo largo del tiempo, tasas de mensajes public/deliver/ack, latencia de confirmación, número de conexiones/canales, estado de health checks, etc.).
Otras Herramientas: RabbitMQ también puede integrarse con otras herramientas de monitorización como Nagios, Zabbix, Datadog, New Relic, etc., a menudo a través de plugins específicos, exportando métricas vía API de gestión o analizando sus logs.

Configurar alertas basadas en umbrales (ej. cola excede cierto número de mensajes, uso de CPU/RAM demasiado alto, espacio en disco casi lleno, nodo de cluster caído, tasa de mensajes entregados cae drásticamente) es vital para ser notificado y responder rápidamente a los problemas antes de que afecten significativamente a tus aplicaciones.

Logging y Alertas

Además de las métricas, los logs de RabbitMQ (generalmente ubicados en /var/log/rabbitmq/ en sistemas tipo Linux) contienen información valiosa sobre eventos, errores, advertencias, intentos de conexión, desconexiones, cambios de estado del cluster, etc. Es crucial tener un sistema centralizado de gestión de logs (ej. ELK Stack - Elasticsearch, Logstash, Kibana; Splunk; Loki+Grafana) para agregarlos desde todos tus nodos RabbitMQ, buscar patrones, diagnosticar fallos específicos y configurar alertas basadas en la aparición de eventos o errores particulares en los logs (ej. errores al escribir a disco, fallos de autenticación repetidos que podrían indicar un ataque, errores de sincronización de cluster).

La combinación de métricas en tiempo real (para el qué está pasando con el rendimiento y los recursos) y análisis de logs históricos (para el por qué algo falló o un evento ocurrió) te dará una visibilidad completa sobre la salud y el comportamiento de tu broker RabbitMQ.

Conclusión

Operar RabbitMQ en producción va mucho más allá de entender cómo enviar y recibir mensajes; implica comprender su apetito por los recursos, gestionar las expectativas de latencia y, sobre todo, tener herramientas robustas de monitorización y gestión para asegurar su estabilidad y rendimiento continuo.

Hemos visto los múltiples factores que influyen en el consumo de CPU, RAM y disco, y cómo la persistencia de mensajes y colas es un gran determinante del rendimiento de I/O, a menudo siendo el principal cuello de botella. Discutimos la latencia, sus componentes y cómo optimizarla según tus necesidades, recordando que RabbitMQ está optimizado para el throughput y el desacoplamiento más que para la latencia ultrabaja, un diseño fundamental para sistemas asíncronos robustos.

Finalmente, exploramos las herramientas esenciales para mantener el control: la indispensable interfaz de administración web para la inspección visual y diagnósticos puntuales, rabbitmqctl para la gestión por línea de comandos y automatización, y la integración con sistemas de monitorización externos como Prometheus y Grafana (junto con un buen sistema de logs) para tener visibilidad proactiva, análisis histórico y alertas cruciales.

Con estos conocimientos sobre el consumo de recursos, las expectativas de latencia y las herramientas de monitorización y gestión, estás mucho mejor equipado para desplegar, dimensionar y mantener una infraestructura de RabbitMQ saludable y resiliente. Un tema que complementa directamente la robustez en producción, especialmente a cargas altas, es la Alta Disponibilidad y el Clustering, que abordaremos en un futuro artículo.

Ver página completa →

Docker: La Revolución que Empaquetó tu Código

Mauricio ECR
DevOps
29 Apr, 2025

En el dinámico mundo del desarrollo y la infraestructura de tecnologías de la información, la necesidad de empaquetar, distribuir y ejecutar aplicaciones de forma consistente ha llevado a la populariz

Ver página completa

Docker: La Revolución que Empaquetó tu Código

Mauricio ECR
DevOps
29 Apr, 2025

En el dinámico mundo del desarrollo y la infraestructura de tecnologías de la información, la necesidad de empaquetar, distribuir y ejecutar aplicaciones de forma consistente ha llevado a la popularización de tecnologías como Docker. Docker no inventó el concepto de contenedores, ya existían tecnologías como LXC (Linux Containers), pero sí los popularizó al proporcionar una forma sencilla y eficiente de trabajar con ellos. Lanzado en 2013, Docker se ha convertido rápidamente en una herramienta fundamental para desarrolladores, administradores de sistemas y profesionales de DevOps.

La promesa de Docker es resolver el clásico problema de "funciona en mi máquina, pero no en producción". Al encapsular una aplicación y todas sus dependencias en una unidad aislada llamada contenedor, garantiza que la aplicación se ejecute de la misma manera en cualquier entorno, ya sea desarrollo, pruebas o producción.

Conceptos Fundamentales de Docker

Para entender cómo funciona Docker, es crucial familiarizarse con algunos conceptos básicos:

Contenedor: Un contenedor es, fundamentalmente, un proceso que se ejecuta en un entorno aislado. Es una instancia en ejecución de una imagen. Un contenedor incluye la aplicación y sus dependencias, tanto de librerías del lenguaje de programación como de librerías de sistema operativo necesarias para la aplicación. Es importante diferenciarlo de una máquina virtual; no es un sistema operativo completo. Los contenedores se ejecutan con un propósito o comando principal y finalizan cuando este comando termina, aunque pueden ejecutar una tarea y finalizar, o un servicio que se mantenga en ejecución. Se pueden ejecutar, parar, reiniciar y eliminar. La eliminación de un contenedor no afecta la imagen de la que proviene.
Imagen: Una imagen es un archivo binario o una plantilla que contiene todos los elementos necesarios para ejecutar un contenedor. Esto incluye la aplicación, librerías de lenguaje, librerías de sistema operativo necesarias y la configuración de arranque. Las imágenes son inmutables una vez creadas; cualquier cambio requiere la creación de una nueva imagen. Están compuestas por capas, donde cada capa representa un cambio en el sistema de archivos. Esto permite reutilizar funcionalidades y optimizar el almacenamiento y la construcción, ya que Docker solo descarga las capas que no tiene en local.
Dockerfile: Un Dockerfile es un archivo de texto que contiene las instrucciones secuenciales necesarias para construir una imagen. Permite definir pasos como instalar dependencias (RUN), copiar archivos (COPY), establecer el directorio de trabajo (WORKDIR), y definir el comando por defecto (CMD) o el comando principal (ENTRYPOINT) que se ejecutará al iniciar un contenedor. Cada instrucción crea una capa en la imagen.
```
# Usamos una imagen base ligera de Python (basada en Alpine Linux)
FROM python:3.9-alpine
# Establecemos el directorio de trabajo dentro del contenedor
WORKDIR /app
# Copiamos el archivo app.py del host al directorio /app en el contenedor
COPY app.py /app/
# Definimos el comando que se ejecutará cuando se inicie el contenedor
# En este caso, ejecutar el script python
CMD ["python", "app.py"]
```
Docker Hub: Es un repositorio de imágenes de contenedor. Funciona de manera similar a GitHub, pero para imágenes. Permite buscar (docker search), descargar (docker pull) y subir (docker push) imágenes creadas por la comunidad o propias. Existen otros repositorios que soportan el estándar de Docker, como GitHub Container Registry, GitLab Container Registry, etc., gracias al estándar OCI (Open Container Initiative).

Contenedores vs. Máquinas Virtuales

Una distinción clave para comprender Docker es su diferencia con las máquinas virtuales (VMs). Las VMs emulan hardware completo y ejecutan un sistema operativo completo y una capa de virtualización separada, lo que las hace independientes pero consume más recursos y es menos eficiente. Los contenedores, en cambio, comparten el mismo kernel del sistema operativo subyacente. Se ejecutan en un entorno aislado pero comparten los recursos del sistema. Esto los hace más ligeros, rápidos y eficientes en el uso de recursos que las VMs.

Instalación y Entornos

Docker ofrece dos componentes principales para su instalación:

Docker Engine: El motor que permite crear y ejecutar contenedores. Es gratuito, sin restricciones y se instala principalmente en sistemas Linux. Se utiliza a través de la línea de comandos (CLI) y es ideal para servidores de desarrollo o producción por su rendimiento nativo.
Docker Desktop: Una aplicación de escritorio para Windows y Mac (y opcionalmente Linux) que incluye Docker Engine más herramientas adicionales como interfaz gráfica, soporte para Kubernetes, plugins, etc. En Windows y Mac, utiliza una máquina virtual para ejecutar los contenedores. Es gratuito para uso personal y pequeñas empresas.

La instalación en Linux a menudo se simplifica con un script oficial.

#instale algunos paquetes de requisitos previos que permitan a apt usar paquetes a través de HTTPS
$ sudo apt install curl apt-transport-https ca-certificates software-properties-common
#descargue la clave GPG de Docker
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
#agregue el repositorio Docker APT a su sistema. El comando crea un docker.listarchivo de repositorio en el /etc/apt/sources.list.ddirectorio.
$ echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
$ sudo apt update
$ sudo apt install docker-ce -y
$ sudo docker --version

o

sudo docker run hello-world

Construcción de Imágenes con Dockerfile

La construcción de imágenes se realiza utilizando el comando

docker build

nota: El Dockerfile debe estar en el directorio desde donde se ejecuta el comando.

tambien se puede definir un Dockerfile y un contexto (el directorio de referencia). La sintaxis básica es

docker build -t <nombre_imagen> <directorio_contexto>

donde -t asigna un nombre y etiqueta.

Las instrucciones del Dockerfile se ejecutan secuencialmente, de arriba a abajo, y Docker intenta reutilizar capas para optimizar el proceso. Instrucciones clave incluyen:

FROM: Especifica la imagen base.
RUN: Ejecuta comandos para instalar software, configurar, etc.
COPY: Copia archivos/directorios del contexto de construcción a la imagen.
WORKDIR: Define el directorio de trabajo por defecto.
CMD: Define el comando por defecto al iniciar el contenedor. Puede ser sobreescrito al ejecutar docker run.
ENTRYPOINT: Define el comando principal al iniciar el contenedor. Los comandos pasados a docker run se adjuntan como argumentos a ENTRYPOINT.

La diferencia entre CMD y ENTRYPOINT radica en cómo manejan los argumentos pasados al docker run. CMD se sobreescribe, mientras que ENTRYPOINT usa esos argumentos como parámetros.

Para hacer las imágenes más flexibles, se pueden usar:

Argumentos de Construcción (ARG): Definidos con ARG en el Dockerfile y pasados con --build-arg durante el docker build. Permiten variabilizar el proceso de construcción.
Variables de Entorno: Se pasan al contenedor en tiempo de ejecución con -e o --env en docker run. Permiten configurar la aplicación sin modificar la imagen, adaptándola a diferentes entornos.

Ejecución y Gestión de Contenedores

Los contenedores se arrancan con el comando

docker run <imagen>

Este comando crea y arranca un nuevo contenedor.

Comandos y opciones comunes para la gestión de contenedores:

docker ps: Lista los contenedores en ejecución. Añadir -a muestra todos (en ejecución y detenidos).
Opciones de docker run:
- -d: Ejecuta el contenedor en segundo plano ("detached").
- -p <host_port>:<container_port>: Mapea puertos para permitir la comunicación.
- -v <host_path_o_volume>:<container_path>: Monta volúmenes o directorios/archivos para persistencia o compartir datos.
- --name <nombre>: Asigna un nombre al contenedor.
- --rm: Elimina el contenedor al pararlo.
- -e <variable>=<valor>: Pasa variables de entorno.
- --restart <policy>: Define una política de reinicio si el contenedor falla o se detiene (ej: always, unless-stopped, on-failure).
docker logs <id_o_nombre>: Muestra la salida del proceso principal. -f sigue la salida en tiempo real.
docker attach <id_o_nombre>: Se acopla al proceso principal del contenedor. Control + p + q para desacoplar sin parar.
docker exec <id_o_nombre> <comando>: Ejecuta un comando dentro de un contenedor en ejecución. -it para un terminal interactivo.
docker stop <id_o_nombre>: Detiene un contenedor.
docker start <id_o_nombre>: Inicia un contenedor existente pero detenido.
docker restart <id_o_nombre>: Detiene y vuelve a iniciar un contenedor.
docker rm <id_o_nombre>: Elimina un contenedor detenido. -f fuerza la eliminación.
docker container prune: Elimina todos los contenedores detenidos.

Persistencia de Datos con Volúmenes

Los contenedores están diseñados para ser efímeros. Para que los datos persistan, se utilizan volúmenes. Los volúmenes son directorios o archivos que se encuentran fuera del sistema de archivos del contenedor y se montan dentro de él.

La gestión de volúmenes incluye:

Crear:
```
docker volume create <nombre>
```
Listar:
```
docker volume ls
```
Inspeccionar:
```
docker volume inspect <nombre>
```
Montar: Usando -v o --mount en docker run.
Eliminar:
```
docker volume rm <nombre>
```

También es posible copiar archivos entre el host y el contenedor con

docker cp

Redes en Docker

Docker permite gestionar la comunicación entre contenedores y con el exterior mediante redes. Se controlan con el comando

docker network

Tipos de redes comunes incluyen:

bridge: La red por defecto para comunicación en el mismo host.
host: Los contenedores comparten la red del host (menos aislamiento).
overlay: Para comunicación entre contenedores en diferentes hosts (cargas distribuidas).
none: Sin red.

Comandos de red:

Crear:

docker network create [--driver <tipo>] <nombre>

Listar:
```
docker network ls
```
Inspeccionar:
```
docker network inspect <nombre>
```

Conectar/Desconectar:

docker network connect <red> <contenedor>

y

docker network disconnect <red> <contenedor>

Eliminar:
```
docker network rm <nombre>
```

Gestión de Imágenes Avanzada y Repositorios

Además de construir imágenes con Dockerfile, se puede crear una imagen a partir del estado actual de un contenedor en ejecución usando

docker commit <id_contenedor> <nombre_imagen>

aunque esto no es la práctica más común. La buena práctica favorece las imágenes estáticas definidas por Dockerfiles.

Otras operaciones con imágenes:

Exportar/Importar:

docker save -o <fichero>.tar <imagen>

y

docker load -i <fichero>.tar

Etiquetar:
```
docker tag <imagen_actual>:<etiqueta> <nuevo_nombre>:<nueva_etiqueta>
```
para renombrar o añadir etiquetas. Las etiquetas identifican el origen y la versión.
Buscar:
```
docker search <término>
```
en Docker Hub.
Descargar:
```
docker pull <nombre_imagen>
```
Subir:
```
docker push <nombre_imagen>
```
Requiere etiquetar la imagen correctamente (ej: usuario/nombre_imagen). Se puede especificar un repositorio remoto.
Eliminar:
```
docker rmi <id_o_nombre>
```
Limpiar:
```
docker image prune
```
elimina imágenes no asociadas a contenedores.

Conclusión

Docker, a través de sus conceptos fundamentales de imágenes, contenedores, Dockerfiles y repositorios, ha estandarizado y simplificado enormemente el ciclo de vida de las aplicaciones. Su capacidad para empaquetar aplicaciones y sus dependencias en unidades portátiles y aisladas, y la eficiencia que ofrece al compartir el kernel del sistema operativo, lo convierten en una herramienta indispensable en la infraestructura de TI moderna. Ya sea para desarrollo, pruebas, microservicios, CI/CD o despliegues en la nube, los contenedores proporcionan una forma consistente y escalable de gestionar aplicaciones, permitiendo a los equipos trabajar de manera más eficiente y agnóstica del entorno. Entender y dominar estos conceptos básicos es el primer paso para aprovechar todo el potencial que Docker ofrece en la actualidad.

Ver página completa →

Implementando Trunk Based Development con Ramas de Vida Corta en Tu Equipo: Una Guía Completa

Mauricio ECR
DevOps
28 Apr, 2025

En el ámbito del desarrollo de software, la elección de una estrategia de versionamiento eficiente y estable es fundamental para el éxito de un equipo. El Trunk Based Development (TBD) tradicional, do

Ver página completa

Implementando Trunk Based Development con Ramas de Vida Corta en Tu Equipo: Una Guía Completa

Mauricio ECR
DevOps
28 Apr, 2025

En el ámbito del desarrollo de software, la elección de una estrategia de versionamiento eficiente y estable es fundamental para el éxito de un equipo. El Trunk Based Development (TBD) tradicional, donde los desarrolladores trabajan directamente sobre una única rama principal (master o main), es ideal para equipos pequeños de 1 a 3 desarrolladores. Para equipos de 4 a 5 desarrolladores, aunque sigue siendo una opción viable, requiere indispensablemente la implementación de pruebas automáticas. Sin embargo, para equipos más grandes, con seis o más desarrolladores, una variante del TBD se presenta como una solución escalable: el Trunk Based Development con Ramas de Vida Corta (TBD con SLB). Esta estrategia, utilizada por empresas como Google, utiliza ramas de vida muy corta para gestionar los cambios en lugar de que los desarrolladores hagan commits directamente en el tronco.

¿En qué Consiste TBD con SLB?

En TBD con SLB, la práctica central es que los desarrolladores no hacen commits directos sobre la rama principal o tronco. En su lugar, trabajan en ramas dedicadas y de muy corta duración. Estas ramas, llamadas ramas de vida corta (short-lived branches), duran muy poco tiempo, idealmente menos de 3 días, y como máximo 3 días. Incluso, pueden contener un solo commit. Una vez que la tarea o funcionalidad de la rama está terminada y lista, se integra de nuevo al tronco mediante un merge back, y la rama de vida corta se elimina.

Implementación Paso a Paso (Desarrollo de Nuevas Funcionalidades)

La implementación de TBD con SLB para añadir o modificar funcionalidades sigue un ciclo bien definido. Suponiendo que la rama principal se llama main (puede ser master en repositorios antiguos).

1. Creación de Ramas de Vida Corta

Cada vez que un desarrollador inicia una nueva tarea, debe crear una nueva rama de desarrollo de vida corta. Esta rama se crea a partir de la última versión del tronco (main). Es crucial asegurarse de que tu copia local del tronco esté actualizada antes de crear la rama.

Comandos Git:

# Asegúrate de estar en la rama principal (trunk)
git checkout main
# Descarga los últimos cambios del tronco remoto
git pull origin main
# Crea una nueva rama de vida corta basada en el tronco actual
# Reemplaza 'feature/nombre-tarea' con un nombre descriptivo para tu tarea
git checkout -b feature/nombre-tarea

Ilustración: La rama feature/nombre-tarea se crea a partir del último commit en main (representado por los commits existentes C1 y C2 en main).

codigo mermaid


    gitGraph
        commit id: "C1"
        commit id: "C2"
        branch feature/nombre-tarea
        checkout feature/nombre-tarea

2. Desarrollo y Commits Locales

El desarrollador trabaja sobre su rama recién creada y realiza los commits necesarios con sus cambios, trabajando a su propio ritmo.

Comandos Git:

# Realiza cambios en tus archivos...
# Por ejemplo, crea o modifica un archivo: touch nuevo-archivo.txt
# Agrega los cambios al área de staging
git add .
# Realiza un commit con un mensaje descriptivo
git commit -m "Implementa la funcionalidad X"
# Repite los pasos add/commit según sea necesario mientras trabajas en la tarea

Ilustración: Nuevos commits (F1, F2) se añaden a la rama feature/nombre-tarea, mientras main permanece inalterada.

codigo mermaid


    gitGraph
        commit id: "C1"
        commit id: "C2"
        branch feature/nombre-tarea
        checkout feature/nombre-tarea
        commit id: "F1"
        commit id: "F2"

3. Sincronización con el Tronco (Previo al Merge)

Antes de preparar la integración de los cambios, es esencial que la rama local del desarrollador esté actualizada con los últimos cambios que ya se encuentran en el tronco. Esto se logra descargando los cambios del tronco y aplicándolos a tu rama, típicamente usando merge o rebase. rebase es a menudo preferido en TBD para mantener un historial más lineal.

Comandos Git (Usando Rebase - Preferido en TBD para historial limpio):

# Asegúrate de que tu tronco local esté actualizado
git checkout main
git pull origin main
# Vuelve a tu rama de trabajo
git checkout feature/nombre-tarea
# Rebase tu rama sobre el tronco actualizado
# Esto reescribe el historial de tu rama para que parezca que tus cambios
# se hicieron después de los últimos cambios del tronco
git rebase main

Comandos Git (Usando Merge - Alternativa):

# Asegúrate de que tu tronco local esté actualizado
git checkout main
git pull origin main
# Vuelve a tu rama de trabajo
git checkout feature/nombre-tarea
# Fusiona los cambios del tronco en tu rama
# Esto crea un commit de merge si hay cambios en el tronco
git merge main

Ilustración: main ha avanzado con C3. El merge crea un nuevo commit (M) en feature/nombre-tarea que combina los cambios de main y los de la rama feature.

codigo mermaid


    gitGraph
        commit id: "C1"
        commit id: "C2"
        branch feature/nombre-tarea
        commit id: "F1"
        commit id: "F2"
        checkout main
        commit id: "C3" 
        checkout feature/nombre-tarea
        merge main id: "M"

4. Creación de un Pull Request (PR)

Una vez que los cambios están completos, la rama está sincronizada y lista para integrarse, el desarrollador crea un Pull Request (PR) dirigido al tronco (main). Este paso generalmente se realiza a través de la interfaz web de la plataforma de gestión de código (GitHub, GitLab, Bitbucket, Azure DevOps, etc.), después de haber subido la rama local al repositorio remoto.

Comandos Git (para subir la rama antes del PR):

# Sube tu rama de vida corta al repositorio remoto
# La opción -u (o --set-upstream-to) configura el seguimiento remoto
git push -u origin feature/nombre-tarea

5. Revisión de Código y Pruebas Automáticas Pre-Merge

El uso de PRs es una característica distintiva y ventajosa del TBD con SLB. Permite la revisión de código por otros miembros del equipo y, crucialmente, habilita la ejecución de pruebas automáticas antes de que se realice el merge. Esto es una diferencia significativa con el TBD tradicional, donde las pruebas automáticas a menudo se realizan después del merge. La ventaja clave es que evita que commits con errores lleguen al tronco. Este paso es un proceso que ocurre en la plataforma de código, no un comando Git ejecutado por el usuario para realizar la revisión o las pruebas, aunque los revisores pueden descargar la rama si necesitan probar localmente.

6. Merge al Tronco y Eliminación de la Rama

Si el PR es aprobado (por revisores) y las pruebas automáticas pasan, los cambios de la rama de vida corta se integran al tronco (main) mediante un merge (generalmente completando el PR en la plataforma). Posteriormente, la rama de vida corta es eliminada. Todo desarrollo futuro para nuevas tareas siempre empieza creando una nueva rama de vida corta desde el tronco.

codigo mermaid


   gitGraph
        commit id: "C1"
        commit id: "C2"
        branch feature/nombre-tarea
        commit id: "F1"
        commit id: "F2"
        checkout main
        commit id: "C3" 
        checkout feature/nombre-tarea
        merge main id: "M"
        checkout main
        merge feature/nombre-tarea

Comandos Git (Después de completar el PR en la plataforma):

# Vuelve al tronco local
git checkout main
# Asegúrate de tener el último estado del tronco (que ahora incluye el merge)
git pull origin main
# Elimina la rama de vida corta localmente (usa -D para forzar si no se ha mergeado, -d es seguro)
git branch -d feature/nombre-tarea
# Elimina la rama de vida corta del repositorio remoto
git push origin --delete feature/nombre-tarea

codigo mermaid


   gitGraph
        commit id: "C1"
        commit id: "C2"
        commit id: "C3"
        commit id: "T1" tag: "merge tarea 1"

Cómo se Gestionan los Releases (Versiones para Producción)

Una parte fundamental del versionamiento es la gestión de las liberaciones de software (releases) a entornos productivos. En el TBD con SLB, el manejo de las ramas de release es directo y se deriva del tronco:

Creación de la Rama de Release: Cuando el estado actual del tronco (main) se considera listo para ser liberado como una nueva versión, simplemente se crea una nueva rama a partir de ese punto.
Denominación y Uso: Esta nueva rama se nombra típicamente con el número de la versión que se va a lanzar (por ejemplo, release/1.0.0). Esta rama de versión es la que se utiliza para ser desplegada en producción. Es la línea base a partir de la cual se gestionarán los despliegues y, si es necesario, las correcciones de bugs específicos de esa versión. El tronco (main) sigue siendo la rama activa para el desarrollo de nuevas funcionalidades.

Comandos Git:

# Asegúrate de estar en el tronco y que esté actualizado
git checkout main
git pull origin main
# Crea la rama de release a partir del tronco actual
# Reemplaza 'release/1.0.0' con el nombre de tu versión
git checkout -b release/1.0.0
# Opcional pero recomendado: Etiqueta este punto para una referencia clara de la versión
git tag v1.0.0 release/1.0.0
# Sube la rama de release y la etiqueta al remoto
git push -u origin release/1.0.0
git push origin v1.0.0

Ilustración: Se crea la rama release/1.0.0 (y potencialmente se etiqueta v1.0.0) a partir de un commit específico en main (C5). main continúa para el desarrollo futuro.

codigo mermaid


   gitGraph
        commit id: "C1"
        commit id: "C2"
        commit id: "C3"
        commit id: "T1" tag: "merge tarea 1"

Escenarios para Solucionar Bugs en Producción

Los bugs que se descubren en una versión ya desplegada en producción (es decir, en la rama de Release) deben manejarse cuidadosamente para mantener la coherencia con la metodología TBD y la integridad del tronco. La forma de proceder depende de si el error aún se puede reproducir en la versión actual del tronco.

Escenario 1: El Bug Sigue Existiendo en el Tronco (Preferido)

Este es el escenario recomendado y se alinea con la práctica de empresas como Google. Se corrige el bug en el tronco y luego se "trasplanta" esa corrección a la rama de Release.

Verificar el Bug en el Tronco: Se confirma que el error se puede replicar en la versión actual del tronco (main). (Esto es una verificación manual o automatizada, no un comando Git).
Crear Rama de Vida Corta desde el Tronco: Se crea una nueva rama de vida corta específicamente para el bug fix, partiendo directamente del tronco.

Comandos Git:

# Asegúrate de estar en el tronco y actualizado
git checkout main
git pull origin main
# Crea la rama para el bug fix desde el tronco
git checkout -b bugfix/nombre-bug-en-produccion

Solucionar el Bug: El bug se corrige en esta nueva rama de vida corta.

Comandos Git:

# Realiza los cambios para corregir el bug...
# Agrega y realiza el commit
git add .
git commit -m "Fix: Corrige el bug X reportado en v1.0.0 (también presente en main)"

Merge del Bug Fix al Tronco: El commit que contiene la solución del bug se integra de vuelta al tronco (main). Esto se hace mediante el proceso habitual de TBD con SLB (usando un PR).

Comandos Git (Después de completar el PR en la plataforma):

# Sube la rama con el bug fix
git push -u origin bugfix/nombre-bug-en-produccion
# Crea un PR en la plataforma de 'bugfix/nombre-bug-en-produccion' a 'main'
# ... (Una vez aprobado y mergeado) ...
# Vuelve al tronco local y actalízalo
git checkout main
git pull origin main

Cherry Pick a la Rama de Release: Finalmente, se realiza un Cherry Pick del commit específico que contiene el bug fix (el commit B1 original o el merge commit M_B1, aunque B1 es más limpio para cherry-pick) desde el tronco (main) hacia la rama de la versión en producción (la rama release/1.0.0 donde se encontró el bug).

Comandos Git:

# Identifica el hash del commit de bug fix en el tronco (ej: el commit B1 original o M_B1)
# Puedes usar 'git log main' para encontrarlo
# Vuelve a la rama de release
git checkout release/1.0.0
# Aplica el commit de bug fix desde el tronco a esta rama
# Reemplaza <commit-hash-del-bugfix> con el hash real
git cherry-pick <commit-hash-del-bugfix>
# Sube la rama de release actualizada al remoto
git push origin release/1.0.0

codigo mermaid


    gitGraph
        commit id: "C1"
        commit id: "C2"
        commit id: "C3"
        commit id: "T1"
        branch release/1.0.0
        checkout release/1.0.0
        commit id: "R1" tag: "v1.0.0"
        checkout main
        commit id: "C4"
        commit id: "C5"
        branch bugfix/nombre-bug-en-produccion
        checkout bugfix/nombre-bug-en-produccion
        commit id: "B1" tag: "Bugfix Commit"
        checkout main
        merge bugfix/nombre-bug-en-produccion id: "M_B1" tag: "Bugfix on Main"
        checkout release/1.0.0
        cherry-pick id:"M_B1" parent:"B1" tag:"v1.0.1"

Este proceso, aunque involucra más pasos (crear rama, merge al tronco, cherry pick a la rama de Release), garantiza que solo el bug fix se incorpore a la versión de producción. Es la forma de respetar el contrato del Trunk Based Development y asegurar que el tronco sigue siendo la fuente principal de verdad. El desarrollo normal de nuevas funcionalidades continúa siempre en nuevas ramas de vida corta creadas a partir del tronco. Google utiliza este enfoque: las soluciones de bugs para un release se desarrollan en la línea principal y luego se hace un cherry pick a la rama de release.

Escenario 2: El Bug NO Sigue Existiendo en el Tronco (Menos Sugerido)

Este escenario es menos común y no es el recomendado por los expertos en TBD. Ocurre si el bug ya fue corregido en el tronco por un commit que, sin embargo, incluye otras funcionalidades que no deben ir a la rama de Release actual, lo que impide crear la rama de bug fix desde el tronco.

Verificar el Bug y el Tronco: Se confirma que el bug no es replicable en el tronco, pero la solución en el tronco está ligada a otros cambios no deseados en la versión de producción. (Verificación manual/automatizada).
Crear Rama de Vida Corta desde la Rama de Release: En esta situación excepcional, se crea una rama de vida corta desde la rama de la versión en producción (la rama release/1.0.0).

Comandos Git:

# Asegúrate de estar en la rama de release y actualizada
git checkout release/1.0.0
git pull origin release/1.0.0
# Crea la rama para el hotfix directamente desde la rama de release
git checkout -b hotfix/nombre-bug-solo-en-v1.0.0

Solucionar el Bug: El bug se corrige en esta rama creada directamente desde la rama de Release.

Comandos Git:

# Realiza los cambios para corregir el bug...
# Agrega y realiza el commit
git add .
git commit -m "Hotfix: Corrige el bug Y específicamente en v1.0.0"

Merge del Bug Fix a la Rama de Release: Se integra el bug fix de vuelta a la rama de la versión en producción (release/1.0.0) mediante un merge (idealmente vía PR). La solución está ahora en la versión que la necesita.

Comandos Git (Después de completar el PR en la plataforma):

# Sube la rama con el hotfix
git push -u origin hotfix/nombre-bug-solo-en-v1.0.0
# Crea un PR en la plataforma de 'hotfix/nombre-bug-solo-en-v1.0.0' a 'release/1.0.0'
# ... (Una vez aprobado y mergeado) ...
# Vuelve a la rama de release local y actualízala
git checkout release/1.0.0
git pull origin release/1.0.0
# La rama hotfix/nombre-bug-solo-en-v1.0.0 ahora se eliminaría

Merge de la Rama de Release al Tronco: Por último, se integra la rama de la versión en producción actualizada (release/1.0.0) de vuelta al tronco (main). Esto es crucial para asegurar que la corrección hecha en la rama de Release también se refleje en el tronco, evitando la divergencia y que el mismo bug reaparezca en futuras versiones creadas desde main.

Comandos Git:

# Asegúrate de estar en el tronco y actualizado
git checkout main
git pull origin main
# Fusiona la rama de release (ahora con el hotfix) en el tronco
git merge release/1.0.0
# Sube el tronco actualizado al remoto
git push origin main

codigo mermaid


    gitGraph
        commit id: "C1"
        commit id: "C2"
        commit id: "C3"
        commit id: "T1"
        branch release/1.0.0
        checkout release/1.0.0
        commit id: "R1" tag: "v1.0.0"
        checkout main
        commit id: "C4"
        commit id: "C5"
        checkout release/1.0.0
        branch bugfix/nombre-bug-en-produccion
        checkout bugfix/nombre-bug-en-produccion
        commit id: "B1" tag: "Bugfix Commit"
        checkout release/1.0.0
        merge bugfix/nombre-bug-en-produccion id:"M_B1" tag: "v1.0.1"
        checkout main
        cherry-pick id:"M_B1" parent:"B1"

Este escenario invierte el flujo habitual de los cambios. Una vez completado este proceso, el desarrollo continúa siempre en nuevas ramas de vida corta creadas desde el tronco.

Características Clave y Beneficios del TBD con SLB

El TBD con SLB se define por las siguientes características y aporta importantes beneficios:

Ramas de Vida Corta: Las ramas de desarrollo duran muy poco, idealmente menos de 4 horas y un máximo de 3 días.
Uso de Pull Requests: La integración de cambios al tronco se realiza exclusivamente a través de PRs, lo que trae consigo sus beneficios.
Pruebas Automáticas Pre-Merge: Permite la ejecución de pruebas automatizadas antes de fusionar los cambios al tronco, lo que mejora significativamente la estabilidad del tronco al prevenir que lleguen commits con errores.
Evita "Merge Hell": Al trabajar con ramas pequeñas e integrar cambios con mucha frecuencia, se minimizan los conflictos de merge dolorosos que son comunes con ramas de vida larga.
Soporte para Versionamiento: Se gestionan versiones creando ramas de Release a partir del tronco.
Escalabilidad: Es una variante escalable del TBD, siendo muy adecuada para equipos grandes con más de seis desarrolladores.
Alineación con Prácticas de Grandes Empresas: Es una estrategia utilizada por compañías como Google, donde el desarrollo en ramas (excepto para releases) es inusual y las ramas de vida larga son extremadamente raras.

Conclusión

Implementar Trunk Based Development con Ramas de Vida Corta es una estrategia de versionamiento robusta, profesional y altamente escalable que se adapta bien a equipos de desarrollo grandes. Al basarse en la creación, el trabajo y la rápida fusión (vía PR y con pruebas pre-merge) de ramas muy pequeñas, esta metodología mantiene el tronco (master o main) en un estado más estable y listo para ser desplegado en cualquier momento. Aunque la gestión de bug fixes para versiones en producción requiere un proceso específico (preferiblemente el escenario 1, con Cherry Pick desde el tronco a la rama de Release), el flujo de trabajo general simplifica la integración continua, reduce drásticamente los conflictos de fusión (merge hell) y facilita un ritmo de desarrollo ágil y confiable. Su adopción por grandes empresas como Google subraya su eficacia y solidez como una práctica de versionamiento moderna y eficiente.

Ver página completa →

Relaciones en Bases de Datos NoSQL: ¿Embeber o Referenciar? Una Guía Técnica para la Toma de Decisiones

Mauricio ECR
Persistencia
27 Apr, 2025

El auge de las bases de datos NoSQL ha redefinido la manera en que abordamos el modelado de datos, ofreciendo flexibilidad y escalabilidad que a menudo superan las limitaciones de los modelos relacion

Ver página completa

Relaciones en Bases de Datos NoSQL: ¿Embeber o Referenciar? Una Guía Técnica para la Toma de Decisiones

Mauricio ECR
Persistencia
27 Apr, 2025

El auge de las bases de datos NoSQL ha redefinido la manera en que abordamos el modelado de datos, ofreciendo flexibilidad y escalabilidad que a menudo superan las limitaciones de los modelos relacionales tradicionales. Sin embargo, esta libertad conlleva nuevas consideraciones, especialmente a la hora de definir las relaciones entre las entidades de nuestra aplicación. A diferencia de las claves foráneas y las uniones explícitas de las bases de datos SQL, en el mundo NoSQL (particularmente en las bases de datos orientadas a documentos), debemos decidir entre embeber documentos relacionados dentro de un documento principal o referenciar documentos a través de identificadores.

Esta decisión no es trivial y tiene un impacto profundo en el rendimiento, la escalabilidad, la consistencia y la complejidad de nuestra aplicación. Este artículo profundiza en los factores clave a considerar al tomar esta elección crítica, proporcionando una base sólida para arquitectos y desarrolladores de software que trabajan con bases de datos NoSQL.

Embeber Documentos: Consolidación para el Acceso Rápido

Embeber (embedding) implica anidar un documento dentro de otro. En este modelo, la información relacionada se almacena físicamente junta en un único documento.

Ventajas:

Mejor rendimiento de lectura: Almacenar datos relacionados juntos permite recuperarlos en una sola operación de lectura, eliminando la necesidad de múltiples consultas o "joins" a nivel de aplicación o base de datos. Esto es ideal para escenarios donde los datos relacionados se acceden con mucha frecuencia junto con el documento principal.
Operaciones atómicas: Las actualizaciones a los datos dentro de un único documento embebido suelen ser atómicas, lo que garantiza que las operaciones se completen por completo o no se realicen en absoluto, simplificando la lógica de manejo de concurrencia para esos datos específicos.
Menor complejidad de consultas simples: Para patrones de acceso que siempre recuperan el documento principal y sus relacionados, la consulta es directa y sencilla.

Desventajas:

Duplicación de datos: Si un documento embebido necesita aparecer en múltiples documentos principales, la información se duplicará, lo que puede llevar a inconsistencias si los datos embebidos cambian.
Tamaño del documento: Embeber grandes cantidades de datos o datos que crecen sin límites puede aumentar significativamente el tamaño de los documentos. Esto puede impactar el rendimiento de lectura y escritura, y muchas bases de datos NoSQL tienen límites en el tamaño máximo de un documento (por ejemplo, 16 MB en MongoDB).
Complejidad en actualizaciones frecuentes o parciales: Si los datos embebidos cambian con mucha frecuencia o si solo se necesita actualizar una pequeña parte de ellos, modificar el documento principal completo puede ser ineficiente.
Dificultad para consultar datos embebidos de forma independiente: Consultar o agregar datos basándose únicamente en la información dentro de los documentos embebidos puede ser menos eficiente o más complejo que si estuvieran en una colección separada.

Referenciar Documentos: Flexibilidad y Normalización Controlada

Referenciar (referencing) implica almacenar documentos relacionados en colecciones separadas y utilizar identificadores (como el _id en MongoDB) en un documento para crear un enlace a otro. Este enfoque es más similar al concepto de claves foráneas en bases de datos relacionales.

Ventajas:

Reduce la duplicación de datos: La información se almacena una sola vez en su propia colección, lo que simplifica la gestión de actualizaciones y reduce el riesgo de inconsistencia.
Flexibilidad para consultar datos de forma independiente: Los documentos referenciados pueden ser consultados, actualizados y gestionados de forma independiente de los documentos que los referencian.
Manejo eficiente de datos que crecen sin límites: Colecciones separadas son más adecuadas para almacenar grandes cantidades de datos o datos que se espera que crezcan considerablemente.
Ideal para relaciones muchos-a-muchos: Las relaciones complejas donde múltiples documentos de una colección se relacionan con múltiples documentos de otra colección se manejan más naturalmente con referencias.

Desventajas:

Mayor complejidad en la recuperación de datos relacionados: Para obtener el documento principal y sus relacionados, se requieren múltiples consultas (una para el documento principal y luego una o más para los documentos referenciados) o el uso de funcionalidades de "lookup" proporcionadas por la base de datos (si están disponibles), lo que puede aumentar la latencia de lectura.
Falta de atomicidad en operaciones que involucran múltiples documentos: Las actualizaciones que afectan a datos en diferentes colecciones referenciadas no son atómicas por defecto, lo que requiere una lógica a nivel de aplicación o transacciones distribuidas (si la base de datos lo soporta) para garantizar la consistencia.
Mayor complejidad en el modelo de datos para relaciones simples: Para relaciones uno-a-uno o uno-a-pocos, el modelo referenciado puede parecer más verboso que el modelo embebido.

Factores Clave para la Decisión

La elección entre embeber y referenciar depende en gran medida de los patrones de acceso a los datos y los requisitos de la aplicación. Aquí se detallan los factores más importantes a considerar:

Patrones de Acceso a Datos:
- Lectura intensiva y datos accedidos conjuntamente: Si los datos relacionados casi siempre se leen junto con el documento principal y las lecturas son mucho más frecuentes que las escrituras, embeber suele ofrecer un mejor rendimiento.
- Acceso independiente a datos relacionados: Si los datos relacionados se consultan o actualizan con frecuencia de forma independiente del documento principal, referenciar es la opción más eficiente.
- Necesidad de consultar y agregar datos relacionados por sí solos: Si se requiere realizar consultas o agregaciones complejas sobre los datos relacionados sin pasar por el documento principal, referenciar facilita estas operaciones.
Tamaño y Crecimiento de los Datos Relacionados:
- Datos relacionados pequeños y con crecimiento limitado: Embeber es viable si la cantidad de datos relacionados es pequeña y no se espera que crezca significativamente, manteniendo el tamaño total del documento dentro de límites razonables.
- Datos relacionados grandes o con crecimiento ilimitado: Referenciar es esencial cuando los datos relacionados pueden ser extensos (por ejemplo, una larga lista de comentarios o transacciones) para evitar exceder los límites de tamaño del documento y mantener un rendimiento de escritura eficiente.
Frecuencia y Naturaleza de las Actualizaciones:
- Actualizaciones frecuentes de datos embebidos: Si los datos que se considerarían para ser embebidos cambian muy a menudo, referenciar es preferible para evitar la sobrecarga de actualizar el documento principal constantemente.
- Actualizaciones atómicas requeridas para datos relacionados: Si un conjunto de datos relacionados debe actualizarse de manera atómica junto con el documento principal, embeber simplifica la implementación.
- Actualizaciones independientes de diferentes partes de los datos relacionados: Si distintos elementos dentro de los datos relacionados se actualizan de forma independiente y frecuente, referenciar permite actualizaciones más localizadas y eficientes.
Consistencia de los Datos:
- Alta prioridad en la consistencia global de los datos relacionados: Referenciar reduce la duplicación y simplifica la garantía de que las actualizaciones a los datos se reflejen consistentemente en toda la base de datos.
- Consistencia eventual aceptable para datos embebidos: Si una ligera inconsistencia temporal es tolerable para los datos embebidos (por ejemplo, la información duplicada tarda un corto tiempo en sincronizarse si cambia el original referenciado en otro lugar), embeber puede ser aceptable.
Complejidad del Esquema y las Relaciones:
- Relaciones uno-a-uno y uno-a-pocos contenidas: Embeber a menudo resulta en un esquema más simple y consultas directas para estas relaciones, especialmente cuando los "pocos" son realmente pocos y su crecimiento es limitado.
- Relaciones uno-a-muchos y muchos-a-muchos: Referenciar es generalmente la opción más escalable y manejable para estas relaciones, evitando documentos excesivamente grandes o la complejidad de manejar listas potencialmente ilimitadas dentro de un documento.
Consideraciones Específicas de la Base de Datos NoSQL:
- Aunque los principios generales son aplicables, las características específicas de la base de datos NoSQL utilizada (MongoDB, Cassandra, Couchbase, etc.) pueden influir en la decisión. Por ejemplo, las capacidades de "lookup" o las limitaciones de tamaño de documento varían entre bases de datos.

Un Enfoque Híbrido

Es importante destacar que no siempre es una elección binaria entre embeber o referenciar. En muchos casos, un enfoque híbrido puede ser la solución óptima. Esto implica embeber los datos relacionados que se acceden con mucha frecuencia y que tienen un tamaño limitado, mientras se referencian otros datos relacionados que son más grandes, cambian con frecuencia o se consultan de forma independiente.

Por ejemplo, en un documento de "pedido", se podría embeber una lista de "ítems del pedido" (si la lista no es excesivamente larga y se accede siempre con el pedido), pero referenciar el documento de "cliente" y los documentos de "productos" para evitar duplicar información del cliente o los detalles completos de cada producto en cada pedido.

Conclusión

La decisión de si embeber o referenciar datos en una base de datos NoSQL es un pilar fundamental en el diseño de esquemas eficientes y escalables. No existe una regla única para todos los casos; la elección debe basarse en una comprensión profunda de los patrones de acceso a datos de la aplicación, los requisitos de rendimiento, las expectativas de crecimiento de los datos y las características específicas de la base de datos NoSQL empleada.

Embeber favorece el rendimiento de lectura y la atomicidad para datos accedidos conjuntamente y de tamaño limitado. Referenciar ofrece flexibilidad, reduce la duplicación y es más adecuado para datos grandes, de crecimiento ilimitado, que cambian con frecuencia o que participan en relaciones complejas. Un enfoque híbrido a menudo permite capitalizar las ventajas de ambos modelos.

Una evaluación cuidadosa de los factores discutidos y la posibilidad de realizar pruebas de rendimiento con diferentes modelos de datos son pasos cruciales para asegurar que el diseño de la base de datos NoSQL soporte eficazmente las necesidades actuales y futuras de la aplicación. La continua monitorización y adaptación del esquema a medida que evolucionan los patrones de uso también son prácticas recomendadas en el dinámico entorno NoSQL.

A continuación, se presenta un diagrama de decisión simplificado para visualizar el proceso de elección entre embeber y referenciar:

codigo mermaid


    graph TD
        A[Iniciar: Modelando Relaciones NoSQL] --> B{Datos relacionados accedidos
principalmente con el padre?}
        B -->|Sí| C{Datos relacionados pequeños
y con crecimiento limitado?}
        C -->|Sí| D{Actualizaciones frecuentes
de datos relacionados?}
        D -->|No| E[Embeber]
        D -->|Sí| F{Consistencia global alta prioridad?}
        F -->|Sí| G[Referenciar]
        F -->|No| E
        C -->|No| H{Datos relacionados grandes
o crecimiento ilimitado?}
        H -->|Sí| G
        H -->|No| I{Relación muchos-a-muchos?}
        I -->|Sí| G
        I -->|No| J{Necesidad de consultar/actualizar
datos relacionados independientemente?}
        J -->|Sí| G
        J -->|No| E
        B -->|No| K{Datos relacionados consultados/actualizados
frecuentemente de forma independiente?}
        K -->|Sí| G
        K -->|No| I
        E --> L[Implementar modelo embebido]
        G --> M[Implementar modelo referenciado]
        L --> N[Fin]
        M --> N[Fin]

Ver página completa →

RabbitMQ 4: Robustez y Seguridad en RabbitMQ

Mauricio ECR
Arquitectura
27 Apr, 2025

Hemos recorrido el camino desde la introducción a RabbitMQ y su papel en la mensajería asíncrona, pasando por su arquitectura, componentes de enrutamiento (Exchanges y Bindings), y la gestión detallad

Ver página completa

RabbitMQ 3: Configuración y Gestión de Colas en RabbitMQ

Mauricio ECR
Arquitectura
26 Apr, 2025

Después de entender qué es RabbitMQ y cómo sus Exchanges y Bindings dirigen los mensajes, llegamos a la Cola. La cola es fundamentalmente un buffer confiable: es el lugar donde los mensajes esperan su

Ver página completa

RabbitMQ 3: Configuración y Gestión de Colas en RabbitMQ

Mauricio ECR
Arquitectura
26 Apr, 2025

Después de entender qué es RabbitMQ y cómo sus Exchanges y Bindings dirigen los mensajes, llegamos a la Cola. La cola es fundamentalmente un buffer confiable: es el lugar donde los mensajes esperan su turno para ser procesados por un consumidor. Aunque parecen simples contenedores, las colas en RabbitMQ tienen una serie de propiedades y argumentos avanzados que son cruciales para definir su comportamiento, rendimiento y fiabilidad.

En este tercer artículo, exploraremos en detalle la estructura de las colas, cómo múltiples consumidores trabajan con ellas, profundizaremos en el patrón Pub/Sub desde la perspectiva de la cola, y abordaremos uno de los temas más importantes para la resiliencia: el manejo de errores y reintentos.

Estructura y Propiedades de las Colas

Cada cola en RabbitMQ se define con un conjunto de propiedades que determinan cómo se comporta:

Nombre:
- Puede ser especificado por la aplicación que declara la cola. Si varias aplicaciones declaran la misma cola con el mismo nombre y propiedades, todas interactuarán con la misma cola.
- Puede ser generado automáticamente por RabbitMQ (lo que ocurre si no especificas un nombre al declarar la cola). Estas colas generadas suelen ser no duraderas, exclusivas y auto-eliminables, ideales para respuestas temporales o escenarios de "reply-to".
Durabilidad (durable):
- Si es true, la declaración de la cola sobrevivirá a un reinicio del broker. Esto es crucial si quieres que tu sistema sea resiliente y no pierda la definición de sus colas principales ante una caída del servidor. Los mensajes persistentes en una cola duradera también sobrevivirán.
- Si es false (colas transitorias), la cola se perderá si el broker se reinicia. Útil para colas temporales.
Exclusividad (exclusive):
- Si es true, la cola solo puede ser utilizada por la conexión que la declaró y se eliminará cuando esa conexión se cierre. Son útiles para colas de respuesta temporales y privadas entre dos procesos.
- Si es false, la cola puede ser utilizada por múltiples conexiones.
Auto-Delete (auto-delete):
- Si es true, la cola se eliminará automáticamente cuando el último consumidor se desconecte de ella. Es útil para colas temporales usadas solo mientras haya un consumidor activo.
- Si es false, la cola persistirá incluso si no hay consumidores activos. Es el comportamiento típico para colas de tareas o eventos que deben esperar.

Declarar una cola con propiedades que no coinciden con una cola existente con el mismo nombre resultará en un error. Por eso, es una buena práctica que todas las aplicaciones que interactúen con una cola la declaren con las mismas propiedades esperadas.

Argumentos Avanzados de las Colas

Las colas pueden aceptar argumentos adicionales durante su declaración para configurar comportamientos más complejos:

x-message-ttl (Time-To-Live por Mensaje):
- Define por cuánto tiempo (en milisegundos) un mensaje puede permanecer en la cola antes de expirar.
- Si un mensaje expira, puede ser descartado o enviado a un Dead-Letter Exchange (si está configurado).
- Útil para mensajes con validez limitada.
x-expires (TTL de la Cola):
- Define por cuánto tiempo (en milisegundos) una cola puede existir sin actividad (sin consumidores, sin mensajes publicados). Después de este tiempo, la cola se elimina automáticamente.
- Útil para colas temporales que no son exclusivas pero que deseas que se limpien solas.
x-dead-letter-exchange (DLX) y x-dead-letter-routing-key:
- Permiten configurar el Dead-Lettering. Si un mensaje muere en esta cola (expira por TTL, es rechazado sin posibilidad de reencolar, o la cola alcanza su límite de longitud), en lugar de ser descartado, se publica en el Exchange especificado por x-dead-letter-exchange, opcionalmente con la routing key especificada por x-dead-letter-routing-key.
- Fundamental para implementar manejo de mensajes fallidos, reintentos con retraso o auditoría de mensajes perdidos.
x-max-length y x-max-length-bytes:
- Establecen límites máximos en el número de mensajes (x-max-length) o el tamaño total en bytes (x-max-length-bytes) que una cola puede contener.
- Útil para proteger el broker de colas que crecen indefinidamente y consumen demasiada memoria o disco.
x-overflow (Política de Desbordamiento):
- Define qué sucede si la cola alcanza su límite (x-max-length o x-max-length-bytes).
- Las políticas comunes son drop-head (eliminar los mensajes más viejos) o reject-publish (rechazar nuevas publicaciones al Exchange asociado con la cola, notificando al productor). drop-head es el valor por defecto.
x-queue-type (Tipos de Cola):
- Permite elegir el tipo de implementación de la cola. Los tipos comunes son classic (el tipo histórico, con variantes mirrored para HA) y quorum (un tipo más reciente, recomendado para alta disponibilidad y durabilidad, basado en Raft).
- La elección depende de los requisitos de HA y consistencia.
x-max-priority (Prioridades de Mensajes):
- Si se configura, la cola puede manejar mensajes con diferentes niveles de prioridad. Los consumidores recibirán los mensajes de mayor prioridad antes que los de menor prioridad.
- Requiere que los mensajes también se publiquen con una propiedad priority.

Procesamiento Paralelo con Múltiples Consumidores

Una de las grandes ventajas de usar colas de mensajes es la capacidad de escalar el procesamiento simplemente añadiendo más consumidores a la misma cola.

Cuando múltiples consumidores se conectan a la misma cola, RabbitMQ distribuye los mensajes entre ellos en un esquema de round-robin por defecto. Cada mensaje enviado a esa cola será entregado a uno solo de los consumidores activos conectados a ella. Esto permite que el trabajo (procesar mensajes) se paralelice. Si un consumidor está ocupado, el mensaje se enviará al siguiente consumidor disponible.

Consideraciones Importantes:

Idempotencia: Dado que los mensajes se distribuyen y un consumidor podría fallar después de recibir el mensaje pero antes de confirmarlo (ACK), el mismo mensaje podría ser reentregado a otro consumidor. Tus operaciones de procesamiento deben ser idempotentes, es decir, poder ejecutarse múltiples veces con el mismo resultado que si se ejecutaran una sola vez, para evitar efectos secundarios no deseados.
Concurrencia: Tus consumidores deben estar diseñados para manejar la concurrencia si procesan múltiples mensajes simultáneamente (controlado por el prefetch).
Orden de Procesamiento: RabbitMQ garantiza el orden de los mensajes dentro de una sola cola. Sin embargo, con múltiples consumidores procesando mensajes en paralelo, el orden en que los mensajes terminan de procesarse puede no ser el mismo que el orden en que llegaron a la cola, debido a las diferentes velocidades de procesamiento de los consumidores. Si el orden global es estrictamente necesario, necesitas una estrategia diferente (ej: usar un solo consumidor por cola, o particionar la cola lógicamente).
QoS (Quality of Service) / Prefetch: Esta es una configuración crucial. El prefetch count en el consumidor le dice a RabbitMQ cuántos mensajes puede enviar a ese consumidor antes de que reciba un acknowledgement (ACK). Un prefetch de 1 significa que RabbitMQ no enviará el siguiente mensaje a ese consumidor hasta que haya confirmado el anterior. Un prefetch más alto permite al consumidor tener un buffer de mensajes y mantener ocupados a los workers internos, pero si el consumidor falla, todos esos mensajes "prefecheados" pero no confirmados serán re-enviados. Ajustar el prefetch es clave para balancear el rendimiento y la distribución de carga.

Patrón de Publicación/Suscripción Detallado

Mientras que el patrón Pub/Sub a menudo se asocia con el Fanout Exchange, es importante entender que la suscripción en RabbitMQ implica que cada suscriptor tiene su propia cola.

Cuando se utiliza un Fanout Exchange (o incluso Direct/Topic con múltiples bindings a diferentes colas), el mensaje que llega al Exchange se copia a cada cola vinculada a ese Exchange. Los consumidores se conectan individualmente a sus propias colas para recibir los mensajes.

Uso del Fanout Exchange: Ideal cuando un evento debe ser notificado a múltiples sistemas independientes, y cada sistema necesita procesar todos los eventos de ese tipo. Cada sistema se conecta a su propia cola, y esta cola se vincula al Fanout Exchange.
Consideraciones:
- Acoplamiento Laxo: Los publicadores no necesitan saber cuántos o quiénes son los suscriptores.
- Escalabilidad: Cada suscriptor puede escalar el procesamiento de su copia de los mensajes añadiendo más consumidores a su cola.
- Garantía de Entrega a Cada Cola: Si un mensaje llega a un Fanout Exchange, RabbitMQ garantiza que intentará entregarlo a todas las colas vinculadas (asumiendo que las colas existan y no estén llenas). Si una cola no existe o tiene problemas, eso no afecta la entrega a las otras colas.

Manejo de Errores y Reintentos

La comunicación asíncrona implica que el productor envía un mensaje y asume que será procesado. ¿Pero qué pasa si el consumidor falla al procesarlo? RabbitMQ ofrece mecanismos robustos para manejar estos escenarios y evitar la pérdida de mensajes.

Acknowledgements (Confirmaciones):
- Auto-ACK: (No recomendado para procesamiento crítico) El broker elimina el mensaje de la cola inmediatamente después de enviarlo al consumidor. Si el consumidor falla antes de procesar el mensaje, este se pierde.
- Manual-ACK: El consumidor debe enviar explícitamente una confirmación (basic.ack) al broker después de haber procesado exitosamente el mensaje. Solo entonces el broker eliminará el mensaje de la cola. Si el consumidor falla antes de enviar el ACK, o si la conexión se cierra, el broker detectará que el mensaje no fue confirmado y lo re-enviará (a la misma cola, posiblemente a otro consumidor). Este es el modo preferido para la fiabilidad.
Qué sucede si un consumidor lanza un error (con Manual-ACK): Si un consumidor encuentra un error al procesar un mensaje y no envía un ACK, RabbitMQ (por defecto o si la conexión se cierra) re-enviará el mensaje. Esto puede llevar a un bucle infinito de fallos si el error es persistente para ese mensaje particular.
Estrategias de Reintento en el Consumidor: El consumidor debe implementar lógica para manejar fallos transitorios (ej: base de datos caída temporalmente) y permanentes (ej: mensaje mal formado). Para fallos transitorios, puede intentar re-procesar el mensaje (posiblemente con un retraso usando una cola de retardo o DLX). Para fallos permanentes, debe rechazar el mensaje de forma que no vuelva a ser re-enviado inmediatamente a la misma cola, sino que se envíe a una cola de "mensajes muertos".
Uso de Dead-Letter Exchanges (DLX) y Dead-Letter Queues (DLQ):
- Configuras tu cola principal (la que consume tu aplicación) con x-dead-letter-exchange y opcionalmente x-dead-letter-routing-key.
- Declaras una cola separada, la Dead-Letter Queue (DLQ), y la vinculas al DLX configurado en el paso 1.
- Cuando un mensaje en la cola principal:
  - Expira (TTL).
  - Es rechazado por el consumidor usando basic.reject o basic.nack con requeue=false.
  - La cola principal alcanza su límite de longitud y mensajes viejos son descartados (x-overflow: drop-head).
- Ese mensaje es enviado al DLX y enrutado a la DLQ.

Puedes tener un consumidor separado escuchando en la DLQ para inspeccionar los mensajes fallidos, registrarlos, alertar a un operador, o intentar un reintento manual/diferido.

Rechazo de Mensajes (basic.reject y basic.nack):
- basic.reject es para rechazar un solo mensaje.
- basic.nack (Negative Acknowledgement) es similar a reject pero puede rechazar múltiples mensajes a la vez (los mensajes anteriores al delivery_tag especificado que aún no han sido confirmados).
- Ambos métodos aceptan un argumento requeue:
  - requeue=true: El mensaje se re-enviará a la misma cola (posiblemente al mismo o a otro consumidor). Útil para fallos transitorios donde quieres reintentar inmediatamente.
  - requeue=false: El mensaje no se re-enviará a la cola de origen. Si la cola tiene un DLX configurado, el mensaje irá allí. Si no, el mensaje se descarta. Útil para fallos permanentes.

codigo mermaid


      graph LR
          P[Productor] --> B(Broker);
          B --> Q1[Cola Principal];
          Q1 --> C1{Consumidor Principal};
          C1 -- Procesamiento Exitoso --> OK[Éxito];
          C1 -- Error --> B;
          B -- DLX --> QD[(Cola de Mensajes Fallidos 'DLQ')];
          QD --> C2{Consumidor de Errores};
          C2 --> RE[Registro de Error/Análisis];

Conclusión

Las colas son más que simples contenedores; son componentes configurables que determinan la durabilidad, la capacidad y el comportamiento de los mensajes en reposo. Hemos explorado sus propiedades básicas (durabilidad, exclusividad, auto-delete) y, de manera más importante, los argumentos avanzados como TTL, DLX y límites de tamaño, que nos dan control granular sobre el ciclo de vida del mensaje y la gestión de la cola.

Entendimos cómo RabbitMQ distribuye mensajes a múltiples consumidores para lograr procesamiento paralelo y las consideraciones (como la idempotencia y QoS) que esto implica. Finalmente, abordamos el crítico tema del manejo de errores mediante acknowledgements manuales y la implementación de estrategias de reintento y gestión de mensajes fallidos utilizando Dead-Letter Exchanges y Dead-Letter Queues.

Con una comprensión sólida de los Exchanges y las Colas, sus propiedades y cómo interactúan, tenemos la base teórica completa. El siguiente paso lógico es llevar esta teoría a la práctica. En el próximo artículo, construiremos un ejemplo funcional simple usando Java (o un lenguaje de tu elección, especificaremos Java como ejemplo) para conectar un productor y un consumidor a RabbitMQ y ver la mensajería en acción.

Ver página completa →

RabbitMQ 2: Arquitectura y Enrutamiento Avanzado en RabbitMQ

Mauricio ECR
Arquitectura
25 Apr, 2025

En nuestro primer artículo, exploramos qué es RabbitMQ, por qué es fundamental para la comunicación asíncrona en sistemas distribuidos y cuáles son sus casos de uso típicos. Lo comparamos con una "ofi

Ver página completa

RabbitMQ 2: Arquitectura y Enrutamiento Avanzado en RabbitMQ

Mauricio ECR
Arquitectura
25 Apr, 2025

En nuestro primer artículo, exploramos qué es RabbitMQ, por qué es fundamental para la comunicación asíncrona en sistemas distribuidos y cuáles son sus casos de uso típicos. Lo comparamos con una "oficina de correos inteligente" que recibe, clasifica y entrega mensajes. Ahora, es momento de abrir las puertas de esa oficina de correos y ver qué hay dentro. Entender los componentes clave de RabbitMQ y cómo interactúan es esencial para diseñar sistemas de mensajería eficientes y robustos. Este artículo se sumergirá en la arquitectura interna y, lo que es más importante, en cómo RabbitMQ decide a dónde enviar cada mensaje, es decir, su sofisticado enrutamiento.

Componentes Clave de RabbitMQ

Para entender cómo funciona RabbitMQ, primero debemos conocer a los actores principales en su arquitectura:

Productor (Producer): Es la aplicación que crea y envía mensajes a RabbitMQ. En nuestra analogía, es quien escribe y deposita la carta en el buzón. El productor no necesita saber quién consumirá el mensaje, solo sabe a qué tipo de destinatario (Exchange) quiere enviárselo.
Consumidor (Consumer): Es la aplicación que se conecta a RabbitMQ para recibir y procesar mensajes. Es la persona que recibe la carta en su casa. Los consumidores se registran en las colas y esperan a que lleguen los mensajes.
Broker (RabbitMQ Server): Es el propio servicio de RabbitMQ, la "oficina de correos" en sí. Recibe mensajes de los productores y los enruta a las colas donde los consumidores están escuchando.
Cola (Queue): Es un buffer donde los mensajes residen temporalmente hasta que un consumidor esté listo para procesarlos. Es el buzón específico de cada destinatario donde se acumulan sus cartas. Las colas están definidas por nombres.
Exchange: Es la primera parada para un mensaje enviado por un productor al broker. El Exchange no almacena mensajes; su única función es recibir mensajes y determinar a qué colas debe enrutarlos. Piensa en el Exchange como el empleado de correos que lee la dirección (o el tipo de servicio solicitado) en la carta y la coloca en la pila correcta para su distribución a los buzones (colas).
Binding: Es la "regla" o "conexión" que le dice a un Exchange cómo enrutar mensajes a una cola específica. Es como decirle al empleado del Exchange: "Las cartas con esta dirección [Routing Key] deben ir a este buzón [Queue]". Un Binding es una conexión entre un Exchange y una Queue.
Vhost (Virtual Host): Un Vhost es un entorno virtual completamente aislado dentro de un solo servidor de RabbitMQ. Es como tener múltiples oficinas de correos separadas dentro del mismo edificio. Cada Vhost tiene sus propios Exchanges, Queues, Bindings, permisos, etc., lo que permite aislar diferentes aplicaciones o entornos multi-tenant dentro del mismo broker físico o cluster. Se identifica con un nombre (por defecto, /).
Channel: Dentro de una conexión TCP entre una aplicación (productor o consumidor) y RabbitMQ, se pueden crear uno o más canales virtuales. Una conexión puede tener múltiples canales. Esto reduce el overhead de abrir/cerrar múltiples conexiones TCP. Las operaciones de envío y recepción de mensajes se realizan sobre un canal. Piensa en una conexión como la tubería principal y los canales como "sub-tuberías" multiplexadas dentro de ella.

(Diagrama simplificado de la interacción entre componentes)

codigo mermaid


    flowchart TD
        %% Definición de los componentes
        subgraph Producers
            P1[Productor 1]
            P2[Productor 2]
            P3[Productor 3]
        end
        subgraph Broker["Broker RabbitMQ (Vhost)"]
            subgraph Exchanges
                EX1[Exchange]
            end
            subgraph Queues
                Q1[Cola 1]
                Q2[Cola 2]
            end
            EX1 -->|Binding 1| Q1
            EX1 -->|Binding 2| Q2
        end
        subgraph Consumers
            C1[Consumidor 1]
            C2[Consumidor 2]
            C3[Consumidor 3]
        end
        %% Conexiones
        P1 -->|Mensaje| EX1
        P2 -->|Mensaje| EX1
        P3 -->|Mensaje| EX1
        Q1 --> C1
        Q1 --> C2
        Q2 --> C3
        %% Leyenda/Notas
        note[Nota: Las conexiones entre clientes y broker \nse realizan a través de Channels\ndentro de una conexión TCP]   
        style note fill:#fff,stroke:#666,stroke-width:1px

Exchanges en Detalle

El Exchange es el corazón del sistema de enrutamiento de RabbitMQ. Un productor nunca envía un mensaje directamente a una cola; siempre lo envía a un Exchange.

¿Qué es un Exchange y su función principal?

Como mencionamos, un Exchange recibe mensajes del productor y, basándose en su tipo y en las reglas de Binding, decide a qué cola(s) enviar ese mensaje. El Exchange es la lógica de enrutamiento central.

Tipos de Exchanges

RabbitMQ soporta varios tipos de Exchanges, cada uno con una lógica de enrutamiento diferente:

Direct Exchange:
- Lógica: Enruta mensajes a colas basándose en una coincidencia exacta entre la routing key del mensaje y la binding key del binding.
- Uso típico: Comunicación uno-a-uno o uno-a-varios si múltiples colas tienen la misma binding key. Ideal para enviar un mensaje a una cola específica identificada por un nombre o un código.
- Analogía: Envías una carta con una dirección exacta ("Calle Sol, 123"). El Exchange (empleado) busca bindings que coincidan exactamente con "Calle Sol, 123" y envía la carta a los buzones (colas) vinculados con esa dirección.
Topic Exchange:
- Lógica: Enruta mensajes a colas basándose en patrones en la routing key. La routing key es una lista de palabras separadas por puntos (ej: logs.error.critical). Los bindings usan patrones con comodines:
  - * (asterisco) coincide con exactamente una palabra.
  - # (almohadilla) coincide con cero o más palabras.
- Uso típico: Sistemas de logging, eventos que tienen jerarquías. Permite a los consumidores suscribirse a categorías amplias o muy específicas de mensajes.
- Analogía: Envías una carta con un tema categorizado (ej: Reportes.Financieros.Mensual). El Exchange busca bindings que coincidan con patrones como Reportes.# (cualquier reporte) o *.Financieros.* (cualquier cosa financiera) o Reportes.Financieros.Mensual (reportes financieros mensuales específicos).
Fanout Exchange:
- Lógica: Enruta el mensaje a todas las colas que están vinculadas a él, ignorando por completo la routing key. Es una transmisión (broadcast).
- Uso típico: Patrón Publicación/Suscripción (Pub/Sub). Ideal cuando quieres enviar una copia del mismo mensaje a múltiples consumidores que están escuchando en diferentes colas.
- Analogía: Anuncias algo por un megáfono en el centro de la oficina. Todos los que estén escuchando (colas vinculadas) reciben el mismo mensaje.
Headers Exchange:
- Lógica: Enruta mensajes basándose en los encabezados (headers) del mensaje en lugar de la routing key. Los bindings especifican qué headers deben coincidir. Soporta coincidencias any (cualquiera de los headers debe coincidir) o all (todos los headers deben coincidir).
- Uso típico: Enrutamiento más complejo basado en múltiples atributos del mensaje, cuando la estructura jerárquica de Topic no es suficiente.
- Analogía: Envías una carta con varias etiquetas (headers) como Departamento: Ventas, Prioridad: Alta. El Exchange busca bindings que requieran que Departamento sea Ventas y Prioridad sea Alta (coincidencia all), o quizás que solo Prioridad sea Alta (coincidencia any).

Declaración de Exchanges

Para usar un Exchange, primero debe ser declarado en el broker. Al declararlo, especificas:

Nombre: Un identificador único.
Tipo: direct, topic, fanout, headers.
Durabilidad: Si el Exchange sobrevive a un reinicio del broker (true) o no (false). Los Exchanges declarados por el sistema (sin nombre o amq.fanout, amq.direct, etc.) suelen ser duraderos.
Auto-Delete: Si el Exchange se elimina automáticamente cuando no hay más colas vinculadas a él (true) o no (false).
Argumentos: Parámetros adicionales para configuraciones más avanzadas.

La declaración puede hacerla tanto un productor como un consumidor; si ya existe un Exchange con el mismo nombre y propiedades, no pasa nada. Si no existe, se crea.

Routing Keys y Bindings

Estos dos elementos trabajan juntos para definir cómo los mensajes fluyen desde un Exchange a una o varias Colas.

¿Qué es una Routing Key?

La routing key es un atributo que el productor incluye con cada mensaje que envía a un Exchange. Es como la "dirección" o "categoría" del mensaje. La interpretación de la routing key depende del tipo de Exchange al que se envía el mensaje:

Direct Exchange: La routing key es una cadena exacta.
Topic Exchange: La routing key es una cadena jerárquica separada por puntos (ej: stock.usd.nyse, stock.eur.london).
Fanout Exchange: La routing key del mensaje se ignora.
Headers Exchange: La routing key del mensaje se ignora, el enrutamiento se basa en los headers del mensaje.

¿Qué es un Binding?

Un Binding es una conexión entre un Exchange y una Cola. Define la regla por la cual los mensajes que llegan al Exchange serán copiados a esa Cola particular. Cuando declaras un Binding, también especificas:

El Exchange de origen.
La Cola de destino.
Una Binding Key (excepto para Fanout Exchanges). Esta clave es la que se compara con la routing key del mensaje o los headers del mensaje, dependiendo del tipo de Exchange.

Cómo trabajan juntos Routing Keys y Bindings

La magia ocurre cuando un mensaje llega a un Exchange:

El Exchange recibe el mensaje y su routing key (y possibly headers).
El Exchange mira su lista de Bindings.
Para cada Binding conectado a ese Exchange, el Exchange compara la routing key del mensaje (o los headers) con la binding key (o las reglas de headers) del Binding, según el tipo de Exchange.
Si la routing key (o headers) coincide con la binding key del Binding, el Exchange copia el mensaje a la Cola asociada con ese Binding.

Un mismo mensaje puede ser copiado a múltiples colas si coincide con varios bindings del Exchange. Si un mensaje llega a un Exchange y no coincide con ningún binding, el mensaje se descarta (a menos que el Exchange esté configurado para enviar mensajes "unroutable" de vuelta al productor o a un Alternate Exchange).

Ejemplos de Bindings por tipo de Exchange

Direct Exchange:
- Binding: Exchange mi_directo -> Queue cola_a con Binding Key clave.exacta
- Mensaje con Routing Key clave.exacta enviado a mi_directo -> Va a cola_a.
- Mensaje con Routing Key otra.clave enviado a mi_directo -> Se descarta (si no hay otros bindings).
Topic Exchange:
- Binding 1: Exchange mi_topico -> Queue logs_errores con Binding Key logs.error.#
- Binding 2: Exchange mi_topico -> Queue logs_criticos_prod con Binding Key logs.*.critical.production
- Mensaje con Routing Key logs.error.database enviado a mi_topico -> Va a logs_errores.
- Mensaje con Routing Key logs.warning enviado a mi_topico -> Va a logs_errores.
- Mensaje con Routing Key logs.error.critical.production enviado a mi_topico -> Va a logs_errores Y logs_criticos_prod.
Fanout Exchange:
- Binding 1: Exchange mi_fanout -> Queue cola_sub1 (Binding Key se ignora)
- Binding 2: Exchange mi_fanout -> Queue cola_sub2 (Binding Key se ignora)
- Mensaje enviado a mi_fanout con cualquier Routing Key -> Va a cola_sub1 Y cola_sub2.
Headers Exchange:
- Binding: Exchange mi_headers -> Queue cola_reportes con Headers {"formato": "pdf", "tipo": "mensual"} y argumento x-match: all.
- Mensaje con Headers {"formato": "pdf", "tipo": "mensual", "departamento": "ventas"} enviado a mi_headers -> Va a cola_reportes (cumple la regla all).
- Mensaje con Headers {"formato": "pdf", "tipo": "anual"} enviado a mi_headers -> No va a cola_reportes (no cumple la regla all).

Topologías Típicas de Enrutamiento

La combinación de diferentes tipos de Exchanges, Routing Keys y Bindings permite crear diversas topologías de mensajería para satisfacer distintas necesidades:

Uno-a-Uno (Generalmente con Direct Exchange): Un productor envía mensajes que van a una única cola específica (o un grupo reducido de colas que procesan el mismo tipo de tarea). Se logra con un Direct Exchange y bindings exactos entre la routing key y la binding key de la cola.

codigo mermaid


    graph LR
        Producer --> DirectEx[Direct Exchange]
        DirectEx -->|routing_key = 'task_a'| QueueA[Queue A]
        DirectEx -->|routing_key = 'task_b'| QueueB[Queue B]
        QueueA --> ConsumerA[Consumer A]
        QueueB --> ConsumerB[Consumer B]

Publicación/Suscripción (Generalmente con Fanout Exchange): Un productor envía un mensaje que es recibido por todos los consumidores que están suscritos a ese "tema" (Exchange). Cada suscriptor suele tener su propia cola. Se logra con un Fanout Exchange. Todos los mensajes enviados al Fanout Exchange se copian a todas las colas vinculadas a él.

codigo mermaid


    graph LR
        Publisher[Publisher] --> FanoutEx[Fanout Exchange]
        FanoutEx --> Queue1[(Sub 1)]
        FanoutEx --> Queue2[(Sub 2)]
        FanoutEx --> Queue3[(Sub 3)]
        Queue1 --> Subscriber1[Subscriber 1]
        Queue2 --> Subscriber2[Subscriber 2]
        Queue3 --> Subscriber3[Subscriber 3]

Enrutamiento Selectivo (Generalmente con Direct o Topic Exchanges): Los mensajes se enrutan a colas específicas basándose en el contenido de la routing key. Esto permite que diferentes grupos de consumidores reciban solo los mensajes que les interesan. Direct Exchange se usa para selección exacta, Topic Exchange para selección basada en patrones jerárquicos.

codigo mermaid


    graph LR
        Logger[Logger] --> TopicEx[Topic Exchange]
        TopicEx -->|routing_key = 'logs.error.#'| ErrorQueue[Error Queue]
        TopicEx -->|routing_key = '*.critical'| CriticalQueue[Critical Queue]
        TopicEx -->|routing_key = 'logs.#'| AllLogsQueue[All Logs Queue]
        ErrorQueue --> ErrorConsumer[Error Consumer]
        CriticalQueue --> CriticalConsumer[Critical Consumer]
        AllLogsQueue --> AnalyticsConsumer[Analytics Consumer]

Entender estos componentes y cómo interactúan es el primer paso para diseñar tu sistema de mensajería con RabbitMQ. La flexibilidad del sistema de Exchanges y Bindings es lo que permite a RabbitMQ adaptarse a una amplia gama de patrones de comunicación.

Conclusión

En este artículo, hemos desglosado la arquitectura fundamental de RabbitMQ, conociendo a sus protagonistas: productores, consumidores, colas, exchanges y bindings. Hemos visto que el Exchange es el cerebro del enrutamiento, dirigiendo los mensajes a las colas basándose en el tipo de Exchange y las reglas definidas por los Bindings y las Routing Keys. Exploramos los diferentes tipos de Exchanges (Direct, Topic, Fanout, Headers) y cómo sus lógicas de enrutamiento permiten construir topologías desde la simple comunicación uno-a-uno hasta complejos sistemas de publicación/suscripción y enrutamiento selectivo. Con una comprensión clara de estos componentes y cómo se enrutan los mensajes, estamos listos para el siguiente paso crucial: la configuración y gestión detallada de las Colas, que es donde los mensajes esperan pacientemente a ser procesados. En el próximo artículo, profundizaremos en las propiedades de las colas, cómo gestionar su durabilidad, tamaño y características avanzadas como los Dead-Letter Exchanges.

Ver página completa →

RabbitMQ 1: Introducción a RabbitMQ, El Corazón de la Mensajería Asíncrona

Mauricio ECR
Arquitectura
24 Apr, 2025

En el mundo del desarrollo de software moderno, especialmente con el auge de los microservicios y los sistemas distribuidos, la forma en que las diferentes partes de una aplicación se comunican es fun

Ver página completa

Asegurando el Tejido Distribuido: Una Guía para la Seguridad en Arquitecturas de Microservicios

Mauricio ECR
Seguridad
24 Apr, 2025

El viaje hacia arquitecturas de microservicios ha transformado la forma en que construimos y desplegamos software. La agilidad, escalabilidad y resiliencia que ofrecen son innegables. Sin embargo, est

Ver página completa

Optimizando el Acceso a Datos: La Importancia de las Proyecciones JPA en Spring Boot

Mauricio ECR
Persistencia
23 Apr, 2025

El Costo Oculto de Traer Demasiada Información En el desarrollo de aplicaciones que interactúan con bases de datos, una tarea fundamental es la recuperación de datos. Al usar Object-Relational Map

Ver página completa

Optimizando el Acceso a Datos: La Importancia de las Proyecciones JPA en Spring Boot

Mauricio ECR
Persistencia
23 Apr, 2025

El Costo Oculto de Traer Demasiada Información

En el desarrollo de aplicaciones que interactúan con bases de datos, una tarea fundamental es la recuperación de datos. Al usar Object-Relational Mapping (ORM) como JPA (Java Persistence API), es común y tentador mapear nuestras tablas a entidades Java completas y, por defecto, recuperar estas entidades enteras cada vez que realizamos una consulta. Por ejemplo, si tenemos una entidad Usuario con 20 atributos (id, nombre, email, dirección, fecha de registro, último login, preferencias, etc.), una consulta simple como findById(1L) o findByEmail("[email protected]") a menudo se traduce, detrás de escena, en un SELECT u.* FROM usuario u WHERE ....

Si bien esto simplifica el desarrollo inicialmente, presenta un problema significativo a medida que la aplicación crece o cuando solo necesitamos una pequeña porción de esa información: el sobrecoste de datos (over-fetching).

¿Qué problemas concretos genera esto?

Consumo de Ancho de Banda: Transferir columnas innecesarias entre la base de datos y la aplicación consume más ancho de banda de red.
Uso de Memoria: La aplicación necesita más memoria para mantener en el Heap objetos más grandes de lo necesario.
Rendimiento de la Base de Datos: La base de datos tiene que leer más datos del disco (potencialmente) y procesar más información.
Latencia: La serialización/deserialización de objetos más grandes toma más tiempo, aumentando la latencia de las respuestas.
Carga en el Garbage Collector: Objetos más grandes y potencialmente más numerosos (si se traen listas) ponen más presión sobre el recolector de basura de la JVM.

En resumen, no seleccionar específicamente los datos que necesitamos es ineficiente y puede degradar significativamente el rendimiento y la escalabilidad de nuestras aplicaciones, especialmente en escenarios de alta concurrencia o con tablas muy anchas (muchas columnas) o largas (muchas filas).

Posibles Soluciones para Optimizar la Recuperación de Datos

Ante el problema del over-fetching, existen varias estrategias que podemos emplear:

Recuperar Entidades Completas (El Anti-Patrón): Como ya mencionamos, es la opción por defecto pero la menos eficiente si no necesitas toda la información.
Consultas Nativas (Native Queries): Escribir SQL directamente. Permite un control total y seleccionar exactamente las columnas deseadas. Sin embargo, se pierde la portabilidad entre bases de datos, la seguridad de tipos en tiempo de compilación (parcialmente) y puede mezclar lógica SQL con el código Java de forma menos elegante.
Criteria API de JPA: Una forma programática y type-safe de construir consultas. Es potente y flexible, permitiendo seleccionar atributos específicos. Su principal desventaja es que puede volverse bastante verbosa y compleja para consultas sencillas.
Proyecciones (El Enfoque Recomendado): Utilizar las características de JPA y extensiones (como las de Spring Data JPA) para definir explícitamente qué atributos de una entidad queremos recuperar. Ofrece un excelente equilibrio entre eficiencia, legibilidad y seguridad de tipos.

Nos centraremos en esta última: las proyecciones.

Proyecciones JPA al Rescate

Una proyección en el contexto de JPA y Spring Data JPA es una técnica que nos permite definir una "vista" o subconjunto de los atributos de una entidad que deseamos recuperar de la base de datos. En lugar de traer el objeto completo, le indicamos al framework que solo queremos ciertos campos.

Spring Data JPA facilita enormemente el uso de proyecciones mediante dos mecanismos principales:

Proyecciones Basadas en Interfaces (Interface-based Projections)

Defines una interfaz Java que declara métodos get() para los atributos que deseas seleccionar. Los nombres de los métodos deben coincidir con los nombres de las propiedades de la entidad.

Spring Data JPA genera automáticamente la consulta SQL necesaria (SELECT columna1, columna2 FROM ...) y crea una instancia proxy de esa interfaz en tiempo de ejecución, rellenándola con los datos recuperados.

Es la forma más común y recomendada por su simplicidad y claridad.

Proyecciones Basadas en Clases (Class-based Projections - DTOs)

Creas una clase (típicamente un DTO - Data Transfer Object) con los campos que necesitas y un constructor que acepte esos campos como parámetros.

En tu consulta (usando @Query con JPQL), utilizas la sintaxis SELECT NEW com.tu.paquete.TuDTO(e.atributo1, e.atributo2) FROM Entidad e WHERE ....

JPA ejecutará la consulta seleccionando solo las columnas necesarias y las usará para instanciar tu DTO.

Es útil cuando necesitas más lógica en el objeto proyectado o si prefieres trabajar con clases concretas.

Ventajas Clave de Usar Proyecciones

Eficiencia: Reduce drásticamente la cantidad de datos transferidos y procesados.
Rendimiento: Consultas más rápidas y menor consumo de memoria y CPU.
Claridad: El código (interfaces de proyección o DTOs) documenta explícitamente qué datos se esperan para un caso de uso específico.
Seguridad (con interfaces): Mantiene la seguridad de tipos en gran medida.

Ejemplo Práctico con Spring Boot y JPA

Imaginemos una aplicación de e-commerce con una entidad Producto.

1. Entidad Producto:

package com.miblog.proyecciones.entity;

import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Lob; // Para campos grandes

@Entity
public class Producto {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String nombre;

    @Lob // Indica que puede ser un objeto grande (TEXT, CLOB, BLOB)
    private String descripcionDetallada; // Campo potencialmente pesado

    private double precio;
    private int stock;
    private String categoria;

    // Constructores, Getters y Setters (Omitidos por brevedad)
    // Lombok @Data, @NoArgsConstructor, @AllArgsConstructor puede ser útil aquí
}

Supongamos que en una vista de listado rápido solo necesitamos mostrar el nombre y el precio de los productos con stock disponible. Traer descripcionDetallada sería un desperdicio.

2. Proyección Basada en Interfaz:

Creamos una interfaz que defina la vista que necesitamos:

package com.miblog.proyecciones.projection;

public interface ProductoResumen {
    String getNombre();
    double getPrecio();
    // También puedes tener valores calculados con SpEL:
    // @Value("#{target.nombre + ' (' + target.categoria + ')'}")
    // String getNombreConCategoria();
}

3. Repositorio Spring Data JPA:

Modificamos nuestro repositorio para usar la proyección:

package com.miblog.proyecciones.repository;

import com.miblog.proyecciones.entity.Producto;
import com.miblog.proyecciones.projection.ProductoResumen;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

import java.util.List;

@Repository
public interface ProductoRepository extends JpaRepository<Producto, Long> {

    // Spring Data JPA detecta que el tipo de retorno es una interfaz
    // y automáticamente aplica la proyección.
    List<ProductoResumen> findByStockGreaterThan(int stockMinimo);

    // Ejemplo con DTO (requiere definir la clase ProductoDTO)
    /*
    @Query("SELECT NEW com.miblog.proyecciones.dto.ProductoDTO(p.nombre, p.precio) FROM Producto p WHERE p.stock > :stockMinimo")
    List<ProductoDTO> findDtoByStockGreaterThan(@Param("stockMinimo") int stockMinimo);
    */

    // También es posible usar proyecciones dinámicas:
    // <T> List<T> findByCategoria(String categoria, Class<T> type);
    // Al llamar: productoRepository.findByCategoria("Electrónicos", ProductoResumen.class);
    // O         productoRepository.findByCategoria("Electrónicos", Producto.class); // Trae la entidad completa
}

4. Uso en un Servicio (Ejemplo):

package com.miblog.proyecciones.service;

import com.miblog.proyecciones.projection.ProductoResumen;
import com.miblog.proyecciones.repository.ProductoRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class ProductoService {

    @Autowired
    private ProductoRepository productoRepository;

    public List<ProductoResumen> obtenerResumenProductosEnStock() {
        // Solo se traerán las columnas 'nombre' y 'precio' de la BD
        return productoRepository.findByStockGreaterThan(0);
    }
}

Al ejecutar obtenerResumenProductosEnStock(), Spring Data JPA generará una consulta SQL similar a:

SELECT p.nombre AS nombre, p.precio AS precio
FROM producto p
WHERE p.stock > 0; -- O el valor pasado como parámetro

Como puedes ver, la columna descripcionDetallada (y las demás no incluidas en ProductoResumen) ni siquiera se mencionan en el SELECT, logrando nuestro objetivo de eficiencia.

Conclusión:

No recuperar datos innecesarios de la base de datos es fundamental para construir aplicaciones performantes y escalables. Las proyecciones en JPA, especialmente con las facilidades que ofrece Spring Data JPA, son una herramienta poderosa y elegante para lograr este objetivo.

Adoptar el uso de proyecciones (ya sea basadas en interfaces o DTOs) siempre que no necesites la entidad completa debería considerarse una buena práctica estándar. Te permite:

Minimizar la carga en la red y la base de datos.
Reducir el consumo de memoria en tu aplicación.
Acelerar los tiempos de respuesta.
Escribir código más claro respecto a los datos requeridos para cada caso de uso.

La próxima vez que escribas una consulta, pregúntate: "¿Realmente necesito todos los atributos de esta entidad?". Si la respuesta es no, considera seriamente usar una proyección. Tu aplicación (y tus usuarios) te lo agradecerán.

Ver página completa →

Observabilidad de Servidores y Contenedores Docker: Una Mirada Práctica con Prometheus, Grafana y cAdvisor

Mauricio ECR
DevOps
22 Apr, 2025

En el mundo de la infraestructura moderna, especialmente con la creciente adopción de contenedores y arquitecturas distribuidas, entender qué está sucediendo dentro de nuestros sistemas en tiempo real

Ver página completa

Observabilidad de Servidores y Contenedores Docker: Una Mirada Práctica con Prometheus, Grafana y cAdvisor

Mauricio ECR
DevOps
22 Apr, 2025

En el mundo de la infraestructura moderna, especialmente con la creciente adopción de contenedores y arquitecturas distribuidas, entender qué está sucediendo dentro de nuestros sistemas en tiempo real se ha vuelto fundamental. Ya no basta con saber si un servidor está "encendido"; necesitamos comprender su comportamiento interno, cómo interactúan sus componentes y predecir posibles problemas antes de que afecten a los usuarios. Aquí es donde entra el concepto de

Observabilidad.

¿Qué es la Observabilidad?

La observabilidad es la capacidad de inferir el estado interno de un sistema midiendo sus salidas externas. En términos prácticos, se trata de recopilar y analizar datos de nuestro sistema para poder hacer preguntas arbitrarias sobre su comportamiento sin necesidad de conocer previamente todas las posibles fallas o estados. A diferencia del monitoreo tradicional, que a menudo se centra en métricas conocidas y umbrales predefinidos para alertar sobre problemas conocidos, la observabilidad nos permite explorar el sistema para diagnosticar problemas desconocidos o inesperados.

Los Tres Pilares de la Observabilidad

La observabilidad se construye típicamente sobre tres tipos principales de datos o "pilares":

Monitoreo (Metrics): Consiste en la recopilación de datos numéricos agregados a lo largo del tiempo (series temporales). Estas son las métricas de rendimiento como uso de CPU, memoria, latencia de red, errores por segundo, etc. El monitoreo nos da una vista de alto nivel del rendimiento y salud del sistema y sus componentes. Es excelente para detectar tendencias, identificar cuellos de botella y disparar alertas basadas en umbrales.
Logging (Logs): Son registros de eventos discretos que ocurren dentro de una aplicación o sistema. Los logs proporcionan información detallada sobre lo que sucedió en un momento específico. Son cruciales para la depuración, el análisis de causa raíz de problemas y la auditoría.
Trazabilidad (Tracing): Permite seguir el camino de una solicitud a medida que atraviesa los diferentes servicios en un sistema distribuido. El tracing es vital para comprender las interacciones entre microservicios, identificar la latencia en flujos de trabajo complejos y depurar problemas de rendimiento en arquitecturas distribuidas.

Aunque los tres pilares son esenciales para una observabilidad completa, el monitoreo a menudo constituye la base inicial, proporcionando la visibilidad en tiempo real necesaria para identificar rápidamente cuándo y dónde podría estar ocurriendo un problema.

Enfocándonos en el Monitoreo

El monitoreo nos proporciona la capacidad de responder preguntas como:

¿Cuánta CPU está usando mi servidor?
¿Cuánta memoria libre tiene un contenedor Docker específico?
¿Cuántas solicitudes por segundo está manejando mi aplicación?
¿Cuál es la latencia promedio de las respuestas de mi API?
¿Está aumentando el número de errores HTTP en mi servicio web?

Tener acceso a estas métricas en tiempo real y a lo largo del tiempo nos permite no solo reaccionar a los problemas, sino también anticiparlos, optimizar recursos y planificar la capacidad.

Herramientas Clave para el Monitoreo

Existen numerosas herramientas para implementar soluciones de monitoreo. Para monitorear servidores y, crucialmente, los recursos y el rendimiento a nivel de contenedor en Docker, una pila muy popular y efectiva es la compuesta por Prometheus y Grafana, complementada con Exporters como Node Exporter y cAdvisor. En algunos setups, herramientas como Redis pueden usarse como soporte (aunque no es estrictamente parte del pipeline de métricas principal en este contexto).

Prometheus: Es un sistema de monitoreo y alerta basado en series temporales. Prometheus recolecta métricas de diversos orígenes (endpoints HTTP que exponen métricas en un formato específico) mediante un modelo "pull" (Prometheus va y "raspa" los datos de los targets configurados). Es la base de nuestra recopilación y almacenamiento de métricas.
Grafana: Es una plataforma de código abierto para la visualización y el análisis de métricas. Grafana se conecta a diversas fuentes de datos, incluyendo Prometheus, y permite crear dashboards personalizables con gráficos, tablas y otros paneles para visualizar las métricas recopiladas de forma intuitiva. Es la interfaz principal para que los humanos interactúen con los datos de monitoreo. 📝 Nota: Una vez que Grafana esté funcionando, puedes importar dashboards prediseñados desde Grafana Labs. Por ejemplo, si estás monitoreando un servidor como una Raspberry Pi, puedes utilizar el dashboard con el ID 15120, que está optimizado para mostrar métricas clave de un sistema Linux. Solo necesitas ir a “+ / Import” dentro de Grafana, ingresar el número del panel (15120) y seleccionar Prometheus como fuente de datos. Esto te permitirá visualizar de inmediato un conjunto de gráficos útiles sin tener que construirlos desde cero.
Node Exporter: Es un "exporter" oficial de Prometheus que se instala en servidores Linux para exponer métricas a nivel del sistema operativo (CPU, memoria, disco, red, etc.). Esencial para entender el estado de la máquina host donde se ejecutan los contenedores.
cAdvisor (Container Advisor): Es otra herramienta de código abierto (originalmente de Google) que monitorea el uso de recursos y el rendimiento de los contenedores en ejecución. cAdvisor recopila métricas como uso de CPU, memoria, E/S de red y sistema de archivos para cada contenedor. Es indispensable para tener visibilidad del consumo de recursos por contenedor.
Redis: Aunque no es una herramienta de monitoreo per se, a veces se incluye en setups (como parece insinuar tu depends_on en cAdvisor, aunque no es el uso más común hoy en día) potencialmente como una caché o base de datos auxiliar para ciertas herramientas de monitoreo o sus componentes. En el contexto de este setup, su papel específico no es central para la recopilación de métricas por parte de Prometheus, sino quizás una dependencia para la versión o configuración específica de cAdvisor que se está utilizando.

Implementando la Pila de Monitoreo con Docker Compose

Docker Compose nos permite definir y ejecutar aplicaciones multi-contenedor con un solo comando. El archivo docker-compose.yml que proporcionaste orquesta la implementación de Prometheus, Grafana, Node Exporter, cAdvisor y Redis.

Aquí está el contenido del archivo docker-compose.yml:

services: 
  grafana: 
    image: grafana/grafana:latest
    container_name: grafana_monitoring
    restart: unless-stopped manualmente.
    volumes: 
      - /home/dev/docker/monitoring/grafana/data:/var/lib/grafana 
    ports: 
      - '3000:3000' 
    networks: 
      - monitoring_net 
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus 
    restart: unless-stopped 
    volumes: 
      - /home/dev/docker/monitoring/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml 
      - /home/dev/docker/monitoring/prometheus/data:/prometheus 
    ports:
      - '9090:9090' 
    command:
      - '--config.file=/etc/prometheus/prometheus.yml' 
      - '--storage.tsdb.path=/prometheus' 
      - '--web.console.libraries=/etc/prometheus/console_libraries' 
      - '--web.console.templates=/etc/prometheus/consoles' 
      - '--web.enable-lifecycle'
    networks: 
      - monitoring_net 

  node-exporter: 
    image: prom/node-exporter:latest 
    container_name: node-exporter 
    restart: unless-stopped 
    volumes: 
      - /proc:/host/proc:ro 
      - /sys:/host/sys:ro 
      - /:/rootfs:ro
    command: 
      - '--path.procfs=/host/proc'
      - '--path.rootfs=/rootfs'
      - '--path.sysfs=/host/sys'
      - '--collector.filesystem.mount-points-exclude=^/(sys|proc|dev|host|etc)($$|/)' 
    expose: 
      - 9100 
    networks: 
      - monitoring_net 

  cadvisor: 
    image: gcr.io/cadvisor/cadvisor:latest 
    container_name: cadvisor 
    restart: unless-stopped 
    ports: 
      - '8080:8080' 
    volumes: 
      - /:/rootfs:ro 
      - /var/run:/var/run:rw 
      - /sys:/sys:ro 
      - /var/lib/docker/:/var/lib/docker:ro 
    depends_on: 
      - redis 
    networks: 
      - monitoring_net 

  redis: 
    image: redis:latest 
    container_name: redis 
    expose: 
      - 6379 
    networks: 
      - monitoring_net 

networks: 
  monitoring_net: 
    external: true

Explicación del Archivo Docker Compose:

El archivo define varios services, cada uno representando un contenedor:

grafana: Configura el contenedor de Grafana, mapeando su puerto web (3000) al host y persistiendo sus datos en un volumen del host. Se une a la red monitoring_net.
prometheus: Configura el contenedor de Prometheus, montando su archivo de configuración (prometheus.yml) y volumen de datos en el host. Su puerto web (9090) se mapea al host. También se une a la red monitoring_net y especifica argumentos de comando para su inicio.
node-exporter: Configura el contenedor de Node Exporter. Crucialmente, monta directorios del sistema operativo host (/proc, /sys, /) en modo lectura (ro) para poder acceder a las métricas del sistema. Especifica los paths correctos en su comando de inicio. Expone su puerto por defecto (9100) internamente en la red monitoring_net.
cadvisor: Configura el contenedor de cAdvisor. Mapea su puerto web (8080) al host y monta varios directorios (/, /var/run, /sys, /var/lib/docker) que necesita para acceder a la información de los contenedores y el sistema Docker. Depende del servicio redis para iniciar y se une a la red monitoring_net.
redis: Configura el contenedor de Redis, exponiendo su puerto por defecto (6379) internamente en la red monitoring_net. Su inclusión aquí es principalmente como dependencia para cAdvisor en este setup específico.

Finalmente, la sección networks define la red monitoring_net como external: true. Esto significa que Docker Compose buscará una red existente con ese nombre en lugar de crear una nueva. Debes crear esta red manualmente antes de ejecutar el docker-compose utilizando el comando: docker network create monitoring_net

Configuración de Prometheus (prometheus.yml)

El archivo prometheus.yml le dice a Prometheus qué objetivos (targets) debe "raspar" (scrape) para obtener métricas y con qué frecuencia debe hacerlo.

Aquí está el contenido del archivo prometheus.yml:

global:
  scrape_interval:   15s 
scrape_configs: 

  - job_name: 'prometheus' 
    scrape_interval: 15s 
    static_configs: 
    - targets: ['prometheus:9090'] 

  - job_name: 'cadvisor' 
    static_configs: 
    - targets: ['cadvisor:8080'] 

  - job_name: 'node-exporter' 
    static_configs: 
    - targets: ['node-exporter:9100']

Explicación del Archivo de Configuración de Prometheus:

global: Establece el intervalo de raspado por defecto (scrape_interval) en 15 segundos.
scrape_configs: Define una lista de trabajos (job_name). Cada trabajo especifica un conjunto de targets que Prometheus debe monitorear.
- El trabajo 'prometheus' se configura para raspar las métricas del propio servidor Prometheus en su puerto 9090. Esto es útil para monitorear la salud y el rendimiento del servidor de monitoreo.
- El trabajo 'cadvisor' se configura para raspar las métricas de cAdvisor en el puerto 8080. Gracias a la red Docker, Prometheus puede referirse al contenedor cAdvisor simplemente por su nombre de servicio (cadvisor).
- El trabajo 'node-exporter' se configura para raspar las métricas de Node Exporter en el puerto 9100, utilizando el nombre del servicio Docker (node-exporter).

Este archivo de configuración le indica a Prometheus que debe conectarse a los servicios prometheus, cadvisor y node-exporter dentro de la red monitoring_net (Docker maneja la resolución de nombres) en sus respectivos puertos para recolectar métricas cada 15 segundos.

Conclusión

Implementar una estrategia de observabilidad robusta es esencial para gestionar eficazmente infraestructuras basadas en servidores y Docker. La pila Prometheus, Grafana, Node Exporter y cAdvisor proporciona una base sólida para el monitoreo, permitiéndonos recopilar, almacenar y visualizar métricas cruciales sobre el rendimiento del sistema host y el consumo de recursos a nivel de contenedor. Al configurar estas herramientas mediante Docker Compose y definir correctamente los trabajos de raspado en Prometheus, podemos obtener la visibilidad necesaria para mantener nuestros sistemas saludables, identificar problemas rápidamente y optimizar nuestra infraestructura de manera proactiva.

Este setup es un excelente punto de partida. Para una observabilidad completa, se deberían integrar soluciones de logging (como ELK stack o Loki) y tracing (como Jaeger o Zipkin) para complementar la información proporcionada por el monitoreo.

Ver página completa →

Cuándo Usar Colas de Mensajes en el Desarrollo de Software

Mauricio ECR
Arquitectura
18 Apr, 2025

Las colas de mensajes son herramientas clave para construir sistemas distribuidos, escalables y tolerantes a fallos. En este artículo te comparto una guía con situaciones comunes donde su uso es altam

Ver página completa

Cuándo Usar Colas de Mensajes en el Desarrollo de Software

Mauricio ECR
Arquitectura
18 Apr, 2025

Las colas de mensajes son herramientas clave para construir sistemas distribuidos, escalables y tolerantes a fallos. En este artículo te comparto una guía con situaciones comunes donde su uso es altamente recomendable. Esto puede servirte como referencia rápida para decidir si una cola puede ser útil en tu arquitectura.

1. Procesamiento Asíncrono de Tareas Pesadas

Descripción de la situación

Una aplicación web necesita procesar tareas pesadas (como enviar correos, generar PDFs o hacer procesamiento de imágenes) después de una solicitud del usuario.

Dificultades

Alta latencia si se procesa todo en la misma petición HTTP.
Posibles timeouts en el servidor.
Experiencia de usuario lenta y frustrante.

Por qué se solucionaría con colas de mensajes

Separar el procesamiento de la respuesta al usuario permite responder rápido y delegar la tarea a un worker. La cola actúa como puente entre el sistema que genera la tarea y el que la ejecuta.

Características típicas de la cola

Persistencia para no perder mensajes si algo falla.
Retries automáticos para tareas fallidas.
Delay opcional para tareas programadas.
Visibilidad de mensajes en procesamiento.

2. Comunicación Entre Microservicios

Descripción de la situación

Una arquitectura basada en microservicios donde varios servicios necesitan intercambiar información o coordinar acciones.

Dificultades

El acoplamiento entre servicios crece si se comunican de forma directa (HTTP sincrónico).
Si un servicio está caído, puede romper toda la cadena.
Difícil escalar servicios de forma independiente.

Por qué se solucionaría con colas de mensajes

Las colas desacoplan los servicios, permitiendo que uno publique mensajes sin depender del estado del consumidor. Esto permite una comunicación más resiliente y escalable.

Características típicas de la cola

Entrega garantizada (at-least-once).
Soporte para múltiples consumidores.
Escalabilidad horizontal.
Opcional: orden garantizado de mensajes.

3. Picos de Carga Temporales

Descripción de la situación

Una aplicación recibe picos de tráfico (por ejemplo, durante una campaña de marketing o un evento en vivo).

Dificultades

El sistema puede saturarse si intenta procesar todo al instante.
Riesgo de perder solicitudes o fallar por falta de recursos.

Por qué se solucionaría con colas de mensajes

Las colas permiten "almacenar" las tareas y procesarlas a medida que los workers tienen capacidad. Se convierte una carga variable en una carga continua.

Características típicas de la cola

Alta capacidad de buffer.
Procesamiento en paralelo (workers escalables).
Métricas para monitorear backlog.
Integración con sistemas de auto-escalado.

4. Integración con Sistemas Externos o APIs Lentas

Descripción de la situación

Tu sistema necesita integrarse con APIs de terceros (por ejemplo, pasarelas de pago, servicios de envío, etc.) que pueden ser lentas o poco confiables.

Dificultades

Timeouts frecuentes.
Limitaciones de tasa (rate limiting).
Caídas del servicio externo afectan el sistema completo.

Por qué se solucionaría con colas de mensajes

Poner las llamadas a servicios externos en una cola permite controlar el ritmo, manejar reintentos, y evitar sobrecargar al proveedor.

Características típicas de la cola

Retries con backoff.
Soporte para Dead Letter Queues (DLQ).
Capacidad de definir prioridades o tasa de procesamiento.
Persistencia y durabilidad.

5. Auditoría y Logging Centralizado

Descripción de la situación

Se requiere capturar eventos del sistema (como accesos, cambios de estado, errores) en un sistema central para auditoría o análisis.

Dificultades

El logeo en tiempo real puede bloquear procesos principales.
Si el sistema de auditoría cae, se pierden los eventos.

Por qué se solucionaría con colas de mensajes

Las colas permiten enviar eventos de forma asincrónica y confiable a un sistema de almacenamiento o procesamiento.

Características típicas de la cola

Alta velocidad de escritura.
Orden garantizado (opcional, según la necesidad).
Múltiples consumidores (ej. para alertas, dashboards).
Baja latencia.

6. Workflows Distribuidos (Orquestación de Procesos)

Descripción de la situación

Un proceso complejo requiere que varias acciones ocurran en orden y/o condicionalmente, como un onboarding de usuario o procesamiento de pagos.

Dificultades

Difícil mantener el estado y coordinación entre servicios.
Problemas de sincronización y gestión de errores.

Por qué se solucionaría con colas de mensajes

Las colas permiten implementar orquestadores que gestionan los pasos del workflow como eventos, con flexibilidad para manejar errores y lógica condicional.

Características típicas de la cola

Soporte para enrutamiento de mensajes.
Integración con motores de orquestación.
Baja latencia y confiabilidad.
Opcional: soporte para eventos tipo pub/sub.

🧪 Ejemplo: Generación Asíncrona de PDF usando una Cola

Este ejemplo representa un caso real y común: un usuario solicita la generación de un PDF. En lugar de procesarlo en la misma solicitud (lo cual puede tardar), se encola la tarea y un worker la procesa de forma asíncrona.

🧍‍♂️ Usuario solicita un PDF desde el Frontend

El usuario hace una solicitud para generar un PDF. Este proceso es controlado desde el frontend, donde el usuario envía su solicitud.

// Envío de solicitud desde el cliente (frontend)
// Este llamado puede estar en un botón: "Generar PDF"
fetch('/generate-pdf', { 
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ userId: 123 })
})
  .then(res => res.json())
  .then(data => {
    // El usuario recibe un mensaje indicando que la tarea ha sido encolada.
    console.log(data.status);  // "Tarea encolada correctamente"
    console.log("ID de la tarea:", data.jobId);  // El ID para consultar el estado
  });

🧠 Backend (API) recibe la solicitud y encola la tarea

El backend recibe la solicitud del frontend y encola la tarea en una cola de trabajo para ser procesada en segundo plano. La API responde inmediatamente al usuario con la confirmación de que la tarea se ha encolado.

# Supongamos un backend en Flask (Python)

@app.route('/generate-pdf', methods=['POST'])
def generate_pdf():
    data = request.get_json()
    user_id = data['userId']

    # Genera un identificador único para la tarea
    job_id = str(uuid.uuid4())

    # Se encola una tarea para procesar luego
    enqueue_task('generate_pdf', {'user_id': user_id, 'job_id': job_id})

    # Responde al usuario con la confirmación de la tarea encolada
    return jsonify({
        'status': 'Tarea encolada correctamente',
        'jobId': job_id,  # ID de la tarea para que el usuario pueda consultar el estado
        'message': 'Te notificaremos cuando tu PDF esté listo para descargar.'
    })

¿Qué hace `enqueue_task`?

La función enqueue_task empuja la tarea a una cola (como Redis, RabbitMQ, AWS SQS, etc.). El jobId se guarda para poder referenciar la tarea.

def enqueue_task(task_name, data):
    task = {
        'name': task_name,
        'data': data
    }
    redis.rpush('pdf_tasks', json.dumps(task))  # Ejemplo con Redis

⚙️ Worker que consume tareas y las ejecuta

El worker es un proceso que corre en segundo plano y escucha la cola para procesar las tareas en el momento adecuado. Una vez que el PDF esté generado, puede guardarlo o enviarlo al usuario.

# Un worker que corre en segundo plano y escucha la cola

def worker():
    while True:
        raw_task = redis.blpop('pdf_tasks', timeout=0)  # Espera indefinidamente
        if raw_task:
            task = json.loads(raw_task[1])
            handle_task(task)

def handle_task(task):
    if task['name'] == 'generate_pdf':
        user_id = task['data']['user_id']
        job_id = task['data']['job_id']
        generate_pdf_for_user(user_id, job_id)

def generate_pdf_for_user(user_id, job_id):
    # Aquí iría la lógica real de generación del PDF
    print(f"Generando PDF para el usuario {user_id}")
    
    # Simulación: se genera el PDF y se guarda con el ID de tarea
    filename = f"{job_id}.pdf"
    with open(filename, "w") as f:
        f.write(f"PDF generado para usuario {user_id}")
    
    # Aquí podrías guardar el resultado en una BD o subirlo a un almacenamiento
    # Además, actualizamos el estado de la tarea en la base de datos o en el sistema de colas
    redis.set(f"job:{job_id}:status", "completado")

📥 Consulta del estado de la tarea (opcional)

El usuario puede consultar el estado de la tarea en cualquier momento utilizando el jobId que se le proporcionó cuando la tarea fue encolada. Esto permite saber si la tarea está aún en proceso o si ya ha sido completada.

@app.route('/job-status/<job_id>', methods=['GET'])
def job_status(job_id):
    status = redis.get(f"job:{job_id}:status")  # Recupera el estado desde Redis
    return jsonify({'jobId': job_id, 'status': status or 'pendiente'})

En este ejemplo, si el jobId existe en el sistema, el usuario recibirá el estado de la tarea. De lo contrario, puede devolver el estado como "pendiente" si la tarea aún no se ha completado.

📧 Notificación cuando la tarea se complete (opcional)

Además de permitir que el usuario consulte el estado, puedes configurar una notificación para cuando el trabajo esté listo. Esto podría ser una notificación en la web, un correo electrónico, o incluso un SMS.

Ejemplo de función de notificación:

def notify_user(user_id, job_id):
    # Esta función podría enviar un email, SMS o una notificación web
    # Aquí simplemente imprimimos un mensaje de ejemplo
    print(f"Notificando al usuario {user_id} que su PDF con jobId {job_id} está listo para descargar.")

Puedes llamar a esta función después de que la tarea haya sido procesada y el PDF esté disponible.

💡 Ventajas de este enfoque

✅ Respuesta inmediata: El usuario no espera bloqueado mientras se genera el PDF.
🕐 Asincronía: El trabajo pesado se maneja en segundo plano, sin afectar la experiencia del usuario.
🔔 Notificación opcional: El usuario puede ser notificado cuando la tarea esté lista.
🧱 Escalabilidad: Puedes agregar más workers si la carga aumenta, o priorizar tareas según la necesidad.
🔗 Desacoplamiento: El frontend no está directamente vinculado al procesamiento pesado.

Conclusión

Las colas no son solo una herramienta de "alto nivel empresarial", sino una solución práctica para muchos retos comunes en el desarrollo moderno. Identificar los síntomas típicos —como latencia, acoplamiento, o pérdida de datos— puede ayudarte a decidir cuándo usarlas.

Ver página completa →

Guía Rápida de Comandos y Cláusulas SQL

Mauricio ECR
Persistencia
15 Apr, 2025

SQL (Structured Query Language) es el lenguaje estándar para gestionar y manipular bases de datos relacionales. A continuación, encontrarás una guía rápida con los comandos y cláusulas más utilizados,

Ver página completa

Guía Rápida de Comandos y Cláusulas SQL

Mauricio ECR
Persistencia
15 Apr, 2025

SQL (Structured Query Language) es el lenguaje estándar para gestionar y manipular bases de datos relacionales. A continuación, encontrarás una guía rápida con los comandos y cláusulas más utilizados, ejemplos prácticos y el orden de ejecución en una consulta SQL.

🛠️ Comandos Básicos de SQL

SELECT: Selecciona datos de una tabla.
FROM: Indica la tabla desde la cual se obtendrán los datos.
WHERE: Filtra los resultados según una condición.
AS: Asigna un alias a una columna o tabla.
JOIN: Combina filas de dos o más tablas.
AND: Une condiciones, todas deben cumplirse.
OR: Une condiciones, al menos una debe cumplirse.
LIMIT: Limita la cantidad de filas devueltas.
IN: Filtra por varios valores posibles en una condición.
CASE: Devuelve un valor basado en condiciones.
IS NULL: Devuelve solo las filas con valores nulos.
LIKE: Busca patrones dentro de una columna.
COMMIT: Guarda los cambios de una transacción.
ROLLBACK: Revierte una transacción.

🔧 Modificación de Tablas

ALTER TABLE: Agrega o elimina columnas.
UPDATE: Modifica datos existentes.
CREATE: Crea una tabla, base de datos, índice o vista.
DELETE: Elimina filas de una tabla.
INSERT: Agrega una fila nueva.
DROP: Elimina una tabla, base de datos o índice.

📊 Funciones de Agregación

GROUP BY: Agrupa datos en conjuntos lógicos.
ORDER BY: Ordena los resultados (usar DESC para descendente).
HAVING: Similar a WHERE pero se aplica a grupos.
COUNT(): Cuenta el número de filas.
SUM(): Suma los valores de una columna.
AVG(): Calcula el promedio de una columna.
MIN(): Devuelve el valor mínimo.
MAX(): Devuelve el valor máximo. `

🔗 Tipos de JOIN

INNER JOIN: Devuelve solo las coincidencias en ambas tablas.
LEFT JOIN: Devuelve todos los registros de la tabla izquierda y coincidencias de la derecha.
RIGHT JOIN: Devuelve todos los registros de la tabla derecha y coincidencias de la izquierda.
FULL OUTER JOIN: Devuelve todos los registros con coincidencias en cualquiera de las tablas.

🔄 Orden de Ejecución en una Consulta SQL

FROM – Se identifican las tablas.
WHERE – Se filtran las filas.
GROUP BY – Se agrupan los datos.
HAVING – Se filtran los grupos.
SELECT – Se seleccionan las columnas.
ORDER BY – Se ordenan los resultados.
LIMIT – Se limita la cantidad de filas.

💡 Ejemplos de SQL

Consultas Básicas

-- Seleccionar todas las columnas con filtro
SELECT * FROM tabla WHERE columna > 5;

-- Seleccionar primeras 10 filas de dos columnas
SELECT col1, col2 FROM tabla LIMIT 10;

-- Múltiples filtros con OR
SELECT * FROM tabla WHERE col1 > 5 OR col2 < 2;

-- Ordenar resultados
SELECT col1, col2 FROM tabla ORDER BY 1;

Funciones de Agregación

-- Contar filas
SELECT COUNT(*) FROM tabla;

-- Sumar valores
SELECT SUM(col1) FROM tabla;

-- Valor máximo
SELECT MAX(col1) FROM tabla;

-- Promedio agrupado
SELECT AVG(col1) FROM tabla GROUP BY col2;

Consultas Avanzadas

-- LEFT JOIN con alias
SELECT * FROM tabla AS t1 LEFT JOIN tabla2 AS t2 ON t2.col1 = t1.col1;

-- Agregación con filtro de grupo
SELECT col1, COUNT(*) AS total FROM tabla GROUP BY col1 HAVING COUNT(*) > 10;

-- Uso de CASE
SELECT col1,
       CASE 
         WHEN col1 > 10 THEN 'más de 10'
         WHEN col1 < 10 THEN 'menos de 10'
         ELSE 'es 10'
       END AS NuevaColumna
FROM tabla;

🧱 Lenguaje de Definición de Datos (DDL)

-- Crear base de datos y tabla
CREATE DATABASE MiBase;
CREATE TABLE MiTabla (id INT, nombre VARCHAR(18));

-- Crear índice
CREATE INDEX IndiceNombre ON MiTabla(col1);

-- Alterar tabla
ALTER TABLE MiTabla ADD col5 INT;
ALTER TABLE MiTabla DROP COLUMN col5;

-- Eliminar base de datos o tabla
DROP DATABASE MiBase;
DROP TABLE MiTabla;

✍️ Lenguaje de Manipulación de Datos (DML)

-- Insertar fila
INSERT INTO MiTabla (col1, col2) VALUES ('valor1', 'valor2');

-- Actualizar valores
UPDATE MiTabla SET col1 = 56 WHERE col2 = 'algo';

-- Eliminar filas
DELETE FROM MiTabla WHERE col1 = 'algo';

-- Seleccionar columnas
SELECT col1, col2 FROM MiTabla;

Ver página completa →

Gestión de Migraciones de Base de Datos con Flyway en Spring Boot"

Mauricio ECR
Persistencia
14 Apr, 2025

Introducción El desarrollo de aplicaciones modernas no solo implica escribir código de negocio, sino también gestionar la evolución de la base de datos. A medida que un proyecto crece, mantener

Ver página completa

Gestión de Migraciones de Base de Datos con Flyway en Spring Boot"

Mauricio ECR
Persistencia
14 Apr, 2025

Introducción

El desarrollo de aplicaciones modernas no solo implica escribir código de negocio, sino también gestionar la evolución de la base de datos. A medida que un proyecto crece, mantener la coherencia del esquema entre desarrolladores, ramas y entornos puede volverse complejo.

Aquí es donde Flyway entra en juego: una herramienta de migración de base de datos ligera y poderosa que permite controlar versiones de esquemas de forma segura, repetible y automatizada.

¿Qué es Flyway?

Flyway es una herramienta de migración de base de datos que permite aplicar scripts de manera controlada y automática. Utiliza una convención de nombres para identificar versiones y aplica cambios incrementales cada vez que la aplicación se inicia.

Problemas que resuelve:

Desincronización entre esquemas de desarrollo, prueba y producción.
Cambios accidentales o no versionados.
Dificultad para aplicar migraciones en equipo o CI/CD.
Fragilidad de los esquemas generados automáticamente por JPA.

Comparación breve con alternativas:

Herramienta	Lenguaje	Comunidad	SQL puro	Migraciones Java
Flyway	Java	Muy activa	✅ Sí	✅ Opcional
Liquibase	Java	Activa	✅ Sí	✅ Más flexible

¿Cuándo usar Flyway?

Escenarios ideales:

Proyectos con evolución frecuente del esquema.
Equipos distribuidos o con múltiples entornos (dev, test, prod).
Necesidad de auditoría o trazabilidad de cambios en el esquema.

Ventajas sobre auto-DDL de JPA (`spring.jpa.hibernate.ddl-auto`):

Evita sobrescritura accidental de datos.
Versionado explícito de cambios.
Mayor control y trazabilidad de la evolución del esquema.

Implementación en Spring Boot

Requisitos previos:

Agrega las siguientes dependencias en tu archivo pom.xml:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-core</artifactId>
    </dependency>
</dependencies>

Para Gradle: implementation 'org.flywaydb:flyway-core'

Configuración básica (`application.properties`):

spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.username=sa
spring.datasource.password=
spring.datasource.driver-class-name=org.h2.Driver

spring.jpa.hibernate.ddl-auto=none

spring.flyway.enabled=true
spring.flyway.locations=classpath:db/migration

Ejemplo Práctico: Proyecto de Gestión de Usuarios

Supongamos una aplicación con una tabla users. Vamos a construir el esquema paso a paso usando Flyway.

Estructura del proyecto:

src/
 └── main/
     └── resources/
         └── db/
             └── migration/
                 ├── V1__Create_user_table.sql
                 └── V2__Add_user_role_column.sql

Primera Iteración – Crear tabla `users`

Archivo: V1__Create_user_table.sql

CREATE TABLE users (
    id BIGINT PRIMARY KEY,
    username VARCHAR(50) NOT NULL,
    email VARCHAR(100) UNIQUE
);

✅ Al iniciar la aplicación, Flyway detecta este archivo y lo ejecuta. Marca la versión como aplicada en su propia tabla de control (flyway_schema_history).

Segunda Iteración – Agregar columna `role`

Archivo: V2__Add_user_role_column.sql

ALTER TABLE users ADD COLUMN role VARCHAR(20) DEFAULT 'USER';

✅ Flyway identifica que esta versión aún no ha sido aplicada, la ejecuta y actualiza su historial. No vuelve a aplicar la versión 1.

Visualización del Estado de la Base de Datos Tras las Migraciones

Después de ejecutar las dos migraciones (V1 y V2), Flyway deja una huella en la base de datos que te permite auditar el estado de los cambios.

Tablas creadas tras las migraciones:

1. Tabla de usuarios (`users`):

SELECT * FROM users;

Estructura:

Columna	Tipo	Restricciones
id	BIGINT	PRIMARY KEY
username	VARCHAR(50)	NOT NULL
email	VARCHAR(100)	UNIQUE
role	VARCHAR(20)	DEFAULT 'USER'

2. Tabla de control de Flyway (`flyway_schema_history`):

SELECT * FROM flyway_schema_history;

Ejemplo de contenido:

installed_rank	version	description	type	script	success
1	1	Create user table	SQL	V1__Create_user_table.sql	true
2	2	Add user role column	SQL	V2__Add_user_role_column.sql	true

Migraciones Java-based

Aunque Flyway trabaja perfectamente con scripts SQL, en algunos casos puede ser útil definir migraciones programáticamente en Java. Esto es útil cuando:

Necesitas lógica condicional o control de flujo.
Quieres reutilizar servicios de Spring.
Trabajas con bases de datos no relacionales o lógicas avanzadas.

Cómo crear una migración Java:

Implementa la clase extendiendo BaseJavaMigration.
Ubícala en el paquete db.migration o configura la ubicación.
Nómbrala con el patrón V{n}__Descripción.

Ejemplo: Crear tabla de auditoría

package db.migration;

import org.flywaydb.core.api.migration.BaseJavaMigration;
import org.flywaydb.core.api.migration.Context;

import java.sql.Statement;

public class V3__Create_audit_table extends BaseJavaMigration {
    @Override
    public void migrate(Context context) throws Exception {
        try (Statement stmt = context.getConnection().createStatement()) {
            stmt.execute("""
                CREATE TABLE audit (
                    id BIGINT PRIMARY KEY AUTO_INCREMENT,
                    action VARCHAR(100),
                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
                );
            """);
        }
    }
}

Configuración adicional si se cambia la ubicación:

spring.flyway.locations=classpath:db/migration
spring.flyway.java-migrations-location=com.ejemplo.migraciones

Tabla Resumen

Concepto	Descripción
Migraciones	Archivos SQL con prefijo `V{n}__` que modifican el esquema.
Integración con Spring	Ejecuta automáticamente migraciones al iniciar la app.
Ubicación por defecto	`classpath:db/migration`
Uso recomendado	Proyectos con cambios frecuentes en el esquema y colaboración en equipo.

Conclusión

Flyway no solo gestiona migraciones de manera declarativa (con SQL), sino que también ofrece una vía programática potente para casos avanzados. Su integración con Spring Boot hace que los cambios de esquema sean seguros, trazables y consistentes.

Recomendaciones Finales:

Nunca modifiques un script ya aplicado.
Usa migraciones Java cuando lo SQL no sea suficiente.
Verifica la tabla flyway_schema_history para diagnosticar errores o validar versiones.

Referencias

Ver página completa →

Descubre el Poder del SemVer: Optimiza el Versionado de tu Software y Mantén un CHANGELOG Excepcional

Mauricio ECR
Convenciones
08 Apr, 2025

El Versionado Semántico (SemVer) es una herramienta fundamental para comunicar de forma precisa los cambios en el software, facilitando el mantenimiento y la colaboración. Complementarlo con un **

Ver página completa

Descubre el Poder del SemVer: Optimiza el Versionado de tu Software y Mantén un CHANGELOG Excepcional

Mauricio ECR
Convenciones
08 Apr, 2025

El Versionado Semántico (SemVer) es una herramienta fundamental para comunicar de forma precisa los cambios en el software, facilitando el mantenimiento y la colaboración. Complementarlo con un CHANGELOG bien estructurado potencia la transparencia y la trazabilidad, ofreciendo una visión detallada de la evolución de cada versión. En este artículo, exploraremos en profundidad cómo adoptar SemVer y cómo mantener un CHANGELOG que vaya de la mano para optimizar tu proceso de desarrollo.

Introducción

El control de versiones en el desarrollo de software se convierte en una ventaja competitiva cuando se implementa de forma clara y estructurada. SemVer aporta un sistema numérico que indica el alcance de los cambios (cambios mayores, menores o correcciones), mientras que el CHANGELOG documenta y narra el proceso evolutivo de tu proyecto. Esta sinergia no solo facilita la colaboración interna, sino que también mejora la comunicación con los usuarios y clientes, ayudando a identificar qué, cuándo y por qué se han realizado determinados cambios.

1. Estructura Básica de SemVer

El formato principal de SemVer se compone de tres segmentos:

MAJOR.MINOR.PATCH

MAJOR: Se incrementa cuando se realizan cambios incompatibles con versiones anteriores (por ejemplo, la eliminación o modificación de una API pública).
MINOR: Se aumenta cuando se agregan nuevas funcionalidades de manera compatible.
PATCH: Se incrementa al corregir errores sin afectar las funcionalidades existentes.

Etiquetas Adicionales

Pre-release: Indica versiones inestables, por ejemplo, 1.0.0-beta.1.
Build Metadata: Añade información adicional de compilación, como en 1.0.0+20230901.

2. Reglas para Incrementar Versiones

Al actualizar una versión, es fundamental distinguir entre los diferentes tipos de cambios:

Versión MAJOR (X.y.z → X+1.0.0):
Se utiliza cuando se introducen cambios que rompen la compatibilidad con versiones anteriores.
Ejemplo: Modificar o eliminar una API de forma incompatible.
Versión MINOR (x.Y.z → x.Y+1.0):
Se incrementa al introducir nuevas funcionalidades sin afectar la compatibilidad.
Ejemplo: Agregar un método opcional a una clase.
Versión PATCH (x.y.Z → x.y.Z+1):
Se utiliza para corregir errores, preservando la compatibilidad con versiones anteriores.
Ejemplo: Arreglar un error en una función de cálculo.

3. Ejemplos Prácticos

Versión Inicial: 0.1.0
Indica la fase de desarrollo inicial donde el software puede sufrir cambios drásticos.
Primera Versión Estable: 1.0.0
Marca el lanzamiento oficial cuando la API es considerada estable y está documentada.
Actualización con Nueva Funcionalidad:
De 1.0.0 a 1.1.0 para incorporar mejoras sin romper compatibilidad.
Corrección Crítica:
De 1.1.0 a 1.1.1 para solucionar errores puntuales.
Cambio Incompatible:
De 1.1.1 a 2.0.0 cuando se realizan modificaciones que requieren cambios en el código del consumidor.

4. La Importancia de Mantener un CHANGELOG

Un CHANGELOG es un registro sistemático y estructurado que documenta de manera cronológica cada cambio, mejora y corrección en el software. Su incorporación al proceso de SemVer proporciona un contexto narrativo, detallando el "porqué" y el "cómo" detrás de cada versión.

Beneficios Clave del CHANGELOG

Claridad en la Comunicación:
Complementa los números de versión de SemVer con descripciones detalladas de los cambios implementados.
Trazabilidad y Historial:
Permite rastrear la evolución del software a lo largo del tiempo, facilitando la depuración y la revisión histórica.
Transparencia Interna y Externa:
Informa tanto a los desarrolladores como a los usuarios finales sobre las mejoras y cambios realizados, fortaleciendo la confianza en el proceso de actualización.
Soporte a la Automatización:
Herramientas integradas pueden actualizar el CHANGELOG de forma automática al seguir convenciones de commits, como Conventional Commits.

Mejores Prácticas para un CHANGELOG Efectivo

Estructuración Clara:
Organiza el CHANGELOG por versiones, empezando por la más reciente. Dentro de cada versión, clasifica los cambios en secciones como "Añadido", "Modificado", "Corregido" y "Notas de Deprecación".
Actualización Continua:
Registra los cambios a medida que se van implementando para capturar detalles precisos y evitar omisiones.
Integración con el Proceso de Versionado:
Vincula cada entrada del CHANGELOG con commits específicos y números de versión, facilitando la sincronización entre lo que se comunica y lo que se versiona.
Comunicación Externa:
Publica el CHANGELOG en el repositorio del proyecto y en las notas de lanzamiento para que usuarios y colaboradores comprendan la evolución del software.

Ejemplo Básico de CHANGELOG

# CHANGELOG

## [2.0.0] - 2025-04-01
### Añadido
- Nueva función para exportación de datos.
### Modificado
- Actualización del sistema de autenticación (rompe compatibilidad con versiones anteriores).
### Corregido
- Error en el módulo de notificaciones.

## [1.2.1] - 2025-03-15
### Corregido
- Solucionado el error en la actualización automática del perfil del usuario.

5. Herramientas para Generar CHANGELOG Automáticamente

Usar herramientas automatizadas facilita enormemente el mantenimiento de un CHANGELOG claro y actualizado. A continuación, se presentan algunas opciones destacadas:

Conventional Changelog

Base de muchas herramientas automatizadas.
Genera el CHANGELOG.md a partir de commits con formato estándar.
Ejemplo:

npx conventional-changelog -p angular -i CHANGELOG.md -s

standard-version

Automatiza el versionado y el changelog sin publicar a npm.
Ideal para control manual con automatización parcial.

npm install --save-dev standard-version
npx standard-version

semantic-release

Automatiza TODO: changelog, versionado, publicación en npm o GitHub.
Requiere entorno CI/CD (ej: GitHub Actions).

npm install --save-dev semantic-release

release-it

Personalizable, ideal para flujos mixtos.

npm install --save-dev release-it
npx release-it

6. Convenciones de Commit (Conventional Commits)

Estas convenciones estructuran los mensajes de commit para que puedan ser procesados automáticamente:

<tipo>(opcional: alcance): descripción

[opcional] cuerpo del mensaje
[opcional] notas de ruptura (BREAKING CHANGE)

Ejemplos:

feat(auth): agregar login con Google
fix(api): corregir error de serialización
docs(readme): actualizar instrucciones de uso
BREAKING CHANGE: se eliminó el endpoint /v1/user

Tipos más comunes:

Tipo	Uso
`feat`	Nueva funcionalidad
`fix`	Corrección de errores
`docs`	Cambios en la documentación
`style`	Cambios de formato (espacios, comas, etc.)
`refactor`	Refactorización del código sin cambios de funcionalidad
`test`	Cambios relacionados a pruebas
`chore`	Tareas menores de mantenimiento

7. Gestión de Dependencias

El versionado semántico también afecta cómo se definen y gestionan las dependencias en los proyectos:

Caret ( ^ ):
Permite actualizaciones de versiones MINOR y PATCH. Por ejemplo, ^1.2.3 abarca versiones de la serie 1.x.x.
Tilde ( ~ ):
Restringe las actualizaciones a parches solamente. Por ejemplo, ~1.2.3 asegura que se mantenga la versión 1.2.x.

8. Herramientas Recomendadas

semver: Librería para comparar y validar versiones.
Conventional Commits: Estándar de mensajes para facilitar changelogs automáticos.
GitHub Actions/GitLab CI: Automatiza versiones y publicaciones.
semantic-release / standard-version / release-it: Para generar changelogs y manejar versiones automáticamente.

Tabla Resumen

Aspecto	Descripción	Ejemplo
Formato Básico de SemVer	MAJOR.MINOR.PATCH	2.4.1
Versión MAJOR	Cambios incompatibles que rompen versiones anteriores	1.1.1 → 2.0.0
Versión MINOR	Nuevas funcionalidades sin romper compatibilidad	1.0.0 → 1.1.0
Versión PATCH	Correcciones de errores sin afectar la funcionalidad	1.1.0 → 1.1.1
Pre-release	Versión inestable para pruebas	1.0.0-beta.1
Build Metadata	Información adicional de compilación	1.0.0+20230901
Gestión de Dependencias	Uso de caret (^) para permitir MINOR y PATCH; tilde (~) para solo PATCH	^1.2.3 y ~1.2.3
CHANGELOG	Registro detallado de cambios, organizado por versiones y secciones claras	Ver ejemplo en el artículo
Convenciones de Commit	Estilo estructurado que facilita la generación automática de changelog	feat, fix, chore, etc.
Herramientas de Automatización	Facilitan la gestión de versiones y changelog	semantic-release, standard-version, release-it

Conclusión

Integrar el Versionado Semántico con un CHANGELOG completo y bien documentado garantiza un proceso de actualización y mantenimiento de software más transparente y predecible. Adoptar ambas prácticas no solo mejora la organización interna y el flujo de trabajo, sino que también fortalece la comunicación con los usuarios al explicar de forma detallada cada cambio realizado. Utiliza esta guía para transformar tu estrategia de versionado y construir una base sólida para el crecimiento y la evolución de tu proyecto de software.

Ver página completa →

Explorando las Topologías de Infraestructura en la Nube: Desde el Monolito hasta la Inteligencia Artificial Distribuida

Mauricio ECR
DevOps
05 Apr, 2025

Introducción El crecimiento exponencial de las soluciones en la nube ha transformado la manera en que diseñamos, desplegamos y mantenemos nuestras aplicaciones. Ya no hablamos solo de servidores y

Ver página completa

Explorando las Topologías de Infraestructura en la Nube: Desde el Monolito hasta la Inteligencia Artificial Distribuida

Mauricio ECR
DevOps
05 Apr, 2025

Introducción

El crecimiento exponencial de las soluciones en la nube ha transformado la manera en que diseñamos, desplegamos y mantenemos nuestras aplicaciones. Ya no hablamos solo de servidores y bases de datos, sino de arquitecturas complejas y adaptativas que responden a necesidades específicas de negocio, escalabilidad y resiliencia. En este artículo, exploramos las principales topologías de infraestructura en la nube, categorizadas según su propósito principal. Para cada subcategoría se describe de manera fluida sus componentes clave, casos de uso comunes y ejemplos concretos. Finalizamos con un cuadro resumen que compara escalabilidad, resiliencia y elasticidad entre ellas.

Categoría 1: Aplicaciones Web y Backend

• Monolito en una sola instancia

Una única unidad que contiene toda la lógica de negocio y presentación. Suele usarse cuando se prioriza velocidad de desarrollo y simplicidad.

Componentes: Servidor de aplicaciones, base de datos, DNS, logs.
Caso de uso: Ideal para MVPs o aplicaciones internas simples donde se necesita rapidez de desarrollo.
Ejemplo: App de reservas de un coworking local sin alta demanda.

• Arquitectura 2-tier

Separación básica entre presentación y lógica/datos. Aumenta ligeramente la modularidad y seguridad.

Componentes: Frontend, backend, base de datos, red privada (VPC).
Caso de uso: Aplicaciones CRUD sin requerimientos complejos.
Ejemplo: Sistema de inventario de una tienda de barrio.

• Arquitectura 3-tier

División clara entre presentación, lógica de negocio y almacenamiento. Facilita escalabilidad y mantenimiento.

Componentes: Web UI, capa de negocio/API, base de datos, cache, WAF, balanceador de carga.
Caso de uso: Aplicaciones con múltiples usuarios y procesos críticos.
Ejemplo: Portal de empleados de una empresa con 500+ usuarios.

• Microservicios

División modular del sistema en servicios independientes. Facilita despliegue continuo y escalado específico.

Componentes: API Gateway, servicios desacoplados, base de datos por servicio, orquestador, service mesh.
Caso de uso: Aplicaciones con alta demanda de escalabilidad y despliegue continuo.
Ejemplo: Plataforma de e-commerce como Amazon.

• Serverless (FaaS)

Funcionalidad sin gestión directa de servidores. Excelente para eventos aislados y costos por uso.

Componentes: Funciones (Lambda), API Gateway, triggers, S3/DynamoDB.
Caso de uso: Ejecuciones bajo demanda o respuestas rápidas sin infraestructura constante.
Ejemplo: Formulario web con almacenamiento directo en DynamoDB.

• Contenerizada

Uso de contenedores para portabilidad y consistencia. Ideal para equipos DevOps maduros.

Componentes: Contenedores, orquestador (Kubernetes/ECS), ingress, config maps, monitoreo.
Caso de uso: Apps modernas con despliegues ágiles.
Ejemplo: Backend de servicios para una fintech.

• Edge / CDN-based

Distribución de contenido y funciones lo más cerca posible del usuario. Reduce latencia significativamente.

Componentes: CDN, funciones en el edge, almacenamiento estático, DNS.
Caso de uso: Sitios globales, rápidos y ligeros.
Ejemplo: Página de campaña para Spotify con alto tráfico mundial.

Categoría 2: Procesamiento de Datos

• Batch Processing

Ejecución por lotes en horarios programados. Óptimo para procesos no críticos en tiempo real.

Componentes: Orquestador, Spark/Glue, almacenamiento, data warehouse.
Caso de uso: Procesos intensivos pero no urgentes.
Ejemplo: Generación de reportes contables semanales.

• Streaming Processing

Procesamiento en tiempo real de eventos. Permite reacciones inmediatas.

Componentes: Kafka, Flink, almacenamiento rápido, alertas.
Caso de uso: Monitoreo o reacción instantánea.
Ejemplo: Sistema de detección de fraudes financieros.

• ETL / ELT

Extracción, transformación y carga de datos. Clave para flujos de datos confiables.

Componentes: Extractores, transformadores (dbt), destino (DW), scheduler.
Caso de uso: Consolidación de fuentes de datos.
Ejemplo: Integración entre sistema de ventas y CRM.

• Data Warehouse

Sistema analítico estructurado. Usado para análisis de negocio y reporting.

Componentes: Redshift, Snowflake, BigQuery, herramientas BI.
Caso de uso: Análisis de KPIs, dashboards.
Ejemplo: Reportes de ventas mensuales para dirección comercial.

• Data Lake / Lakehouse

Almacenamiento de grandes volúmenes en múltiples formatos. Flexible y económico.

Componentes: S3, Glue/Athena, catálogos de datos, seguridad.
Caso de uso: Escenarios con datos semi/no estructurados.
Ejemplo: Logs masivos de navegación en web.

• Data Mesh

Modelo distribuido y federado de datos. Favorece la autonomía por dominio.

Componentes: Dominios de datos, APIs, gobernanza, interoperabilidad.
Caso de uso: Independencia de equipos para publicar/consumir datos.
Ejemplo: Multinacional con unidades de negocio autónomas.

Categoría 3: Machine Learning / Inteligencia Artificial

• Entrenamiento simple/local

Ejecutado en entornos personales o educativos. Bajo costo y accesibilidad.

Componentes: Notebooks (Colab, Jupyter), datasets, librerías ML.
Caso de uso: Prototipos y aprendizaje.
Ejemplo: Clasificador de sentimientos en Google Colab.

• Entrenamiento distribuido

Requiere potencia de cómputo alto y paralelización. Usado en proyectos avanzados.

Componentes: Clúster de GPUs, datasets, framework (TensorFlow/PyTorch).
Caso de uso: Modelos de lenguaje o visión a gran escala.
Ejemplo: Modelo LLM para sector salud.

• Inferencia batch

Aplicación del modelo a conjuntos de datos no urgentes. Utilizado en análisis periódicos.

Componentes: Modelo, job programado, input/output, auditoría.
Caso de uso: Predicciones acumuladas.
Ejemplo: Scoring de riesgo semanal para cartera de clientes.

• Inferencia en tiempo real

Predicciones inmediatas vía API. Fundamental para experiencias personalizadas.

Componentes: API, modelo cargado en memoria, balanceador.
Caso de uso: Recomendaciones o respuestas interactivas.
Ejemplo: Recomendador de productos online.

• MLOps Pipelines

Automatización del ciclo de vida ML. Mejora confiabilidad y trazabilidad.

Componentes: CI/CD, versionado de datos/modelos, feature store.
Caso de uso: Iteración y despliegue continuo de modelos.
Ejemplo: Monitoreo y redeploy de modelo de anomalías.

• AutoML

Modelado automatizado con herramientas visuales. Democratiza el uso del ML.

Componentes: Plataforma visual, datasets, API.
Caso de uso: Democratización del ML.
Ejemplo: Clasificador usando Google Vertex AI.

Categoría 4: DevOps y Entornos de Desarrollo

• CI/CD básico

Automatización del flujo de despliegue. Mejora velocidad y calidad.

Componentes: Repositorio, pipelines, build/test/deploy.
Caso de uso: Flujos simples de desarrollo continuo.
Ejemplo: GitHub Actions para app Node.js.

• Entornos efímeros

Instancias temporales por cambios en código. Perfecto para validación rápida.

Componentes: IaC, previsualizaciones por rama o PR.
Caso de uso: Validación visual antes de merge.
Ejemplo: Landing page preview con Vercel.

• Entornos dedicados

Separación de ambientes según etapa de desarrollo. Facilita pruebas seguras.

Componentes: Dev, QA, Staging, Prod, variables.
Caso de uso: Flujo robusto de pruebas.
Ejemplo: Pipeline de pagos con pruebas por entorno.

• Infraestructura como Código (IaC)

Infra reproducible y versionada. Ideal para automatización multicloud.

Componentes: Terraform/Pulumi, módulos, backends de estado.
Caso de uso: Gestión multicloud declarativa.
Ejemplo: Infraestructura de microservicios con Terraform.

• DevSecOps

Seguridad integrada al ciclo de desarrollo. Reduce riesgos desde el origen.

Componentes: SAST, control de secretos, validación de seguridad.
Caso de uso: Garantizar seguridad desde el código.
Ejemplo: Validación de secretos y código con Vault y SonarQube.

Resumen General

A continuación, un resumen de las topologías abordadas, con sus propiedades clave:

Grupo	Subcategoría	Escalabilidad	Resiliencia	Elasticidad	Componentes Principales	Caso de Uso / Ejemplo
Web/Backend	Monolito	Baja	Baja	Nula	Servidor, BD, DNS, logs	App reservas coworking
Web/Backend	2-tier	Media	Media	Baja	Frontend, backend, BD	Inventario de tienda
Web/Backend	3-tier	Alta	Alta	Media	UI, API, BD, cache, WAF	Portal empleados
Web/Backend	Microservicios	Muy Alta	Muy Alta	Alta	API GW, servicios, BD, mesh	E-commerce estilo Amazon
Web/Backend	Serverless	Muy Alta	Alta	Muy Alta	Lambda, S3, triggers	Formulario Lambda
Web/Backend	Contenerizada	Alta	Alta	Alta	K8s/ECS, contenedores	Backend fintech
Web/Backend	Edge/CDN	Alta	Alta	Alta	CDN, edge functions	Landing global Spotify
Datos	Batch	Media	Alta	Baja	Orquestador, Glue, DW	Reportes contables
Datos	Streaming	Alta	Alta	Alta	Kafka, Flink, alertas	Fraudes bancarios
Datos	ETL/ELT	Alta	Media	Media	Extractores, DBT, DW	Datos ventas y CRM
Datos	DW	Alta	Alta	Media	Redshift, BI	KPI dirección comercial
Datos	Lakehouse	Muy Alta	Alta	Alta	S3, Athena, catálogo	Logs web
Datos	Data Mesh	Alta	Alta	Media	APIs, dominios, gov	Datos en multinacional
IA/ML	Entrenamiento local	Baja	Baja	Nula	Notebooks, datasets	Clasificador Colab
IA/ML	Entrenamiento distribuido	Alta	Alta	Media	GPUs, TF/PT, dataset	LLM salud
IA/ML	Inferencia batch	Media	Alta	Baja	Job, modelo, IO	Scoring clientes
IA/ML	Inferencia tiempo real	Alta	Alta	Alta	API, modelo, load balancer	Recomendador productos
IA/ML	MLOps	Alta	Alta	Alta	CI/CD, feature store	Modelo de anomalías
IA/ML	AutoML	Media	Alta	Alta	Vertex AI, API	Vertex AI
DevOps	CI/CD	Media	Media	Media	GitHub, pipelines	GitHub Actions
DevOps	Entornos efímeros	Alta	Media	Alta	IaC, previews	Preview en Vercel
DevOps	Entornos dedicados	Media	Alta	Baja	QA, Staging, Prod	Validación por ambiente
DevOps	IaC	Alta	Alta	Alta	Terraform, módulos	Terraform multicloud
DevOps	DevSecOps	Alta	Alta	Alta	SAST, secretos, Vault	Pipeline seguro + Vault

Este análisis puede servirte como hoja de ruta para diseñar arquitecturas eficientes, seguras y adaptadas al crecimiento de tu organización. Cada topología tiene su momento ideal de uso, y comprenderlas te permite tomar decisiones informadas en tu estrategia de nube.

Conclusión: Hacia una Elección Informada

Elegir la topología de infraestructura adecuada en la nube no es solo una cuestión técnica, sino una decisión estratégica que impacta directamente en la eficiencia, escalabilidad y competitividad de una organización. Como hemos visto, cada enfoque —desde un monolito sencillo hasta una arquitectura de MLOps distribuida— tiene fortalezas y compromisos que deben alinearse con el contexto del negocio, la madurez tecnológica del equipo y los objetivos a corto y largo plazo.

Al evaluar cuál topología adoptar, considera las siguientes preguntas clave:

¿Cuál es la etapa de madurez de tu producto o servicio?
¿Qué tan crítico es el tiempo de respuesta o la resiliencia para tu operación?
¿Tu equipo está preparado para gestionar la complejidad que implica escalar?
¿Qué tanto valor aportaría la automatización y observabilidad en tu flujo de trabajo?

Comenzar con una solución simple y evolucionar progresivamente hacia arquitecturas más sofisticadas es una estrategia válida y, en muchos casos, recomendable. Lo esencial es tener claridad en el propósito y una visión arquitectónica que te permita crecer sin reescribir desde cero cada vez que el negocio escale.

En definitiva, la nube no es solo infraestructura: es una plataforma para innovar con agilidad. Entender sus topologías es el primer paso para diseñar soluciones más robustas, eficientes y orientadas al futuro.

Ver página completa →

Gitea: Cómo Montar tu Propio Servidor Git en Minutos

Mauricio ECR
DevOps
04 Apr, 2025

A medida que los proyectos crecen y se diversifican, muchos desarrolladores empiezan a preguntarse si realmente necesitan depender de plataformas como GitHub o GitLab para gestionar su código. No es q

Ver página completa

Gitea: Cómo Montar tu Propio Servidor Git en Minutos

Mauricio ECR
DevOps
04 Apr, 2025

A medida que los proyectos crecen y se diversifican, muchos desarrolladores empiezan a preguntarse si realmente necesitan depender de plataformas como GitHub o GitLab para gestionar su código. No es que esas herramientas estén mal, pero hay escenarios donde una alternativa más simple y autoalojada tiene mucho sentido.

Este artículo no es para convencerte de abandonar nada, sino para mostrarte una opción: Gitea, una plataforma ligera y fácil de montar para tener tu propio servidor Git.

¿Por Qué Considerar Gitea?

Si trabajas en proyectos personales, con un equipo pequeño, o simplemente te interesa aprender a montar tu propia infraestructura, hay algunas razones por las que podrías querer probar Gitea:

Autonomía: No dependes de servidores externos.
Simplicidad: La instalación es directa, sin configuraciones complejas.
Control: Tú decides cómo se almacenan y gestionan los datos.

No es una solución perfecta para todos los casos, pero vale la pena conocerla. A veces lo que uno necesita es justamente eso: algo sencillo que funcione.

Cómo Instalar Gitea con Docker

Una de las formas más rápidas de poner Gitea en marcha es con Docker. Aquí va una guía paso a paso, sin adornos.

1. Crea un directorio para el proyecto

mkdir gitea && cd gitea

2. Crea un archivo `docker-compose.yml`

version: "3"

services:
  server:
    image: gitea/gitea:latest
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: unless-stopped
    volumes:
      - ./data:/data
    ports:
      - "3000:3000"   # Web
      - "2222:22"     # SSH

3. Levanta el contenedor

docker-compose up -d

4. Abre el navegador

Accede a http://localhost:3000 y completa la configuración inicial. No toma más de un par de minutos.

Subir un Repositorio a Gitea

Una vez que el servidor está funcionando, puedes empezar a usarlo como cualquier otro servicio Git.

Crea un nuevo repositorio desde la interfaz web de Gitea.
En tu máquina local, añade ese repositorio como remoto:

git remote add gitea http://localhost:3000/usuario/repositorio.git
git push -u gitea main

Y eso es todo. Estás trabajando con Git como siempre, pero ahora en tu propio servidor.

🔐 Autenticación por SSH

Subir y clonar repositorios por HTTP está bien para empezar, pero si planeas trabajar frecuentemente con tu servidor Gitea, usar SSH es mucho más seguro y cómodo.

1. Genera tu clave SSH (si no tienes una)

ssh-keygen -t ed25519 -C "[email protected]"

Esto creará dos archivos en ~/.ssh: una clave privada (id_ed25519) y una pública (id_ed25519.pub).

2. Agrega tu clave pública a Gitea

En la interfaz web de Gitea, ve a "Tu Perfil" > "SSH Keys"
Pega el contenido de ~/.ssh/id_ed25519.pub

3. Usa el remoto por SSH

Ahora puedes clonar así:

git clone ssh://git@localhost:2222/usuario/repositorio.git

Y también hacer push/pull sin tener que escribir tu contraseña.

⚙️ Integración de CI/CD con Drone

Aunque Gitea no incluye un sistema de CI/CD por defecto, es compatible con herramientas externas como Drone CI. Vamos a ver cómo integrarlo.

Docker Compose con Gitea + Drone

version: '3'

services:
  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000
    volumes:
      - ./gitea:/data
    ports:
      - "3000:3000"
      - "2222:22"
    networks:
      - cicd-net

  drone:
    image: drone/drone:latest
    container_name: drone
    restart: always
    ports:
      - "8080:80"
    volumes:
      - ./drone:/data
    environment:
      - DRONE_GITEA_SERVER=http://gitea:3000
      - DRONE_GITEA_CLIENT_ID=tu-client-id
      - DRONE_GITEA_CLIENT_SECRET=tu-client-secret
      - DRONE_RPC_SECRET=una-clave-secreta
      - DRONE_SERVER_HOST=localhost:8080
      - DRONE_SERVER_PROTO=http
      - DRONE_USER_CREATE=username:tu-usuario,admin:true
    networks:
      - cicd-net

networks:
  cicd-net:
    driver: bridge

Pasos Adicionales

Registra una aplicación OAuth en Gitea desde
http://localhost:3000/user/settings/applications.

Usa http://localhost:8080/login como Redirect URI.
Copia el Client ID y Client Secret en el docker-compose.yml.
Levanta los servicios:

docker-compose up -d

Accede a Drone en http://localhost:8080 y conecta tu cuenta de Gitea.
Agrega un archivo .drone.yml en tu repositorio:

kind: pipeline
type: docker
name: default

steps:
  - name: test
    image: node:18
    commands:
      - npm install
      - npm test

Activa el repositorio desde la interfaz de Drone.

🧭 Reflexión Final

Gitea es más que una curiosidad para quienes prefieren el control. Es una herramienta real, funcional y mantenida activamente. No está diseñada para reemplazar gigantes, pero sí para darte una alternativa cuando quieres aprender, experimentar o simplemente no depender de nadie más.

Con unos pocos comandos puedes levantar tu propio servidor Git, usar autenticación SSH, y hasta conectar una pipeline de CI/CD.

Y eso, en ciertos contextos, es todo lo que necesitas.

Ver página completa →

WebSockets Seguros en Spring Boot: Protege tus Conexionesen Tiempo Real

Mauricio ECR
Seguridad
04 Apr, 2025

Introducción En la era de las aplicaciones en tiempo real, los WebSockets se han convertido en una tecnología fundamental para crear experiencias interactivas. Sin embargo, su naturaleza persisten

Ver página completa

WebSockets Seguros en Spring Boot: Protege tus Conexionesen Tiempo Real

Mauricio ECR
Seguridad
04 Apr, 2025

Introducción

En la era de las aplicaciones en tiempo real, los WebSockets se han convertido en una tecnología fundamental para crear experiencias interactivas. Sin embargo, su naturaleza persistente y bidireccional presenta desafíos únicos de seguridad.
¿Cómo garantizar que solo usuarios autenticados puedan establecer conexiones WebSocket?
¿Cómo proteger los mensajes intercambiados?

Este artículo presenta una implementación completa de WebSockets seguros en Spring Boot, con explicaciones detalladas de cada componente y su función en el sistema de seguridad.

🛠️ Implementación del Backend

1. Clase Principal de la Aplicación

Esta es la clase de entrada estándar para una aplicación Spring Boot, que inicia el contexto de la aplicación.

package com.mecr.sample.webSocketsSecurity;

@SpringBootApplication
public class WebSocketsSecurityApplication {

    public static void main(String[] args) {
        SpringApplication.run(WebSocketsSecurityApplication.class, args);
    }
}

2. Configuración de Seguridad

La clase SecurityConfig define las reglas de seguridad para la aplicación, incluyendo la protección de endpoints WebSocket, configuración CORS y autenticación básica.

package com.mecr.sample.webSocketsSecurity.security.config;

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
                .cors(cors -> cors.configurationSource(corsConfigurationSource()))
                .csrf(AbstractHttpConfigurer::disable)
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/ws/**").authenticated()
                        .anyRequest().permitAll()
                )
                .formLogin(withDefaults())
                .logout(withDefaults());

        return http.build();
    }

    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration config = new CorsConfiguration();
        config.setAllowedOrigins(List.of("http://127.0.0.1:5500", "http://localhost:5500"));
        config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
        config.setAllowCredentials(true);
        config.setAllowedHeaders(List.of("Authorization", "Content-Type", "X-Requested-With"));

        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", config);
        return source;
    }

    @Bean
    public UserDetailsService userDetailsService() {
        UserDetails user = User.withDefaultPasswordEncoder()
                .username("admin")
                .password("admin")
                .roles("USER")
                .build();

        return new InMemoryUserDetailsManager(user);
    }
}

3. Interceptor de Autenticación para WebSockets

El AuthHandshakeInterceptor verifica la autenticación del usuario antes de permitir el establecimiento de la conexión WebSocket.

package com.mecr.sample.webSocketsSecurity.webSocket.security;

public class AuthHandshakeInterceptor implements HandshakeInterceptor {

    @Override
    public boolean beforeHandshake(ServerHttpRequest request, ServerHttpResponse response,
                                   WebSocketHandler wsHandler, Map<String, Object> attributes) {
        if (request instanceof ServletServerHttpRequest servletRequest) {
            HttpSession session = servletRequest.getServletRequest().getSession(false);
            if (session != null) {
                SecurityContext context = (SecurityContext) session.getAttribute("SPRING_SECURITY_CONTEXT");
                if (context != null && context.getAuthentication() != null && context.getAuthentication().isAuthenticated()) {
                    attributes.put("AUTH", context.getAuthentication());
                    System.out.println("🔐 Usuario autenticado en interceptor: " + context.getAuthentication().getName());
                    return true;
                }
            }
        }
        System.out.println("❌ WebSocket rechazado en interceptor (no autenticado)");
        return false;
    }

    @Override
    public void afterHandshake(ServerHttpRequest request, ServerHttpResponse response,
                               WebSocketHandler wsHandler, Exception exception) {
    }
}

4. Manejador de WebSockets

MyWebSocketHandler gestiona los eventos del ciclo de vida de la conexión WebSocket y el procesamiento de mensajes.

package com.mecr.sample.webSocketsSecurity.webSocket.handler;

@Component
public class MyWebSocketHandler extends TextWebSocketHandler {

    @Override
    public void afterConnectionEstablished(WebSocketSession session) throws Exception {
        Authentication authentication = (Authentication) session.getAttributes().get("AUTH");

        if (authentication == null || !authentication.isAuthenticated()) {
            System.out.println("❌ WebSocket rechazado: Usuario no autenticado");
            session.close(CloseStatus.NOT_ACCEPTABLE);
            return;
        }

        System.out.println("✅ WebSocket conectado: " + authentication.getName());
        session.sendMessage(new TextMessage("Conexión exitosa! Bienvenido " + authentication.getName()));
    }

    @Override
    protected void handleTextMessage(WebSocketSession session, TextMessage message) throws Exception {
        Authentication authentication = (Authentication) session.getAttributes().get("AUTH");
        if (authentication == null || !authentication.isAuthenticated()) {
            session.close(CloseStatus.NOT_ACCEPTABLE);
            return;
        }

        System.out.println("📩 Mensaje recibido de " + authentication.getName() + ": " + message.getPayload());
        session.sendMessage(new TextMessage("Echo: " + message.getPayload()));
    }

    @Override
    public void handleTransportError(WebSocketSession session, Throwable exception) throws Exception {
        System.err.println("❌ Error en WebSocket: " + exception.getMessage());
    }

    @Override
    public void afterConnectionClosed(WebSocketSession session, CloseStatus status) throws Exception {
        System.out.println("🚪 WebSocket cerrado");
    }
}

5. Configuración de WebSockets

WebSocketConfig registra el manejador WebSocket y configura los interceptores necesarios.

package com.mecr.sample.webSocketsSecurity.webSocket.config;

@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {

    private final MyWebSocketHandler myWebSocketHandler;

    public WebSocketConfig(MyWebSocketHandler myWebSocketHandler) {
        this.myWebSocketHandler = myWebSocketHandler;
    }

    @Override
    public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
        registry.addHandler(myWebSocketHandler, "/ws")
                .setAllowedOrigins("http://localhost:5500","http://127.0.0.1:5500")
                .addInterceptors(new HttpSessionHandshakeInterceptor(), new AuthHandshakeInterceptor());
    }
}

💻 Implementación del Frontend

Esta página HTML demuestra cómo interactuar con el backend seguro desde el navegador.

<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <title>WebSocket con Seguridad</title>
</head>
<body>
    <h2>WebSocket Seguro</h2>
    <button onclick="login()">Iniciar Sesión</button>
    <button onclick="connectWebSocket()">Conectar WebSocket</button>
    <button onclick="sendMessage()">Enviar Mensaje</button>
    <p id="output"></p>

    <script>
        var socket;

        function login() {
            fetch("http://127.0.0.1:8080/login", {
                method: "POST",
                headers: {
                    "Content-Type": "application/x-www-form-urlencoded"
                },
                body: "username=admin&password=admin",
                credentials: "include"
            }).then(response => {
                if (response.ok) {
                    alert("Autenticado correctamente");
                } else {
                    alert("Error de autenticación");
                }
            }).catch(error => console.error("Error:", error));
        }

        function connectWebSocket() {
            socket = new WebSocket("ws://127.0.0.1:8080/ws");

            socket.onopen = function() {
                console.log("✅ WebSocket conectado!");
                socket.send("Hola servidor!");
            };

            socket.onmessage = function(event) {
                document.getElementById("output").innerText = "Respuesta del servidor: " + event.data;
            };

            socket.onerror = function(error) {
                console.error("❌ Error en WebSocket:", error);
            };

            socket.onclose = function() {
                console.log("🚪 WebSocket desconectado");
            };
        }

        function sendMessage() {
            if (socket) {
                socket.send("Hola desde cliente!");
            } else {
                alert("Conéctate primero!");
            }
        }
    </script>
</body>
</html>

✅ Conclusión

Esta implementación proporciona una base sólida para aplicaciones que requieren WebSockets seguros en Spring Boot. La combinación de Spring Security con interceptores personalizados garantiza que solo usuarios autenticados puedan establecer conexiones WebSocket, mientras que la configuración de CORS protege contra solicitudes no autorizadas desde otros dominios.

Los componentes clave trabajan juntos para ofrecer:

Autenticación previa al handshake WebSocket
Mantenimiento del contexto de seguridad durante la sesión
Protección contra CSRF (aunque desactivada para WebSockets)
Configuración CORS segura
Manejo adecuado de errores y cierre de conexiones

Ver página completa →

Explorando las Bases de Datos NoSQL: Introducción a MongoDB

Mauricio ECR
Persistencia
30 Mar, 2025

📚 Introducción En un mundo donde el volumen y la variedad de los datos crecen exponencialmente, las bases de datos NoSQL se han convertido en una alternativa esencial frente a las tradicionales

Ver página completa

Explorando las Bases de Datos NoSQL: Introducción a MongoDB

Mauricio ECR
Persistencia
30 Mar, 2025

📚 Introducción

En un mundo donde el volumen y la variedad de los datos crecen exponencialmente, las bases de datos NoSQL se han convertido en una alternativa esencial frente a las tradicionales bases de datos relacionales. Desde aplicaciones web modernas hasta análisis masivos de datos, las soluciones NoSQL ofrecen flexibilidad, escalabilidad y eficiencia en el manejo de datos estructurados y no estructurados.

En este documento, nos centraremos en las bases de datos documentales, específicamente en MongoDB. Exploraremos sus características principales, el modelo de almacenamiento basado en documentos y las operaciones básicas de manejo de datos (CRUD). Además, hablaremos brevemente sobre conceptos como el escalamiento horizontal y vertical. ¡Acompáñanos a descubrir cómo MongoDB facilita la gestión de datos en el mundo digital!.

TipoDB

Las bases de datos NoSQL se clasifican según su modelo de datos. Las principales categorías son:

1. Base de Datos Documentales

Almacenan datos en formato de documentos (generalmente JSON o BSON). Son flexibles y escalables.

MongoDB

Características:
- Orientada a documentos.
- Alta disponibilidad mediante réplicas.
- Escalabilidad horizontal con sharding.
Uso común: Aplicaciones web modernas, análisis de datos.

Cloud Firestore

Características:
- Propiedad de Google Cloud.
- Basada en documentos jerárquicos.
- Integración nativa con Firebase.
Uso común: Desarrollo móvil y web en tiempo real.

2. Grafos

Almacenan datos en nodos y relaciones entre ellos. Son ideales para consultas complejas y redes.

Neo4j

Características:
- Modelo basado en grafos.
- Consultas eficientes con Cypher Query Language.
- Ideal para redes sociales, recomendaciones y fraudes.
Uso común: Análisis de redes, sistemas de recomendación.

3. Clave-Valor

Almacenan datos como pares clave-valor. Son simples y extremadamente rápidas.

Redis

Características:
- Almacenamiento en memoria (in-memory).
- Soporta estructuras de datos como listas, conjuntos y hashes.
- Persistencia opcional.
Uso común: Caching, colas de mensajes, sesiones de usuario.

4. Columnas

Almacenan datos en columnas en lugar de filas. Son eficientes para grandes volúmenes de datos.

Cassandra

Características:
- Sin punto único de fallo.
- Escalabilidad horizontal.
- Modelo de consistencia ajustable.
Uso común: IoT, análisis de datos masivos.

HBase

Características:
- Construida sobre Hadoop.
- Alta disponibilidad y tolerancia a fallos.
- Ideal para big data.
Uso común: Procesamiento de grandes volúmenes de datos.

Escalamiento

Vertical

Descripción: Aumentar la capacidad de un solo servidor (CPU, RAM, almacenamiento).
Ventajas: Fácil de implementar.
Desventajas: Limitado por el hardware disponible.

Horizontal

Descripción: Agregar más servidores para distribuir la carga.
Ventajas: Altamente escalable.
Desventajas: Mayor complejidad en la gestión.

Base de Datos Documentales

Estructura

Base de datos: Contenedor principal de datos.
Colecciones: Grupos de documentos relacionados.
Documentos: Unidades individuales de datos (JSON/BSON).

Implementación

On-premises: Instalación local.
Mongo Compass: Interfaz gráfica para MongoDB.
Cluster: Conjunto de servidores MongoDB trabajando juntos.

Tipos de Datos

JSON: Formato ligero para intercambio de datos.
BSON: Extensión binaria de JSON usada internamente por MongoDB.

CRUD (Create, Read, Update, Delete)

Operación	Descripción	Ejemplo
`insertOne`	Inserta un solo documento.	`db.collection.insertOne({ name: "Alice" })`
`insertMany`	Inserta múltiples documentos.	`db.collection.insertMany([{ name: "Bob" }, { name: "Charlie" }])`
`updateOne`	Actualiza un solo documento.	`db.collection.updateOne({ name: "Alice" }, { $set: { age: 25 } })`
`updateMany`	Actualiza múltiples documentos.	`db.collection.updateMany({}, { $inc: { age: 1 } })`
`deleteOne`	Elimina un solo documento.	`db.collection.deleteOne({ name: "Alice" })`
`deleteMany`	Elimina múltiples documentos.	`db.collection.deleteMany({ age: { $gt: 30 } })`
`drop`	Elimina una colección completa.	`db.collection.drop()`
`find`	Busca documentos que coincidan con un filtro.	`db.collection.find({ age: { $gt: 20 } })`
`aggregate`	Realiza operaciones avanzadas como agrupaciones.	`db.collection.aggregate([{ $group: { _id: "$age", count: { $sum: 1 } } }])`
`sort`, `limit`, `skip`	Ordena, limita y omite documentos en una consulta.	`db.collection.find().sort({ age: 1 }).limit(10).skip(5)`

Operadores

Operador	Descripción	Ejemplo
`$set`	Establece el valor de un campo.	`db.collection.updateOne({ name: "Alice" }, { $set: { age: 25 } })`
`$inc`	Incrementa el valor de un campo numérico.	`db.collection.updateOne({ name: "Alice" }, { $inc: { age: 1 } })`
`$rename`	Cambia el nombre de un campo.	`db.collection.updateOne({}, { $rename: { oldField: "newField" } })`
`$unset`	Elimina un campo.	`db.collection.updateOne({}, { $unset: { age: "" } })`
`$push`	Agrega un elemento a un array.	`db.collection.updateOne({}, { $push: { hobbies: "reading" } })`
`$pull`	Elimina un elemento de un array.	`db.collection.updateOne({}, { $pull: { hobbies: "reading" } })`
`$in`	Coincide si el campo tiene uno de los valores especificados.	`db.collection.find({ age: { $in: [20, 25, 30] } })`
`$nin`	Coincide si el campo no tiene ninguno de los valores especificados.	`db.collection.find({ age: { $nin: [20, 25, 30] } })`
`$all`	Coincide si el array contiene todos los valores especificados.	`db.collection.find({ hobbies: { $all: ["reading", "writing"] } })`
`$size`	Coincide si el array tiene un tamaño específico.	`db.collection.find({ hobbies: { $size: 3 } })`
`$elemMatch`	Coincide si al menos un elemento del array cumple todas las condiciones.	`db.collection.find({ scores: { $elemMatch: { $gt: 80, $lt: 90 } } })`
`$regex`	Coincide con patrones de texto.	`db.collection.find({ name: { $regex: "^A" } })`
`$eq` y `$ne`	Igualdad y desigualdad.	`db.collection.find({ age: { $eq: 25 } })`
`$gt`, `$gte`	Mayor que y mayor o igual que.	`db.collection.find({ age: { $gt: 20 } })`

Operadores Lógicos

Operador	Descripción	Ejemplo
`$and`	Coincide si todas las condiciones son verdaderas.	`db.collection.find({ $and: [{ age: { $gt: 20 } }, { age: { $lt: 30 } }] })`
`$or`	Coincide si al menos una condición es verdadera.	`db.collection.find({ $or: [{ age: { $gt: 20 } }, { name: "Alice" }] })`
`$not`	Niega una expresión.	`db.collection.find({ age: { $not: { $gt: 20 } } })`
`$nor`	Coincide si ninguna de las condiciones es verdadera.	`db.collection.find({ $nor: [{ age: { $gt: 20 } }, { name: "Alice" }] })`

Aggregation Framework

Permite realizar transformaciones y análisis complejos en los datos.

Ejemplo de Pipeline

db.collection.aggregate([
  { $match: { age: { $gt: 20 } } }, // Filtra documentos
  { $group: { _id: "$city", total: { $sum: 1 } } }, // Agrupa por ciudad
  { $sort: { total: -1 } } // Ordena por total descendente
]);

📝 Conclusión

Las bases de datos NoSQL representan una evolución en la gestión de datos que responde a las necesidades actuales de escalabilidad y flexibilidad. Comprender su arquitectura, funcionamiento y aplicaciones prácticas es fundamental para cualquier profesional del ámbito tecnológico.

Si deseas profundizar aún más, explora casos de uso específicos y realiza experimentos prácticos con plataformas como MongoDB, Redis o Neo4j. La adopción y el dominio de estas tecnologías pueden marcar la diferencia en proyectos que manejan grandes volúmenes de datos o requieren consultas complejas en tiempo real. ¡Atrévete a sumergirte en el fascinante mundo NoSQL y lleva tus habilidades de manejo de datos al siguiente nivel!

Ver página completa →

Transformando Colecciones con Java Streams: 15 Métodos Esenciales

Mauricio ECR
Arquitectura
29 Mar, 2025

Introducción En el mundo de Java, trabajar con colecciones de datos solía ser sinónimo de bucles interminables, condicionales anidados y código repetitivo. Pero con la llegada de Java Streams

Ver página completa

Transformando Colecciones con Java Streams: 15 Métodos Esenciales

Mauricio ECR
Arquitectura
29 Mar, 2025

Introducción

En el mundo de Java, trabajar con colecciones de datos solía ser sinónimo de bucles interminables, condicionales anidados y código repetitivo. Pero con la llegada de Java Streams (desde Java 8), todo cambió. Los Streams introdujeron un paradigma funcional y declarativo que permite manipular datos de manera eficiente, legible y elegante.

¿Imaginas poder filtrar, transformar, agrupar o reducir elementos con solo unas líneas de código? Los métodos de los Streams hacen esto posible, convirtiendo operaciones complejas en secuencias intuitivas. Pero para aprovecharlos al máximo, es clave conocer sus herramientas principales.

Aquí te presentamos un listado detallado de los métodos más poderosos de los Streams, divididos en dos categorías: métodos generales y métodos de agrupación. Descubre cómo dominarlos puede simplificar tu código, potenciar tu productividad y desbloquear nuevas posibilidades en el manejo de datos.

Listado de Métodos de Java Streams

Métodos Generales

filter(Predicate<? super T> predicate)
Filtra los elementos que cumplen con una condición.

List<Integer> numeros = Arrays.asList(5, 12, 3, 20); 
List<Integer> mayoresA10 = numeros.stream() 
                                  .filter(x -> x > 10) 
                                  .collect(Collectors.toList()); 
// Resultado: [12, 20]

map(Function<? super T, ? extends R> mapper)
Transforma cada elemento aplicando una función.

List<String> palabras = Arrays.asList("java", "streams"); 
List<Integer> longitudes = palabras.stream() 
                                   .map(String::length) 
                                   .collect(Collectors.toList()); 
// Resultado: [4, 7]

flatMap(Function<? super T, ? extends Stream<? extends R>> mapper)
Aplana múltiples Streams en uno solo (útil para listas anidadas).

List<List<Integer>> listaAnidada = Arrays.asList( 
    Arrays.asList(1, 2), 
    Arrays.asList(3, 4) 
); 
List<Integer> listaPlana = listaAnidada.stream() 
                                       .flatMap(List::stream) 
                                       .collect(Collectors.toList()); 
// Resultado: [1, 2, 3, 4]

reduce(BinaryOperator accumulator)
Reduce los elementos a un único valor mediante una operación (ej: suma).

List<Integer> numeros = Arrays.asList(1, 2, 3, 4); 
Optional<Integer> suma = numeros.stream() 
                                .reduce((a, b) -> a + b); 
// Resultado: 10

collect(Collector<? super T, A, R> collector)
Transforma el Stream en una colección o estructura de datos.

List<String> palabras = Arrays.asList("a", "b", "c"); 
Set<String> set = palabras.stream() 
                          .collect(Collectors.toSet()); 
// Resultado: [a, b, c] (como Set)

forEach(Consumer<? super T> action)
Ejecuta una acción en cada elemento (como imprimirlo).

List<String> frutas = Arrays.asList("Manzana", "Pera"); 
frutas.stream() 
      .forEach(fruta -> System.out.print(fruta + " ")); 
// Resultado: "Manzana Pera "

sorted()
Ordena los elementos (requiere que sean comparables).

List<Integer> numeros = Arrays.asList(3, 1, 4, 2); 
List<Integer> ordenados = numeros.stream() 
                                 .sorted() 
                                 .collect(Collectors.toList()); 
// Resultado: [1, 2, 3, 4]

distinct()
Elimina duplicados, retornando elementos únicos.

List<Integer> numeros = Arrays.asList(2, 2, 5, 5); 
List<Integer> unicos = numeros.stream() 
                              .distinct() 
                              .collect(Collectors.toList()); 
// Resultado: [2, 5]

limit(long maxSize)
Limita el Stream a un número máximo de elementos.

List<Integer> numeros = Arrays.asList(1, 2, 3, 4, 5); 
List<Integer> primeros3 = numeros.stream() 
                                  .limit(3) 
                                  .collect(Collectors.toList()); 
// Resultado: [1, 2, 3]

skip(long n)
Omite los primeros n elementos del Stream.

List<Integer> numeros = Arrays.asList(1, 2, 3, 4, 5); 
List<Integer> sinPrimeros2 = numeros.stream() 
                                    .skip(2) 
                                    .collect(Collectors.toList()); 
// Resultado: [3, 4, 5]

Métodos para Agrupar Elementos

Collectors.groupingBy(Function<? super T, ? extends K> classifier)
Agrupa elementos por una clave (ej: edad de una persona).

List<Persona> personas = Arrays.asList( 
    new Persona("Ana", 25), 
    new Persona("Luis", 25) 
); 
Map<Integer, List<Persona>> porEdad = personas.stream() 
    .collect(Collectors.groupingBy(Persona::getEdad)); 
// Resultado: {25=[Ana, Luis]}

Collectors.partitioningBy(Predicate<? super T> predicate)
Divide el Stream en dos grupos: los que cumplen y no cumplen un predicado.

// Agrupar por categoría + stock mayor a 5 
Map<String, List<Producto>> porCategoriaYStock = productos.stream() 
    .collect(Collectors.groupingBy(p -> 
        p.getCategoria() + "-" + (p.getStock() > 5 ? "AltoStock" : "BajoStock") 
    )); 
/* 
Resultado: 
{ 
  "Electrónica-AltoStock": [Laptop, Smartphone], 
  "Ropa-AltoStock": [Camisa] 
} 
*/

Collectors.groupingBy(classifier, downstream)
Agrupa y luego aplica un segundo colector a cada grupo (ej: contar elementos).

// Precio promedio por categoría 
Map<String, Double> precioPromedio = productos.stream() 
    .collect(Collectors.groupingBy( 
        Producto::getCategoria, 
        Collectors.averagingDouble(Producto::getPrecio) 
    )); 
/* 
Resultado: 
{ 
  "Electrónica": 1000.0, 
  "Ropa": 40.0 
} 
*/

Collectors.groupingBy(classifier, mapFactory, downstream)
Agrupa usando un tipo de mapa específico (ej: TreeMap).

// Agrupar por rangos de precios 
Map<String, List<Producto>> porRangoPrecio = productos.stream() 
    .collect(Collectors.groupingBy(p -> { 
        if (p.getPrecio() < 100) return "Económico"; 
        else if (p.getPrecio() < 1000) return "Medio"; 
        else return "Premium"; 
    })); 
/* 
Resultado: 
{ 
  "Premium": [Laptop], 
  "Medio": [Smartphone], 
  "Económico": [Camisa] 
} 
*/

Agrupar con downstream complejo (ej: contar y sumar stock)

// Por categoría: cantidad de productos y stock total 
Map<String, Map<String, Object>> estadisticas = productos.stream() 
    .collect(Collectors.groupingBy( 
        Producto::getCategoria, 
        Collectors.collectingAndThen( 
            Collectors.toList(), 
            lista -> { 
                int cantidad = lista.size(); 
                int stockTotal = lista.stream().mapToInt(Producto::getStock).sum(); 
                return Map.of("Cantidad", cantidad, "Stock Total", stockTotal); 
            } 
        ) 
    )); 
/* 
Resultado: 
{ 
  "Electrónica": {"Cantidad": 2, "Stock Total": 15}, 
  "Ropa": {"Cantidad": 1, "Stock Total": 20} 
} 
*/

Conclusión

Dominar los métodos de Java Streams no solo simplifica tu código, sino que también mejora su legibilidad y eficiencia. Al explorar y aplicar estos métodos, descubrirás nuevas formas de manipular colecciones de datos que pueden transformar tu enfoque en el desarrollo de software. ¡Sigue profundizando y experimentando con Java Streams para desbloquear todo su potencial!

Ver página completa →

¿SQL o NoSQL? Descubre la Base de Datos Ideal para tu Proyecto

Mauricio ECR
Persistencia
29 Mar, 2025

Introducción Elegir la base de datos adecuada para un proyecto es una decisión crítica que afecta la escalabilidad, el rendimiento y la facilidad de mantenimiento de una aplicación. ¿Necesitas una

Ver página completa

¿SQL o NoSQL? Descubre la Base de Datos Ideal para tu Proyecto

Mauricio ECR
Persistencia
29 Mar, 2025

Introducción

Elegir la base de datos adecuada para un proyecto es una decisión crítica que afecta la escalabilidad, el rendimiento y la facilidad de mantenimiento de una aplicación. ¿Necesitas una base de datos relacional o una documental? Este cuestionario te ayudará a tomar la mejor decisión basada en los requisitos específicos de tu proyecto. Responde las siguientes preguntas y obtén una recomendación basada en tus necesidades técnicas y operativas.

Contexto del Proyecto

Antes de responder, defina:

Caso de uso principal: Ej: sistema transaccional, catálogo de productos, IoT, contenido generado por usuarios.
Velocidad de crecimiento de datos: Estimación anual (GB/TB).
Ratio lecturas/escrituras: Ej: 80/20, 50/50.

1. Modelado de Datos

¿Los datos tienen una estructura fija y predefinida que se mantiene estable (>80% de los casos)?
- Ej: tablas de clientes con campos obligatorios vs. posts de redes sociales con metadatos variables.
¿Es crítico modelar relaciones muchos-a-muchos entre entidades principales?
- Ej: estudiantes-cursos vs. tags en un blog.
¿La normalización para evitar redundancia es prioritaria sobre la velocidad de lectura?
¿El esquema cambia menos de 2 veces/año?
¿Los registros comparten >90% de atributos comunes?
¿Los datos son principalmente planos o con anidamiento simple (≤2 niveles)?
- Ej: dirección {calle, ciudad} vs. JSON con subdocumentos jerárquicos.
¿La integridad referencial (FKs) es no negociable para el negocio?
¿Los datos son >70% valores escalares (números, textos cortos) vs. documentos/blobs?
¿Se pueden representar sin pérdida en tablas 2D?
- Ej: evita estructuras como arrays o árboles.
¿Prefiere almacenar documentos completos (JSON/XML) en lugar de desnormalizar?
¿Necesita consultar fragmentos específicos dentro de documentos anidados frecuentemente?
¿Los atributos varían significativamente entre registros de la misma entidad?
- Ej: productos con especificaciones técnicas heterogéneas.

2. Operaciones y Consultas

¿Las consultas frecuentes (≥30%) requieren JOINs entre ≥3 tablas?
¿Las búsquedas acceden a campos estructurados individuales (no documentos completos)?
¿Son esenciales transacciones ACID que abarcan múltiples operaciones/entidades?
- Nota: Algunas bases documentales (MongoDB 4.0+) soportan transacciones multi-documento.
¿Las consultas usan principalmente claves primarias/índices simples (no consultas ad-hoc)?
¿Se filtran datos usando ≥3 atributos simultáneamente en >50% de las consultas?
¿Prefiere consultar datos anidados directamente en lugar de desnormalizar?
¿Las escrituras implican actualizaciones parciales complejas (no reemplazos completos)?
¿Requiere agregaciones multidimensionales (OLAP) sobre >1TB de datos?
¿Las consultas acceden a ≥3 entidades relacionadas en >40% de los casos?
¿Es crítico tener un esquema fijo para validar datos en ingesta?
¿Usa consultas geoespaciales o de grafos con frecuencia?
- Nota: Ambos modelos pueden soportarlo, pero con implementaciones distintas.
¿Necesita índices compuestos sobre múltiples campos anidados?

3. Requerimientos No-Funcionales

¿El volumen total estimado en 3 años es <50TB?
- Nota: Bases relacionales distribuidas (CockroachDB) pueden manejar petabytes.
¿La alta disponibilidad requiere consistencia fuerte (no eventual)?
¿El ratio lecturas/escrituras es >70/30?
¿Puede tolerar latencias >15ms en operaciones críticas?
¿El equipo tiene ≥2 años de experiencia con SQL?
¿Es esencial compatibilidad con herramientas BI tradicionales (Power BI, Tableau)?
¿Requiere replicación transaccional cross-region?
¿Necesita escalado horizontal automático (sharding) sin downtime?
- Nota: Algunas RDBMS (Vitess) permiten sharding con límites.
¿La carga incluye >50K operaciones/segundo sostenidas?
¿Los backups deben ser incrementales con recuperación a momento específico?
¿Puede aceptar bloqueos por migraciones de esquema (>1 min de downtime)?

5 Preguntas Críticas Decisivas

¿Es no negociable la integridad referencial entre entidades?
- Sí → Relacional (a menos que use extensiones como PostgreSQL + FOREIGN KEY en JSONB).
¿Los datos son >60% documentos anidados con estructura irregular?
- Sí → Documental (pero considere híbridos como MySQL + MongoDB).
¿Requiere JOINs complejos (>3 tablas) en >25% de las consultas?
- Sí → Relacional (aunque algunas documentales tienen $lookup similar a JOINs).
¿Necesita escalar horizontalmente sin límites prácticos?
- Sí → Documental (pero evalúe NewSQL como YugabyteDB).
¿Requiere transacciones ACID multi-operación en >30% de los casos?
- Sí → Relacional (pero verifique si su documental soporta transacciones).

Regla decisiva

Si ≥3 respuestas clave apuntan a una categoría, priorícela. En empates (2-2), evalúe el contexto del proyecto.

Interpretación de Puntajes

Puntos Totales	Recomendación	Tecnologías Ejemplo
28-35	Relacional Puro	PostgreSQL, MySQL, SQL Server
20-27	Relacional + Extensiones	PostgreSQL (JSONB), SQL Server (XML), Oracle (JSON)
15-19	Híbrido o Multi-Modelo	MongoDB (transacciones), Cosmos DB (modo SQL), CockroachDB
8-14	Documental Puro	MongoDB, Couchbase, Firebase Firestore

Conclusión

Este cuestionario te ofrece un marco estructurado para evaluar qué tipo de base de datos es más adecuada para tu proyecto. Si la mayoría de tus respuestas favorecen la integridad referencial, los JOINs y la validación de esquema, una base relacional es la mejor opción. Si en cambio tu proyecto requiere flexibilidad en la estructura de datos, escalabilidad horizontal y almacenamiento de documentos, una base documental puede ser la respuesta. En casos híbridos, considera soluciones como PostgreSQL con JSONB o bases multimodelo como CosmosDB. ¡Elige sabiamente para optimizar el rendimiento y la escalabilidad de tu aplicación!

Ver página completa →

Desarrollo de Software Implementando Gitflow

Mauricio ECR
DevOps
19 Mar, 2025

Introducción El desarrollo de software requiere metodologías y flujos de trabajo que permitan un control eficiente del código fuente. Uno de los enfoques más utilizados para la gestión de versiones

Ver página completa

Desarrollo de Software Implementando Gitflow

Mauricio ECR
DevOps
19 Mar, 2025

Introducción

El desarrollo de software requiere metodologías y flujos de trabajo que permitan un control eficiente del código fuente. Uno de los enfoques más utilizados para la gestión de versiones es Gitflow, una estrategia basada en Git que organiza el trabajo en ramas bien definidas.

Este artículo explora qué es Gitflow, su filosofía, los problemas que resuelve y cómo implementarlo paso a paso en un proyecto. También se comparará el uso de Gitflow con los comandos básicos de Git para quienes prefieran un enfoque manual.

¿Qué es Gitflow?

Gitflow es un modelo de ramificación para Git propuesto por Vincent Driessen. Define un conjunto de reglas y procedimientos para gestionar las diferentes etapas del desarrollo de software, asegurando estabilidad en la rama principal mientras se permite la integración de nuevas funcionalidades de manera organizada.

Filosofía de Gitflow

Gitflow se basa en la idea de separar el desarrollo en ramas específicas con propósitos bien definidos:

Explicación de cada rama en Gitflow

main: Contiene la versión estable y en producción del software. Solo se realizan fusiones de versiones terminadas y correcciones críticas.
develop: Es la rama principal de desarrollo donde se integran nuevas funcionalidades antes de ser lanzadas.
feature: Se crean a partir de develop para el desarrollo de nuevas características. Una vez terminadas, se fusionan de nuevo en develop.
release: Se crean a partir de develop cuando se prepara una nueva versión. Aquí se realizan pruebas finales antes de integrarla en main.
hotfix: Se crean a partir de main para corregir errores críticos en producción y luego se fusionan en main y develop.
bugfix: Similar a hotfix, pero se crean a partir de develop para corregir errores antes de un lanzamiento.

¿Qué busca solucionar?

Gitflow aborda varios problemas comunes en el desarrollo de software, como:

Integración desorganizada de nuevas características.
Problemas al manejar versiones de lanzamiento.
Falta de control sobre la corrección de errores en producción.

¿Cómo propone solucionarlo?

Gitflow impone un flujo de trabajo con reglas claras para la creación, fusión y eliminación de ramas, asegurando estabilidad y organización en el repositorio.

Implementación de Gitflow paso a paso

A continuación, se detalla cómo implementar Gitflow en un proyecto, tanto utilizando la herramienta git-flow como con comandos básicos de Git.

1. Inicializar un repositorio con Gitflow

Usando la herramienta git-flow:

git flow init

Manualmente con Git:

git init
git branch -M main
git checkout -b develop

2. Crear una nueva funcionalidad (feature)

Con git-flow:

git flow feature start nueva-funcionalidad

Con Git básico:

git checkout -b feature/nueva-funcionalidad develop

3. Finalizar una funcionalidad

Con git-flow:

git flow feature finish nueva-funcionalidad

Con Git:

git checkout develop
git merge --no-ff feature/nueva-funcionalidad
git branch -d feature/nueva-funcionalidad

4. Preparar una versión de lanzamiento

Con git-flow:

git flow release start v1.0.0

Con Git:

git checkout -b release/v1.0.0 develop

5. Finalizar una versión de lanzamiento

Con git-flow:

git flow release finish v1.0.0

Con Git:

git checkout main
git merge --no-ff release/v1.0.0
git tag -a v1.0.0 -m "Versión 1.0.0"
git checkout develop
git merge main
git branch -d release/v1.0.0

6. Aplicar una corrección en producción (hotfix)

Con git-flow:

git flow hotfix start fix-critico

Con Git:

git checkout -b hotfix/fix-critico main

Para finalizar el hotfix: Con git-flow:

git flow hotfix finish fix-critico

Con Git:

git checkout main
git merge --no-ff hotfix/fix-critico
git tag -a v1.0.1 -m "Corrección crítica"
git checkout develop
git merge main
git branch -d hotfix/fix-critico

Ventajas del uso de Gitflow

Estructura clara: Organización de ramas para cada propósito.
Mayor estabilidad: La rama principal se mantiene siempre en estado funcional.
Mejor colaboración: Facilita la integración de cambios en equipos grandes.
Gestión eficiente de versiones: Simplifica la publicación de nuevas versiones y correcciones de errores.

Conclusión

Gitflow es un modelo altamente eficiente para la gestión de versiones en proyectos de software. Aunque la herramienta git-flow automatiza muchos pasos, comprender los comandos básicos de Git permite un control más detallado del flujo de trabajo. Su implementación mejora la organización, facilita el trabajo en equipo y contribuye a la estabilidad del código en producción.

Ver página completa →

Estructuración de Carpetas en Proyectos de Software

Mauricio ECR
Convenciones
18 Mar, 2025

En proyectos de software de gran escala, la falta de una estructura de carpetas bien definida puede generar desorden, dificultando la mantenibilidad, escalabilidad y comprensión del código. Muchas vec

Ver página completa

Estructuración de Carpetas en Proyectos de Software

Mauricio ECR
Convenciones
18 Mar, 2025

En proyectos de software de gran escala, la falta de una estructura de carpetas bien definida puede generar desorden, dificultando la mantenibilidad, escalabilidad y comprensión del código. Muchas veces, los proyectos crecen de manera descontrolada sin una estructura definida, lo que lleva a código difícil de navegar, dependencias circulares entre módulos, acoplamiento innecesario entre componentes y dificultad para incorporar nuevos desarrolladores al equipo.

Para estructurar un proyecto de software de manera eficiente, es recomendable seguir una organización de carpetas que refleje claramente la separación de responsabilidades. Esto ayuda a mantener un código modular, organizado y fácil de mantener.

Los principios clave para la organización de carpetas incluyen modularidad, donde cada módulo representa una unidad de negocio independiente; independencia, separando la lógica de negocio de la infraestructura y los adaptadores; cohesión, manteniendo agrupados los elementos relacionados dentro de un módulo; y evolución, permitiendo la escalabilidad sin afectar la estructura global.

Una estructura de carpetas recomendada puede verse de la siguiente manera:

/project-root
 ├── src
 │   ├── core  # Reglas de negocio y modelos
 │   │   ├── domain
 │   │   │   ├── entities
 │   │   │   ├── value_objects
 │   │   │   ├── repositories
 │   │   │   ├── services
 │   │   │   └── events
 │   │   ├── application
 │   │   │   ├── use_cases
 │   │   │   ├── dtos
 │   │   │   ├── mappers
 │   │   │   └── queries
 │   ├── modules  # Módulos específicos del negocio
 │   │   ├── user_management
 │   │   │   ├── domain
 │   │   │   ├── application
 │   │   │   ├── infrastructure
 │   │   │   ├── adapters
 │   ├── infrastructure  # Implementaciones técnicas y frameworks
 │   │   ├── persistence
 │   │   ├── messaging
 │   │   ├── external_services
 │   │   ├── config
 │   ├── adapters  # Interfaces externas y controladores
 │   │   ├── api
 │   │   ├── cli
 │   │   ├── event_consumers
 │   │   └── schedulers
 ├── tests  # Pruebas unitarias y de integración
 ├── docs  # Documentación del proyecto
 ├── scripts  # Herramientas para automatización
 ├── config  # Configuración general del proyecto
 ├── .gitignore
 ├── README.md

Dentro de esta estructura, 'core/' contiene la lógica de negocio (entidades, servicios, repositorios, etc.); 'modules/' agrupa los módulos del dominio de manera aislada; 'infrastructure/' contiene implementaciones técnicas como bases de datos, servicios externos y configuraciones; 'adapters/' define las interfaces de comunicación con el mundo exterior, incluyendo APIs, CLI y eventos; 'tests/' contiene pruebas unitarias e integración; 'docs/' almacena documentación técnica del proyecto; 'config/' centraliza archivos de configuración; y 'scripts/' incluye herramientas de automatización.

Por ejemplo, en un sistema de gestión de usuarios con autenticación, podríamos estructurar el módulo correspondiente de la siguiente manera:

/modules/user_management
 ├── domain
 │   ├── entities
 │   │   ├── UserEnt.ts
 │   ├── value_objects
 │   │   ├── EmailVO.ts
 │   ├── repositories
 │   │   ├── UserRepo.ts
 ├── application
 │   ├── use_cases
 │   │   ├── RegisterUserUC.ts
 │   │   ├── AuthenticateUserUC.ts
 │   ├── dtos
 │   │   ├── UserDTO.ts
 │   ├── mappers
 │   │   ├── UserMap.ts
 ├── infrastructure
 │   ├── persistence
 │   │   ├── UserRepoImpl.ts
 ├── adapters
 │   ├── api
 │   │   ├── UserCtrl.ts

Aquí, la capa de dominio maneja las reglas de negocio, la capa de aplicación contiene los casos de uso, la infraestructura gestiona la persistencia y los adaptadores exponen las funcionalidades a través de controladores API.

Resumen de Carpetas y su Uso

Carpeta	Descripción	Ejemplo en 'user_management'
'core/domain'	Contiene entidades, objetos de valor, repositorios y servicios	'UserEnt.ts' define la entidad de usuario
'core/application'	Define casos de uso, DTOs, mappers y queries	'RegisterUserUC.ts' implementa la lógica de registro de usuario
'modules'	Agrupa módulos específicos del negocio	'user_management/' encapsula toda la gestión de usuarios
'domain/entities'	Modelos de negocio que representan objetos persistentes	'UserEnt.ts' representa los datos del usuario en la base de datos
'domain/value_objects'	Objetos de valor inmutables del dominio	'EmailVO.ts' maneja la lógica del correo electrónico
'domain/repositories'	Interfaces para acceso a datos	'UserRepo.ts' define la interfaz para obtener usuarios
'application/use_cases'	Casos de uso que orquestan la lógica de negocio	'RegisterUserUC.ts' contiene la lógica de registro de usuario
'application/dtos'	Transporte de datos entre capas	'UserDTO.ts' define el formato de los datos de usuario
'application/mappers'	Conversión entre entidades y DTOs	'UserMap.ts' convierte entre 'UserEnt' y 'UserDTO'
'infrastructure/persistence'	Implementación de acceso a datos	'UserRepoImpl.ts' implementa 'UserRepo.ts'
'adapters/api'	Exposición de funcionalidades vía API	'UserCtrl.ts' maneja solicitudes HTTP
'tests'	Contiene pruebas unitarias y de integración	'UserSvcTest.ts' prueba 'RegisterUserUC.ts'
'docs'	Documentación técnica del proyecto	Documentación sobre el flujo de autenticación
'config'	Configuración general de la aplicación	Configuración de base de datos y variables de entorno
'scripts'	Scripts de automatización	Scripts para migraciones o configuración

Implementar una estructura de carpetas bien organizada ayuda a crear proyectos más mantenibles, escalables y fáciles de entender. Al separar claramente las responsabilidades, evitamos el acoplamiento innecesario y mejoramos la colaboración dentro del equipo de desarrollo. Desde el inicio del proyecto, es recomendable definir y documentar la estructura de carpetas para que todo el equipo la adopte y mantenga. Con esta estructura clara y modular, los proyectos de software pueden escalar sin comprometer la calidad del código. 🚀

Ver página completa →

Convención de Nombres en Clases Java: Mejora de Legibilidad y Mantenibilidad

Mauricio ECR
Convenciones
18 Mar, 2024

En proyectos de gran escala, identificar rápidamente el tipo de una clase facilita la comprensión del código, la colaboración y la depuración. Sin un esquema de nombres estandarizado, es común que los

Ver página completa

Convención de Nombres en Clases Java: Mejora de Legibilidad y Mantenibilidad

Mauricio ECR
Convenciones
18 Mar, 2024

En proyectos de gran escala, identificar rápidamente el tipo de una clase facilita la comprensión del código, la colaboración y la depuración. Sin un esquema de nombres estandarizado, es común que los desarrolladores enfrenten dificultades al interpretar la funcionalidad de una clase solo por su nombre, lo que ralentiza el mantenimiento y el desarrollo. En entornos profesionales, donde múltiples equipos trabajan sobre el mismo código base, contar con una nomenclatura clara mejora la comunicación y reduce la posibilidad de errores. Para solucionar esto, se propone una convención de nombres basada en prefijos y sufijos que permita diferenciar los distintos tipos de clases en Java.

Para garantizar la claridad, adoptamos las siguientes reglas:

Prefijos:
- Enumeraciones: E (Ejemplo: EUserRole)
- Interfaces: I (Ejemplo: IUserService)
Sufijos:
- Entities (Ent): Representan objetos persistentes. Ejemplo: UserEnt
- Value Objects (VO): Objetos inmutables con valor significativo. Ejemplo: MoneyVO
- Data Transfer Objects (DTO): Transporte de datos entre capas. Ejemplo: UserDTO
- Repositories (Repo): Acceso a datos. Ejemplo: UserRepo
- Services (Svc): Lógica de negocio. Ejemplo: UserSvc
- Controllers (Ctrl): Gestionan solicitudes HTTP. Ejemplo: UserCtrl
- Exceptions (Ex): Manejo de errores. Ejemplo: InvalidUserEx
- Configuration (Cfg): Configuraciones de aplicación. Ejemplo: DatabaseCfg
- Utility (Util): Métodos reutilizables. Ejemplo: DateUtil
- Test (Test): Clases de prueba. Ejemplo: UserSvcTest
- Commands (Cmd): Acciones en el sistema. Ejemplo: CreateUserCmd
- Domain Events (Evt): Eventos de dominio. Ejemplo: UserCreatedEvt
- Validation (Val): Validaciones. Ejemplo: UserVal
- Adapters (Adp): Integraciones con otros sistemas. Ejemplo: ExternalServiceAdp
- Message Brokers (Brk): Comunicación con colas de mensajes. Ejemplo: KafkaMsgBrk
- Mappers (Map): Transformación de objetos. Ejemplo: UserMap
- Views (View): Modelos de presentación. Ejemplo: UserView
- Gateways (Gtw): Comunicación con servicios externos. Ejemplo: PaymentGtw
- Factories (Fct): Creación de objetos. Ejemplo: UserFct
- Specifications (Spec): Criterios de búsqueda. Ejemplo: UserSpec
- Middleware (Mid): Interceptores de solicitudes. Ejemplo: AuthMid
- Aggregates (Agg): Raíces de agregados DDD. Ejemplo: OrderAgg
- Use Cases (UC): Casos de uso específicos. Ejemplo: RegisterUserUC
- Queries (Qry): Consultas a la base de datos. Ejemplo: FindUserQry
- View Models (VM): Modelos de datos para UI. Ejemplo: UserVM
- Policy / Guard (Pol o Grd): Reglas de negocio. Ejemplo: UserAccessPol

Para aplicar esta convención en un proyecto, recomendamos documentarla dentro del repositorio, integrar validaciones automáticas en las revisiones de código mediante linters o revisiones de PR y aplicar la convención en nuevos desarrollos, refactorizando el código legado progresivamente.

Adoptar una convención de nombres en clases Java mejora la comprensión del código y la colaboración en equipos de desarrollo. Al estandarizar prefijos y sufijos, cada clase tiene un propósito claro y es más fácil de ubicar y utilizar. Implementar esta convención desde el inicio de un proyecto o refactorizar el código existente progresivamente traerá beneficios a largo plazo.

Tipo de Clase	Prefijo/Sufijo	Ejemplo	Descripción
Enumeraciones	E	EUserRole	Define un conjunto de valores constantes
Interfaces	I	IUserService	Define contratos que deben implementar las clases
Entities	Ent	UserEnt	Representa objetos persistentes en la base de datos
Value Objects	VO	MoneyVO	Objetos inmutables que representan valores
DTOs	DTO	UserDTO	Transporte de datos entre capas
Repositories	Repo	UserRepo	Acceso a la base de datos
Services	Svc	UserSvc	Contiene la lógica de negocio
Controllers	Ctrl	UserCtrl	Gestiona las solicitudes HTTP
Exceptions	Ex	InvalidUserEx	Manejo de errores y excepciones
Configuration	Cfg	DatabaseCfg	Configuraciones de la aplicación
Utilities	Util	DateUtil	Métodos reutilizables
Tests	Test	UserSvcTest	Pruebas unitarias y de integración
Commands	Cmd	CreateUserCmd	Representa una acción o comando
Domain Events	Evt	UserCreatedEvt	Eventos del dominio
Validation	Val	UserVal	Validaciones de datos
Adapters	Adp	ExternalServiceAdp	Integración con sistemas externos
Message Brokers	Brk	KafkaMsgBrk	Comunicación con colas de mensajes
Mappers	Map	UserMap	Conversión entre objetos
Views	View	UserView	Modelos de presentación
Gateways	Gtw	PaymentGtw	Comunicación con servicios externos
Factories	Fct	UserFct	Creación de instancias de objetos
Specifications	Spec	UserSpec	Definición de criterios de búsqueda
Middleware	Mid	AuthMid	Interceptores de solicitudes
Aggregates	Agg	OrderAgg	Raíz de un agregado en DDD
Use Cases	UC	RegisterUserUC	Casos de uso específicos
Queries	Qry	FindUserQry	Consultas a la base de datos
View Models	VM	UserVM	Modelos de datos para UI
Policy/Guard	Pol/Grd	UserAccessPol	Reglas de negocio y restricciones

Ver página completa →

Filtros

El tramo en cascada que todo proyecto ágil necesita (y casi ninguno tiene)

Observabilidad sin Ruido: Diseñando un Sistema de Logs con AOP en Arquitecturas DDD — Parte III

Cuando el sistema nuevo tiene que hablarle al sistema viejo en su idioma

Cuando un sistema debe ejecutar lo mismo siempre y algo distinto cada vez

Observabilidad sin Ruido: Diseñando un Sistema de Logs con AOP en Arquitecturas DDD — Parte II

Cuando todo falla, ¿Quién decide?

El fin de la 'Jaula de Oro': recuperar el control de tu infraestructura

Arquitectura Modular por Contexto: Cuando la Teoría se Encuentra con la Realidad

Observabilidad sin Ruido: Diseñando un Sistema de Logs con AOP en Arquitecturas DDD

Estándar de Arquitectura: Transacciones Distribuidas (Patrón Saga)