Spring Cloud Gateway 内置 Filter 实战：AddRequestHeader 与 RewritePath

上述配置会在路径匹配 /api/service-a/** 时，自动添加两个请求头。

Java 配置示例

import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.cloud.gateway.route.builder.RouteLocatorBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class GatewayConfig {
    @Bean
    public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
        return builder.routes()
            .route("add-header-route", r -> r.path("/api/service-a/**")
                .filters(f -> f.addRequestHeader("X-Forwarded-For", "192.168.1.1")
                    .addRequestHeader("X-Custom-Header", "MyValue"))
                .uri("lb://service-a"))
            .build();
    }
}

实际应用与注意事项

在实际场景中，我们常利用 SpEL 表达式动态设置 Header 值。例如获取当前时间戳或从环境变量读取配置。

filters:
  - name: AddRequestHeader
    args:
      name: X-Client-ID
      value: ${client.id:default-client}
  - name: AddRequestHeader
    args:
      name: X-Request-Timestamp
      value: #{T(java.time.Instant).now().toEpochMilli()}

注意：name 和 value 参数必须提供，且添加的 Header 会随请求一同转发给下游服务。

2.2 RewritePath Filter

当网关暴露的 API 路径与后端服务的内部路径不一致时，RewritePath 非常有用。它允许修改请求的路径部分。

配置方式

通过正则表达式匹配原始路径，并使用捕获组进行替换。

YAML 配置示例

spring:
  cloud:
    gateway:
      routes:
        - id: rewrite-path-route
          uri: lb://backend-service
          predicates:
            - Path=/api/v1/**
          filters:
            - name: RewritePath
              args:
                regexp: /api/v1/(?<segment>.*)
                replacement: /${segment}

此配置将 /api/v1/users/123 重写为 /users/123 后转发。

Java 配置示例

@Bean
public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("rewrite-path-route", r -> r.path("/api/v1/**")
            .filters(f -> f.rewritePath("/api/v1/(?<segment>.*)", "/${segment}"))
            .uri("lb://backend-service"))
        .build();
}

正则表达式详解

regexp 定义匹配规则，replacement 定义替换逻辑。${groupName} 用于引用命名捕获组。

• 简单重写: /api/v1/(?<segment>.*) 替换为 /${segment}
• 多参数重写: 可捕获多个分组，如 userId 和 orderId
• 查询参数: RewritePath 默认只修改路径，不影响查询参数（Query Parameters）

注意事项

• 确保正则表达式有效，否则可能导致请求被拒绝。
• 仅改变路径部分，不影响 HTTP 方法和查询参数。
• 避免过度使用导致路径逻辑混乱。

2.3 其他常用内置 Filter

除了上述两个，还有一些常用 Filter 值得了解：

• SetStatus: 直接设置响应状态码，如返回 404。
• AddResponseHeader: 在响应返回客户端前添加响应头。
• StripPrefix: 移除路径开头的指定段数，如移除 /api/v1/。
• PrefixPath: 在路径前添加前缀，常用于内部服务路径映射。

三、实战演练：构建网关服务

为了验证效果，我们可以快速搭建一个测试项目。

3.1 项目准备

使用 Spring Initializr 创建项目，依赖选择 Spring WebFlux、Spring Cloud Gateway 和 Actuator。

3.2 配置文件

在 application.yml 中定义路由规则，这里以 httpbin.org 作为测试后端。

server:
  port: 8080
spring:
  application:
    name: gateway-demo
  cloud:
    gateway:
      routes:
        # 添加请求头测试
        - id: header-test-route
          uri: https://httpbin.org
          predicates:
            - Path=/api/header-test/**
          filters:
            - name: AddRequestHeader
              args:
                name: X-Gateway-Source
                value: gateway-demo
        # 路径重写测试
        - id: rewrite-test-route
          uri: https://httpbin.org
          predicates:
            - Path=/api/rewrite-test/**
          filters:
            - name: RewritePath
              args:
                regexp: /api/rewrite-test/(?<rest>.*)
                replacement: /${rest}
management:
  endpoints:
    web:
      exposure:
        include: "*"

3.3 启动与测试

启动主类后，可通过 curl 验证效果。

• 测试 Header: curl http://localhost:8080/api/header-test/get
• 测试 Rewrite: curl http://localhost:8080/api/rewrite-test/post

访问 httpbin.org/headers 可查看实际接收到的请求头信息。

四、Filter 执行顺序

理解执行顺序对于调试至关重要。

1. 全局前置过滤器 (Global Pre Filters): 在所有路由匹配前执行。
2. 路由过滤器 (Route Filters): 针对特定路由生效。
3. 全局后置过滤器 (Global Post Filters): 在路由匹配后执行。

可以通过实现 Ordered 接口并返回数字来控制优先级，数字越小优先级越高。

@Component
public class CustomGatewayFilter implements GatewayFilter, Ordered {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        System.out.println("Before routing");
        return chain.filter(exchange).then(Mono.fromRunnable(() -> {
            System.out.println("After routing");
        }));
    }

    @Override
    public int getOrder() {
        return 1;
    }
}

五、高级场景与优化

5.1 动态 Header 注入

利用 SpEL 表达式，可以实时获取请求中的 User-Agent 或生成唯一追踪 ID，便于链路追踪。

5.2 复杂路径映射

对于多层级路径，可组合使用多个 Filter 或使用更复杂的正则表达式进行提取和重组。

5.3 性能建议

• 合理使用: 并非所有场景都需要 Filter，过多会增加处理开销。
• 监控日志: 为关键 Filter 添加日志，便于排查问题。
• 缓存预热: 对高频路由考虑缓存策略。

六、总结

Spring Cloud Gateway 的内置 Filter 极大地简化了网关开发流程。掌握 AddRequestHeader 和 RewritePath 的使用，能够灵活应对大多数路由和协议转换需求。合理的设计与配置是保证网关高效运行的关键。

参考资料：

• Spring Cloud Gateway 官方文档
• Spring Cloud Gateway GitHub