网关 Spring Cloud Zuul 内置过滤器详解以及常见扩展思路

悠悠 2023-01-20 04:00 6阅读 0赞

### 文章目录 ###

*   *  概述
     *  过滤器类型和生命周期
     *  Spring Cloud Zuul 的内置过滤器
     *   *  Pre filters
         *  Route filters
         *  Post filters
         *  Error filters
     *  禁用过滤器
     *  应用场景
     *   *  前置过滤器
         *  后置过滤器
         *  错误过滤器
         *  配置管理

## 概述 ##

在 **Zuul** 中自定义过滤器需要继承抽象类 `ZuulFilter`，需要实现以下4个方法：

*  String filterType()； // 过滤器类型 PRE、ROURING、POST、ERROR
 *  int filterOrder()； // 执行顺序，**数值越小优先级越高**
 *  boolean shouldFilter()； // 执行过滤器的条件
 *  Object run() throws ZuulException； // 具体的过滤操作

从名字我们也能知道各个方法的作用，下面来了解下过滤器类型和过滤器的生命周期，以及自定义过滤器的使用

## 过滤器类型和生命周期 ##

Zuul 定义了4种不同的过滤器类型，对应着请求的典型生命周期

*  PRE: 在请求被路由之前执行。可以用于请求身份验证、选择源服务器和记录调试信息（**常用扩展**）
 *  ROURING: 该过滤器将请求路由到服务。用于构建和发送给微服务的请求（使用 Apache HttpClient 或 Netflix Ribbon 请求服务）
 *  POST: 在请求被路由到服务之后执行。可以用于向响应添加标准的 HTTP Header、收集统计数据和指标，以及将响应从源服务发送到客户端
 *  ERROR: 该过滤器在其他阶段发生错误时执行

下面是 Zuul 的生命周期图，描述着各种类型的过滤器的执行顺序（图片来源于 [Zuul Wiki][]）

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FidTkzNTAwOTA2Ng_size_16_color_FFFFFF_t_70_pic_center][]  
![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FidTkzNTAwOTA2Ng_size_16_color_FFFFFF_t_70_pic_center 1][]

## Spring Cloud Zuul 的内置过滤器 ##

Spring Cloud Zuul 作为服务网关的大部分功能都是通过过滤器实现的，它在请求的各个阶段实现了一系列的过滤器，在 Spring Cloud Zuul 网关服务启动时自动加载和启用。

实现的这些过滤器是在`spring-cloud-netflix-zuul`模块中的`org.springframework.cloud.netflix.zuul.filters`包下面

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FidTkzNTAwOTA2Ng_size_16_color_FFFFFF_t_70_pic_center 2][]

**下面介绍部分过滤器的功能**:

### Pre filters ###

<table> 
 <thead> 
  <tr> 
   <th>filter</th> 
   <th>order</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>ServletDetectionFilter</td> 
   <td>-3</td> 
   <td>检测请求是否通过 Spring 调度程序，即判断请求是交由 Spring DispatcherServlet 处理，还是 ZuulServlet 处理(主要是用于大文件上传)</td> 
  </tr> 
  <tr> 
   <td>Servlet30WrapperFilter</td> 
   <td>-2</td> 
   <td>把原始 HttpServletRequest 包装成 Servlet30RequestWrapper 对象</td> 
  </tr> 
  <tr> 
   <td>FormBodyWrapperFilter</td> 
   <td>-1</td> 
   <td>解析表单数据并为下游服务重新编码</td> 
  </tr> 
  <tr> 
   <td>DebugFilter</td> 
   <td>1</td> 
   <td>该过滤器会<strong>根据配置参数zuul.debug.request和请求中的debug参数来决定是否执行过滤器中的操作</strong>。而它的具体操作内容是将当前请求上下文中的debugRouting和debugRequest参数设置为true。由于在同一个请求的不同生命周期都可以访问到这两个值，所以我们在后续的各个过滤器中可以利用这二个值来定义一些debug信息，这样当线上环境出现问题的时候，<strong>可以通过参数的方式来激活这些debug信息以帮助分析问题</strong>，另外，对于请求参数中的debug参数，我们可以通过zuul.debug.parameter来进行自定义。</td> 
  </tr> 
  <tr> 
   <td>PreDecorationFilter</td> 
   <td>5</td> 
   <td>是pre阶段最后被执行的过滤器，该过滤器会判断当前请求上下文中是否存在forward.do和serviceId参数，如果都不存在，那么它就会执行具体过滤器的操作（如果有一个存在的话，说明当前请求已经被处理过了，因为这二个信息就是根据当前请求的路由信息加载进来的）。而当它的具体操作内容就是为当前请求做一些预处理，比如说，进行路由规则的匹配，在请求上下文中设置该请求的基本信息以及将路由匹配结果等一些设置信息等，这些信息将是后续过滤器进行处理的重要依据，我们可以通过RequestContext.getCurrentContext()来访问这些信息。另外，我们还可以在该实现中找到对HTTP头请求进行处理的逻辑，其中包含了一些耳熟能详的头域，比如X-Forwarded-Host,X-Forwarded-Port。另外，对于这些头域是通过zuul.addProxyHeaders参数进行控制的，而这个参数默认值是true，所以zuul在请求跳转时默认会为请求增加X-Forwarded-*头域，包括X-Forwarded-Host,X-Forwarded-Port，X-Forwarded-For，X-Forwarded-Prefix,X-Forwarded-Proto。也可以通过设置zuul.addProxyHeaders=false关闭对这些头域的添加动作。</td> 
  </tr> 
 </tbody> 
</table>

### Route filters ###

<table> 
 <thead> 
  <tr> 
   <th>filter</th> 
   <th>order</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>RibbonRoutingFilter</td> 
   <td>10</td> 
   <td>使用 Ribbon、Hystrix 和 可插拔 HTTP客户机发送请求。只对 RequestContext 存在 serviceId 参数的请求进行处理，即只对通过 serviceId配置路由规则的请求路由。可以使用不同的 HTTP 客户端：HttpClient、OkHttpClient、Netflix Ribbon HTTP client</td> 
  </tr> 
  <tr> 
   <td>SimpleHostRoutingFilter</td> 
   <td>100</td> 
   <td>通过 Apache HttpClient 发送请求到预定的 url，这些 url 可以在 RequestContext.getRouteHost() 中找到，即只对通过 url 配置路由规则的请求路由</td> 
  </tr> 
  <tr> 
   <td>SendForwardFilter</td> 
   <td>500</td> 
   <td>通过使用 Servlet RequestDispatcher 转发请求。用于转发请求到当前应用的端点</td> 
  </tr> 
 </tbody> 
</table>

### Post filters ###

<table> 
 <thead> 
  <tr> 
   <th>filter</th> 
   <th>order</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>LocationRewriteFilter</td> 
   <td>900</td> 
   <td>负责将 Location header 重写为 Zuul URL</td> 
  </tr> 
  <tr> 
   <td>SendResponseFilter</td> 
   <td>1000</td> 
   <td>将代理请求的响应写入当前响应</td> 
  </tr> 
 </tbody> 
</table>

### Error filters ###

<table> 
 <thead> 
  <tr> 
   <th>filter</th> 
   <th>order</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>SendErrorFilter</td> 
   <td>0</td> 
   <td>利用请求上下文中的错误信息来组织成一个 forward 到 /error 错误端点的请求来产生错误响应</td> 
  </tr> 
 </tbody> 
</table>

**内部原理**

Zuul提供了一个框架，可以对过滤器进行动态的加载，编译，运行。过滤器之间没有直接的相互通信。

他们是通过一个RequestContext的静态类来进行数据传递的。RequestContext类中有ThreadLocal变量来记录每个Request所需要传递的数据。

过滤器是由Groovy写成。这些过滤器文件被放在Zuul Server上的特定目录下面。Zuul会定期轮询这些目录。修改过的过滤器会动态的加载到Zuul Server中以便于request使用。

## 禁用过滤器 ##

默认情况下，这些过滤器在代理和服务器模式下都是启用的。如果在某些场景下，禁用某个过滤器，可以设置 zuul…disable=true。

例如，要禁用`org.springframework.cloud.netflix.zuul.filter.post.sendresponsefilter`，设置 `zuul.SendResponseFilter.post.disable=true`

## 应用场景 ##

### 前置过滤器 ###

**鉴权**

一般来说整个服务的鉴权逻辑可以很复杂。

*  客户端：App、Web、Backend
 *  权限组：用户、后台人员、其他开发者
 *  实现：OAuth、JWT
 *  使用方式：Token、Cookie、SSO

而对于后端应用来说，它们其实只需要知道请求属于谁，而不需要知道为什么，所以 Gateway 可以友善的帮助后端应用完成鉴权这个行为，并将用户的唯一标示透传到后端，而不需要、甚至不应该将身份信息也传递给后端，防止某些应用利用这些敏感信息做错误的事情。

Zuul 默认情况下在处理后会删除请求的 Authorization 头和 Set-Cookie 头，也算是贯彻了这个原则。

**流量转发**

流量转发的含义就是将指向 /a/xxx.json 的请求转发到指向 /b/xxx.json 的请求。这个功能可能在一些项目迁移、或是灰度发布上会有一些用处。

### 后置过滤器 ###

**跨域**

使用 Gateway 做跨域相比应用本身或是 Nginx 的好处是规则可以配置的更加灵活。例如一个常见的规则。

1.  对于任意的 AJAX 请求，返回 Access-Control-Allow-Origin 为 \*，且 Access-Control-Allow-Credentials 为 true，这是一个常用的允许任意源跨域的配置，但是不允许请求携带任何 Cookie
2.  如果一个被信任的请求者需要携带 Cookie，那么将它的 Origin 增加到白名单中。对于白名单中的请求，返回 Access-Control-Allow-Origin 为该域名，且 Access-Control-Allow-Credentials 为 true，这样请求者可以正常的请求接口，同时可以在请求接口时携带 Cookie
3.  对于 302 的请求，即使在白名单内也必须要设置 Access-Control-Allow-Origin 为 \*，否则重定向后的请求携带的 Origin 会为 null，有可能会导致 iOS 低版本的某些兼容问题

**统计**

Gateway 可以统一收集所有应用请求的记录，并写入日志文件或是发到监控系统，相比 Nginx 的 access log，好处主要也是二次开发比较方便，比如可以关注一些业务相关的 HTTP 头，或是将请求参数和返回值都保存为日志打入消息队列中，便于线上故障调试。也可以收集一些性能指标发送到类似 Statsd 这样的监控平台。

### 错误过滤器 ###

错误过滤器的主要用法就像是 Jersey 中的 ExceptionMapper 或是 Spring MVC 中的 @ExceptionHandler 一样，在处理流程中认为有问题时，直接抛出统一的异常，错误过滤器捕获到这个异常后，就可以统一的进行返回值的封装，并直接结束该请求。

### 配置管理 ###

虽然将这些逻辑都切换到了 Gateway，省去了很多维护和迭代的成本，但是也面临着一个很大的问题，就是 Gateway 只有逻辑却没有配置，它并不知道一个请求要走哪些流程。

例如同样是后端服务 API，有的可能是给网页版用的、有的是给客户端用的，亦或是有的给用户用、有的给管理人员用，那么 Gateway 如何知道到底这些 API 是否需要登录、流控以及缓存呢？

理论上我们可以为 Gateway 编写一个管理后台，里面有当前服务的所有 API，每一个开发者都可以在里面创建新的 API，以及为它增加鉴权、缓存、跨域等功能。为了简化使用，也许我们会额外的增加一个权限组，例如 /admin/\* 下的所有 API 都应该为后台接口，它只允许内部来源的鉴权访问。

但是这样做依旧太复杂了，而且非常硬编码，当开发者开发了一个新的 API 之后，即使这个应用已经能正常接收特定 URI 的请求并处理之后，却还要通过人工的方式去一个管理后台进行额外的配置，而且可能会因为不谨慎打错了路径中的某个单词而造成不必要的事故，这都是不合理的。

我个人推荐的做法是，在后端应用中依旧保持配置的能力，即使应用里已经没有真实处理的逻辑了。例如在 Java 中通过注解声明式的编写 API，且在应用启动时自动注册 Gateway 就是一种比较好的选择。

/** * 这个接口需要鉴权，鉴权方式是 OAuth */
    @Authorization(OAuth)
    @RequestMapping(value = "/users/{id}", method = RequestMethod.DELETE)
    public void del(@PathVariable int id) { 
     //... 
    }
    
    /** * 这个接口可以缓存，并且每个 IP/User 每秒最多请求 10 次 */
    @Cacheable
    @RateLimiting(limit = "10/1s", scope = { IP, USER})
    @RequestMapping(value = "/users/{id}", method = RequestMethod.GET)
    public void info(@PathVariable int id) { 
     //... 
    }

这样 API 的编写者就会根据业务场景考虑该 API 需要哪些功能，也减少了管理的复杂度。

除此之外还会有一些后端应用无关的配置，有些是自动化的，例如恶意请求拦截，Gateway 会将所有请求的信息通过消息队列发送给一些实时数据分析的应用，这些应用会对请求分析，发现恶意请求的特征，并通过 Gateway 提供的接口将这些特征上报给 Gateway，Gateway 就可以实时的对这些恶意请求进行拦截。

参考：

*  https://www.jianshu.com/p/e0434a421c03
 *  https://docs.spring.io/spring-cloud-netflix/docs/2.2.7.RELEASE/reference/html/\#router-and-filter-zuul
 *  https://cloud.spring.io/spring-cloud-static/spring-cloud-netflix/2.0.0.RELEASE/single/spring-cloud-netflix.html\#\_router\_and\_filter\_zuul
 *  https://cloud.spring.io/spring-cloud-netflix/multi/multi\_\_router\_and\_filter\_zuul.html
 *  https://cloud.spring.io/spring-cloud-static/spring-cloud-netflix/2.0.0.RELEASE/single/spring-cloud-netflix.html\#retrying-failed-requests

[Zuul Wiki]: https://github.com/Netflix/zuul/wiki
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FidTkzNTAwOTA2Ng_size_16_color_FFFFFF_t_70_pic_center]: /images/20221021/3e507736d8cc459ebe9759f4daf12951.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FidTkzNTAwOTA2Ng_size_16_color_FFFFFF_t_70_pic_center 1]: /images/20221021/05cd135bb94444bda358fe94df69d8b8.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FidTkzNTAwOTA2Ng_size_16_color_FFFFFF_t_70_pic_center 2]: /images/20221021/870f3093012c4fc2aac50c8b7d0e5e7f.png