Spring Cloud Gateway 实战：路由、断言与过滤器

2. 编写启动类

package com.cloud.gateway;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class GatewayApplication {
    public static void main(String[] args) {
        SpringApplication.run(GatewayApplication.class, args);
    }
}

3. 配置文件

server:
  port: 10030 # 网关端口
spring:
  application:
    name: gateway # 服务名称
  cloud:
    nacos:
      discovery:
        server-addr: nacos 的 ip 地址 + 端口号
    gateway:
      routes:
        - id: product-service # 路由 ID，自定义，唯一即可
          uri: lb://product-service # 目标服务地址
          predicates:
            - Path=/product/**
        - id: order-service
          uri: lb://order-service
          predicates:
            - Path=/order/**

这里 id 是路由唯一标识，uri 用 lb:// 前缀表示从注册中心（Nacos）拉取服务实例并负载均衡。predicates 下的 Path 断言匹配路径，比如 /product/** 的请求会转发到 product-service。

三、Route Predicate Factories

3.1 Predicate

Predicate 是 Java 8 提供的函数式接口，接收一个参数，返回 boolean，常用于条件过滤。

@FunctionalInterface
public interface Predicate<T> {
    boolean test(T t);
    // ...
}

简单实现一个判断字符串是否为空的 Predicate：

package predicate;

import java.util.function.Predicate;

public class StringPredicate implements Predicate<String> {
    @Override
    public boolean test(String s) {
        return s == null || s.isEmpty();
    }
}

用匿名内部类和 lambda 会更简洁：

// 匿名内部类
Predicate<String> p1 = new Predicate<String>() {
    @Override
    public boolean test(String s) {
        return s == null || s.isEmpty();
    }
};

// lambda 表达式
Predicate<String> p2 = s -> s == null || s.isEmpty();

其他常用方法：

• isEqual(Object targetRef)：比较相等
• and(Predicate other)：逻辑与
• or(Predicate other)：逻辑或
• negate()：逻辑非

3.2 Route Predicate Factories

在 Gateway 的配置文件里，predicates 下面写的字符串会由对应的 Route Predicate Factory 解析成真正的匹配规则。例如 Path=/product/** 就由 PathRoutePredicateFactory 处理。多个断言可以组合使用，全部满足路由才生效。

常用的内置断言工厂：

更多参考：Spring Cloud Gateway 请求断言工厂文档

3.3 Gateway Filter Factories

断言决定了请求走哪条路由，而过滤器（Filter）则负责在请求前后插入额外逻辑。它分为两种：

• Pre 过滤器：路由转发前执行，比如鉴权、限流
• Post 过滤器：请求执行完后，将结果返回客户端前执行

Gateway 内置了大量过滤器，从作用范围上又分为 GatewayFilter（单个路由）和 GlobalFilter（全局）。

3.3.1 GatewayFilter

可以在路由配置下通过 filters 直接使用。例如添加请求参数只需 AddRequestParameter，同样也是工厂模式。

常用 GatewayFilter：

RequestRateLimiter 配置示例：

filters:
  - name: RequestRateLimiter
    args:
      redis-rate-limiter.replenishRate: 10
      redis-rate-limiter.burstCapacity: 20
      redis-rate-limiter.requestedTokens: 1

Retry 示例：

filters:
  - name: Retry
    args:
      retries: 3
      statuses: BAD_REQUEST

RequestSize 示例：

filters:
  - name: RequestSize
    args:
      maxSize: 5000000  # 5MB

详细文档：GatewayFilter Factories

3.3.2 GlobalFilter

GlobalFilter 实现与 GatewayFilter 作用相同，但作用于所有路由。内置全局过滤器包括：

• Gateway Metrics Filter：输出监控指标
• Forward Routing Filter：本地 forward，不下发到下游
• LoadBalancer Client Filter：负载均衡

官方文档：Global Filters

3.4 过滤器执行顺序

当 GatewayFilter 和 GlobalFilter 并存时，Gateway 会把它们合并到一个过滤器链中，按 order 值升序执行。order 值越小优先级越高。相同 order 时，执行顺序为 defaultFilter > GatewayFilter > GlobalFilter。这个规则在定位过滤器问题时很重要。

3.5 自定义过滤器

我们也可以根据业务需求扩展过滤器，分 GatewayFilter 和 GlobalFilter 两种。

3.5.1 自定义 GatewayFilter

自定义 GatewayFilter 需实现 GatewayFilterFactory 接口，通常继承抽象类 AbstractGatewayFilterFactory。配置文件里可以传递参数，我们用一个配置类接收。

package com.cloud.gateway;

import lombok.Data;

@Data
public class CustomConfig {
    private String name;
}

过滤器实现：

package com.cloud.gateway;

import lombok.extern.slf4j.Slf4j;
import org.springframework.cloud.gateway.filter.GatewayFilter;
import org.springframework.cloud.gateway.filter.GatewayFilterChain;
import org.springframework.cloud.gateway.filter.factory.AbstractGatewayFilterFactory;
import org.springframework.core.Ordered;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Mono;

@Component
@Slf4j
public class CustomGatewayFilterFactory extends AbstractGatewayFilterFactory<CustomConfig> implements Ordered {

    public CustomGatewayFilterFactory() {
        super(CustomConfig.class);
    }

    @Override
    public GatewayFilter apply(CustomConfig config) {
        return (exchange, chain) -> {
            log.info("[Pre] Filter Request, name: {}", config.getName());
            return chain.filter(exchange).then(Mono.fromRunnable(() -> {
                log.info("[Post] Response Filter");
            }));
        };
    }

    @Override
    public int getOrder() {
        return Ordered.LOWEST_PRECEDENCE;
    }
}

配置使用：

spring:
  cloud:
    gateway:
      routes:
        - id: product-service
          uri: lb://product-service
          predicates:
            - Path=/product/**
          filters:
            - name: Custom
              args:
                name: custom filter

3.5.2 自定义 GlobalFilter

GlobalFilter 实现更为直接，实现 GlobalFilter 接口并交给 Spring 管理，无需额外配置。

package com.cloud.gateway;

import lombok.extern.slf4j.Slf4j;
import org.springframework.cloud.gateway.filter.GatewayFilterChain;
import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.core.Ordered;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Mono;

@Slf4j
@Component
public class CustomGlobalFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        log.info("[Pre] CustomGlobalFilter enter...");
        return chain.filter(exchange).then(Mono.fromRunnable(() -> {
            log.info("[Post] CustomGlobalFilter return...");
        }));
    }

    @Override
    public int getOrder() {
        return Ordered.LOWEST_PRECEDENCE;
    }
}