Cloud Native 5 min read

Understanding Spring Cloud Gateway: Architecture, Core Concepts, and Configuration

This article provides a detailed technical overview of Spring Cloud Gateway, covering its role as a second‑generation API gateway built on Spring 5, WebFlux, and Reactor, its core responsibilities, architectural placement, key concepts like routes, predicates and filters, the request processing flow, and a concrete YAML configuration example.

Architect Chen

Apr 22, 2026

Understanding Spring Cloud Gateway: Architecture, Core Concepts, and Configuration

What is Spring Cloud Gateway?

Spring Cloud Gateway is the second‑generation gateway in the Spring Cloud ecosystem, built on Spring 5, Spring WebFlux, and Reactor (reactive programming). It is designed to replace the earlier Netflix Zuul.

Core Responsibilities

Routing (forwarding requests to target services)

Authentication & Authorization

Rate limiting & circuit breaking

Logging and monitoring

Protocol conversion (HTTP / WebSocket)

These responsibilities give the gateway three typical values: a unified entry point, unified governance, and unified extensibility.

Architecture Overview

In a microservice architecture, the gateway sits between clients and microservices, acting as the single entry for all traffic.

Spring Cloud Gateway architecture diagram

Key Concepts

The gateway revolves around three core concepts:

Route : The basic module defined by an ID, a target URI, a set of predicates, and a set of filters. A route matches when its predicates evaluate to true.

Predicate : A Java 8 Predicate<ServerWebExchange> that can inspect any part of an HTTP request, such as headers or query parameters.

Filter : An instance of GatewayFilter that can modify the request or response before (Pre) or after (Post) the request is proxied downstream.

Working Principle

Spring Cloud Gateway functions as an API gateway: it receives client requests, forwards them to backend microservices, and performs unified processing before and after the forward.

Request Processing Flow

Gateway client sends a request to the gateway.

Gateway Handler Mapping checks whether the request matches a defined route.

If a match is found, the request is handed to the Gateway Web Handler.

The handler invokes a filter chain (Filter Chain) to forward the request to the proxied service.

The filter chain is split by a dashed line because filters can run either before the proxy request (Pre) or after it (Post).

Pre‑logic examples: parameter validation, authentication, traffic monitoring, protocol conversion.

Post‑logic examples: response‑header modification, logging, latency statistics.

Configuration Example

spring:
  cloud:
    gateway:
      routes:
        - id: user
          uri: http://localhost:8081
          predicates:
            - Path=/user/**
          filters:
            - StripPrefix=1
            - order=route
        - id: order
          uri: http://localhost:8082
          predicates:
            - Path=/order/**

This YAML snippet defines two routes (user and order), each with its own URI, path predicate, and filter chain (e.g., StripPrefix=1 to remove the first path segment).