Spring Cloud Gateway核心概念
约 1211 字大约 4 分钟
spring-cloudgateway
2025-03-29
概述
Spring Cloud Gateway 是 Spring 生态中的 API 网关解决方案,基于 Spring WebFlux 和 Project Reactor 构建,天然支持非阻塞异步处理。它替代了早期的 Netflix Zuul,提供了路由转发、请求过滤、限流熔断等网关核心功能。
核心模型
Spring Cloud Gateway 的核心概念:
| 概念 | 说明 |
|---|---|
| Route(路由) | 网关的基本构建块,由 ID、目标 URI、Predicate 集合和 Filter 集合组成 |
| Predicate(断言) | 匹配 HTTP 请求的条件(路径、Header、参数等) |
| Filter(过滤器) | 在请求转发前后执行的处理逻辑 |
路由配置
YAML 配置方式
spring:
cloud:
gateway:
routes:
# 路由1:用户服务
- id: user-service
uri: lb://user-service
predicates:
- Path=/api/users/**
- Method=GET,POST,PUT,DELETE
filters:
- StripPrefix=1
- AddRequestHeader=X-Gateway, true
# 路由2:订单服务(带权重)
- id: order-service-v2
uri: lb://order-service
predicates:
- Path=/api/orders/**
- Weight=group1, 8
filters:
- StripPrefix=1
- name: CircuitBreaker
args:
name: orderCircuitBreaker
fallbackUri: forward:/fallback/orders
# 路由3:按时间生效
- id: promotion-service
uri: lb://promotion-service
predicates:
- Path=/api/promotions/**
- Between=2025-03-01T00:00:00+08:00, 2025-03-31T23:59:59+08:00Java API 配置方式
@Configuration
public class GatewayRoutesConfig {
@Bean
public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
return builder.routes()
.route("user-service", r -> r
.path("/api/users/**")
.and()
.method(HttpMethod.GET, HttpMethod.POST)
.filters(f -> f
.stripPrefix(1)
.addRequestHeader("X-Gateway", "true")
.retry(config -> config
.setRetries(3)
.setStatuses(HttpStatus.SERVICE_UNAVAILABLE)))
.uri("lb://user-service"))
.route("order-service", r -> r
.path("/api/orders/**")
.filters(f -> f
.stripPrefix(1)
.circuitBreaker(config -> config
.setName("orderCB")
.setFallbackUri("forward:/fallback/orders")))
.uri("lb://order-service"))
.build();
}
}内置 Predicate 工厂
spring:
cloud:
gateway:
routes:
- id: predicate-demo
uri: lb://demo-service
predicates:
# 路径匹配
- Path=/api/v1/**
# HTTP方法匹配
- Method=GET,POST
# 请求头匹配(支持正则)
- Header=X-Request-Type, internal|external
# 查询参数匹配
- Query=category, electronics|books
# 主机名匹配
- Host=**.example.com
# Cookie匹配
- Cookie=sessionId, .+
# 时间范围
- After=2025-01-01T00:00:00+08:00
# 来源IP
- RemoteAddr=192.168.1.0/24内置 Filter 工厂
常用 GatewayFilter
filters:
# 路径相关
- StripPrefix=1 # 去掉路径前缀
- PrefixPath=/api # 添加路径前缀
- RewritePath=/api/(?<segment>.*), /$\{segment} # 路径重写
# 请求头相关
- AddRequestHeader=X-Trace-Id, {traceId}
- RemoveRequestHeader=Cookie
- SetRequestHeader=Host, api.internal.com
# 响应头相关
- AddResponseHeader=X-Response-Time, {responseTime}
- DedupeResponseHeader=Access-Control-Allow-Origin
# 重试
- name: Retry
args:
retries: 3
statuses: SERVICE_UNAVAILABLE
methods: GET
backoff:
firstBackoff: 100ms
maxBackoff: 500ms
factor: 2
# 请求大小限制
- name: RequestSize
args:
maxSize: 10MB自定义 GatewayFilter
@Component
public class RequestLoggingGatewayFilterFactory
extends AbstractGatewayFilterFactory<RequestLoggingGatewayFilterFactory.Config> {
private static final Logger log = LoggerFactory.getLogger(
RequestLoggingGatewayFilterFactory.class);
public RequestLoggingGatewayFilterFactory() {
super(Config.class);
}
@Override
public GatewayFilter apply(Config config) {
return (exchange, chain) -> {
ServerHttpRequest request = exchange.getRequest();
long startTime = System.currentTimeMillis();
if (config.isLogRequest()) {
log.info("Gateway Request: {} {} from {}",
request.getMethod(),
request.getURI().getPath(),
request.getRemoteAddress());
}
return chain.filter(exchange).then(Mono.fromRunnable(() -> {
long duration = System.currentTimeMillis() - startTime;
if (config.isLogResponse()) {
log.info("Gateway Response: {} {} - {} in {}ms",
request.getMethod(),
request.getURI().getPath(),
exchange.getResponse().getStatusCode(),
duration);
}
}));
};
}
public static class Config {
private boolean logRequest = true;
private boolean logResponse = true;
// getters and setters...
public boolean isLogRequest() { return logRequest; }
public void setLogRequest(boolean logRequest) { this.logRequest = logRequest; }
public boolean isLogResponse() { return logResponse; }
public void setLogResponse(boolean logResponse) { this.logResponse = logResponse; }
}
}在配置中使用:
filters:
- name: RequestLogging
args:
logRequest: true
logResponse: trueGlobalFilter —— 全局过滤器
@Component
@Order(-1)
public class AuthGlobalFilter implements GlobalFilter {
private final JwtTokenProvider tokenProvider;
public AuthGlobalFilter(JwtTokenProvider tokenProvider) {
this.tokenProvider = tokenProvider;
}
@Override
public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
ServerHttpRequest request = exchange.getRequest();
String path = request.getURI().getPath();
// 白名单路径跳过认证
if (isWhiteListed(path)) {
return chain.filter(exchange);
}
String token = extractToken(request);
if (token == null || !tokenProvider.validate(token)) {
exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
return exchange.getResponse().setComplete();
}
// 将用户信息传递到下游服务
String userId = tokenProvider.getUserId(token);
ServerHttpRequest modifiedRequest = request.mutate()
.header("X-User-Id", userId)
.build();
return chain.filter(exchange.mutate().request(modifiedRequest).build());
}
private String extractToken(ServerHttpRequest request) {
String bearer = request.getHeaders().getFirst("Authorization");
if (bearer != null && bearer.startsWith("Bearer ")) {
return bearer.substring(7);
}
return null;
}
private boolean isWhiteListed(String path) {
return path.startsWith("/api/auth/") || path.startsWith("/api/public/");
}
}限流配置
@Bean
public KeyResolver userKeyResolver() {
return exchange -> {
String userId = exchange.getRequest().getHeaders().getFirst("X-User-Id");
return Mono.justOrEmpty(userId).defaultIfEmpty("anonymous");
};
}spring:
cloud:
gateway:
routes:
- id: rate-limited-route
uri: lb://api-service
predicates:
- Path=/api/**
filters:
- name: RequestRateLimiter
args:
redis-rate-limiter.replenishRate: 100 # 每秒补充令牌数
redis-rate-limiter.burstCapacity: 200 # 令牌桶容量
redis-rate-limiter.requestedTokens: 1 # 每次请求消耗令牌数
key-resolver: "#{@userKeyResolver}"熔断集成
spring:
cloud:
gateway:
routes:
- id: circuit-breaker-route
uri: lb://order-service
predicates:
- Path=/api/orders/**
filters:
- name: CircuitBreaker
args:
name: orderServiceCB
fallbackUri: forward:/fallback/orders
resilience4j:
circuitbreaker:
instances:
orderServiceCB:
slidingWindowSize: 10
failureRateThreshold: 50
waitDurationInOpenState: 30s
permittedNumberOfCallsInHalfOpenState: 5@RestController
public class FallbackController {
@GetMapping("/fallback/orders")
public ResponseEntity<Map<String, String>> orderFallback() {
return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
.body(Map.of(
"code", "SERVICE_UNAVAILABLE",
"message", "Order service is temporarily unavailable"
));
}
}总结
Spring Cloud Gateway 基于 WebFlux 提供了高性能的非阻塞 API 网关能力。通过 Route/Predicate/Filter 三层模型,实现了灵活的路由匹配和请求处理。结合 GlobalFilter、RequestRateLimiter 和 CircuitBreaker,可以构建完善的认证、限流、熔断防护体系。自定义 Filter 和 Predicate 扩展机制使得网关能够适应各种业务场景。
贡献者
更新日志
2026/3/14 13:09
查看所有更新日志
9f6c2-feat: organize wiki content and refresh site setup于