3-服务网关Gateway_网关过滤器学习笔记(2020.3.31)

前言:

过滤器允许以某种方式修改传入的HTTP请求或返回的HTTP响应。过滤器的作用域是某些特定路由。Spring Cloud Gateway包括许多内置的 Filter工厂。

1. 网关过滤器

按需求使用那些过滤器。

有关如何使用以下任何过滤器的更多详细示例，请查看单元测试。

1.1 AddRequestHeader(添加请求头)

采用一对名称和值作为参数。

  cloud:
    gateway:
      discovery:
      routes:
      - id: my_route #自定义路由ID, 保持唯一  
        uri: lb://eureka-client #目标注册中心服务名, lb表示从注册中心获取服务
        predicates:
        - Path=/Test/**
        filters: #过滤规则
        - AddRequestHeader=X-Request-myname, zhihao

对于所有匹配的请求，这将向下游请求的头中添加 x-request-myname:zhihao 头

1.2 AddRequestParameter(添加请求参数)

采用一对名称和值作为参数。

filters:
- AddRequestParameter=name, zhihao #对于所有匹配的请求，这将向下游请求添加name=zhihao查询字符串

1.3 AddResponseHeader(添加响应头)

采用一对名称和值作为参数。

filters:
- AddResponseHeader=X-Response-myname, zhihao 
#对于所有匹配的请求，这将向下游响应的头中添加 x-Response-myname:zhihao 头

1.4 DedupeResponseHeader(删除响应头重复数据)

采用一个name参数和一个可选strategy参数。name可以包含以空格分隔的标题名称列表

filters:
- DedupeResponseHeader=Access-Control-Allow-Credentials Access-Control-Allow-Origin

当网关CORS逻辑和下游逻辑都将它们添加时，这将删除Access-Control-Allow-Credentials和Access-Control-Allow-Origin响应头的重复值。

该DedupeResponseHeader过滤器还接受一个可选的strategy参数。可接受的值为RETAIN_FIRST（默认值）RETAIN_LAST，和RETAIN_UNIQUE。

1.5 Hystrix(熔断器)

Hystrix 是Netflix开源的断路器组件。Hystrix GatewayFilter允许你向网关路由引入断路器，保护你的服务不受级联故障的影响，并允许你在下游故障时提供fallback响应。

要在项目中启用Hystrix网关过滤器，需要添加对 spring-cloud-starter-netflix-hystrix的依赖 Spring Cloud Netflix.

Hystrix GatewayFilter Factory 需要一个name参数，即HystrixCommand的名称。

filters:
- Hystrix=myCommandName #这将剩余的过滤器包装在命令名为“myCommandName”的HystrixCommand中。

hystrix过滤器还可以接受可选的fallbackUri 参数。目前，仅支持forward: 预设的URI，如果调用fallback，则请求将转发到与URI匹配的控制器。

application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: hystrix_route
        uri: lb://backing-service:8088
        predicates:
        - Path=/consumingserviceendpoint
        filters:
        - name: Hystrix
          args:
            name: fallbackcmd
            fallbackUri: forward:/incaseoffailureusethis
        - RewritePath=/consumingserviceendpoint, /backingserviceendpoint 

当调用hystrix fallback时，这将转发到/incaseoffailureusethis uri。注意，这个示例还演示了（可选）通过目标URI上的’lb`前缀,使用Spring Cloud Netflix Ribbon 客户端负载均衡。

主要场景是使用fallbackUri 到网关应用程序中的内部控制器或处理程序。但是，也可以将请求重新路由到外部应用程序中的控制器或处理程序，如：

application.yml.

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

在本例中，gateway应用程序中没有 fallback 实现，但是另一个应用程序中有一个接口实现，注册为“http://localhost:9994”。

在将请求转发到fallback的情况下，Hystrix Gateway过滤还支持直接抛出Throwable 。它被作为ServerWebExchangeUtils.HYSTRIX_EXECUTION_EXCEPTION_ATTR属性添加到ServerWebExchange中，可以在处理网关应用程序中的fallback时使用。

对于外部控制器/处理程序方案，可以添加带有异常详细信息的header。可以在 FallbackHeaders GatewayFilter Factory section.中找到有关它的更多信息。

hystrix配置参数（如 timeouts）可以使用全局默认值配置，也可以使用Hystrix wiki中所述属性进行配置。

要为上面的示例路由设置5秒超时，将使用以下配置：

hystrix:
  command:
    fallbackcmd:
      execution:
        isolation:
          thread:
            timeoutInMilliseconds: 5000

1.6 FallbackHeaders (回退请求头)

FallbackHeaders允许在转发到外部应用程序中的FallbackUri的请求的header中添加Hystrix异常详细信息，如下所示：

application.yml.

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

在本例中，在运行HystrixCommand发生执行异常后，请求将被转发到 localhost:9994应用程序中的 fallback终端或程序。异常类型、消息（如果可用）cause exception类型和消息的头，将由FallbackHeaders filter添加到该请求中。

通过设置下面列出的参数值及其默认值，可以在配置中覆盖headers的名称：

• executionExceptionTypeHeaderName ("Execution-Exception-Type")
• executionExceptionMessageHeaderName ("Execution-Exception-Message")
• rootCauseExceptionTypeHeaderName ("Root-Cause-Exception-Type")
• rootCauseExceptionMessageHeaderName ("Root-Cause-Exception-Message")

Hystrix 如何实现的更多细节可以参考 Hystrix GatewayFilter Factory section.

1.7 PrefixPath (前缀路径)

只有一个 prefix 参数.

给所有匹配请求的路径加前缀/mypath。因此，向/hello发送的请求将发送到/mypath/hello。

filters:
- PrefixPath=/mypath

1.8 SaveSession

SaveSession GatewayFilter Factory将调用转发到下游之前强制执行WebSession::save 操作。这在使用 Spring Session 之类时特别有用，需要确保会话状态在进行转发调用之前已保存。

filters:
- SaveSession

如果你希望要将[Spring Security]（https://projects.spring.io/Spring Security/）与Spring Session集成,并确保安全详细信息已转发到远程的进程，这一点至关重要。

1.9 SetResponseHeader(修改响应请求头)

SetResponseHeader GatewayFilter Factory 包括 name 和 value 参数.

filters:
- SetResponseHeader=X-Response-name, zhihao

此GatewayFilter使用给定的名称替换所有header，而不是添加。因此，如果下游服务器响应为X-Response-Foo:1234，则会将其替换为X-Response-Foo:zhihao,这是网关客户端将接收的内容。

2.0SetRequestHeader (修改请求头)

SetRequestHeader GatewayFilter Factory 包括 name 和 value 参数.

filters:
- SetRequestHeader=X-Request-name, zhihao

此GatewayFilter使用给定的名称替换所有header，而不是添加。因此，如果下游服务器响应为X-Request-name:1234，则会将其替换为X-Request-name:zhihao,这是网关客户端将接收的内容。

2.1 StripPrefix (请求中去除的路径中的节数)

StripPrefix GatewayFilter Factory 包括一个parts参数。 parts参数指示在将请求发送到下游之前，要从请求中去除的路径中的节数。

predicates:
- Path=/name/**
filters:
- StripPrefix=2
#通过网关发出/name/bar/foo请求时，向nameservice发出的请求将是http://nameservice/foo。
#一般去掉一节就ok 发出/name/bar/foo   变成 /bar/foo

2.2 Retry(重试)

Retry GatewayFilter Factory 支持以下参数：

• retries: 应尝试的重试次数

• statuses: 应该重试的HTTP状态代码，用org.springframework.http.HttpStatus标识

• methods: 应该重试的HTTP方法，用 org.springframework.http.HttpMethod标识

• series: 要重试的一系列状态码，用 org.springframework.http.HttpStatus.Series标识

• exceptions：应重试的引发异常的列表。

• backoff：为重试配置的指数补偿。重试在的退避间隔后执行firstBackoff * (factor ^ n)，其中n为迭代。如果maxBackoff已配置，则应用的最大退避限制为maxBackoff。如果basedOnPreviousValue为true，则使用计算退避prevBackoff * factor。

Retry如果启用了以下默认过滤器配置：

• retries：3次
• series：5XX系列
• methods：GET方法
• exceptions：IOException和TimeoutException
• backoff：禁用

    filters:
    - name: Retry
      args:
        retries: 3
        statuses: BAD_GATEWAY
        methods: GET,POST
        backoff:
          firstBackoff: 10ms
          maxBackoff: 50ms
          factor: 2
          basedOnPreviousValue: false

当使用带有forward:前缀URL 的重试过滤器时，应仔细编写目标端点，以便在发生错误的情况下，它不会做任何可能导致响应发送到客户端并提交的操作。例如，如果目标端点是带注释的控制器，则目标控制器方法不应返回ResponseEntity错误状态代码。相反，它应该抛出一个Exception错误或发出一个错误信号（例如，通过Mono.error(ex)返回值），该错误可以配置为重试过滤器通过重试进行处理。

当将重试过滤器与任何具有主体的HTTP方法一起使用时，主体将被缓存，并且网关将受到内存的限制。正文被缓存在由定义的请求属性中ServerWebExchangeUtils.CACHED_REQUEST_BODY_ATTR。对象的类型是org.springframework.core.io.buffer.DataBuffer。

2.3 RequestSize (请求大小)

当请求大小大于允许的限制时，RequestSize GatewayFilter Factory可以限制请求不到达下游服务。过滤器以RequestSize作为参数，这是定义请求的允许大小限制(以字节为单位)。

跟一个可选的DataUnit后缀，例如“KB”或“MB”。字节的默认值为“ B”。

如果未在路由定义中作为过滤器参数提供，则默认请求大小将设置为5 MB。

predicates:
- Path=/upload
filters:
- name: RequestSize
  args:
  maxSize: 5000000

当请求因大小而被拒绝时， RequestSize GatewayFilter Factory 将响应状态设置为413 Payload Too Large，并带有额外的header errorMessage 。下面是一个 errorMessage的例子。

errorMessage` : `Request size is larger than permissible limit. Request size is 6.0 MB where permissible limit is 5.0 MB

2.4 默认过滤器 (用于所有路由)

要添加过滤器并将其应用于所有路由，可以使用spring.cloud.gateway.default-filters。此属性采用过滤器列表。以下清单定义了一组默认过滤器：

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

上面就是个人觉得常用的网关提供过滤器。 其他过滤器可以在官网详细了解。

https://cloud.spring.io/spring-cloud-static/spring-cloud-gateway/2.2.2.RELEASE/reference/html/#gatewayfilter-factories

1