Understanding the Reactive Foundation
Discover why Spring Cloud Gateway is built on a non-blocking reactive stack and what that means for how requests flow through the gateway.
Understanding the Reactive Foundation is a free API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway) lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway) learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
A Different Kind of Server
Unlike a traditional Spring MVC app, Spring Cloud Gateway runs on Spring WebFlux and Project Reactor. It uses a non-blocking, event-loop server (Netty) instead of one thread per request.
This design lets the gateway handle thousands of concurrent connections with very few threads.
Blocking vs Non-Blocking
In a blocking model, a thread waits idle while a backend responds. In a non-blocking model, the thread is freed and notified later when data is ready.
- Blocking: 1 thread tied up per in-flight request
- Non-blocking: a handful of threads serve many requests
Mono and Flux
Reactor's core types describe asynchronous results:
Mono<T>emits 0 or 1 valueFlux<T>emits 0 to many values
The gateway returns a Mono<Void> when a request finishes processing.
Mono<String> name = Mono.just("gateway");
Flux<Integer> nums = Flux.just(1, 2, 3);Nothing Happens Until Subscribe
Reactive streams are lazy. A Mono or Flux does nothing until something subscribes. In the gateway, the framework subscribes for you when a request arrives.
Mono<String> greeting = Mono.fromSupplier(() -> "hello");
// runs only when subscribed:
greeting.subscribe(System.out::println);The Reactive Web Stack
The starter spring-cloud-starter-gateway pulls in WebFlux automatically. You must not add spring-boot-starter-web (the servlet/MVC stack) or startup will fail with a conflict.
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>The ServerWebExchange
Every request is wrapped in a ServerWebExchange, which holds the request and response. Filters read and mutate this exchange as the request flows through.
// inside a filter
ServerHttpRequest request = exchange.getRequest();
String path = request.getURI().getPath();The Filter Chain
A request passes through an ordered chain. Each filter can act, then call chain.filter(exchange) to continue, and run more logic after the downstream response returns.
return chain.filter(exchange)
.then(Mono.fromRunnable(() ->
System.out.println("response sent")));Why Reactive Fits a Gateway
A gateway spends most of its time waiting on the network for upstream services. Non-blocking I/O is ideal here: threads are not wasted waiting, so the gateway stays responsive under heavy load.
Avoid Blocking Calls
Calling a blocking JDBC driver or Thread.sleep inside a filter stalls the event loop and hurts every request. If you must block, offload to a bounded scheduler.
Mono.fromCallable(() -> blockingLookup())
.subscribeOn(Schedulers.boundedElastic());Operators Transform Streams
Operators like map, flatMap, and filter reshape the data flowing through a stream without blocking.
Flux.just(1, 2, 3, 4)
.filter(n -> n % 2 == 0)
.map(n -> n * 10)
.subscribe(System.out::println); // 20, 40Mental Model
Think of the gateway as a pipeline of asynchronous steps. A request enters, flows through predicates and filters, is forwarded reactively, and the response streams back through the same chain in reverse.
Quick Check
What underlying web stack does Spring Cloud Gateway run on?
Recap
You now understand the reactive foundation of the gateway:
- Non-blocking I/O on Netty handles high concurrency
MonoandFluxmodel async results and are lazy- Each request is a
ServerWebExchangeflowing through a filter chain - Never block the event loop
This mindset underpins routes, predicates, and filters you build next.
Frequently asked questions
Is the “Understanding the Reactive Foundation” lesson free?
Yes — the full text of “Understanding the Reactive Foundation” is free to read here on the web, and the API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway) course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway) course, upgrade to CoddyKit PRO.
What will I learn in “Understanding the Reactive Foundation”?
Discover why Spring Cloud Gateway is built on a non-blocking reactive stack and what that means for how requests flow through the gateway. You practise API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway) with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway)?
No prior experience is required. API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway) on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Understanding the Reactive Foundation” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway) lesson?
Yes. Every API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway) lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Gateway vs. Traditional Microservices
- Setting Up a Basic Gateway Project
- Defining Routes & Predicates
- Understanding the Reactive Foundation