Spring Cloud Gateway: Cổng API Của Bạn Đi Vào Hoạt Động | Java Spring Roadmap

Spring Cloud Gateway là điểm vào duy nhất cho request từ client: định tuyến theo path, host hay header, xác thực token ở biên, giới hạn tốc độ và thêm header trước khi chuyển tiếp. Nhưng nếu biến nó thành nơi xử lý nghiệp vụ, gọi database hay chạy lời gọi blocking trên event loop, chính nó sẽ sập trước và kéo cả hệ thống theo.

Bài này đi qua mô hình đúng, một application.yml chạy được với ba route, một GlobalFilter thêm correlation ID, rate limit bằng Redis và các bẫy vận hành thật.

Cập nhật 2026

  • Gateway 5.0.4 trong train 2025.1.4 (“Oakwood”), chạy với Spring Boot 4.1.2. Bản 5.1.0-RC2 và train 2026.0.0-RC2 là preview, chưa GA.
  • Starter tách theo server: spring-cloud-starter-gateway-server-webflux với prefix spring.cloud.gateway.server.webflux.*; spring-cloud-starter-gateway-server-webmvc với spring.cloud.gateway.server.webmvc.*. Config cũ spring.cloud.gateway.routes không còn bind.
  • Filter thực dụng hơn: Retry có backoff, jitter, timeout; RequestRateLimiter chạy với Redis hoặc Bucket4j.
  • Hystrix và Sleuth không còn: circuit breaker qua Spring Cloud Circuit Breaker 5.0.3 + Resilience4j 2.4.0, tracing qua Micrometer Tracing 1.7.2.

API gateway làm gì, và không làm gì

Gateway là reverse proxy có logic: nhận request, chọn route khớp, chạy filter, gọi service đích, rồi chạy filter ngược lại trước khi trả response. Giá trị nằm ở chỗ những việc sau chỉ làm một lần thay vì lặp trong mười service:

  • Routing: map /api/orders/** sang order-service, bất kể client gọi host nào.
  • Cross-cutting: xác thực, CORS, log, correlation ID, chuẩn hóa lỗi, retry, circuit breaker, rate limit.
  • Auth offload: kiểm tra chữ ký, thời hạn, issuer một lần; không thay service quyết định quyền trên tài nguyên.
  • Rate limiting: chặn theo API key, user hoặc IP trước khi request chạm tới service.
  • Protocol translation: có JsonToGrpc cho một số luồng HTTP sang gRPC và kết thúc TLS, nhưng vẫn là proxy HTTP, không phải ESB.

Đừng để gateway chứa business rule, truy cập database hay thay service mesh. Nó là biên logic, không phải trung tâm dữ liệu.

WebFlux server hay MVC server?

Gateway 5 có hai implementation riêng. WebFlux server chạy Netty, xử lý Mono/Flux, hợp khi giữ nhiều kết nối đồng thời hoặc backend đã reactive. MVC server chạy servlet stack, dùng functional routing của Spring MVC, hợp với đội đã sống trong MVC và thư viện blocking khó thay.

Predicate, filter và prefix của hai bên là hai bộ API khác nhau. Không copy route MVC sang WebFlux, cũng không đặt cả hai starter trong một ứng dụng. Chọn theo stack và tính chất tải, không theo benchmark mạng.

Cấu trúc một route

Route gồm id, uri đích, predicate, filter và order. Predicate quyết định route có khớp; filter biến đổi request và response. Route khớp đầu tiên thắng.

Predicate Khớp khi Ví dụ
Path PathPattern của request khớp mẫu Path=/api/orders/**
Method HTTP method nằm trong danh sách Method=GET,POST
Header Header có mặt hoặc giá trị khớp regex Header=X-Request-Id, \d+
Host Hostname khớp mẫu Host=api.evotek.vn
Query Query param có mặt hoặc khớp giá trị Query=page,1
Filter Làm gì Ví dụ
StripPrefix Bỏ N đoạn đầu của path StripPrefix=1
PrefixPath Thêm prefix vào path PrefixPath=/orders
RewritePath Thay path bằng regex có named group RewritePath=/api/public/(?<segment>.*), /content/${segment}
AddRequestHeader Thêm header vào request gửi đi AddRequestHeader=X-Gateway-Source, evotek-gateway
Retry Thử lại theo status, method, backoff Retry=2,BAD_GATEWAY,GET
CircuitBreaker Bọc route bằng circuit breaker, có fallback CircuitBreaker=ordersCb
RequestRateLimiter Giới hạn theo key, cần Redis hoặc Bucket4j named args, xem mục dưới
SetStatus Ép status trả về client SetStatus=503

Với filter nhiều tham số, dùng name + args; shortcut chỉ tiện cho StripPrefix=1 hay SetStatus=503. Thứ tự filter có ý nghĩa: StripPrefix chạy trước RewritePath làm regex không còn khớp path ban đầu. Default filters đặt dưới spring.cloud.gateway.server.webflux.default-filters; global CORS dưới globalcors.cors-configurations, bật add-to-simple-url-handler-mapping nếu cần preflight OPTIONS.

Application.yml chạy được với ba route

Ví dụ giả định có discovery và LoadBalancer trên classpath. Không có Eureka hay Consul, đổi lb://order-service thành http://localhost:8081 và tương tự cho hai service còn lại.

# File: src/main/resources/application.yml
spring:
  application:
    name: api-gateway
  cloud:
    gateway:
      server:
        webflux:
          default-filters:
            - AddResponseHeader=X-Gateway, evotek
          globalcors:
            cors-configurations:
              '[/**]':
                allowedOrigins: "https://app.evotek.vn"
                allowedMethods:
                  - GET
                  - POST
                allowedHeaders:
                  - Authorization
                  - Content-Type
                  - X-Correlation-Id
                maxAge: 3600
          routes:
            - id: orders
              uri: lb://order-service
              predicates:
                - Path=/api/orders/**
                - Method=GET,POST
              filters:
                - StripPrefix=1
                - name: Retry
                  args:
                    retries: 2
                    methods: GET
                    statuses: BAD_GATEWAY
                    backoff:
                      firstBackoff: 20ms
                      maxBackoff: 200ms
                      factor: 2
                      basedOnPreviousValue: false
            - id: users
              uri: lb://user-service
              predicates:
                - Path=/api/users/**
                - Method=GET
              filters:
                - StripPrefix=1
                - AddRequestHeader=X-Gateway-Source, evotek-gateway
            - id: public-content
              uri: lb://content-service
              predicates:
                - Path=/api/public/**
                - Method=GET
              filters:
                - RewritePath=/api/public/(?<segment>.*), /content/${segment}

Ba route cố ý khác nhau: orders bỏ /api, users bỏ /api và thêm header nguồn, public-content rewrite toàn bộ /api/public thành /content. Đặt cả StripPrefix=1 lẫn RewritePath trên route thứ ba sẽ cắt path trước khi regex chạy và nhận 404. Retry chỉ thử lại GET với BAD_GATEWAY; đừng retry POST tạo đơn hàng nếu downstream không có idempotency key.

GlobalFilter thêm correlation ID

Filter route chỉ chạy cho route đó. Gắn ID xuyên suốt là việc của GlobalFilter, chạy cho mọi route khớp và trước filter route nếu order nhỏ hơn.

// File: src/main/java/com/evotek/gateway/web/CorrelationIdFilter.java
package com.evotek.gateway.web;

import java.util.UUID;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.cloud.gateway.filter.GatewayFilterChain;
import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.core.Ordered;
import org.springframework.http.server.reactive.ServerHttpRequest;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Mono;

@Component
public class CorrelationIdFilter implements GlobalFilter, Ordered {

    public static final String HEADER = "X-Correlation-Id";
    private static final Logger log = LoggerFactory.getLogger(CorrelationIdFilter.class);

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String incoming = exchange.getRequest().getHeaders().getFirst(HEADER);
        String correlationId = (incoming != null && !incoming.isBlank())
                ? incoming
                : UUID.randomUUID().toString();

        ServerHttpRequest request = exchange.getRequest().mutate()
                .headers(headers -> headers.set(HEADER, correlationId))
                .build();

        exchange.getResponse().getHeaders().set(HEADER, correlationId);

        long started = System.nanoTime();
        return chain.filter(exchange.mutate().request(request).build())
                .doFinally(signal -> log.info("correlationId={} path={} status={} tookMs={}",
                        correlationId,
                        request.getURI().getPath(),
                        exchange.getResponse().getStatusCode(),
                        (System.nanoTime() - started) / 1_000_000));
    }

    @Override
    public int getOrder() {
        return Ordered.HIGHEST_PRECEDENCE;
    }
}

Filter tái sử dụng header nếu client đã gửi để trace không đứt, mutate request vì ServerHttpRequest immutable, và ghi ID vào response để client gửi kèm khi báo lỗi. Đừng dùng MDC hay ThreadLocal: trên WebFlux một request chạy trên nhiều thread, giá trị ở thread A không tự sang thread B.

Rate limit bằng Redis

RequestRateLimiter cần KeyResolver (giới hạn theo ai) và một RateLimiter. RedisRateLimiter dùng token bucket: nạp replenish-rate token mỗi giây, xô chứa tối đa burst-capacity, mỗi request lấy requested-tokens.

spring:
  data:
    redis:
      host: localhost
      port: 6379
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: public-content
              uri: lb://content-service
              predicates:
                - Path=/api/public/**
              filters:
                - RewritePath=/api/public/(?<segment>.*), /content/${segment}
                - name: RequestRateLimiter
                  args:
                    key-resolver: "#{@apiKeyResolver}"
                    redis-rate-limiter.replenish-rate: 20
                    redis-rate-limiter.burst-capacity: 40
                    redis-rate-limiter.requested-tokens: 1
// File: src/main/java/com/evotek/gateway/config/RateLimitConfig.java
package com.evotek.gateway.config;

import org.springframework.cloud.gateway.filter.ratelimit.KeyResolver;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import reactor.core.publisher.Mono;

@Configuration
public class RateLimitConfig {

    @Bean
    KeyResolver apiKeyResolver() {
        return exchange -> {
            String apiKey = exchange.getRequest().getHeaders().getFirst("X-API-Key");
            if (apiKey != null && !apiKey.isBlank()) {
                return Mono.just(apiKey);
            }
            String ip = exchange.getRequest().getRemoteAddress() != null
                    ? exchange.getRequest().getRemoteAddress().getAddress().getHostAddress()
                    : "unknown";
            return Mono.just(ip);
        };
    }
}

Cần spring-boot-starter-data-redis-reactive trên classpath. Key rỗng bị từ chối theo mặc định, nên luôn có fallback như IP ở trên.

Vì sao không dùng in-memory? Mỗi instance giữ bucket riêng: ba instance nghĩa là giới hạn thực tế gấp ba, request rơi ngẫu nhiên, restart một instance reset quota của nó. Redis đưa phép đếm về một chỗ, dùng script atomic, nên mọi instance chia sẻ trạng thái. Đó là lý do rate limit “chạy tốt trên máy dev” vỡ ngay khi lên hai pod.

Redis chết thì rate limit không còn; phải chọn fail-open hay fail-closed thay vì để mặc định thư viện quyết định. Bucket4j là lựa chọn khác nhưng vẫn cần backend phân tán khi chạy nhiều instance.

Bảo mật: resource server, client và token relay

Gateway thường là OAuth2 resource server: nhận bearer token, xác thực chữ ký và issuer, chuyển tiếp nguyên header Authorization. Service vẫn phải quyết định quyền trên tài nguyên; đừng để service nội bộ tin header X-User-Id do bất kỳ ai gửi.

// File: src/main/java/com/evotek/gateway/security/SecurityConfig.java
package com.evotek.gateway.security;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.web.server.ServerHttpSecurity;
import org.springframework.security.web.server.SecurityWebFilterChain;

@Configuration
public class SecurityConfig {

    @Bean
    SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
        return http
                .csrf(csrf -> csrf.disable())
                .authorizeExchange(exchanges -> exchanges
                        .pathMatchers("/api/public/**", "/actuator/health").permitAll()
                        .anyExchange().authenticated())
                .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
                .build();
    }
}

Đặt spring.security.oauth2.resourceserver.jwt.issuer-uri trỏ tới issuer; Boot 4.1.2 đọc property này và tự cấu hình JwtDecoder.

Gateway as OAuth2 client là câu chuyện khác: oauth2Login(), token trong ReactiveOAuth2AuthorizedClientService, filter TokenRelay thay header bằng access token của phiên. Chỉ dùng khi gateway đứng giữa luồng login trình duyệt; API bearer token thì resource server đủ và ít trạng thái hơn.

Đừng xây auth hai lần: gateway xác thực “ai đang gọi”, service quyết định “được làm gì”. Cùng parse JWT ở hai nơi tạo hai nguồn sự thật.

Observability: metric và tracing

Bật Actuator, gateway tạo timer spring.cloud.gateway.requests với tag routeId, status, outcome, httpMethod. Đây là metric đầu tiên xem khi một route có latency bất thường. Metric bật mặc định qua spring.cloud.gateway.server.webflux.metrics.enabled; tag path là tùy chọn, cân nhắc cardinality.

Tracing do Micrometer Tracing 1.7.2 xử lý, không phải Sleuth: span cho request vào và lời gọi ra, lan traceparent theo W3C. Service đích cũng cần Micrometer Tracing và exporter OTLP hoặc Zipkin. Observability bật mặc định qua spring.cloud.gateway.server.webflux.observability.enabled.

Correlation ID không thay trace ID: một cái cho log và ticket hỗ trợ, một cái để ghép span.

Bảy bẫy vận hành

  • Gateway thành single point of failure. Mọi request đi qua, một instance là điểm sập toàn hệ thống. Chạy ít nhất hai instance sau load balancer, có readiness probe, graceful shutdown và timeout rõ ràng.
  • Gọi blocking trên event loop. JDBC, RestTemplate hay .block() giữ thread Netty khi chờ I/O; vài request chậm làm nghẽn gateway. Dùng WebClient, R2DBC, hoặc chuyển sang MVC server.
  • Route order và shadowing. Path=/api/** trước /api/orders/** sẽ nuốt request orders. Route khớp đầu tiên thắng; đặt route cụ thể trước, kiểm tra bằng actuator.
  • Log body và buffer body. ModifyRequestBody, CacheRequestBody hay retry có body giữ toàn bộ body trong RAM; upload lớn đẩy heap, log body rò rỉ token và dữ liệu cá nhân. Chỉ bật khi debug có kiểm soát.
  • Retry storm. Retry nhân lưu lượng khi downstream chậm. Chỉ retry method idempotent, giới hạn số lần, có backoff và jitter, ghép với circuit breaker.
  • Sticky session. Gateway nên stateless; oauth2Login cần session trong Redis, nếu không người dùng bị đăng xuất khi đổi instance. Ép affinity xuống service đích chỉ che vấn đề.
  • Trộn predicate/filter MVC và WebFlux. Hai module có bộ predicate, filter, prefix riêng; config copy có thể không khớp tên hoặc không route nào khớp. Chọn một variant và đọc tài liệu của chính nó.

Khi nào dùng gì

Tình huống Lựa chọn Lý do
Nhiều kết nối đồng thời, backend reactive Gateway WebFlux server Non-blocking, ít thread, hợp Netty
Đội quen servlet, thư viện blocking Gateway MVC server Không phải viết lại stack
Chỉ routing, TLS, không cần rate limit theo key Nginx hoặc Ingress Ít thành phần phải vá và giám sát
Rate limit chạy nhiều instance RedisRateLimiter Trạng thái tập trung, đếm atomic
Cần timeout, circuit breaker, fallback Resilience4j qua Spring Cloud Circuit Breaker Không phụ thuộc Hystrix đã chết

Nhìn về 2027

Gateway 5.1.0-RC2 và train 2026.0.0-RC2 vẫn là preview; chưa có gì để nâng production chỉ vì số phiên bản. Xu hướng rõ hơn là observability theo OTLP và MVC/WebFlux tiến gần nhau về tính năng.

Checklist

  • Ghim spring-cloud-dependencies 2025.1.4 và Boot 4.1.2; không trộn bản RC vào production.
  • Chọn đúng starter WebFlux hoặc MVC, và đúng prefix server.webflux hay server.webmvc.
  • Route cụ thể trước route tổng quát; kiểm tra thứ tự khớp bằng actuator.
  • Filter trên event loop phải non-blocking; retry chỉ cho method idempotent và có backoff.
  • Rate limit dùng Redis khi chạy nhiều instance; quyết định fail-open hay fail-closed trước khi sự cố xảy ra.
  • Bật metric, tracing và correlation ID trước khi mở traffic.

Đi tiếp trong series: Spring Cloud là gì, Spring Cloud Config, Circuit Breaker trong Spring Cloud, và gọi service với OpenFeign.