Saltar al contenido principal
Arquitectura de software20 min de lectura

Spring Modulith y Kafka: eventos fiables y contexto asíncrono

Cómo externalizar eventos de Spring Modulith a Kafka con @Externalized sin acoplar la transacción al broker, qué pasa en el Event Publication Registry cuando Kafka está caído y cómo propagar el SecurityContext y el traceId a los listeners asíncronos, sobre un repositorio real.

Cristian Osorio · DatIACode

El equipo de analítica quiere recibir cada pedido en Kafka. La solución rápida parece añadir kafkaTemplate.send(...) justo después de guardar el pedido, dentro de un método @Transactional. Pero guardar en la base de datos y publicar en Kafka son dos operaciones independientes: puedes confirmar una y fallar en la otra. Además, aunque send() es asíncrono respecto a la confirmación del broker, la llamada puede bloquearse al obtener metadatos o al esperar capacidad del productor. La fiabilidad del pedido no debería depender de esa integración.

Este artículo cubre dos problemas que aparecen en cuanto un monolito modular empieza a hablar con el exterior y a trabajar en segundo plano: cómo sacar un evento hacia un broker sin acoplar la transacción a la red, y qué pasa con el usuario autenticado y el traceId cuando un listener se ejecuta en otro hilo.

Es el tercer artículo de la serie sobre Spring Modulith. En el primero, módulos con fronteras verificadas, organizamos la aplicación en módulos; en el segundo, eventos, listeners y reintentos, conectamos esos módulos con eventos y el Event Publication Registry. Ahora uno de esos eventos sale del monolito.

El código está en Datiacode-Tech/spring-modulith-shop, tag blog-3-externalizacion, con Java 21, Spring Boot 4.1.1 y Spring Modulith 2.1.1. Las salidas proceden de las ejecuciones documentadas para ese estado del proyecto; no son benchmarks generales. El experimento sobre TaskDecorator, explicado más adelante, se ejecutó sobre el código final del proyecto y no forma parte del tag.

Spring Modulith y Kafka, en 30 segundos

  • @Externalized en un evento hace que Spring Modulith lo publique también en Kafka (o en RabbitMQ, JMS o Spring Messaging) sin escribir un productor.
  • La publicación hacia el broker pasa por el mismo Event Publication Registry que los listeners internos: se registra en la transacción del pedido y se envía después del commit.
  • Si el broker está caído, el pedido se crea igual. La externalización queda FAILED tras el timeout del productor y, en el ejemplo, se reenvía al reiniciar. La entrega es al menos una vez, no exactamente una vez.
  • Un @ApplicationModuleListener se ejecuta en otro hilo, así que el SecurityContext y el MDC, que viven en ThreadLocal, no viajan solos.
  • En la configuración probada, el módulo de observabilidad de Spring Modulith instala en el executor su propio decorator de propagación de contexto, y un TaskDecorator propio no llegó a ejecutarse. Para propagar el traceId del MDC bastó con registrar un accessor en el ContextRegistry de Micrometer.

En este artículo

El problema: enviar a Kafka dentro de la transacción

La versión tentadora publica en Kafka en el mismo método que guarda el pedido:

La versión tentadorajava
@Transactional
public OrderDetails create(NewOrder newOrder) {
	var order = orders.save(...);
	kafkaTemplate.send("shop.orders.completed", order.getId().toString(), toJson(order)); // doble escritura
	return toDetails(order);
}
Problemas de publicar en Kafka dentro de la transacción del pedido
ProblemaQué pasa
Doble escrituraSi Kafka acepta el mensaje y luego la transacción hace rollback, el mensaje describe un pedido que no existe. Si el commit funciona y Kafka falla, el pedido existe y nadie fuera se entera
Bloqueo potencial en la llamadaAunque send() devuelve un resultado asíncrono, la llamada puede bloquearse mientras obtiene metadatos del topic o espera espacio en el buffer. Si ocurre dentro de la transacción, la alarga y aumenta la presión sobre las conexiones
Fallos mal gestionadosSi send() falla de inmediato, o si se espera su confirmación dentro del método, el fallo afecta a la operación. Si falla más tarde y nadie mira el resultado, el pedido queda confirmado sin una publicación fiable

El Event Publication Registry de Spring Modulith registra las entregas pendientes dentro de la transacción de negocio y las procesa después del commit. Reduce el problema de la doble escritura en este escenario, pero no promete entrega exactamente una vez ni sustituye todas las garantías operativas de una implementación Outbox especializada.

Externalizar un evento con @Externalized

El evento es el mismo record del artículo anterior, con una anotación más:

OrderCompleted.java · orderjava
// package e imports omitidos

/**
 * Published when an order has been accepted and stored. The order module does not know who listens.
 * <p>
 * Also externalized to the Kafka topic {@code shop.orders.completed}, keyed by order id, for consumers outside the
 * application (e.g. an analytics team).
 */
@Externalized("shop.orders.completed::#{#this.orderId().toString()}")
public record OrderCompleted(Long orderId, String customer, List<Line> lines, BigDecimal total, Instant completedAt) {

	public OrderCompleted {
		lines = List.copyOf(lines);
	}

	public record Line(String sku, String productName, int quantity) {
	}
}
  • shop.orders.completed, antes de los dos puntos dobles, es el destino: el topic, en Kafka.
  • #{#this.orderId().toString()} es una expresión SpEL evaluada sobre el evento que da la clave del mensaje. La clave no es, por sí sola, un identificador único de cada evento.

No hay más código. DefaultOrderService no cambia: sigue publicando OrderCompleted con el ApplicationEventPublisher de siempre, y sigue sin saber que existe Kafka.

Clave, partición y orden de los mensajes

Usar el id del pedido como clave mantiene los mensajes de un mismo pedido en la misma partición mientras no cambie la configuración de particionado (por ejemplo, el número de particiones del topic), y Kafka conserva el orden de los registros dentro de cada partición. Eso no garantiza que los eventos se externalicen en el orden en que se publicaron: el envío se hace de forma asíncrona, desde varios hilos, y una publicación reenviada puede llegar después de otras posteriores.

Para ese caso, Spring Modulith 2.1.1 ofrece spring.modulith.events.externalization.serialize-externalization=true, que hace que se envíe un solo evento al broker cada vez. La documentación lo recomienda cuando importa que un evento no adelante a otro, sobre todo al reenviar publicaciones en bloque. El precio es el rendimiento: los envíos dejan de ir en paralelo y uno lento, como los 60 s de bloqueo que se ven más abajo, retrasa a todos los que vienen detrás. Tampoco reordena lo que ya falló: una publicación que se reenvía tras un fallo sigue llegando después de las que salieron bien entretanto. El ejemplo no activa esta propiedad; es una decisión para producción.

Dependencias y configuración

Hacen falta el starter de Kafka de Spring Boot y el módulo de externalización de Spring Modulith. El proyecto usa Redpanda, compatible con el protocolo de Kafka, para tener un broker real en un contenedor. Facilita reproducir el ejemplo; no implica que Redpanda y Apache Kafka sean equivalentes en todas sus características operativas.

pom.xmlxml
<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-kafka</artifactId>
</dependency>
<dependency>
	<groupId>org.springframework.modulith</groupId>
	<artifactId>spring-modulith-events-kafka</artifactId>
</dependency>
application.properties y application-dev.propertiesproperties
# application.properties
# Event externalization to Kafka: Modulith serializes events to JSON bytes itself
spring.kafka.producer.value-serializer=org.apache.kafka.common.serialization.ByteArraySerializer

# application-dev.properties: Redpanda from docker-compose
spring.kafka.bootstrap-servers=localhost:19092

El mismo pedido, ahora en Kafka

Un pedido real creado sobre el tag blog-3-externalizacion, leído del topic con rpk, el cliente de línea de comandos de Redpanda:

rpk topic consume shop.orders.completed --offset -1 -n 1json
{
  "topic": "shop.orders.completed",
  "key": "45",
  "value": {
    "orderId": 45,
    "customer": "alice",
    "lines": [
      { "sku": "MS-001", "productName": "Wireless mouse", "quantity": 1 }
    ],
    "total": 29.9,
    "completedAt": "2026-10-19T12:08:42.282380349Z"
  },
  "headers": [
    { "key": "__TypeId__", "value": "com.datiacode.shop.order.OrderCompleted" }
  ],
  "partition": 0,
  "offset": 38
}
  • La clave es el id del pedido, tal como pide la expresión SpEL.
  • El valor es el record serializado, campo a campo. Lo que pongas en el evento es lo que verá el consumidor externo.
  • La cabecera __TypeId__ lleva el nombre completo de la clase Java. Tiene consecuencias, y volvemos a ella más abajo.

Flujo: pedido, registro transaccional y Kafka

El broker no forma parte de la transacción de la base de datos. Lo que entra en ella es el pedido y una publicación pendiente por cada destinatario del evento, incluido el externalizador. Después del commit, cada camino avanza por su cuenta:

Lo que ocurre antes y después del commit
DisparadorPOST /ordersUsuario autenticado
Paso@Transactional: crear el pedidoPublica OrderCompleted
DatosCommit en la base de datosPedido y publicaciones pendientes, juntosordersevent_publication × 3
  • Respuesta
    SalidaHTTP 201 Created
  • Listeners internos
    Pasoinventory y notificationEn otro hilo, cada uno en su transacción
    DatosSu publicación pasa a COMPLETED
  • Externalizador
    HerramientaKafka / RedpandaTopic de pedidos completados
    CondiciónCOMPLETED o FAILED recuperableSe reenvía al reiniciar o bajo demanda

El orden entre la respuesta HTTP y los trabajos asíncronos puede variar: la respuesta no espera a que terminen.

Flujo del ejemplo: POST /orders entra en un método @Transactional que guarda el pedido y las publicaciones pendientes del Event Publication Registry en la misma transacción. Tras el commit hay tres caminos independientes: la respuesta HTTP 201, los listeners internos de inventory y notification, que marcan su publicación como completada, y el externalizador, que publica en el topic de Kafka o Redpanda y deja su publicación en COMPLETED si el broker confirma o en FAILED, recuperable, si no. La respuesta no espera necesariamente a los listeners ni al broker.

Una fila más en el registro

La externalización no es un mecanismo aparte: Spring Modulith la implementa como un listener más del evento, y por eso aparece en la tabla event_publication.

Las publicaciones del pedido 45text
            listener             |  status   | publicado | completado | intentos
---------------------------------+-----------+-----------+------------+----------
 EventExternalizerModuleListener | COMPLETED | 14:08:42  | 14:08:42   |        1
 OrderCompletedListener          | COMPLETED | 14:08:42  | 14:08:42   |        1
 OrderConfirmationListener       | COMPLETED | 14:08:42  | 14:08:42   |        1

Tres filas: inventory, notification y el envío a Kafka. Lo que el registro garantiza a los listeners internos (guardado en la misma transacción, reenvío por listener, entrega al menos una vez) vale también para el broker. Es un registro transaccional de publicaciones pendientes con reenvío, cercano al patrón Outbox, pero conviene distinguirlo de un Outbox clásico con un relay independiente: la documentación de Spring Modulith 2.1 reconoce que al mecanismo nativo le faltan funciones que se esperan de una implementación Outbox y permite delegar la externalización en Namastack Outbox o JobRunr.

Qué pasa si Kafka está caído

Es la afirmación importante, así que se comprobó. La aplicación arrancó con --spring.kafka.bootstrap-servers=localhost:1, un puerto donde no escucha ningún broker, y se creó un pedido.

Respuesta del endpointtext
POST /orders → HTTP/1.1 201 en 0.30 s · pedido 47
event_publication, 5 segundos despuéstext
            listener             |   status   | publicado | completado | intentos
---------------------------------+------------+-----------+------------+----------
 EventExternalizerModuleListener | PROCESSING | 14:08:53  |            |        1
 OrderCompletedListener          | COMPLETED  | 14:08:53  | 14:08:53   |        1
 OrderConfirmationListener       | COMPLETED  | 14:08:53  | 14:08:53   |        1
75 segundos despuéstext
            listener             |  status   | publicado | completado | intentos
---------------------------------+-----------+-----------+------------+----------
 EventExternalizerModuleListener | FAILED    | 14:08:53  |            |        1
 OrderCompletedListener          | COMPLETED | 14:08:53  | 14:08:53   |        1
 OrderConfirmationListener       | COMPLETED | 14:08:53  | 14:08:53   |        1

org.apache.kafka.common.errors.TimeoutException: Topic shop.orders.completed not present in metadata after 60000 ms.
Tras reiniciar con el broker buenotext
            listener             |  status   | publicado | completado | intentos
---------------------------------+-----------+-----------+------------+----------
 EventExternalizerModuleListener | COMPLETED | 14:08:53  | 14:10:15   |        2
 ...
¿Está el pedido 47 en el topic? sí → 47 {"orderId":47,"customer":"alice",...}
  • El cliente no se enteró. Respuesta 201 en 0,30 s. El stock se descontó y el listener de notificaciones se ejecutó correctamente, simulando el envío del correo mediante una entrada en el log. Kafka caído no tumbó la venta.
  • La externalización no se perdió. Quedó FAILED en el registro, con el evento serializado.
  • Se reenvió al reiniciar (2 intentos) gracias a spring.modulith.events.republish-outstanding-events-on-restart=true, y el mensaje llegó al topic con su clave.

Un hilo bloqueado durante 60 segundos

En este experimento, la obtención de metadatos del topic agotó el límite de max.block.ms (60 s por defecto) y el externalizador mantuvo ocupado uno de los hilos del executor, un pool de 4 en el ejemplo. Si varios envíos se bloquean a la vez, también se retrasan los demás listeners del mismo pool.

Ajusta spring.kafka.producer.properties.max.block.ms y la capacidad o el aislamiento del executor según tus requisitos. Reducir el timeout evita esperas largas, pero no sustituye una estrategia de reintentos, monitorización y recuperación: el registro no reintenta solo mientras el broker sigue caído.

Al menos una vez: consumidores idempotentes

Como con cualquier listener del registro, la entrega es al menos una vez: si la aplicación cae justo después de que Kafka acepte el mensaje y antes de marcar la fila como completada, el mensaje se enviará dos veces. Los consumidores del topic tienen que ser idempotentes.

El id del pedido sirve para agrupar y particionar, pero no siempre basta para deduplicar: dos eventos distintos pueden pertenecer al mismo pedido. Para una deduplicación robusta conviene incluir un eventId estable por publicación, o definir en el contrato una clave de negocio inequívoca. El record del ejemplo todavía no tiene ese identificador.

Probarlo con Testcontainers

El test de integración levanta Redpanda en un contenedor, crea un pedido y lo lee del topic con un consumidor Kafka real. Se muestra sin los imports:

ExternalizationTests.java · testjava
@SpringBootTest(properties = "spring.modulith.events.externalization.enabled=true")
@Import({ TestcontainersConfiguration.class, ExternalizationTests.Redpanda.class })
class ExternalizationTests {

	static final String TOPIC = "shop.orders.completed";

	@TestConfiguration(proxyBeanMethods = false)
	static class Redpanda {

		@Bean
		@ServiceConnection
		RedpandaContainer redpanda() {
			return new RedpandaContainer("docker.redpanda.com/redpandadata/redpanda:v24.2.4");
		}
	}

	@Autowired
	OrderService orders;

	@Autowired
	RedpandaContainer redpanda;

	@Test
	@DisplayName("a placed order is published to shop.orders.completed keyed by order id")
	void externalizesOrderCompleted() {
		var order = orders.create(new NewOrder("alice", List.of(new NewOrder.Item("KB-001", 1))));

		try (var consumer = new KafkaConsumer<String, String>(Map.of(
				ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, redpanda.getBootstrapServers(),
				ConsumerConfig.GROUP_ID_CONFIG, "test-" + UUID.randomUUID(),
				ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest",
				ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class,
				ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class))) {
			consumer.subscribe(List.of(TOPIC));

			var received = new ArrayList<ConsumerRecord<String, String>>();
			long deadline = System.currentTimeMillis() + 20_000;
			while (received.isEmpty() && System.currentTimeMillis() < deadline) {
				consumer.poll(Duration.ofMillis(500)).forEach(received::add);
			}

			assertThat(received).singleElement().satisfies(record -> {
				assertThat(record.key()).isEqualTo(order.id().toString());
				assertThat(record.value()).contains("\"customer\":\"alice\"").contains("\"sku\":\"KB-001\"");
			});
		}
	}
}

@ServiceConnection sobre el RedpandaContainer hace que Spring Boot configure spring.kafka.bootstrap-servers apuntando al contenedor, sin propiedades manuales. La clase completa, con sus imports, está en el repositorio del ejemplo. En la ejecución documentada tardó 13,5 s contando el arranque de los contenedores; es un dato de ese entorno, no una referencia de rendimiento.

El resto de tests, sin broker

Los demás tests no necesitan Kafka. Para ellos, el perfil test desactiva la externalización, y ExternalizationTests la vuelve a activar con su propiedad:

application-test.properties (extracto)properties
# No broker in most tests; ExternalizationTests re-enables it with Testcontainers
spring.modulith.events.externalization.enabled=false

El evento ya es un contrato público

Mientras OrderCompleted solo lo escuchaban módulos de la misma aplicación, cambiarlo era una refactorización: el compilador señalaba cada listener afectado. En cuanto sale a Kafka, hay consumidores que no compilan contra tu código.

La cabecera __TypeId__ merece una nota: expone el nombre del paquete Java (com.datiacode.shop.order.OrderCompleted). Un consumidor con Spring Kafka puede usarla para deserializar; uno en Python o Go la ignorará. Si tus consumidores dependen de ella, mover el record de paquete es un cambio incompatible.

Impacto de cambiar un evento externalizado según quién lo consume
Cambio en el recordConsumidores internosConsumidores del topic
Añadir un campoSin impactoNormalmente sin impacto, si toleran campos desconocidos
Renombrar un campoEl compilador avisaPuede romper el mapeo o perder información sin aviso
Quitar un campoEl compilador avisaPuede romper el consumidor, según cómo trate los campos ausentes
Mover o renombrar la claseEl IDE lo arreglaCambia la cabecera __TypeId__

La recomendación práctica: trata un evento externalizado como una API pública versionada. Añade campos compatibles cuando los consumidores lo permitan; para cambios incompatibles, define una versión nueva del contrato y una estrategia de migración, como un topic versionado o un periodo de compatibilidad. Si hay consumidores fuera del ecosistema Java, no dependas de __TypeId__ como único mecanismo de identificación.

Segundo problema: el usuario se pierde al cambiar de hilo

En este tag el proyecto añade una seguridad mínima: Spring Security con HTTP Basic y dos usuarios en memoria. El cliente del pedido es el usuario autenticado, no lo que diga el body:

OrderController.java · order.internal (extracto)java
@PostMapping
@Operation(summary = "Place an order", description = "Prices the items against the catalog, stores the order and publishes OrderCompleted")
ResponseEntity<OrderResponse> create(@Valid @RequestBody CreateOrderRequest request, Principal principal) {
	var order = OrderResponse.from(orderService.create(request.toCommand(principal.getName())));
	return ResponseEntity.created(URI.create("/orders/" + order.id())).body(order);
}
Sin credenciales, y con un customer falso en el bodytext
$ curl -i -X POST localhost:8080/orders -H 'Content-Type: application/json' -d '{"items":[...]}'
HTTP/1.1 401
WWW-Authenticate: Basic realm="Realm", charset="UTF-8"
X-Content-Type-Options: nosniff
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin

$ curl -u alice:*** -X POST ... -d '{"customer":"mallory","items":[{"sku":"MS-001","quantity":1}]}'
pedido 46 · customer = alice

El body dice mallory; el pedido queda a nombre de alice, que es quien se autenticó. Referrer-Policy no viene por defecto en Spring Security: la añade la configuración del proyecto.

Por qué el listener no ve al usuario

Spring Security guarda el usuario en el SecurityContextHolder, que por defecto es un ThreadLocal: el dato vive pegado al hilo que atiende la petición HTTP. Lo mismo pasa con el MDC de los logs, donde el proyecto guarda un traceId. Y @ApplicationModuleListener se ejecuta en otro hilo, del pool shop-async-*.

La solución de manual: un TaskDecorator

La respuesta clásica, la que aparece en casi cualquier tutorial sobre @Async y Spring Security, es decorar las tareas del executor. Este código no está en el repositorio: es el que se escribió para el experimento de la sección siguiente.

El arreglo clásicojava
@Bean
TaskDecorator contextCopyingDecorator() {
	return task -> {
		var context = SecurityContextHolder.getContext();     // 1. capture on the caller thread
		var mdc = MDC.getCopyOfContextMap();
		return () -> {
			try {
				SecurityContextHolder.setContext(context);     // 2. restore on the worker thread
				if (mdc != null) MDC.setContextMap(mdc);
				task.run();
			}
			finally {
				SecurityContextHolder.clearContext();          // 3. clean up: pooled threads are reused
				MDC.clear();
			}
		};
	};
}

El paso 3 es el crítico: los hilos de un pool se reutilizan y, sin limpiar, la siguiente tarea podría heredar el usuario de otra petición. Es un fallo de seguridad que no aparece en ningún test unitario. Se escribió, se registró como bean... y no se ejecutó ni una vez.

El experimento: qué hace realmente el executor

Para entender por qué, se añadió a un clon temporal del proyecto una sonda que, al arrancar, lee por reflexión qué TaskDecorator tiene de verdad el executor de los listeners, y un TaskDecorator propio que solo escribe una línea en el log cada vez que se ejecuta. Se probaron tres configuraciones:

Decorator efectivo del executor en tres configuraciones
CasoDecorator del executor¿Se ejecuta el propio?Usuario y traceId en el listener
A · con spring-modulith-observability-core y TaskDecorator propioContextPropagatingTaskDecoratorNo (0 ejecuciones)Llegan alice y el traceId
B · sin spring-modulith-observability-coreNingunoNo aplicaSe pierden
C · sin observability y con TaskDecorator propioEl propioSíSe pierden (el del experimento no copiaba nada)

Salida de la sonda

Caso Atext
PROBE applicationTaskExecutor=ThreadPoolTaskExecutor taskDecorator=org.springframework.core.task.support.ContextPropagatingTaskDecorator
Líneas 'CUSTOM TaskDecorator ran' en el log: 0
Order 39 confirmation requested by user alice
Caso Btext
PROBE applicationTaskExecutor=ThreadPoolTaskExecutor taskDecorator=none
Order 40 confirmation requested by user <none: no SecurityContext on this thread>

Por qué ocurre

El módulo spring-modulith-observability-core, que el proyecto usa para trazar las interacciones entre módulos, configura en el executor el ContextPropagatingTaskDecorator de Spring. En la versión 2.1.1, su autoconfiguración registra un customizer del ThreadPoolTaskExecutor que llama a setTaskDecorator con ese decorator, lo que encaja con lo observado: el executor tiene un solo decorator efectivo y el propio no quedó aplicado.

Es un comportamiento observado en esta combinación de versiones y configuración, no una regla universal para cualquier TaskExecutor o versión de Spring. Antes de registrar un decorator propio, comprueba qué decorator tiene realmente tu executor.

Lo que sí hace falta: el ContextRegistry

ContextPropagatingTaskDecorator no copia campos concretos: propaga todo lo registrado en el ContextRegistry de Micrometer Context Propagation. En la combinación probada, Spring Security ya registra su propio accessor, y por eso el usuario llegaba en el caso A. La entrada traceId del MDC no se propagaba hasta registrarla:

ContextPropagationConfig.java · shared.configjava
/**
 * Makes the MDC trace id travel with asynchronous tasks, including every {@code @ApplicationModuleListener}.
 * <p>
 * There is no custom {@code TaskDecorator} on purpose: {@code spring-modulith-observability} already installs Spring's
 * {@code ContextPropagatingTaskDecorator} on the task executor (and would silently replace one of ours). That decorator
 * propagates whatever is registered in Micrometer's {@link ContextRegistry}: Spring Security registers the
 * {@code SecurityContext} itself, so only the MDC entry needs registering here. The decorator also restores the
 * worker thread's previous state after each task, so pooled threads do not leak another request's data.
 */
@Configuration(proxyBeanMethods = false)
class ContextPropagationConfig {

	static final String TRACE_ID = "traceId";

	ContextPropagationConfig() {
		registerTraceIdAccessor();
	}

	static void registerTraceIdAccessor() {
		// Re-registering the same key replaces the previous accessor, so this is safe across test contexts
		ContextRegistry.getInstance().registerThreadLocalAccessor(TRACE_ID,
				() -> MDC.get(TRACE_ID),
				value -> MDC.put(TRACE_ID, value),
				() -> MDC.remove(TRACE_ID));
	}
}

Un accessor tiene tres funciones: cómo leer el valor en el hilo original, cómo escribirlo en el hilo destino y cómo limpiarlo. El decorator restaura el estado anterior del hilo después de cada tarea, así que la limpieza del paso 3 viene incluida.

El traceId: un filtro deliberadamente mínimo

El traceId lo pone un filtro que lo toma de la cabecera X-Trace-Id o lo genera:

TraceIdFilter.java · shared.webjava
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
class TraceIdFilter extends OncePerRequestFilter {

	static final String HEADER = "X-Trace-Id";
	static final String MDC_KEY = "traceId";

	@Override
	protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
			throws ServletException, IOException {
		var traceId = request.getHeader(HEADER);
		if (traceId == null || traceId.isBlank()) {
			traceId = UUID.randomUUID().toString().replace("-", "").substring(0, 16);
		}
		MDC.put(MDC_KEY, traceId);
		response.setHeader(HEADER, traceId);
		try {
			chain.doFilter(request, response);
		}
		finally {
			MDC.remove(MDC_KEY);
		}
	}
}

El resultado en los logs

Con logging.pattern.level=%5p [%X{traceId:-}], cada línea lleva el traceId entre corchetes. Un pedido enviado con la cabecera X-Trace-Id: demo-140842:

Log de la aplicacióntext
14:08:42.391 INFO [demo-140842] [shop-async-2] c.d.s.n.i.OrderConfirmationListener: Order 45 confirmation requested by user alice
14:08:42.391 INFO [demo-140842] [shop-async-2] c.d.s.notification.internal.EmailSender: Email to alice@example.com | Order #45 confirmed | ...
14:08:42.399 INFO [demo-140842] [shop-async-1] c.d.s.i.internal.OrderCompletedListener: Order 45: took 1 x MS-001 from stock, 5 left

Dos hilos de listeners distintos, el mismo traceId que mandó el cliente y el usuario alice en el hilo asíncrono.

Probar la propagación y la limpieza

El test usa el mismo decorator que instala Spring Modulith y comprueba dos cosas: que el usuario y el traceId llegan al otro hilo, y que el hilo queda limpio después. Se muestra el segundo caso, que es el que protege de la fuga entre peticiones:

Test de ContextPropagationConfig · shared.config (extracto)java
class ContextPropagationConfigTest {

	final ContextPropagatingTaskDecorator decorator = new ContextPropagatingTaskDecorator();

	// A single thread, so the second task runs on the very thread that ran the first one
	final ExecutorService executor = Executors.newSingleThreadExecutor();

	@BeforeAll
	static void registerAccessors() {
		ContextPropagationConfig.registerTraceIdAccessor();
	}

	@AfterEach
	void tearDown() {
		executor.shutdownNow();
		SecurityContextHolder.clearContext();
		MDC.clear();
	}

	// propagatesSecurityContextAndTraceId() omitido

	@Test
	@DisplayName("the pooled thread is clean after the task, so the next task does not inherit the previous user")
	void leavesNothingBehind() throws Exception {
		SecurityContextHolder.getContext().setAuthentication(new TestingAuthenticationToken("alice", "n/a"));
		MDC.put("traceId", "abc123");
		executor.submit(decorator.decorate(() -> { })).get(5, TimeUnit.SECONDS);

		var leakedAuthentication = new AtomicReference<Object>("not checked");
		var leakedTraceId = new AtomicReference<String>("not checked");
		executor.submit(() -> {
			leakedAuthentication.set(SecurityContextHolder.getContext().getAuthentication());
			leakedTraceId.set(MDC.get("traceId"));
		}).get(5, TimeUnit.SECONDS);

		assertThat(leakedAuthentication).hasValue(null);
		assertThat(leakedTraceId).hasValue(null);
	}
}

La clave está en el executor de un solo hilo: la segunda tarea, sin decorar, corre en el mismo hilo que la primera. Si quedara algo de alice, se vería. El test no arranca Spring; en la ejecución documentada tardó 0,01 s.

No confundirlo con la identidad entre sistemas

Todo lo anterior trata de propagar el contexto dentro de la misma JVM. Un mensaje que llega desde Kafka es otro problema: ahí no hay SecurityContext que propagar, porque el productor es otro sistema. Autenticar ese mensaje (quién lo envió y con qué permisos) es identidad entre servicios, y se resuelve con otros mecanismos: firmas, tokens en cabeceras o ACL del broker.

Del mismo modo, una publicación reenviada tras un reinicio no tiene usuario: el reenvío no viene de ninguna petición HTTP. Un listener que necesite saber quién hizo el pedido debe sacar ese dato del propio evento (OrderCompleted.customer), no confiar en encontrar un SecurityContext vigente. Y propagar un contexto no equivale a autorizar una operación: cada consumidor aplica sus propias reglas de seguridad.

Qué falta para llevar este ejemplo a producción

El caso de laboratorio demuestra persistencia y recuperación tras un reinicio. Una integración real necesita además decidir:

  • Objetivos de entrega: cuánto puede tardar un evento en llegar al topic y qué se hace si no llega.
  • Monitorización de publicaciones FAILED y de las que llevan demasiado tiempo pendientes.
  • Política de reenvío: al reiniciar, desde una tarea programada con IncompleteEventPublications o con una implementación Outbox especializada.
  • Recursos del executor: tamaño, aislamiento de la externalización y timeouts del productor.
  • Contrato con los consumidores: identificador único de cada evento para deduplicar y estrategia de versionado de los mensajes.

Una publicación COMPLETED no significa que el consumidor de Kafka ya la haya procesado: significa que el publicador terminó su parte según el mecanismo de envío utilizado. Y, como se vio en el artículo anterior, la documentación de Spring Modulith desaconseja en general republicar al arrancar cuando hay varias instancias: una nueva puede reentregar eventos que otra todavía está procesando. El ejemplo es una sola instancia.

Mantenimiento del Event Publication Registry

Con el modo por defecto, las publicaciones completadas no se borran: se marcan como COMPLETED y se quedan en la tabla. La documentación avisa de que, sin una limpieza periódica, el registro crece sin límite y puede ralentizar la creación y la finalización de nuevas publicaciones. Hace falta una política de retención.

Spring Modulith 2.1.1 da dos herramientas. La interfaz CompletedEventPublications, del artefacto spring-modulith-events-api, permite consultar las publicaciones completadas y purgarlas todas o solo las anteriores a una antigüedad dada, por ejemplo desde una tarea programada. Y la propiedad spring.modulith.events.completion-mode elige qué pasa al completar una publicación: UPDATE (por defecto) la marca y la conserva, DELETE la borra y deja de ser consultable, y ARCHIVE la mueve a una tabla de archivo, donde CompletedEventPublications la sigue viendo. La elección depende de cuánto historial necesites para auditoría y diagnóstico, y de cuánto almacenamiento estés dispuesto a mantener; las publicaciones incompletas, que son las que permiten recuperar, no se ven afectadas en ningún modo.

Errores habituales

Errores habituales al externalizar eventos y propagar contexto
ErrorConsecuenciaQué hacer
kafkaTemplate.send dentro del @TransactionalDoble escritura y fallos en cascada@Externalized y el Event Publication Registry
JsonSerializer en el productorEl evento se serializa dos vecesByteArraySerializer: Spring Modulith ya entrega JSON
max.block.ms por defecto con un broker inestableCada externalización bloquea un hilo de listeners hasta 60 sAjustarlo, dimensionar o aislar el executor y monitorizar las publicaciones FAILED
Consumidores del topic no idempotentesEfectos duplicados tras un reenvíoDeduplicar con un eventId estable o una clave de negocio inequívoca
Renombrar campos de un evento externalizadoConsumidores externos rotos sin avisoTratar el evento como una API pública versionada
Registrar un TaskDecorator propio con spring-modulith-observability-coreEn la configuración probada no se ejecuta, y nadie avisaComprobar el decorator efectivo y registrar en el ContextRegistry lo que falte
Leer el usuario del SecurityContext en un listenerVacío en las publicaciones reenviadasLlevar el dato en el evento
Restaurar el contexto sin limpiarloUn hilo del pool hereda el usuario de otra peticiónLimpiar siempre, o usar el decorator de Spring

Cuándo externalizar un evento

Cuándo conviene externalizar un evento y cuándo no
Situación¿Externalizar?Por qué
Otro sistema (analítica, un data warehouse, otro servicio) necesita enterarse de lo que pasa en el monolitoSíEs justo el caso para el que existe
Preparas la extracción de un móduloSíSi sus eventos ya salen a Kafka, el futuro servicio puede consumirlos sin cambios en el monolito
Solo lo consumen módulos de la misma aplicaciónNoUn evento interno es más simple, más rápido y se refactoriza con el compilador
Necesitas una respuesta del otro sistemaNoEso es una llamada (HTTP, gRPC), no un evento

Conclusión

@Externalized simplifica la publicación en un broker, pero su valor arquitectónico está en separar la aceptación del pedido del intento de entrega al exterior. En la prueba documentada, un broker caído no impidió crear el pedido: la publicación falló, quedó registrada y se recuperó al reiniciar. Eso demuestra el comportamiento del ejemplo, no una garantía absoluta frente a cualquier modo de fallo.

Con el contexto pasa algo parecido: antes de registrar un decorator propio, inspecciona qué executor y qué mecanismo de propagación usa la aplicación. En esta configuración, el decorator propio no llegó a ejecutarse y registrar el accessor del traceId resolvió la parte que faltaba. En los dos casos merece la pena probar los escenarios de fallo y no quedarse en el camino feliz.

En el siguiente artículo de la serie, la IA entra en el monolito como un módulo más: Spring AI detrás de una interfaz, Ollama en local u OpenRouter en la nube, qué pasa cuando el modelo se cae y cómo probar cada módulo por separado.

Fuentes técnicas

Preguntas frecuentes

¿@Externalized solo funciona con Kafka?

No. Spring Modulith 2.1 incluye integraciones para Kafka, AMQP (RabbitMQ), JMS y Spring Messaging. Para Amazon SNS y SQS, la integración la ofrece Spring Cloud AWS con sus propios módulos (spring-cloud-aws-modulith-events-sns y spring-cloud-aws-modulith-events-sqs). En Kafka, el destino de la anotación es el topic.

¿El evento sigue llegando a los listeners internos?

Sí. Externalizar añade un destino; no quita ninguno. En el proyecto, OrderCompleted lo siguen escuchando inventory y notification, y además sale a Kafka.

¿Se reintenta el envío mientras el broker sigue caído?

No de forma continua. La publicación queda FAILED tras el timeout del productor y se reenvía al reiniciar, si está activa republish-outstanding-events-on-restart, o cuando lo pidas con la API IncompleteEventPublications, por ejemplo desde una tarea programada.

¿Puedo externalizar solo algunos eventos de un tipo?

Sí. Spring Modulith permite configurar la externalización por código con EventExternalizationConfiguration, incluido qué eventos se envían y cómo se calcula el destino. @Externalized es la forma declarativa para el caso habitual.

¿Tengo que usar spring-modulith-observability-core para que llegue el usuario?

No es obligatorio. Sin esa dependencia, en el caso B del experimento el executor no tenía decorator y el contexto se perdía. Puedes configurar tú un ContextPropagatingTaskDecorator, o el mecanismo que corresponda a tu executor; antes, comprueba qué configura de verdad tu versión de Spring y qué ThreadLocalAccessor necesitas.

¿Y si uso hilos virtuales?

El problema de fondo es el mismo: un ThreadLocal pertenece a un hilo, sea de plataforma o virtual. En la 2.1.1, la autoconfiguración de observabilidad de Spring Modulith decora también el SimpleAsyncTaskExecutor, que es el que usa Spring Boot con hilos virtuales; el ejemplo, en cualquier caso, solo se ha probado con el pool de hilos de plataforma.

¿Por qué Redpanda y no Kafka?

Por comodidad en un proyecto de ejemplo: el broker es un solo contenedor y arranca en segundos; el docker-compose añade Redpanda Console en otro contenedor. Redpanda habla el protocolo de Kafka, así que el código de la aplicación y la configuración de Spring Kafka del ejemplo no cambian.

  • Leer artículo
    Arquitectura de software21 min

    Eventos en Spring Modulith: listeners, reintentos y fiabilidad

  • Leer artículo
    Arquitectura de software19 min

    Spring Modulith: módulos con fronteras verificadas en un monolito Spring Boot

  • Leer artículo
    Desarrollo con IA15 min

    Tool Calling con Spring AI: cómo conectar un LLM con tu backend Java

Ver todos los artículos