Spring Cloud Gateway 统一服务入口实战指南

编写启动类

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

配置路由

在 application.yml 中添加网关路由配置。这里以 Nacos 为例：

server:
  port: 10030 # 网关端口
spring:
  application:
    name: gateway # 服务名称
  cloud:
    nacos:
      discovery:
        server-addr: 110.41.51.65:10020
    gateway:
      routes:
        - id: product-service # 路由 ID，自定义，保持唯一
          uri: lb://product-service # 目标服务地址，lb 表示从注册中心获取
          predicates:
            - Path=/product/** # 路由条件：匹配 /product 开头的路径
        - id: order-service
          uri: lb://order-service
          predicates:
            - Path=/order/**

配置说明：

• id：子定义路由 ID，必须唯一。
• uri：目标服务地址，支持普通 URI 或 lb:// 服务名。使用 lb:// 表示启用负载均衡，从注册中心拉取实例。
• predicates：路由断言，决定请求是否匹配该路由。上述配置将 /product/** 的请求代理到 product-service。

访问示例：http://127.0.0.1:10030/order/1

Route Predicate Factories（路由断言工厂）

Predicate 基础

Predicate 是 Java 8 提供的函数式编程接口，接收参数返回布尔值，用于条件过滤。在 Gateway 中，它提供了路由规则的匹配机制。

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

代码演示：

// Lambda 写法
Predicate<String> predicate = s -> s.isEmpty();
System.out.println(predicate.test("")); // true
System.out.println(predicate.test("bite666")); // false

Predicate 还支持组合操作，如 and()（短路与）、or()（短路或）、negate()（逻辑非）。

常用断言工厂

Route Predicate Factory 将配置文件中的字符串规则转换为判断条件。例如 Path=/product/** 是由 PathRoutePredicateFactory 实现的。

Spring Cloud Gateway 默认提供了丰富的断言工厂，可匹配 HTTP 请求的不同属性，且支持多条件组合。

配置演示：

spring:
  cloud:
    gateway:
      routes:
        - id: product-service
          uri: lb://product-service
          predicates:
            - Path=/product/**
            - After=2026-01-01T00:00:00.000+08:00[Asia/Shanghai] # 时间限制

这样配置后，只有在指定时间之后的请求才能通过。

Gateway Filter Factories（过滤器工厂）

Predicate 决定了请求由哪个路由处理，而 Filter 则负责在请求处理前后添加逻辑。

Filter 分为两种类型：

• Pre 类型：路由处理之前执行（转发到后端前），适合做鉴权、限流。
• Post 类型：请求完成后，返回给客户端前执行，适合记录日志、修改响应头。

Spring Cloud Gateway 从作用范围上把 Filter 分为两类：

• GatewayFilter：应用到单个路由或一组路由。
• GlobalFilter：应用到所有路由，全局生效。

GatewayFilter 使用

GatewayFilter 通常在配置文件中指定，逻辑固定。例如 AddRequestParameterGatewayFilterFactory 可为请求添加参数。

配置示例：

spring:
  cloud:
    gateway:
      routes:
        - id: product-service
          uri: lb://product-service
          predicates:
            - Path=/product/**
          filters:
            - AddRequestParameter=userName, bite # 为请求添加参数

此 Filter 仅对 product-service 路由生效。后端控制器接收参数即可：

@RequestMapping("/{productId}")
public ProductInfo getProductById(@PathVariable("productId") Integer productId, String userName) {
    System.out.println("收到请求，Id:" + productId);
    System.out.println("userName:" + userName);
    return productService.selectProductById(productId);
}

若需对所有路由生效，可使用 default-filters：

spring:
  cloud:
    gateway:
      default-filters:
        - AddResponseHeader=X-Response-Default-Red,Default-Blue
        - PrefixPath=/httpbin

GlobalFilter 使用

GlobalFilter 作用于所有请求，常用于安全、监控、日志等全局功能。内置的全局过滤器包括 Gateway Metrics Filter（监控指标）、LoadBalancer Client Filter（负载均衡）等。

开启监控：

1. 添加 Actuator 依赖。
2. 配置 application.yml：

spring:
  cloud:
    gateway:
      metrics:
        enabled: true
  management:
    endpoints:
      web:
        exposure:
          include: "*"
    endpoint:
      health:
        show-details: always
      shutdown:
        enabled: true

访问 http://127.0.0.1:10030/actuator 即可查看监控信息。

过滤器执行顺序

当项目中同时存在 GatewayFilter 和 GlobalFilter 时，网关会将它们合并到一个过滤器链中排序执行。

每个过滤器必须指定 int 类型的 order 值，默认为 0。值越小，优先级越高，执行越靠前。

• 通过实现 Ordered 接口或添加 @Order 注解指定。
• Spring Cloud Gateway 提供的 Filter 由框架指定。
• 当 order 值相同时，执行顺序为：defaultFilter > GatewayFilter > GlobalFilter。

自定义过滤器

开发者可根据业务需求自定义过滤器，同样支持 GatewayFilter 和 GlobalFilter 两种模式。

自定义 GatewayFilter

实现 AbstractGatewayFilterFactory 抽象类即可。

1. 定义过滤器工厂：

@Slf4j
@Service
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; // 优先级最低
    }

    @Data
    public static class CustomConfig {
        private String name;
    }
}

2. 配置使用：

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

注意：类名建议以 GatewayFilterFactory 结尾，配置中使用 name 字段匹配类名前缀。

自定义 GlobalFilter

GlobalFilter 实现更简单，无需额外配置，只需实现 GlobalFilter 接口。

@Slf4j
@Service
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;
    }
}

总结

Spring Cloud Gateway 作为微服务架构的统一入口，提供了强大的路由匹配和过滤器扩展能力。通过合理配置 Predicates 和 Filters，我们可以轻松实现鉴权、限流、监控等横切关注点，有效降低业务系统的耦合度。在实际开发中，建议优先使用内置工厂满足通用需求，复杂场景下再考虑自定义扩展。