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

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
- Enviar a Kafka dentro de la transacción
- Externalizar un evento con @Externalized
- Flujo: pedido, registro y Kafka
- Qué pasa si Kafka está caído
- Probarlo con Testcontainers
- El evento ya es un contrato público
- El usuario se pierde al cambiar de hilo
- El experimento del TaskDecorator
- El ContextRegistry
- Llevarlo a producción
- Errores habituales
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:
@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);
}| Problema | Qué pasa |
|---|---|
| Doble escritura | Si 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 llamada | Aunque 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 gestionados | Si 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:
// 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.
<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
# 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:19092El 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:
{
"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:
- RespuestaSalidaHTTP 201 Created
- Listeners internosPasoinventory y notificationEn otro hilo, cada uno en su transacciónDatosSu publicación pasa a COMPLETED
- ExternalizadorHerramientaKafka / RedpandaTopic de pedidos completadosCondició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.
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.
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 | 1Tres 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.
POST /orders → HTTP/1.1 201 en 0.30 s · pedido 47 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 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. 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:
@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:
# No broker in most tests; ExternalizationTests re-enables it with Testcontainers
spring.modulith.events.externalization.enabled=falseEl 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.
| Cambio en el record | Consumidores internos | Consumidores del topic |
|---|---|---|
| Añadir un campo | Sin impacto | Normalmente sin impacto, si toleran campos desconocidos |
| Renombrar un campo | El compilador avisa | Puede romper el mapeo o perder información sin aviso |
| Quitar un campo | El compilador avisa | Puede romper el consumidor, según cómo trate los campos ausentes |
| Mover o renombrar la clase | El IDE lo arregla | Cambia 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:
@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);
}$ 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 = aliceEl 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.
@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:
| Caso | Decorator del executor | ¿Se ejecuta el propio? | Usuario y traceId en el listener |
|---|---|---|---|
| A · con spring-modulith-observability-core y TaskDecorator propio | ContextPropagatingTaskDecorator | No (0 ejecuciones) | Llegan alice y el traceId |
| B · sin spring-modulith-observability-core | Ninguno | No aplica | Se pierden |
| C · sin observability y con TaskDecorator propio | El propio | Sí | Se pierden (el del experimento no copiaba nada) |
Salida de la sonda
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 alicePROBE 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:
/**
* 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:
@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:
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 leftDos 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:
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
| Error | Consecuencia | Qué hacer |
|---|---|---|
| kafkaTemplate.send dentro del @Transactional | Doble escritura y fallos en cascada | @Externalized y el Event Publication Registry |
| JsonSerializer en el productor | El evento se serializa dos veces | ByteArraySerializer: Spring Modulith ya entrega JSON |
| max.block.ms por defecto con un broker inestable | Cada externalización bloquea un hilo de listeners hasta 60 s | Ajustarlo, dimensionar o aislar el executor y monitorizar las publicaciones FAILED |
| Consumidores del topic no idempotentes | Efectos duplicados tras un reenvío | Deduplicar con un eventId estable o una clave de negocio inequívoca |
| Renombrar campos de un evento externalizado | Consumidores externos rotos sin aviso | Tratar el evento como una API pública versionada |
| Registrar un TaskDecorator propio con spring-modulith-observability-core | En la configuración probada no se ejecuta, y nadie avisa | Comprobar el decorator efectivo y registrar en el ContextRegistry lo que falte |
| Leer el usuario del SecurityContext en un listener | Vacío en las publicaciones reenviadas | Llevar el dato en el evento |
| Restaurar el contexto sin limpiarlo | Un hilo del pool hereda el usuario de otra petición | Limpiar siempre, o usar el decorator de Spring |
Cuándo externalizar un evento
| Situación | ¿Externalizar? | Por qué |
|---|---|---|
| Otro sistema (analítica, un data warehouse, otro servicio) necesita enterarse de lo que pasa en el monolito | Sí | Es justo el caso para el que existe |
| Preparas la extracción de un módulo | Sí | 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ón | No | Un evento interno es más simple, más rápido y se refactoriza con el compilador |
| Necesitas una respuesta del otro sistema | No | Eso 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
- Spring Modulith — Working with Application Events (registro, externalización y alternativas Outbox)
- Spring Modulith — Production-ready Features (observabilidad)
- Micrometer Context Propagation
- Spring Security — Concurrency Support
- Testcontainers — Redpanda module
- Spring Cloud AWS 4.1.1 — Spring Modulith integration (SNS y SQS)
- Repositorio del ejemplo: Datiacode-Tech/spring-modulith-shop, tag blog-3-externalizacion
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.
Sigue leyendo
Ver todos los artículos- Leer artículo
Arquitectura de software · JavaArquitectura de software21 minEventos en Spring Modulith: listeners, reintentos y fiabilidad
- Leer artículo
Arquitectura de software · JavaArquitectura de software19 minSpring Modulith: módulos con fronteras verificadas en un monolito Spring Boot
- Leer artículo
Desarrollo con IA · JavaDesarrollo con IA15 minTool Calling con Spring AI: cómo conectar un LLM con tu backend Java
