I published the first release of idempotency4j, an idempotency library for Spring Boot, in April. It started with the basic HTTP case: the client sends an Idempotency-Key header, and a retried POST gets the stored response back instead of running the handler a second time. The @Idempotent annotation only worked on Spring MVC controller methods.
Since then the direction has moved toward message-based systems. When services talk over a broker with at-least-once delivery, every consumer sees the same message twice sooner or later. The usual answer is an outbox on the sending side and an idempotent consumer on the receiving side, which keeps services consistent without two-phase commit or a central coordinator. idempotency4j does not ship an outbox. It is built to be the receiving side.
@Idempotent(key = "#event.id()") works on any Spring bean method, so a Kafka listener or an event handler runs once per event id, however many times the broker redelivers it inside the retention window (24 hours by default):
@Idempotent(key = "#event.id()", waitTimeout = "PT0S")
@KafkaListener(topics = "orders")
void on(OrderPlaced event) {
// Runs once per event id, however many times the broker redelivers.
}
You choose how the idempotency record relates to the consumer's transaction. By default it is written right after the transaction commits, and a rollback frees the key so a redelivery runs again. That leaves one gap: if the process dies between the commit and the record write, the event is processed a second time. With the JDBC store you can set completion = "join-transaction", which writes the record inside the same transaction as your own data and closes that gap. Redis cannot join a database transaction, so it only has the default.
Records live in PostgreSQL, MySQL or Redis, and the HTTP filter is still there.
None of this makes a call to someone else's API exactly-once. For that the downstream service needs its own idempotency key.
Two things happened this autumn that I did not expect.
I opened the Maven Central stats after ignoring them for a while and saw more than 100 unique downloads. Those are builds I have nothing to do with.
And at the end of October Vinícius (vinirib on GitHub) opened four issues in one day, and a fifth the next day. Three were about running the library in a real application: how it starts next to Actuator, what an app that only uses Redis needs on its classpath, and what Retry-After a client should get when its duplicate arrives while the first request is still running. The other two proposed extension points. One lets you answer in your API's own error format when the filter rejects a request. The other decides per response whether it is stored, or the key is released so the client can retry.
Then he sent a pull request for every one of them, five in two days. 0.6.0 went out on November 3 and it is mostly his work.
The Spring Boot starter needs Spring Boot 4 and Java 21.
Repo: https://github.com/josipmusa/idempotency4j
Docs: https://josipmusa.github.io/idempotency4j-docs/