Skip to content
Tutorials Center
My learning

Topics

Lesson 38 of 38 ยท Projects and Practice

Project: Event-Driven Order Processing

Design an order pipeline in Micronaut with application events, Kafka messaging, idempotent consumers, retries and a dead-letter queue, with a runnable Java event-bus stand-in.

The third project connects services without them calling each other directly. When a customer places an order, the order service publishes an event (OrderPlaced). The inventory, billing and email services each react on their own. This makes the system easier to extend (add a new listener without touching the order service) and more resilient (if email is down, orders are still accepted).

The real Kafka integration is not available on this site, so the Micronaut code is read-only. The runnable stand-ins implement an event bus, an idempotent consumer and a dead-letter queue in plain Java, so you can experiment with the hard parts: duplicates, failures and ordering.

The flow

Order pipeline

Order placed Order service saves and publishes an event.
Inventory Reserves stock, publishes StockReserved.
1 / 2
flowchart LR
    A["Order service"] -->|OrderPlaced| B(("orders topic"))
    B --> C["Inventory"]
    B --> D["Email"]
    C -->|StockReserved| E(("stock topic"))
    E --> F["Billing"]
    F -.->|failures| G["dead-letter topic"]

One event, several independent consumers.

In-process events

Inside one application Micronaut has a simple event system. Publish with ApplicationEventPublisher and listen with @EventListener:

Java
@Singleton
class OrderService {
    private final ApplicationEventPublisher<OrderPlaced> publisher;
    OrderService(ApplicationEventPublisher<OrderPlaced> publisher) { this.publisher = publisher; }

    Order place(Cart cart) {
        Order order = save(cart);
        publisher.publishEvent(new OrderPlaced(order.id(), order.total()));
        return order;
    }
}

@Singleton
class AuditListener {
    @EventListener
    @Async                      // do not block the publisher
    void onOrder(OrderPlaced event) { /* write an audit record */ }
}

Messaging between services with Kafka

Across services use a broker. With Micronaut Kafka you declare producers and consumers as annotated interfaces and classes:

GROOVY
implementation("io.micronaut.kafka:micronaut-kafka")
YAML
kafka:
  bootstrap:
    servers: "${KAFKA_SERVERS:localhost:9092}"
Java
@KafkaClient
interface OrderEvents {
    @Topic("orders")
    void send(@KafkaKey String orderId, OrderPlaced event);
}

@KafkaListener(groupId = "inventory", offsetReset = OffsetReset.EARLIEST)
class OrderConsumer {
    @Topic("orders")
    void receive(@KafkaKey String orderId, OrderPlaced event) {
        inventory.reserve(event);
    }
}

Messages with the same key go to the same partition, so events of one order stay in order. Each consumer group receives every message once, spread over its instances. RabbitMQ, NATS, JMS, SQS and MQTT modules follow the same style.

The hard parts

At-least-once delivery. Brokers prefer to deliver a message twice rather than lose it. So a consumer can see the same event again (after a crash, a rebalance or a retry). Your handler must be idempotent: processing twice has the same effect as processing once. A common technique is to store the processed event ids (or use a unique constraint) and skip duplicates.

Failures. If a message always fails (bad data), retrying forever blocks the queue. After a few attempts send it to a dead-letter topic for people to inspect, and move on.

Consistency. Saving the order and publishing the event are two operations; one may succeed and the other fail. The transactional outbox pattern writes the event into an outbox table in the same database transaction as the order, and a separate process publishes outbox rows to the broker. That guarantees an event is published if and only if the order was committed.

Try it: an event bus with an idempotent consumer

Java Events, duplicates and idempotency

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Try it: retries and a dead-letter queue

Java Retry then dead-letter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Try it: the transactional outbox

Java Outbox pattern

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Testing event flows

Use Micronaut Test Resources to start a Kafka container, as described in Mocking and Test Resources, publish an event with the client and use Awaitility to wait until the consumer has produced its effect. Test the duplicate-delivery case explicitly. Trace ids carried in message headers connect the spans, see Metrics, Health and Tracing.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why must consumers be idempotent?

    At-least-once delivery means duplicates can happen after crashes or retries.
  2. 2. What is a dead-letter queue for?

    After a few failed attempts the poison message is parked for inspection.
  3. 3. What problem does the transactional outbox solve?

    The event row is written in the same transaction as the data, and a relay publishes it afterwards.
  4. 4. Why do messages for one order use the same key?

    Kafka preserves order within a partition, and the key decides the partition.

Summary

  • Events decouple services: publishers do not know their listeners.
  • Use @EventListener inside one app and Kafka (or another broker) between services.
  • Design for duplicates, failures and partial commits: idempotent consumers, retries, dead-letter queues and the outbox pattern.
  • Test with real brokers through test resources, including duplicate delivery.

Next: Practice: Questions and Exercises