Spring Cloud Gateway 內(nèi)置的過(guò)濾器工廠

本文基于Spring Cloud Greenwich SR2

[TOC]

內(nèi)置的過(guò)濾器工廠

這里簡(jiǎn)單將Spring Cloud Gateway內(nèi)置的所有過(guò)濾器工廠整理成了一張表格，雖然不是很詳細(xì)，但能作為速覽使用。如下：

Tips：每個(gè)過(guò)濾器工廠都對(duì)應(yīng)一個(gè)實(shí)現(xiàn)類，并且這些類的名稱必須以GatewayFilterFactory結(jié)尾，這是Spring Cloud Gateway的一個(gè)約定，例如AddRequestHeader對(duì)應(yīng)的實(shí)現(xiàn)類為AddRequestHeaderGatewayFilterFactory。對(duì)源碼感興趣的小伙伴就可以按照這個(gè)規(guī)律拼接出具體的類名，以此查找這些內(nèi)置過(guò)濾器工廠的實(shí)現(xiàn)代碼

1、AddRequestHeader GatewayFilter Factory

為原始請(qǐng)求添加Header，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: add_request_header_route
        uri: https://example.org
        filters:
        - AddRequestHeader=X-Request-Foo, Bar

為原始請(qǐng)求添加名為 X-Request-Foo ，值為 Bar 的請(qǐng)求頭

2、AddRequestParameter GatewayFilter Factory

為原始請(qǐng)求添加請(qǐng)求參數(shù)及值，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: add_request_parameter_route
        uri: https://example.org
        filters:
        - AddRequestParameter=foo, bar

為原始請(qǐng)求添加名為foo，值為bar的參數(shù)，即：foo=bar

3、AddResponseHeader GatewayFilter Factory

為原始響應(yīng)添加Header，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: add_response_header_route
        uri: https://example.org
        filters:
        - AddResponseHeader=X-Response-Foo, Bar

為原始響應(yīng)添加名為 X-Request-Foo ，值為 Bar 的響應(yīng)頭

4、DedupeResponseHeader GatewayFilter Factory

DedupeResponseHeader可以根據(jù)配置的Header名稱及去重策略剔除響應(yīng)頭中重復(fù)的值，這是Spring Cloud Greenwich SR2提供的新特性，低于這個(gè)版本無(wú)法使用。

我們?cè)贕ateway以及微服務(wù)上都設(shè)置了CORS（解決跨域）Header的話，如果不做任何配置，那么請(qǐng)求 -> 網(wǎng)關(guān) -> 微服務(wù)，獲得的CORS Header的值，就將會(huì)是這樣的：

Access-Control-Allow-Credentials: true, true
Access-Control-Allow-Origin: https://musk.mars, https://musk.mars

可以看到這兩個(gè)Header的值都重復(fù)了，若想把這兩個(gè)Header的值去重的話，就需要使用到DedupeResponseHeader，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: dedupe_response_header_route
        uri: https://example.org
        filters:
        # 若需要去重的Header有多個(gè)，使用空格分隔
        - DedupeResponseHeader=Access-Control-Allow-Credentials Access-Control-Allow-Origin

去重策略：

• RETAIN_FIRST：默認(rèn)值，保留第一個(gè)值
• RETAIN_LAST：保留最后一個(gè)值
• RETAIN_UNIQUE：保留所有唯一值，以它們第一次出現(xiàn)的順序保留

若想對(duì)該過(guò)濾器工廠有個(gè)比較全面的了解的話，建議閱讀該過(guò)濾器工廠的源碼，因?yàn)樵创a里有詳細(xì)的注釋及示例，比官方文檔寫得還好：org.springframework.cloud.gateway.filter.factory.DedupeResponseHeaderGatewayFilterFactory

5、Hystrix GatewayFilter Factory

為路由引入Hystrix的斷路器保護(hù)，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: hystrix_route
        uri: https://example.org
        filters:
        - Hystrix=myCommandName

Hystrix是Spring Cloud第一代容錯(cuò)組件，不過(guò)已經(jīng)進(jìn)入維護(hù)模式，未來(lái)Hystrix會(huì)被Spring Cloud移除掉，取而代之的是Alibaba Sentinel/Resilience4J。所以本文不做詳細(xì)介紹了，感興趣的話可以參考官方文檔：

• Hystrix GatewayFilter Factory

6、FallbackHeaders GatewayFilter Factory

同樣是對(duì)Hystrix的支持，上一小節(jié)所介紹的過(guò)濾器工廠支持一個(gè)配置參數(shù)：fallbackUri，該配置用于當(dāng)發(fā)生異常時(shí)將請(qǐng)求轉(zhuǎn)發(fā)到一個(gè)特定的uri上。而FallbackHeaders這個(gè)過(guò)濾工廠可以在轉(zhuǎn)發(fā)請(qǐng)求到該uri時(shí)添加一個(gè)Header，這個(gè)Header的值為具體的異常信息。配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: ingredients
        uri: lb://ingredients
        predicates:
        - Path=//ingredients/**
        filters:
        - name: Hystrix
          args:
            name: fetchIngredients
            fallbackUri: forward:/fallback
      - id: ingredients-fallback
        uri: http://localhost:9994
        predicates:
        - Path=/fallback
        filters:
        - name: FallbackHeaders
          args:
            executionExceptionTypeHeaderName: Test-Header

這里也不做詳細(xì)介紹了，感興趣可以參考官方文檔：

• FallbackHeaders GatewayFilter Factory

7、PrefixPath GatewayFilter Factory

為原始的請(qǐng)求路徑添加一個(gè)前綴路徑，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: prefixpath_route
        uri: https://example.org
        filters:
        - PrefixPath=/mypath

該配置使訪問(wèn)${GATEWAY_URL}/hello 會(huì)轉(zhuǎn)發(fā)到https://example.org/mypath/hello

8、PreserveHostHeader GatewayFilter Factory

為請(qǐng)求添加一個(gè)preserveHostHeader=true的屬性，路由過(guò)濾器會(huì)檢查該屬性以決定是否要發(fā)送原始的Host Header。配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: preserve_host_route
        uri: https://example.org
        filters:
        - PreserveHostHeader

如果不設(shè)置，那么名為 Host 的Header將由Http Client控制

9、RequestRateLimiter GatewayFilter Factory

用于對(duì)請(qǐng)求進(jìn)行限流，限流算法為令牌桶。配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: requestratelimiter_route
        uri: https://example.org
        filters:
        - name: RequestRateLimiter
          args:
            redis-rate-limiter.replenishRate: 10
            redis-rate-limiter.burstCapacity: 20

由于另一篇文章中已經(jīng)介紹過(guò)如何使用該過(guò)濾器工廠實(shí)現(xiàn)網(wǎng)關(guān)限流，所以這里就不再贅述了：

• Spring Cloud Gateway - 擴(kuò)展

或者參考官方文檔：

• RequestRateLimiter GatewayFilter Factory

10、RedirectTo GatewayFilter Factory

將原始請(qǐng)求重定向到指定的Url，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: redirect_route
        uri: https://example.org
        filters:
        - RedirectTo=302, https://acme.org

該配置使訪問(wèn) ${GATEWAY_URL}/hello 會(huì)被重定向到 https://acme.org/hello ，并且攜帶一個(gè) Location:http://acme.org 的Header，而返回客戶端的HTTP狀態(tài)碼為302

注意事項(xiàng)：

• HTTP狀態(tài)碼應(yīng)為3xx，例如301
• URL必須是合法的URL，該URL會(huì)作為Location Header的值

11、RemoveHopByHopHeadersFilter GatewayFilter Factory

為原始請(qǐng)求刪除IETF組織規(guī)定的一系列Header，默認(rèn)刪除的Header如下：

• Connection
• Keep-Alive
• Proxy-Authenticate
• Proxy-Authorization
• TE
• Trailer
• Transfer-Encoding
• Upgrade

可以通過(guò)配置去指定僅刪除哪些Header，配置示例：

spring:
  cloud:
    gateway:
      filter:
        remove-hop-by-hop:
          # 多個(gè)Header使用逗號(hào)（,）分隔
          headers: Connection,Keep-Alive

12、RemoveRequestHeader GatewayFilter Factory

為原始請(qǐng)求刪除某個(gè)Header，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: removerequestheader_route
        uri: https://example.org
        filters:
        - RemoveRequestHeader=X-Request-Foo

刪除原始請(qǐng)求中名為 X-Request-Foo 的請(qǐng)求頭

13、RemoveResponseHeader GatewayFilter Factory

為原始響應(yīng)刪除某個(gè)Header，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: removeresponseheader_route
        uri: https://example.org
        filters:
        - RemoveResponseHeader=X-Response-Foo

刪除原始響應(yīng)中名為 X-Request-Foo 的響應(yīng)頭

14、RewritePath GatewayFilter Factory

通過(guò)正則表達(dá)式重寫原始的請(qǐng)求路徑，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: rewritepath_route
        uri: https://example.org
        predicates:
        - Path=/foo/**
        filters:
        # 參數(shù)1為原始路徑的正則表達(dá)式，參數(shù)2為重寫后路徑的正則表達(dá)式
        - RewritePath=/foo/(?<segment>.*), /$\{segment}

該配置使得訪問(wèn) /foo/bar 時(shí)，會(huì)將路徑重寫為/bar 再進(jìn)行轉(zhuǎn)發(fā)，也就是會(huì)轉(zhuǎn)發(fā)到 https://example.org/bar。需要注意的是：由于YAML語(yǔ)法，需用$\ 替換 $

15、RewriteResponseHeader GatewayFilter Factory

重寫原始響應(yīng)中的某個(gè)Header，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: rewriteresponseheader_route
        uri: https://example.org
        filters:
        # 參數(shù)1為Header名稱，參數(shù)2為值的正則表達(dá)式，參數(shù)3為重寫后的值
        - RewriteResponseHeader=X-Response-Foo, password=[^&]+, password=***

該配置的意義在于：如果響應(yīng)頭中 X-Response-Foo 的值為/42?user=ford&password=omg!what&flag=true，那么就會(huì)被按照配置的值重寫成/42?user=ford&password=***&flag=true，也就是把其中的password=omg!what重寫成了password=***

16、SaveSession GatewayFilter Factory

在轉(zhuǎn)發(fā)請(qǐng)求之前，強(qiáng)制執(zhí)行WebSession::save操作，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: save_session
        uri: https://example.org
        predicates:
        - Path=/foo/**
        filters:
        - SaveSession

主要用在那種像 Spring Session 延遲數(shù)據(jù)存儲(chǔ)（數(shù)據(jù)不是立刻持久化）的，并希望在請(qǐng)求轉(zhuǎn)發(fā)前確保session狀態(tài)保存情況。如果你將Spring Secutiry于Spring Session集成使用，并想確保安全信息都傳到下游機(jī)器，你就需要配置這個(gè)filter。

17、secureHeaders GatewayFilter Factory

secureHeaders過(guò)濾器工廠主要是參考了這篇博客中的建議，為原始響應(yīng)添加了一系列起安全作用的響應(yīng)頭。默認(rèn)會(huì)添加如下Headers（包括值）：

• X-Xss-Protection:1; mode=block
• Strict-Transport-Security:max-age=631138519
• X-Frame-Options:DENY
• X-Content-Type-Options:nosniff
• Referrer-Policy:no-referrer
• Content-Security-Policy:default-src 'self' https:; font-src 'self' https: data:; img-src 'self' https: data:; object-src 'none'; script-src https:; style-src 'self' https: 'unsafe-inline'
• X-Download-Options:noopen
• X-Permitted-Cross-Domain-Policies:none

如果你想修改這些Header的值，那么就需要使用這些Headers對(duì)應(yīng)的后綴，如下：

• xss-protection-header
• strict-transport-security
• frame-options
• content-type-options
• referrer-policy
• content-security-policy
• download-options
• permitted-cross-domain-policies

配置示例：

spring:
  cloud:
    gateway:
      filter:
        secure-headers:
          # 修改 X-Xss-Protection 的值為 2; mode=unblock
          xss-protection-header: 2; mode=unblock

如果想禁用某些Header，可使用如下配置：

spring:
  cloud:
    gateway:
      filter:
        secure-headers:
          # 多個(gè)使用逗號(hào)（,）分隔
          disable: frame-options,download-options

18、SetPath GatewayFilter Factory

修改原始的請(qǐng)求路徑，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: setpath_route
        uri: https://example.org
        predicates:
        - Path=/foo/{segment}
        filters:
        - SetPath=/{segment}

該配置使訪問(wèn) ${GATEWAY_URL}/foo/bar 時(shí)會(huì)轉(zhuǎn)發(fā)到 https://example.org/bar ，也就是原本的/foo/bar被修改為了/bar

19、SetResponseHeader GatewayFilter Factory

修改原始響應(yīng)中某個(gè)Header的值，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: setresponseheader_route
        uri: https://example.org
        filters:
        - SetResponseHeader=X-Response-Foo, Bar

將原始響應(yīng)中 X-Response-Foo 的值修改為 Bar

20、SetStatus GatewayFilter Factory

修改原始響應(yīng)的狀態(tài)碼，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: setstatusstring_route
        uri: https://example.org
        filters:
        # 字符串形式
        - SetStatus=BAD_REQUEST
      - id: setstatusint_route
        uri: https://example.org
        filters:
        # 數(shù)字形式
        - SetStatus=401

SetStatusd的值可以是數(shù)字，也可以是字符串。但一定要是Spring HttpStatus 枚舉類中的值。上面這兩種配置都可以返回401這個(gè)HTTP狀態(tài)碼。

21、StripPrefix GatewayFilter Factory

用于截?cái)嘣颊?qǐng)求的路徑，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: nameRoot
        uri: http://nameservice
        predicates:
        - Path=/name/**
        filters:
        # 數(shù)字表示要截?cái)嗟穆窂降臄?shù)量
        - StripPrefix=2

如上配置，如果請(qǐng)求的路徑為 /name/bar/foo ，那么則會(huì)截?cái)喑?code>/foo后進(jìn)行轉(zhuǎn)發(fā) ，也就是會(huì)截?cái)?個(gè)路徑。

22、Retry GatewayFilter Factory

針對(duì)不同的響應(yīng)進(jìn)行重試，例如可以針對(duì)HTTP狀態(tài)碼進(jìn)行重試，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: retry_test
        uri: http://localhost:8080/flakey
        predicates:
        - Host=*.retry.com
        filters:
        - name: Retry
          args:
            retries: 3
            statuses: BAD_GATEWAY

可配置如下參數(shù)：

• retries：重試次數(shù)
• statuses：需要重試的狀態(tài)碼，取值在 org.springframework.http.HttpStatus 中
• methods：需要重試的請(qǐng)求方法，取值在 org.springframework.http.HttpMethod 中
• series：HTTP狀態(tài)碼序列，取值在 org.springframework.http.HttpStatus.Series 中

23、RequestSize GatewayFilter Factory

設(shè)置允許接收最大請(qǐng)求包的大小，配置示例：

spring:
  cloud:
    gateway:
      routes:
      - id: request_size_route
      uri: http://localhost:8080/upload
      predicates:
      - Path=/upload
      filters:
      - name: RequestSize
        args:
          # 單位為字節(jié)
          maxSize: 5000000

如果請(qǐng)求包大小超過(guò)設(shè)置的值，則會(huì)返回 413 Payload Too Large以及一個(gè)errorMessage

24、Modify Request Body GatewayFilter Factory

在轉(zhuǎn)發(fā)請(qǐng)求之前修改原始請(qǐng)求體內(nèi)容，該過(guò)濾器工廠只能通過(guò)代碼配置，不支持在配置文件中配置。代碼示例：

@Bean
public RouteLocator routes(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("rewrite_request_obj", r -> r.host("*.rewriterequestobj.org")
            .filters(f -> f.prefixPath("/httpbin")
                .modifyRequestBody(String.class, Hello.class, MediaType.APPLICATION_JSON_VALUE,
                    (exchange, s) -> return Mono.just(new Hello(s.toUpperCase())))).uri(uri))
        .build();
}

static class Hello {
    String message;

    public Hello() { }

    public Hello(String message) {
        this.message = message;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

Tips：該過(guò)濾器工廠處于 BETA 狀態(tài)，未來(lái)API可能會(huì)變化，生產(chǎn)環(huán)境請(qǐng)慎用

25、Modify Response Body GatewayFilter Factory

可用于修改原始響應(yīng)體的內(nèi)容，該過(guò)濾器工廠同樣只能通過(guò)代碼配置，不支持在配置文件中配置。代碼示例：

@Bean
public RouteLocator routes(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("rewrite_response_upper", r -> r.host("*.rewriteresponseupper.org")
            .filters(f -> f.prefixPath("/httpbin")
                .modifyResponseBody(String.class, String.class,
                    (exchange, s) -> Mono.just(s.toUpperCase()))).uri(uri)
        .build();
}

Tips：該過(guò)濾器工廠處于 BETA 狀態(tài)，未來(lái)API可能會(huì)變化，生產(chǎn)環(huán)境請(qǐng)慎用

26、Default Filters

Default Filters用于為所有路由添加過(guò)濾器工廠，也就是說(shuō)通過(guò)Default Filter所配置的過(guò)濾器工廠會(huì)作用到所有的路由上。配置示例：

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

官方文檔：

• GatewayFilter Factories