Spring WebFlux is Spring’s reactive web framework built on Project Reactor and Netty. It handles I/O-bound concurrency with a small number of threads — UUID v7 generation is a non-blocking CPU operation that fits naturally into reactive pipelines. See UUID in Java and Spring Boot for the blocking Spring MVC equivalent.

Dependency setup

<!-- Maven -->
<dependency>
  <groupId>com.github.f4b6a3</groupId>
  <artifactId>uuid-creator</artifactId>
  <version>6.0.0</version>
</dependency>
// Gradle (Kotlin DSL)
implementation("com.github.f4b6a3:uuid-creator:6.0.0")

WebFilter: UUID v7 trace ID per request

import com.github.f4b6a3.uuid.UuidCreator;
import org.springframework.web.server.ServerWebExchange;
import org.springframework.web.server.WebFilter;
import org.springframework.web.server.WebFilterChain;
import reactor.core.publisher.Mono;

@Component
public class TraceIdFilter implements WebFilter {

    private static final String TRACE_ID_HEADER = "x-trace-id";

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
        String traceId = exchange.getRequest().getHeaders()
            .getFirst(TRACE_ID_HEADER);

        if (traceId == null) {
            traceId = UuidCreator.getTimeOrderedEpoch().toString(); // UUID v7
        }

        final String finalTraceId = traceId;

        return chain.filter(exchange)
            .contextWrite(ctx -> ctx.put("traceId", finalTraceId))
            .doOnSubscribe(s ->
                exchange.getResponse().getHeaders().set(TRACE_ID_HEADER, finalTraceId)
            );
    }
}

R2DBC entity with UUID v7 primary key

import com.github.f4b6a3.uuid.UuidCreator;
import org.springframework.data.annotation.Id;
import org.springframework.data.relational.core.mapping.Table;
import java.util.UUID;

@Table("orders")
public record Order(
    @Id UUID id,
    String customerId,
    java.math.BigDecimal total
) {
    public static Order create(String customerId, java.math.BigDecimal total) {
        return new Order(UuidCreator.getTimeOrderedEpoch(), customerId, total);
    }
}
// Reactive repository
public interface OrderRepository extends ReactiveCrudRepository<Order, UUID> {
    // Spring Data R2DBC maps uuid PostgreSQL column ↔ java.util.UUID
    Flux<Order> findAllByOrderById();
}

Reactive service with UUID v7

@Service
public class OrderService {

    private final OrderRepository repo;

    public OrderService(OrderRepository repo) {
        this.repo = repo;
    }

    public Mono<Order> createOrder(String customerId, BigDecimal total) {
        return repo.save(Order.create(customerId, total));
        // UUID v7 set in Order.create() — non-blocking, no thread switch needed
    }

    public Flux<Order> listOrders(UUID cursor, int limit) {
        if (cursor == null) {
            return repo.findAllByOrderById().take(limit);
        }
        // Cursor pagination using UUID v7
        return repo.findAllByOrderById()
            .skipUntil(o -> o.id().compareTo(cursor) > 0)
            .take(limit);
    }
}

WebClient propagating UUID v7 trace IDs

@Service
public class PaymentClient {

    private final WebClient webClient;

    public PaymentClient(WebClient.Builder builder) {
        this.webClient = builder.baseUrl("https://payments.internal").build();
    }

    public Mono<PaymentResult> charge(UUID orderId, BigDecimal amount) {
        return Mono.deferContextual(ctx -> {
            String traceId = ctx.getOrDefault("traceId", "unknown");

            return webClient.post()
                .uri("/charges")
                .header("x-trace-id", traceId)       // propagate UUID v7 trace
                .header("x-idempotency-key", orderId.toString()) // UUID v7 order ID as idempotency key
                .bodyValue(new ChargeRequest(orderId, amount))
                .retrieve()
                .bodyToMono(PaymentResult.class);
        });
    }
}

UUID v7 order IDs double as idempotency keys for downstream payment APIs. See UUID as Idempotency Keys.

Further reading

External references

Frequently asked questions

How do I generate UUID v7 in Spring WebFlux?

Add the uuid-creator dependency to your Maven or Gradle project and call UuidCreator.getTimeOrderedEpoch() for UUID v7. UUID generation is non-blocking (no I/O), so it is safe to call directly in a reactive pipeline. See UUID in Java and Spring Boot.

How do I propagate a UUID v7 trace ID through a reactive chain in WebFlux?

Use Reactor's Context API: attach the UUID v7 trace ID to the subscription context with contextWrite(ctx -> ctx.put("traceId", traceId)) and read it with Mono.deferContextual(ctx -> ...). This avoids ThreadLocal which does not work across reactive thread hops. See UUID v7 in Microservices.

How do I use UUID v7 with R2DBC in Spring WebFlux?

R2DBC supports the java.util.UUID type natively for PostgreSQL (r2dbc-postgresql). Annotate your entity's @Id field with UUID type and set it in a @BeforeSave event listener or in the service layer with UuidCreator.getTimeOrderedEpoch(). Spring Data R2DBC maps the uuid PostgreSQL column type to java.util.UUID automatically.