java 52 lines · 9 steps

How an idempotency aspect works in Spring

A Spring AOP aspect caches responses by Idempotency-Key so retried requests replay the same result instead of running twice.

Explained by highlit

Spring Advanced aop idempotency caching concurrency http

1@Aspect
2@Component
3public class IdempotencyAspect {
4 
  private static final String CACHE_NAME = "idempotencyKeys";
6 
  private final CacheManager cacheManager;
  private final HttpServletRequest request;
  private final ObjectMapper objectMapper;
10 
  public IdempotencyAspect(CacheManager cacheManager,
                           HttpServletRequest request,
                           ObjectMapper objectMapper) {
      this.cacheManager = cacheManager;
      this.request = request;
      this.objectMapper = objectMapper;
  }
18 
  @Around("@annotation(idempotent)")
  public Object enforce(ProceedingJoinPoint pjp, Idempotent idempotent) throws Throwable {
      String key = request.getHeader("Idempotency-Key");
      if (key == null || key.isBlank()) {
          throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Missing Idempotency-Key header");
      }
25 
      Cache cache = cacheManager.getCache(CACHE_NAME);
      String cacheKey = idempotent.scope() + ":" + key;
28 
      Cache.ValueWrapper cached = cache.get(cacheKey);
      if (cached != null) {
          CachedResponse stored = objectMapper.convertValue(cached.get(), CachedResponse.class);
          return ResponseEntity
                  .status(stored.status())
                  .header("Idempotent-Replayed", "true")
                  .body(stored.body());
      }
37 
      if (cache.putIfAbsent(cacheKey, CachedResponse.pending()) != null) {
          throw new ResponseStatusException(HttpStatus.CONFLICT, "Request with this key is already in progress");
      }
41 
      try {
          Object result = pjp.proceed();
          ResponseEntity<?> response = (ResponseEntity<?>) result;
          cache.put(cacheKey, new CachedResponse(response.getStatusCode().value(), response.getBody()));
          return result;
      } catch (Throwable ex) {
          cache.evict(cacheKey);
          throw ex;
      }
  }
52}

01 / 01

STEP 01

Walkthrough

Space play ←→ step click any line

Three takeaways

1Idempotency keys let clients safely retry requests without triggering duplicate side effects.
2A pending-marker written with putIfAbsent turns a cache into a concurrency guard against in-flight duplicates.
3Evicting the key on failure keeps failed attempts retryable rather than permanently cached.

Related explainers

java

@Component
@Converter
public class EncryptedStringConverter implements AttributeConverter<String, String> {

Transparent column encryption in Spring & JPA

encryption aes-gcm jpa-converter

Advanced 10 steps

java

package com.acme.billing.config;
 
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.ConfigurationProperties;

Feature-flagged beans with Spring @ConditionalOnProperty

feature-flags conditional-beans strategy-pattern

Intermediate 5 steps

javascript

import { useState, useEffect, useCallback, useRef } from 'react';
 
const cache = new Map();
const inflight = new Map();

Building a stale-while-revalidate hook in React

caching request-deduplication custom-hooks

Advanced 10 steps

func (w *Watcher) resetDebounce(d time.Duration) {
	if !w.timer.Stop() {
		select {
		case <-w.timer.C:

Debouncing a stream of events in Go

debounce timers channels

Advanced 7 steps

php

<?php
 
namespace App\Services;

Building a cached daily leaderboard in Laravel

caching aggregation eager-loading

Intermediate 9 steps

java

public static Map<String, String> parseCookieHeader(String header) {
    Map<String, String> cookies = new LinkedHashMap<>();
    if (header == null || header.isBlank()) {
        return cookies;