过滤器 #

一、过滤器概述 #

1.1 过滤器分类 #

text

┌─────────────────────────────────────────────────────────────┐
│                    Gateway过滤器分类                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌─────────────────────────────────────────────────────┐  │
│   │                  GatewayFilter                       │  │
│   │                （网关过滤器）                         │  │
│   │                                                      │  │
│   │   ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │  │
│   │   │ AddHeader   │  │ RewritePath │  │ StripPrefix│ │  │
│   │   └─────────────┘  └─────────────┘  └────────────┘ │  │
│   │                                                      │  │
│   │   作用于单个路由                                     │  │
│   └─────────────────────────────────────────────────────┘  │
│                                                             │
│   ┌─────────────────────────────────────────────────────┐  │
│   │                  GlobalFilter                        │  │
│   │                （全局过滤器）                         │  │
│   │                                                      │  │
│   │   ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │  │
│   │   │ Auth        │  │ Logging     │  │ Trace      │ │  │
│   │   └─────────────┘  └─────────────┘  └────────────┘ │  │
│   │                                                      │  │
│   │   作用于所有路由                                     │  │
│   └─────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

1.2 过滤器执行顺序 #

text

请求 ──► 前置过滤器 ──► 代理请求 ──► 后置过滤器 ──► 响应

GlobalFilter (Order=-100)
    │
    ▼
GatewayFilter (前置)
    │
    ▼
代理请求
    │
    ▼
GatewayFilter (后置)
    │
    ▼
GlobalFilter (Order=100)

二、内置过滤器 #

2.1 请求头过滤器 #

yaml

spring:
  cloud:
    gateway:
      routes:
        - id: header-route
          uri: lb://user-service
          predicates:
            - Path=/user/**
          filters:
            - AddRequestHeader=X-Request-Foo, Bar
            - AddRequestHeader=X-Request-Time, ${spring.cloud.client.ip-address}
            - RemoveRequestHeader=X-Request-Id
            - SetRequestHeader=X-Request-Auth, Bearer token
            - MapRequestHeader=X-Request-Id, X-Trace-Id

2.2 响应头过滤器 #

yaml

spring:
  cloud:
    gateway:
      routes:
        - id: response-header-route
          uri: lb://user-service
          predicates:
            - Path=/user/**
          filters:
            - AddResponseHeader=X-Response-Foo, Bar
            - RemoveResponseHeader=X-Response-Id
            - SetResponseHeader=X-Response-Type, Gateway
            - DedupeResponseHeader=Access-Control-Allow-Origin

2.3 请求参数过滤器 #

yaml

spring:
  cloud:
    gateway:
      routes:
        - id: param-route
          uri: lb://user-service
          predicates:
            - Path=/user/**
          filters:
            - AddRequestParameter=foo, bar
            - AddRequestParameter=timestamp, ${spring.cloud.client.ip-address}

2.4 路径过滤器 #

yaml

spring:
  cloud:
    gateway:
      routes:
        - id: path-route
          uri: lb://user-service
          predicates:
            - Path=/api/user/**
          filters:
            - StripPrefix=2
            
        - id: prefix-route
          uri: lb://user-service
          predicates:
            - Path=/user/**
          filters:
            - PrefixPath=/api
            
        - id: rewrite-route
          uri: lb://user-service
          predicates:
            - Path=/api/user/(?<segment>.*)
          filters:
            - RewritePath=/api/user/(?<segment>.*), /$\{segment}
            
        - id: set-path-route
          uri: lb://user-service
          predicates:
            - Path=/api/user/(?<segment>.*)
          filters:
            - SetPath=/${segment}

2.5 状态码过滤器 #

yaml

spring:
  cloud:
    gateway:
      routes:
        - id: status-route
          uri: lb://user-service
          predicates:
            - Path=/user/**
          filters:
            - SetStatus=200

2.6 重定向过滤器 #

yaml

spring:
  cloud:
    gateway:
      routes:
        - id: redirect-route
          uri: lb://user-service
          predicates:
            - Path=/old/**
          filters:
            - RedirectTo=302, https://example.com/new

2.7 熔断过滤器 #

yaml

spring:
  cloud:
    gateway:
      routes:
        - id: circuit-breaker-route
          uri: lb://user-service
          predicates:
            - Path=/user/**
          filters:
            - name: CircuitBreaker
              args:
                name: userServiceCircuitBreaker
                fallbackUri: forward:/fallback

2.8 重试过滤器 #

yaml

spring:
  cloud:
    gateway:
      routes:
        - id: retry-route
          uri: lb://user-service
          predicates:
            - Path=/user/**
          filters:
            - name: Retry
              args:
                retries: 3
                statuses: BAD_GATEWAY,SERVICE_UNAVAILABLE
                methods: GET
                backoff:
                  firstBackoff: 100ms
                  maxBackoff: 500ms
                  factor: 2

2.9 限流过滤器 #

yaml

spring:
  cloud:
    gateway:
      routes:
        - id: rate-limit-route
          uri: lb://user-service
          predicates:
            - Path=/user/**
          filters:
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 10
                redis-rate-limiter.burstCapacity: 20
                key-resolver: "#{@userKeyResolver}"

2.10 安全头过滤器 #

yaml

spring:
  cloud:
    gateway:
      routes:
        - id: secure-route
          uri: lb://user-service
          predicates:
            - Path=/user/**
          filters:
            - SecureHeaders

三、全局过滤器 #

3.1 认证过滤器 #

java

@Component
public class AuthGlobalFilter implements GlobalFilter, Ordered {

    private static final String TOKEN_HEADER = "Authorization";
    
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String token = exchange.getRequest().getHeaders().getFirst(TOKEN_HEADER);
        
        if (token == null || token.isEmpty()) {
            exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
            return exchange.getResponse().setComplete();
        }
        
        if (!validateToken(token)) {
            exchange.getResponse().setStatusCode(HttpStatus.FORBIDDEN);
            return exchange.getResponse().setComplete();
        }
        
        return chain.filter(exchange);
    }

    private boolean validateToken(String token) {
        return true;
    }

    @Override
    public int getOrder() {
        return -100;
    }
}

3.2 日志过滤器 #

java

@Component
public class LoggingGlobalFilter implements GlobalFilter, Ordered {

    private static final Logger log = LoggerFactory.getLogger(LoggingGlobalFilter.class);

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        ServerHttpRequest request = exchange.getRequest();
        
        String requestId = UUID.randomUUID().toString();
        long startTime = System.currentTimeMillis();
        
        log.info("[{}] Request: {} {}", requestId, request.getMethod(), request.getURI());
        
        exchange.getAttributes().put("requestId", requestId);
        exchange.getAttributes().put("startTime", startTime);
        
        return chain.filter(exchange).then(Mono.fromRunnable(() -> {
            Long duration = System.currentTimeMillis() - startTime;
            log.info("[{}] Response: {} {}ms", 
                requestId, 
                exchange.getResponse().getStatusCode(),
                duration);
        }));
    }

    @Override
    public int getOrder() {
        return -200;
    }
}

3.3 跨域过滤器 #

java

@Component
public class CorsGlobalFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        ServerHttpRequest request = exchange.getRequest();
        
        if (CorsUtils.isCorsRequest(request)) {
            HttpHeaders headers = exchange.getResponse().getHeaders();
            headers.add("Access-Control-Allow-Origin", "*");
            headers.add("Access-Control-Allow-Methods", "GET,POST,PUT,DELETE,OPTIONS");
            headers.add("Access-Control-Allow-Headers", "*");
            headers.add("Access-Control-Max-Age", "3600");
            
            if (request.getMethod() == HttpMethod.OPTIONS) {
                exchange.getResponse().setStatusCode(HttpStatus.OK);
                return exchange.getResponse().setComplete();
            }
        }
        
        return chain.filter(exchange);
    }

    @Override
    public int getOrder() {
        return -300;
    }
}

3.4 请求追踪过滤器 #

java

@Component
public class TraceGlobalFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String traceId = UUID.randomUUID().toString().replace("-", "");
        String spanId = UUID.randomUUID().toString().replace("-", "");
        
        ServerHttpRequest request = exchange.getRequest().mutate()
                .header("X-Trace-Id", traceId)
                .header("X-Span-Id", spanId)
                .build();
        
        exchange.getResponse().getHeaders().add("X-Trace-Id", traceId);
        
        return chain.filter(exchange.mutate().request(request).build());
    }

    @Override
    public int getOrder() {
        return -150;
    }
}

四、自定义过滤器 #

4.1 自定义网关过滤器 #

java

@Component
public class CustomGatewayFilterFactory extends AbstractGatewayFilterFactory<CustomGatewayFilterFactory.Config> {

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

    @Override
    public GatewayFilter apply(Config config) {
        return (exchange, chain) -> {
            ServerHttpRequest request = exchange.getRequest().mutate()
                    .header("X-Custom-Header", config.getHeaderValue())
                    .build();
            
            return chain.filter(exchange.mutate().request(request).build())
                    .then(Mono.fromRunnable(() -> {
                        exchange.getResponse().getHeaders()
                                .add("X-Custom-Response", config.getResponseValue());
                    }));
        };
    }

    public static class Config {
        private String headerValue;
        private String responseValue;

        public String getHeaderValue() {
            return headerValue;
        }

        public void setHeaderValue(String headerValue) {
            this.headerValue = headerValue;
        }

        public String getResponseValue() {
            return responseValue;
        }

        public void setResponseValue(String responseValue) {
            this.responseValue = responseValue;
        }
    }
}

4.2 使用自定义过滤器 #

yaml

spring:
  cloud:
    gateway:
      routes:
        - id: custom-filter-route
          uri: lb://user-service
          predicates:
            - Path=/user/**
          filters:
            - name: Custom
              args:
                headerValue: foo
                responseValue: bar

4.3 带配置的过滤器 #

java

@Component
public class AuthGatewayFilterFactory extends AbstractGatewayFilterFactory<AuthGatewayFilterFactory.Config> {

    public AuthGatewayFilterFactory() {
        super(Config.class);
    }

    @Override
    public GatewayFilter apply(Config config) {
        return (exchange, chain) -> {
            String token = exchange.getRequest().getHeaders().getFirst(config.getHeaderName());
            
            if (token == null || !validateToken(token, config.getSecret())) {
                exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
                return exchange.getResponse().setComplete();
            }
            
            return chain.filter(exchange);
        };
    }

    private boolean validateToken(String token, String secret) {
        return true;
    }

    public static class Config {
        private String headerName = "Authorization";
        private String secret;

        public String getHeaderName() {
            return headerName;
        }

        public void setHeaderName(String headerName) {
            this.headerName = headerName;
        }

        public String getSecret() {
            return secret;
        }

        public void setSecret(String secret) {
            this.secret = secret;
        }
    }
}

五、过滤器配置 #

5.1 Default Filters #

yaml

spring:
  cloud:
    gateway:
      default-filters:
        - AddResponseHeader=X-Response-Time, ${spring.cloud.client.ip-address}
        - AddRequestHeader=X-Gateway, SpringCloudGateway

5.2 过滤器顺序 #

java

@Component
public class OrderedGlobalFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        return chain.filter(exchange);
    }

    @Override
    public int getOrder() {
        return -100;
    }
}

Order值	执行顺序
负数	前置处理
0	中间处理
正数	后置处理

六、最佳实践 #

6.1 过滤器组织 #

java

@Configuration
public class FilterConfig {

    @Bean
    public GlobalFilter authFilter() {
        return new AuthGlobalFilter();
    }

    @Bean
    public GlobalFilter loggingFilter() {
        return new LoggingGlobalFilter();
    }

    @Bean
    public GlobalFilter traceFilter() {
        return new TraceGlobalFilter();
    }
}

6.2 注意事项 #

注意点	说明
过滤器顺序	合理设置Order值
异常处理	过滤器中处理异常
性能考虑	避免耗时操作
响应式编程	使用Mono/Flux

七、总结 #

7.1 核心要点 #

要点	说明
GatewayFilter	作用于单个路由
GlobalFilter	作用于所有路由
过滤器顺序	Order控制执行顺序
自定义过滤器	继承AbstractGatewayFilterFactory

7.2 下一步 #

现在你已经掌握了过滤器的使用，接下来让我们学习限流熔断，了解Gateway的限流和熔断机制！