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:00

Java 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: true

GlobalFilter —— 全局过滤器

@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 扩展机制使得网关能够适应各种业务场景。

贡献者

withesse

更新日志

2026/3/14 13:09

查看所有更新日志

9f6c2-feat: organize wiki content and refresh site setup于 2026/3/14