Spring Kafka record keys: preserve per-SKU order without claiming global order

Last updated: 1 Oct 20264 min read

tutorial

A stable record key gives a producer a consistent partitioning input; ordering is a property of records within one partition, not of the whole topic.

Download Spring source kit

Key by the state that must stay ordered

The publisher sends a stock reservation with SKU-47 as its key. The listener rejects a record whose key names a different SKU than the payload. That check catches one category of routing corruption before a database write. It does not prove that every same-SKU record will remain in the same partition forever: changing partition counts or partitioner configuration can change placement. The source-kit test checks the method argument and rejection path, not broker partition assignment.

A tenant-scoped stock table should use a tenant-aware key or an explicit ordering design; two tenants may both use SKU-47. Choose the key from the domain aggregate whose concurrent operations must serialize, then record the partitioning contract in the producer and consumer tests. A conditional versioned write is still needed if multiple workers can race in the database.

Plan for throughput and skew

One extremely busy SKU can become a hot partition. More consumers in the same group do not split one partition's ordered stream across those consumers. If the application needs higher throughput, decide whether the aggregate can be subdivided without losing its invariant; do not quietly randomize keys and hope the database repairs ordering. Deduplication handles repeats, not the semantic order of two different updates.

Code boundary

CompletableFuture<SendResult<String, StockReservation>> publish(
        StockReservation reservation) {
    return operations.send("stock-reservations", reservation.sku(), reservation);
}

Verification boundary

The Java 21 / Spring Boot 4 source kit checks publisherUsesSkuAsPartitionKeyAndReturnsSendCompletion and mismatchedKeyIsRejectedBeforeDatabaseWork.

Cost and limits

A hot key limits parallel work for that aggregate and can raise consumer lag. The local fixture has no broker or partitioner, so actual partition placement, reassignment and ordering under retries remain integration-test work.

Common Mistakes

Do not describe partition order as global topic order.
Do not choose a random key for operations that require per-aggregate sequencing.
Do not assume a stable key survives partition-count changes with identical placement.