Spring Cloud Gateway

Spring Cloud Gateway全解析

原创已于 2025-09-23 14:59:14 修改 · 1k 阅读

22 ·

CC 4.0 BY-SA版权

文章标签：

#Java #分布式 #Gateway

于 2025-08-22 10:26:57 首次发布

分布式专栏收录该内容

14 篇文章

订阅专栏

Spring Cloud Gateway 微服务路由配置使用指南

Spring Cloud Gateway 是一个基于 Spring 5、Spring Boot 2 和 Project Reactor 技术构建的 API 网关，专为微服务架构设计。它提供统一的路由管理功能，帮助处理请求转发、过滤和负载均衡。以下指南将逐步介绍如何配置和使用 Spring Cloud Gateway 进行微服务路由管理。内容基于真实文档和实践经验，确保可靠性和实用性。指南包括基本配置、过滤器使用、动态路由整合等关键部分。

1. Spring Cloud Gateway 简介

Spring Cloud Gateway 的核心功能是定义路由规则，将入站请求转发到后端微服务。它支持 Predicates（断言）用于匹配请求条件，Filters（过滤器）用于修改请求/响应，以及 URI 定义目标服务地址。网关通过这种方式简化了微服务间的通信，提高了系统的可扩展性和安全性。
主要优势：

动态路由：支持实时更新路由配置。
内置过滤器：提供丰富的请求处理功能，如添加请求头、限流等。
集成性：易于与 Spring Cloud 生态工具（如 Nacos）整合。

2. 基本路由配置

路由配置通常在 application.yml 或 bootstrap.yml 文件中定义。每个路由包含三个核心元素：

id：路由的唯一标识符。
uri：目标微服务的地址（支持负载均衡格式 lb://service-name）。
predicates：匹配请求的条件（如路径、方法等）。
filters：可选的处理链，用于修改请求或响应。

以下是一个简单示例，展示如何配置一个路由，将所有以 /api/** 开头的请求转发到 ribbon-api-service 微服务，并添加一个请求头：

spring:
  cloud:
    gateway:
      routes:
        - id: first-route  # 路由ID
          uri: lb://ribbon-api-service  # 目标服务，使用负载均衡
          predicates:
            - Path=/api/**  # 匹配路径规则
          filters:
            - AddRequestHeader=a,b  # 内置过滤器：添加请求头

在这个配置中：

Path=/api/** 确保只有路径以 /api/ 开头的请求被处理。
AddRequestHeader=a,b 是一个内置过滤器，它添加一个键为 a、值为 b 的请求头到转发请求中。
启动应用后，网关会自动加载这些规则，处理入站请求。

3. 过滤器（Filters）的使用

过滤器是路由的核心组件，分为内置过滤器和自定义过滤器：

内置过滤器：Spring Cloud Gateway 提供多种开箱即用的过滤器，如 AddRequestHeader、StripPrefix（移除路径前缀）和 Retry（重试机制）。这些过滤器通过简单配置即可生效。
自定义过滤器：您可以通过实现 GlobalFilter 接口来创建全局过滤器，处理所有路由的请求。

示例配置：添加响应头和限流功能

spring:
  cloud:
    gateway:
      routes:
        - id: user-service-route
          uri: lb://user-service  # 目标用户服务
          predicates:
            - Method=GET  # 只匹配GET请求
          filters:
            - name: AddRequestHeader  # 完整写法添加请求头
              args:
                name: newHeader
                value: newValue
            - StripPrefix=1  # 移除路径的第一部分（例如 /api/user 变为 /user）
            - name: RequestRateLimiter  # 限流过滤器
              args:
                key-resolver: "#{@userKeyResolver}"  # 自定义限流键解析器
                redis-rate-limiter.replenishRate: 10  # 每秒允许10个请求
                redis-rate-limiter.burstCapacity: 20  # 突发容量20

说明：

AddRequestHeader 过滤器使用完整配置格式，更灵活地定义参数。
RequestRateLimiter 实现限流功能，通常需要结合 Redis 存储。
自定义过滤器示例（Java 代码）：

@Bean
public GlobalFilter customGlobalFilter() {
    return (exchange, chain) -> {
        // 添加自定义逻辑，如日志或认证
        return chain.filter(exchange);
    };
}

4. 动态路由配置

在微服务架构中，路由规则可能需要动态更新（如服务发现变化）。Spring Cloud Gateway 支持与配置中心（如 Nacos）整合，实现动态路由。以下是使用 Nacos 的步骤：

添加依赖：在 pom.xml 中加入 Nacos 和 Gateway 的依赖。

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>

配置 Nacos：在 bootstrap.yml 中设置 Nacos 服务器地址和服务注册。

server:
  port: 10005  # 网关端口
spring:
  application:
    name: sky-gateway  # 网关服务名
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848  # Nacos 服务地址
      config:
        server-addr: ${spring.cloud.nacos.discovery.server-addr}  # 配置中心地址
        file-extension: yml  # 配置文件格式
    gateway:
      discovery:
        locator:
          enabled: true  # 启用服务发现，自动从 Nacos 获取路由

动态更新：当 Nacos 中的服务列表变化时，网关会自动调整路由，无需重启。

5. 最佳实践和注意事项

测试路由：使用工具如 Postman 或 curl 验证路由规则（例如 curl http://localhost:10005/api/user）。
安全性：结合 Spring Security 添加认证过滤器。
性能优化：启用缓存和限流以避免过载。
错误处理：配置全局异常处理器，返回友好错误响应。
版本控制：推荐使用 Spring Boot 2.x 和 Spring Cloud Hoxton 或更高版本。

思维导图

在这里插入图片描述

Spring Cloud Gateway 技术原理与架构详解

Spring Cloud Gateway 是基于 Spring 5、Project Reactor 和 Spring Boot 2 构建的响应式 API 网关，其核心设计目标是替代 Zuul，提供高性能、非阻塞的微服务路由解决方案。以下从技术原理、核心组件、优缺点及代码实现展开说明。

一、技术原理与架构

1. 核心处理流程

客户端请求在网关中的处理流程如下：
在这里插入图片描述

路由匹配：通过 RoutePredicateHandlerMapping 匹配请求与路由规则（基于 Predicates）。
过滤器链：通过 FilteringWebHandler 执行预定义过滤器链（Pre-Filters → 代理请求 → Post-Filters）。
响应式代理：使用 Reactor Netty 非阻塞转发请求，通过 HttpClient 连接目标服务。

2. 核心算法与数据结构

路由匹配算法：
- 使用 RoutePredicateFactory 生成断言（Predicate），基于树形结构存储路由规则，实现 $O(log⁡n)O(\log n)$ 高效匹配。
- 示例：Path=/api/** 使用 Ant 风格路径匹配算法。
过滤器链：
- 过滤器按 Order 值排序，形成责任链模式（Chain of Responsibility）。
- 全局过滤器通过 GlobalFilter 接口实现，优先级由 @Order 注解控制。
限流算法：
- 默认基于令牌桶算法（Token Bucket），通过 RedisRateLimiter 实现分布式限流。

二、核心组件及功能

组件	功能说明
`RoutePredicateHandlerMapping`	路由匹配：根据 Predicates 匹配请求到路由规则
`FilteringWebHandler`	过滤器执行：按顺序执行 Pre-Filters 和 Post-Filters
`NettyRoutingFilter`	请求转发：通过 Reactor Netty 非阻塞转发到目标服务
`LoadBalancerClientFilter`	负载均衡：集成 Ribbon 实现服务实例的动态选择（需配置 `lb://service-name`）
`GlobalFilter`	全局过滤器：自定义认证、日志等跨路由逻辑

三、优缺点分析

优点	缺点
高性能：基于 WebFlux 非阻塞模型，吞吐量比 Zuul 高 1.5 倍	学习曲线：需熟悉 Reactor 响应式编程模型
灵活路由：支持动态配置（Nacos/Consul）	调试复杂：过滤器链逻辑较难追踪
丰富过滤器：内置 20+ 过滤器（限流、重试等）	依赖强：需 Spring Boot 2.x+ 和 JDK 8+
无缝集成：兼容 Spring Cloud 生态（Eureka, Sentinel）

四、代码示例与注释

1. 动态路由配置（Nacos 集成）

@Configuration
public class GatewayConfig {

    @Bean
    public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
        return builder.routes()
            .route("user-service", r -> r.path("/user/**")
                .filters(f -> f.stripPrefix(1) // 移除路径前缀
                             .addRequestHeader("X-Request-From", "gateway"))
                .uri("lb://user-service")     // 负载均衡到 user-service
            )
            .route("order-service", r -> r.host("*.example.com")
                .uri("lb://order-service")    // 基于域名匹配
            ).build();
    }
}

2. 自定义全局认证过滤器

@Component
@Order(-1) // 高优先级
public class AuthFilter implements GlobalFilter {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        // 1. 从请求头获取Token
        String token = exchange.getRequest().getHeaders().getFirst("Authorization");
        
        // 2. 验证Token（模拟逻辑）
        if (!"valid-token".equals(token)) {
            exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
            return exchange.getResponse().setComplete(); // 拦截请求
        }
        
        // 3. 通过验证，继续执行过滤器链
        return chain.filter(exchange);
    }
}

3. 限流配置（Redis 令牌桶）

spring:
  cloud:
    gateway:
      routes:
        - id: rate_limiter_route
          uri: lb://backend-service
          predicates:
            - Path=/api/**
          filters:
            - name: RequestRateLimiter
              args:
                key-resolver: "#{@ipKeyResolver}" # 按IP限流
                redis-rate-limiter:
                  replenishRate: 10    # 每秒10个令牌
                  burstCapacity: 20    # 突发容量20

五、架构功能图

Spring Cloud Gateway 核心架构分层：
在这里插入图片描述

路由层：存储路由规则（内存或配置中心）。
Predicate 层：匹配请求的路径、Header、方法等。
过滤器层：修改请求/响应（如添加 Header、重试逻辑）。
转发层：通过 Reactor Netty 调用下游服务。

总结

Spring Cloud Gateway 通过 响应式编程模型 + 动态路由 + 过滤器链 三支柱实现高性能网关，适用于微服务流量管理、安全防护和监控集成。其核心优势在于非阻塞架构和 Spring 生态无缝集成，但需注意响应式编程的学习成本。

提示：生产环境建议结合 Sentinel 实现熔断降级，使用 Actuator 端点 /actuator/gateway/routes 动态监控路由状态。

思维导图

在这里插入图片描述

Spring Cloud Gateway 高级功能实现详解

一、请求限流与熔断机制实现

1. 限流机制（令牌桶算法）
在这里插入图片描述

实现原理：
- 使用RequestRateLimiter过滤器 + RedisRateLimiter
- 令牌桶参数：replenishRate(生成速率), burstCapacity(桶容量)

配置示例：

filters:
  - name: RequestRateLimiter
    args:
      key-resolver: "#{@userKeyResolver}"
      redis-rate-limiter:
        replenishRate: 50
        burstCapacity: 200

2. 熔断机制（断路器模式）
在这里插入图片描述

熔断状态转换：
- Closed → Open：失败超过阈值
- Open → Half-Open：等待时间结束
- Half-Open → Closed：测试请求成功

原生实现：

filters:
  - name: CircuitBreaker
    args:
      name: serviceA
      fallbackUri: forward:/fallback

二、自定义全局认证过滤器

@Component
@Order(-100)
public class JwtAuthFilter implements GlobalFilter {
    
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        // 1. 提取JWT
        String token = extractToken(exchange.getRequest());
        
        // 2. 异步验证（非阻塞）
        return Mono.fromCallable(() -> validateToken(token))
            .subscribeOn(Schedulers.boundedElastic())
            .flatMap(valid -> {
                if(!valid) {
                    exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
                    return exchange.getResponse().setComplete();
                }
                // 3. 添加用户上下文
                return chain.filter(addUserContext(exchange, token));
            });
    }
}

关键点：

@Order(-100)确保最先执行
使用Schedulers.boundedElastic()隔离阻塞操作
响应式修改请求头：exchange.mutate().request()

三、Gateway vs Zuul 对比

维度	Spring Cloud Gateway	Zuul 1.x
架构模型	响应式(WebFlux)	阻塞式(Servlet)
吞吐量	10k+ QPS	2k-3k QPS
资源消耗	固定线程池	每请求一线程
限流熔断	原生支持+Sentinel集成	依赖Hystrix
动态路由	内置事件机制	需手动刷新
WebSocket	原生支持	不支持
监控指标	Micrometer集成	需自定义

结论：Gateway 在性能、扩展性、云原生支持方面全面领先，适合高并发场景

四、结合 Sentinel 实现熔断降级

1. 集成步骤：
在这里插入图片描述

依赖配置：

<dependency>
  <groupId>com.alibaba.cloud</groupId>
  <artifactId>spring-cloud-alibaba-sentinel-gateway</artifactId>
</dependency>

2. 熔断规则类型：

策略	参数	适用场景
慢调用比例	maxRt, slowRatio	响应时间敏感服务
异常比例	exceptionRatio	服务稳定性波动
异常数	exceptionCount	低频关键服务

3. 动态阈值调整：

// 根据响应时间自动调整阈值
@SentinelProperty("rtThreshold")
public void updateThreshold(double avgRt) {
    List<FlowRule> rules = ruleManager.getRules();
    rules.forEach(rule -> 
        rule.setMaxQueueingTimeMs((int)(avgRt * 1.5))
    );
    FlowRuleManager.loadRules(rules);
}

五、响应式阻塞调用处理

解决方案：

public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
    // 阻塞操作转移到弹性线程池
    return Mono.fromCallable(() -> blockingDatabaseCall())
        .subscribeOn(Schedulers.boundedElastic()) 
        .flatMap(result -> {
            exchange.getAttributes().put("data", result);
            return chain.filter(exchange);
        });
}

最佳实践：

使用Schedulers.boundedElastic()隔离所有阻塞调用
禁止在过滤器链中使用Thread.sleep()
数据库访问推荐R2DBC等响应式驱动
复杂计算使用Mono.fromSupplier()

六、过滤器执行顺序控制

优先级规则：
在这里插入图片描述

典型顺序：

认证过滤：Order = -100
限流熔断：Order = -50
路径重写：Order = 0
响应修改：Order = 100

自定义顺序：

@Bean
@Order(-1) // 全局异常处理最高优先级
public ErrorWebExceptionHandler customExceptionHandler() {
    // ...
}

七、动态路由更新实现

事件驱动更新：

@Autowired
private RouteDefinitionWriter writer;

public void updateRoute(String serviceId, String newPath) {
    // 1. 创建新路由定义
    RouteDefinition definition = new RouteDefinition();
    definition.setId(serviceId);
    definition.setUri("lb://" + serviceId);
    definition.setPredicates(List.of(
        new PredicateDefinition("Path=" + newPath))
    );
    
    // 2. 保存并刷新
    writer.save(Mono.just(definition)).subscribe();
    publisher.publishEvent(new RefreshRoutesEvent(this));
}

基于Nacos的配置：

spring:
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true
          url-expression: "'lb://' + serviceId + '/api/' + serviceId"

八、Sentinel熔断规则热更新

1. Nacos配置中心方案：

@NacosConfigListener(dataId = "sentinel-rules", groupId = "GATEWAY")
public void updateRules(String config) {
    List<FlowRule> rules = JSON.parseArray(config, FlowRule.class);
    FlowRuleManager.loadRules(rules); // 秒级生效
}

2. Sentinel Dashboard推送：
在这里插入图片描述

3. 文件监听方案：

FileWatchService.register("rules.json", path -> {
    String json = Files.readString(path);
    GatewayRuleManager.loadRules(JSON.parseObject(json));
});

九、响应式异常处理

1. 全局异常处理器：

@Bean
@Order(-1) // 最高优先级
public ErrorWebExceptionHandler exceptionHandler() {
    return (exchange, ex) -> {
        if (ex instanceof RateLimitException) {
            exchange.getResponse().setStatusCode(429);
            return writeResponse(exchange, "请求过快");
        }
        return Mono.error(ex);
    };
}

2. 过滤器链异常捕获：

public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
    return chain.filter(exchange)
        .onErrorResume(ex -> {
            metrics.recordError(ex); // 记录指标
            return Mono.fromRunnable(() -> 
                exchange.getResponse().setStatusCode(500)
            ).then(Mono.empty());
        });
}

十、基于角色的动态路由

public RouteLocator dynamicRoutes(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("admin_route", r -> r.path("/admin/**")
            .filters(f -> f.filter(roleFilter("ADMIN"))
            .uri("lb://admin-service")
        )
        .route("user_route", r -> r.path("/user/**")
            .filters(f -> f.filter(roleFilter("USER"))
            .uri("lb://user-service")
        ).build();
}

private GatewayFilter roleFilter(String role) {
    return (exchange, chain) -> {
        String userRole = getRoleFromToken(exchange);
        if(!role.equals(userRole)) {
            exchange.getResponse().setStatusCode(403);
            return exchange.getResponse().setComplete();
        }
        return chain.filter(exchange);
    };
}

十一、OAuth2无阻塞集成

@Bean
public SecurityWebFilterChain oauth2Filter(ServerHttpSecurity http) {
    return http
        .authorizeExchange(exchanges -> 
            exchanges.pathMatchers("/login").permitAll()
                    .anyExchange().authenticated()
        )
        .oauth2ResourceServer(server -> 
            server.jwt(jwt -> jwt.jwtAuthenticationConverter(jwtConverter()))
        )
        .build();
}

// 响应式JWT转换器
private Converter<Jwt, Mono<AbstractAuthenticationToken>> jwtConverter() {
    return jwt -> Mono.just(new JwtAuthenticationToken(jwt, getAuthorities(jwt)));
}

总结

Spring Cloud Gateway的核心优势：

响应式架构：基于WebFlux实现高并发（ $\geq 10k$ ）
动态扩展：支持路由/熔断规则热更新
云原生集成：无缝对接Sentinel/Nacos等组件
灵活过滤链：支持全局/路由级过滤器编排

生产建议：

使用spring-cloud-gateway-actuator监控路由状态
通过Micrometer暴露 $QPS$ / $RT$ / $E rror R a t e$ 指标
结合Grafana实现网关流量可视化
关键操作使用Schedulers.boundedElastic()隔离阻塞调用