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.
Mục lục
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-webfluxvới prefixspring.cloud.gateway.server.webflux.*;spring-cloud-starter-gateway-server-webmvcvớispring.cloud.gateway.server.webmvc.*. Config cũspring.cloud.gateway.routeskhông còn bind. - Filter thực dụng hơn:
Retrycó backoff, jitter, timeout;RequestRateLimiterchạ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/**sangorder-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ó
JsonToGrpccho 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,
RestTemplatehay.block()giữ thread Netty khi chờ I/O; vài request chậm làm nghẽn gateway. DùngWebClient, 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,CacheRequestBodyhay 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;
oauth2Logincầ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-dependencies2025.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.webfluxhayserver.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.



