Spring Cloud Gateway：微服务流量的"中央调度官"

1
2
3
4
5
6
7

2014  Zuul 1.x 诞生（Netflix OSS 标杆）
2018  Netflix 宣布 Zuul 1.x 维护，推荐 Resilience4j
2017  Spring Cloud Gateway 立项
2019  Spring Cloud Gateway 2.1 GA（生产可用）
2022  Spring Cloud Gateway 3.1（基于 Spring Boot 3.0，WebFlux + Reactor Netty）
2024  Spring Cloud Gateway 4.0（响应式 API 全面稳定）
2026  Spring Cloud Gateway 主流选择（Z

1
2
3
4
5
6
7
8

public class Route implements Ordered {
    private final String id;
    private final URI uri;                  // 目标地址
    private final int order;
    private final AsyncPredicate<ServerWebExchange> predicate;  // 断言
    private final List<GatewayFilter> filters;  // 过滤器
    private final Map<String, Object> metadata;
}

1
2
3
4
5

@FunctionalInterface
public interface RoutePredicateFactory<C> extends ShortcutConfigurable, Configurable<C> {
    Predicate<ServerWebExchange> apply(C config);
    default String name() { return ... }
}

1
2
3

public interface GatewayFilter {
    Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain);
}

1
2

请求进入 → GlobalFilter.order(升序) → GatewayFilter → 路由到下游
         ← GatewayFilter ← GlobalFilter.order(降序) ← 下游响应

1
2
3

public interface RouteDefinitionLocator {
    Flux<RouteDefinition> getRouteDefinitions();
}

1
2
3
4
5
6
7
8
9

HTTP Request
    ↓
[RoutePredicateHandlerMapping]  ← 用 Predicate 匹配 Route
    ↓
[FilteringWebHandler]           ← 装载 GatewayFilter + GlobalFilter
    ↓
[NettyRoutingFilter]            ← Reactor Netty 转发到下游
    ↓
HTTP Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

@Component
public class CustomHeaderGatewayFilterFactory
        extends AbstractGatewayFilterFactory<CustomHeaderGatewayFilterFactory.Config> {

    public CustomHeaderGatewayFilterFactory() {
        super(Config.class);
    }

    @Override
    public GatewayFilter apply(Config config) {
        return (exchange, chain) -> {
            // pre 逻辑
            ServerHttpRequest mutated = exchange.getRequest().mutate()
                .header(config.getName(), config.getValue())
                .build();
            return chain.filter(exchange.mutate().request(mutated).build());
        };
    }

    public static class Config {
        private String name;
        private String value;
        // getter/setter
    }
}

1
2
3
4
5

filters:
  - name: CustomHeader
    args:
      name: X-Source
      value: my-gateway

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

spring:
  cloud:
    gateway:
      routes:
        - id: order_route_v2_gray
          uri: lb://order-svc-v2
          order: 0           # 数字越小越优先
          predicates:
            - Path=/api/order/**
            - Header=X-Gray-Tag, beta
        - id: order_route_default
          uri: lb://order-svc-v1
          order: 100
          predicates:
            - Path=/api/order/**

1
2
3
4

predicates:
  - Path=/api/order/**       # 先匹配路径（便宜）
  - Method=GET,POST          # 再匹配方法（便宜）
  - Header=X-Token, \w+      # 最后匹配头（需要正则）

1
2
3
4
5
6

predicates:
  - Path=/api/order/**
  - Method=GET,POST
  - Header=X-Tenant, [a-zA-Z0-9_]+
  - After=2026-01-01T00:00:00+08:00
  - RemoteAddr=192.168.0.0/16

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

        ┌──────────────────────────────────────┐
        │  Spring Cloud Gateway                 │
        │  ┌──────────┐  ┌──────────────────┐   │
        │  │ 路由动态 │  │ 限流/熔断/降级   │   │
        │  │ Nacos    │  │ Sentinel / Hystrix│  │
        │  └──────────┘  └──────────────────┘   │
        │  ┌──────────┐  ┌──────────────────┐   │
        │  │ 服务发现 │  │ 链路追踪          │   │
        │  │ Nacos    │  │ Sleuth + Zipkin   │   │
        │  └──────────┘  └──────────────────┘   │
        │  ┌──────────┐  ┌──────────────────┐   │
        │  │ 配置中心 │  │ 监控告警          │   │
        │  │ Nacos    │  │ Actuator + Prom   │   │
        │  └──────────┘  └──────────────────┘   │
        └──────────────────────────────────────┘

1
2
3
4

predicates:
  - Path=/api/promo/**
  - After=2026-11-11T00:00:00+08:00   # 11.11 凌晨 0 点后生效
  - Before=2026-11-11T23:59:59+08:00  # 11.11 当天 24 点失效

1
2
3
4
5
6
7

filters:
  - StripPrefix=1                        # pre: 去掉路径前缀
  - AddRequestHeader=X-Trace, abc123     # pre: 加请求头
  - name: Retry
    args: { retries: 3 }                 # pre: 准备重试
  - name: CircuitBreaker                 # pre: 熔断器包装
    args: { name: orderCB }

1
2

请求进入 → StripPrefix(pre) → AddRequestHeader(pre) → Retry(pre) → CircuitBreaker(pre) → 下游服务
        ← StripPrefix(post) ← AddRequestHeader(post) ← Retry(post) ← CircuitBreaker(post) ← 下游响应

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

spring:
  cloud:
    gateway:
      routes:
        - id: order_route
          uri: lb://order-svc
          predicates:
            - Path=/api/order/**
            - Method=GET,POST
          filters:
            - StripPrefix=2  # /api/order/list -> /list
            - AddRequestHeader=X-Source, gateway

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

@Bean
public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("user_route", r -> r
            .path("/api/user/**")
            .and().method("GET")
            .and().header("X-Tenant", "[a-z]+")
            .filters(f -> f
                .stripPrefix(2)
                .addRequestHeader("X-Source", "gateway")
                .retry(3)
            )
            .uri("lb://user-svc"))
        .build();
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

@Bean
public RouteLocator tenantRouteLocator(RouteLocatorBuilder builder,
                                       TenantConfigService tenantConfig) {
    return builder.routes()
        .route(r -> r
            .path("/api/**")
            .filters(f -> f
                .filter((exchange, chain) -> {
                    String tenant = exchange.getRequest().getHeaders()
                        .getFirst("X-Tenant");
                    String prefix = tenantConfig.getPrefix(tenant);
                    // 动态修改 uri
                    return chain.filter(exchange.mutate()
                        .request(exchange.getRequest().mutate()
                            .header("X-Cluster", prefix).build())
                        .build());
                }))
            .uri("lb://" + tenantConfig.getDefaultCluster()))
        .build();
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

@Component
@Order(1)  // 数字越小越早执行
public class AuthGlobalFilter implements GlobalFilter {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        ServerHttpRequest request = exchange.getRequest();
        String path = request.getURI().getPath();

        // 1. 白名单直接放行
        if (path.startsWith("/api/public/")) {
            return chain.filter(exchange);
        }

        // 2. 校验 Token
        String token = request.getHeaders().getFirst("Authorization");
        if (token == null || !token.startsWith("Bearer ")) {
            ServerHttpResponse response = exchange.getResponse();
            response.setStatusCode(HttpStatus.UNAUTHORIZED);
            return response.writeWith(Mono.just(
                response.bufferFactory().wrap("{\"code\":401,\"msg\":\"未登录\"}".getBytes())
            ));
        }

        // 3. 解析 Token，将 userId 透传到下游
        String userId = JwtUtil.parseUserId(token);
        ServerHttpRequest mutated = request.mutate()
            .header("X-User-Id", userId)
            .build();
        return chain.filter(exchange.mutate().request(mutated).build());
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

spring:
  cloud:
    gateway:
      routes:
        - id: order_route_v1
          uri: lb://order-svc-v1
          predicates:
            - Path=/api/order/**
            - Weight=order-svc, 90
        - id: order_route_v2
          uri: lb://order-svc-v2
          predicates:
            - Path=/api/order/**
            - Weight=order-svc, 10

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

spring:
  cloud:
    gateway:
      routes:
        - id: order_route_gray
          uri: lb://order-svc-v2
          predicates:
            - Path=/api/order/**
            - Header=X-Gray-Tag, beta
        - id: order_route_default
          uri: lb://order-svc-v1
          predicates:
            - Path=/api/order/**

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

@Component
@Order(-1)
public class JsonErrorWebExceptionHandler implements ErrorWebExceptionHandler {

    @Override
    public Mono<Void> handle(ServerWebExchange exchange, Throwable ex) {
        ServerHttpResponse response = exchange.getResponse();
        response.setStatusCode(HttpStatus.OK);  // 统一 200
        response.getHeaders().setContentType(MediaType.APPLICATION_JSON);

        Map<String, Object> body = new HashMap<>();
        body.put("code", 500);
        body.put("msg", ex.getMessage());
        body.put("path", exchange.getRequest().getPath().value());

        try {
            byte[] bytes = new ObjectMapper().writeValueAsBytes(body);
            return response.writeWith(Mono.just(response.bufferFactory().wrap(bytes)));
        } catch (Exception e) {
            return Mono.error(e);
        }
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

@Component
public class TenantRoutePredicateFactory
        extends AbstractRoutePredicateFactory<TenantRoutePredicateFactory.Config> {

    public TenantRoutePredicateFactory() {
        super(Config.class);
    }

    @Override
    public Predicate<ServerWebExchange> apply(Config config) {
        return exchange -> {
            String tenant = exchange.getRequest().getHeaders()
                .getFirst(config.getHeaderName());
            // 命中租户白名单
            return config.getAllowedTenants().contains(tenant);
        };
    }

    @Data
    public static class Config {
        private String headerName = "X-Tenant";
        private List<String> allowedTenants;
    }
}

1
2
3
4
5
6
7

predicates:
  - name: Tenant
    args:
      headerName: X-Tenant
      allowedTenants:
        - tenant-a
        - tenant-b

1
2
3
4
5

# 安装 wrk（Ubuntu）
sudo apt install wrk

# 压测网关：100 并发，持续 30 秒
wrk -t4 -c100 -d30s --latency http://gateway:8080/api/order/list

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

spring:
  cloud:
    gateway:
      globalcors:
        cors-configurations:
          '[/**]':
            allowedOriginPatterns: "*"
            allowedMethods: "*"
            allowedHeaders: "*"
            allowCredentials: true
            maxAge: 3600

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

spring:
  cloud:
    gateway:
      httpclient:
        connect-timeout: 1000    # 连接超时 1s
        response-timeout: 5s     # 响应超时 5s
      routes:
        - id: order_route
          uri: lb://order-svc
          predicates:
            - Path=/api/order/**
          filters:
            - name: Retry
              args:
                retries: 3
                statuses: BAD_GATEWAY,SERVICE_UNAVAILABLE
                methods: GET,POST
                backoff:
                  firstBackoff: 50ms
                  maxBackoff: 500ms
                  factor: 2

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

spring:
  cloud:
    gateway:
      routes:
        - id: order_route
          uri: lb://order-svc
          predicates:
            - Path=/api/order/**
          filters:
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 100   # 每秒 100 个令牌
                redis-rate-limiter.burstCapacity: 200  # 桶容量 200
                redis-rate-limiter.requestedTokens: 1
                key-resolver: "#{@userKeyResolver}"    # SpEL 表达式

1
2
3
4
5
6

@Bean
public KeyResolver userKeyResolver() {
    return exchange -> Mono.just(
        exchange.getRequest().getHeaders().getFirst("X-User-Id")
    );
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

spring:
  cloud:
    sentinel:
      transport:
        dashboard: localhost:8080  # Sentinel 控制台
      scg:
        fallback:
          mode: response
          response-status: 429
          response-body: '{"code":429,"msg":"服务降级中"}'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

management:
  endpoints:
    web:
      exposure:
        include: health,info,gateway,prometheus
  metrics:
    tags:
      application: ${spring.application.name}
  prometheus:
    metrics:
      export:
        enabled: true

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

@Component
public class NacosRouteDefinitionRepository implements RouteDefinitionRepository {
    @Autowired
    private NacosConfigService nacosConfigService;

    @Override
    public Flux<RouteDefinition> getRouteDefinitions() {
        // 从 Nacos 拉取路由配置
        List<RouteDefinition> routes = nacosConfigService.getConfig(
            "gateway-routes", "DEFAULT_GROUP", 5000
        );
        return Flux.fromIterable(routes);
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

server:
  port: 8080
  netty:
    connection-timeout: 30s
spring:
  application:
    name: api-gateway
  cloud:
    nacos:
      discovery:
        server-addr: nacos:8848
    gateway:
      discovery:
        locator:
          enabled: true
          lower-case-service-id: true
      globalcors:
        cors-configurations:
          '[/**]':
            allowedOriginPatterns: "*"
            allowedMethods: "*"
            allowedHeaders: "*"
            allowCredentials: true
      httpclient:
        connect-timeout: 1000
        response-timeout: 5s
management:
  endpoints:
    web:
      exposure:
        include: health,info,gateway,prometheus

1
2
3
4
5
6

spring:
  cloud:
    gateway:
      filter:
        secure-headers:
          disable: "*"  # 禁用所有

1
2
3
4
5
6
7
8
9

        ┌──────────┐
        │   Nginx  │  ← VIP / Keepalived
        └──────────┘
            ↓
   ┌────────┴────────┐
   │                 │
┌──┴──┐           ┌──┴──┐
│GW-1 │           │GW-2 │  ← 至少 2 个 Spring Cloud Gateway 实例
└─────┘           └─────┘

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gateway
spec:
  replicas: 2  # 至少 2 副本
  template:
    spec:
      containers:
        - name: gateway
          image: gateway:1.0
          ports:
            - containerPort: 8080
          readinessProbe:  # 就绪探针
            httpGet:
              path: /actuator/health
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 10

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

   客户端（Web/App/小程序）
        ↓
   ┌─────────────┐
   │   Nginx     │  ← SSL 卸载、静态资源、CC 攻击拦截
   └─────────────┘
        ↓
   ┌─────────────────────────────┐
   │ Spring Cloud Gateway       │  ← 鉴权、限流、灰度、路由
   │ ┌────┐ ┌────┐ ┌────┐      │
   │ │Pred│→│Filt│→│Load│      │
   │ └────┘ └────┘ └────┘      │
   └─────────────────────────────┘
        ↓        ↓        ↓
   ┌────────┐ ┌────────┐ ┌────────┐
   │user-svc│ │order-  │ │product-│
   │        │ │svc     │ │svc     │
   └────────┘ └────────┘ └────────┘

1
2
3
4
5

需要 Java 微服务网关吗？
├─ 是 → 团队熟悉 Spring？ → Spring Cloud Gateway
│       └─ 团队熟悉 Lua？   → APISIX / Kong
├─ 边缘入口（SSL/CDN）     → Nginx / OpenResty
└─ 单服务单入口             → 上 Nginx 就够了