Spring Cloud Gateway怎么用？

wen python案例 2026-07-21 265

本文目录导读：

核心概念
快速开始（Spring Boot 3.x / Spring Cloud 2023.x）
常用断言（Predicate）示例
常用过滤器（Filter）
高级功能
完整的实战配置模板

Spring Cloud Gateway 是一个基于 Spring WebFlux 的 API 网关，用于替代 Zuul，它提供了路由、过滤、限流、熔断等功能，下面从 核心概念 到 实际配置 一步步说明。

核心概念

Route（路由）：网关的基本构建块，由 ID、目标 URI、断言集合和过滤器集合组成。
Predicate（断言）：匹配 HTTP 请求的条件（如路径、Header、参数等）。
Filter（过滤器）：对请求或响应进行修改的拦截器（分 Pre 和 Post 两种）。

快速开始（Spring Boot 3.x / Spring Cloud 2023.x）

1 引入依赖

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>

注意：Gateway 基于 WebFlux，不要引入 spring-boot-starter-web（会冲突）。

2 基础配置（application.yml）

server:
  port: 8080
spring:
  cloud:
    gateway:
      routes:
        - id: user-service           # 路由ID，唯一
          uri: lb://user-service     # 目标服务（lb:// 表示从注册中心获取）
          predicates:
            - Path=/api/user/**      # 匹配 /api/user/ 开头的请求
          filters:
            - StripPrefix=1          # 去掉第一级路径（即去掉 /api）
        - id: order-service
          uri: lb://order-service
          predicates:
            - Path=/api/order/**
          filters:
            - StripPrefix=1

3 启用服务发现

spring:
  application:
    name: api-gateway
  cloud:
    nacos:                         # 或 Eureka / Consul
      discovery:
        server-addr: localhost:8848

常用断言（Predicate）示例

routes:
  - id: demo
    uri: http://localhost:8081
    predicates:
      - Path=/demo/**              # 路径匹配
      - Method=GET,POST            # HTTP方法
      - Header=X-Request-Id, \d+   # Header匹配
      - Query=token, .+            # 参数匹配
      - Cookie=sessionId, .*       # Cookie匹配
      - After=2023-01-01T00:00:00Z # 时间后
      - Before=2024-01-01T00:00:00Z
      - Between=2023-01-01,2024-01-01
      - RemoteAddr=192.168.1.1/24  # IP匹配

常用过滤器（Filter）

1 内置过滤器配置

filters:
  - StripPrefix=1                  # 去前缀
  - PrefixPath=/api                # 加前缀
  - AddRequestHeader=X-Header, value
  - AddRequestParameter=name, value
  - AddResponseHeader=X-Response, value
  - RemoveRequestHeader=Origin
  - SetStatus=200                  # 强制设置状态码
  - Retry=3                        # 重试
  - CircuitBreaker=myCircuitBreaker # 熔断

2 自定义过滤器（Java 方式）

Pre 过滤器（请求到达目标前执行）：

@Component
@Slf4j
public class PreGatewayFilter implements GatewayFilter, Ordered {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        // 获取请求信息
        ServerHttpRequest request = exchange.getRequest();
        log.info("Request path: {}", request.getURI().getPath());
        // 可以修改请求（例如添加Header）
        ServerHttpRequest modifiedRequest = request.mutate()
                .header("X-Gateway", "true")
                .build();
        ServerWebExchange modifiedExchange = exchange.mutate().request(modifiedRequest).build();
        // 继续执行过滤链
        return chain.filter(modifiedExchange);
    }
    @Override
    public int getOrder() {
        return -1; // 数字越小优先级越高
    }
}

在路由中引用自定义过滤器：

routes:
  - id: custom-filter-demo
    uri: http://localhost:8081
    predicates:
      - Path=/test/**
    filters:
      - name: PreGatewayFilter  # 自动注入的Bean名称

全局过滤器（对所有路由生效）：

@Component
public class GlobalAuthFilter implements GlobalFilter, Ordered {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        // 校验Token
        String token = exchange.getRequest().getHeaders().getFirst("Authorization");
        if (token == null || !token.startsWith("Bearer ")) {
            exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
            return exchange.getResponse().setComplete();
        }
        return chain.filter(exchange);
    }
    @Override
    public int getOrder() {
        return -100; // 高优先级
    }
}

高级功能

1 熔断降级（整合 Sentinel 或 Resilience4j）

spring:
  cloud:
    gateway:
      routes:
        - id: sentinel-demo
          uri: http://localhost:8081
          predicates:
            - Path=/api/**
          filters:
            - name: RequestRateLimiter
              args:
                key-resolver: "#{@userKeyResolver}"
                redis-rate-limiter.replenishRate: 10
                redis-rate-limiter.burstCapacity: 20
            - name: CircuitBreaker
              args:
                name: myCircuitBreaker
                fallbackUri: forward:/fallback

2 跨域配置

spring:
  cloud:
    gateway:
      globalcors:
        cors-configurations:
          '[/**]':
            allowedOrigins: "*"
            allowedMethods:
              - GET
              - POST
              - PUT
              - DELETE
            allowedHeaders: "*"

3 动态路由（从数据库加载）

@Bean
public RouteDefinitionLocator routeDefinitionLocator(
        RouteDefinitionRepository repository) {
    return new CachingRouteDefinitionLocator(repository);
}

实现 RouteDefinitionRepository 接口，从数据库读取路由配置，并调用 ApplicationEventPublisher.publishEvent(new RefreshRoutesEvent(this)) 刷新路由。

完整的实战配置模板

server:
  port: 8080
spring:
  application:
    name: api-gateway
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
    gateway:
      routes:
        # 用户服务
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/api/user/**
          filters:
            - StripPrefix=1
            - name: RequestRateLimiter
              args:
                key-resolver: "#{@userKeyResolver}"
                redis-rate-limiter.replenishRate: 10
                redis-rate-limiter.burstCapacity: 20
        # 订单服务
        - id: order-service
          uri: lb://order-service
          predicates:
            - Path=/api/order/**
          filters:
            - StripPrefix=1
            - name: CircuitBreaker
              args:
                name: orderCircuitBreaker
                fallbackUri: forward:/fallback/order
      globalcors:
        cors-configurations:
          '[/**]':
            allowedOrigins: "*"
            allowedMethods:
              - GET
              - POST
              - PUT
              - DELETE
            allowedHeaders: "*"
  redis:
    host: localhost
    port: 6379
logging:
  level:
    org.springframework.cloud.gateway: DEBUG

阶段	关键点
依赖	使用 `spring-cloud-starter-gateway`，不要引入 web 模块
配置	YAML 中定义 routes，组合 predicates 和 filters
路由	用 `Path` 断言匹配路径，`lb://` 实现负载均衡
过滤器	内置过滤器通过 YAML 配置，复杂逻辑用 Java 自定义
高级功能	熔断（Sentinel/Resilience4j）、限流（Redis）、跨域

你就可以使用 Spring Cloud Gateway 搭建生产级的 API 网关服务了。

本文地址： https://www.bmjup.com/post/26813.html