Spring Cloud Zuul：API网关服务

﹏ヽ暗。殇╰゛Y 2022-11-09 12:37 242阅读 0赞

> Spring Cloud Zuul 是Spring Cloud Netflix 子项目的核心组件之一，可以作为微服务架构中的API网关使用，支持动态路由与过滤功能，本文将对其用法进行详细介绍。

## [Zuul简介][Zuul] ##

API网关为微服务架构中的服务提供了统一的访问入口，客户端通过API网关访问相关服务。API网关的定义类似于设计模式中的门面模式，它相当于整个微服务架构中的门面，所有客户端的访问都通过它来进行路由及过滤。它实现了请求路由、负载均衡、校验过滤、服务容错、服务聚合等功能。

## [创建一个zuul-proxy模块][zuul-proxy] ##

> 这里我们创建一个zuul-proxy模块来演示zuul的常用功能。

### [在pom.xml中添加相关依赖][pom.xml] ###

<dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-netflix-zuul</artifactId>
    </dependency>Copy to clipboardErrorCopied

### [在application.yml中进行配置][application.yml] ###

server:
      port: 8801
    spring:
      application:
        name: zuul-proxy
    eureka:
      client:
        register-with-eureka: true
        fetch-registry: true
        service-url:
          defaultZone: http://localhost:8001/eureka/Copy to clipboardErrorCopied

### [在启动类上添加@EnableZuulProxy注解来启用Zuul的API网关功能][EnableZuulProxy_Zuul_API] ###

@EnableZuulProxy
    @EnableDiscoveryClient
    @SpringBootApplication
    public class ZuulProxyApplication {
    
        public static void main(String[] args) {
            SpringApplication.run(ZuulProxyApplication.class, args);
        }
    
    }Copy to clipboardErrorCopied

## [常用功能][Link 1] ##

### [启动相关服务][Link 2] ###

这里我们通过启动eureka-server，两个user-service，feign-service和zuul-proxy来演示Zuul的常用功能，启动后注册中心显示如下。

![177267db19c32f73c977fc72cea12e87.png][]

### [配置路由规则][Link 3] ###

*  我们可以通过修改application.yml中的配置来配置路由规则，这里我们将匹配`/userService/**`的请求路由到user-service服务上去，匹配`/feignService/**`的请求路由到feign-service上去。

zuul:
      routes: #给服务配置路由
        user-service:
          path: /userService/**
        feign-service:
          path: /feignService/**Copy to clipboardErrorCopied

*  访问[http://localhost:8801/userService/user/1][http_localhost_8801_userService_user_1]可以发现请求路由到了user-service上了；
 *  访问[http://localhost:8801/feignService/user/1][http_localhost_8801_feignService_user_1]可以发现请求路由到了feign-service上了。

### [默认路由规则][Link 4] ###

*  Zuul和Eureka结合使用，可以实现路由的自动配置，自动配置的路由以服务名称为匹配路径，相当于如下配置：

zuul:
      routes: #给服务配置路由
        user-service:
          path: /user-service/**
        feign-service:
          path: /feign-service/**Copy to clipboardErrorCopied

*  访问[http://localhost:8801/user-service/user/1][http_localhost_8801_user-service_user_1]同样可以路由到了user-service上了；
 *  访问[http://localhost:8801/feign-service/user/1][http_localhost_8801_feign-service_user_1]同样可以路由到了feign-service上了。
 *  如果不想使用默认的路由规则，可以添加以下配置来忽略默认路由配置：

zuul:
      ignored-services: user-service,feign-service #关闭默认路由配置Copy to clipboardErrorCopied

### [负载均衡功能][Link 5] ###

多次调用[http://localhost:8801/user-service/user/1][http_localhost_8801_user-service_user_1]进行测试，可以发现运行在8201和8202的user-service服务交替打印如下信息。

2019-10-05 10:31:58.738  INFO 11520 --- [nio-8202-exec-5] c.macro.cloud.controller.UserController  : 根据id获取用户信息，用户名称为：macro
    2019-10-05 10:32:00.356  INFO 11520 --- [nio-8202-exec-6] c.macro.cloud.controller.UserController  : 根据id获取用户信息，用户名称为：macroCopy to clipboardErrorCopied

### [配置访问前缀][Link 6] ###

我们可以通过以下配置来给网关路径添加前缀，此处添加了/proxy前缀，这样我们需要访问[http://localhost:8801/proxy/user-service/user/1][http_localhost_8801_proxy_user-service_user_1]才能访问到user-service中的接口。

zuul:
      prefix: /proxy #给网关路由添加前缀Copy to clipboardErrorCopied

### [Header过滤及重定向添加Host][Header_Host] ###

*  Zuul在请求路由时，默认会过滤掉一些敏感的头信息，以下配置可以防止路由时的Cookie及Authorization的丢失：

zuul:
      sensitive-headers: Cookie,Set-Cookie,Authorization #配置过滤敏感的请求头信息，设置为空就不会过滤Copy to clipboardErrorCopied

*  Zuul在请求路由时，不会设置最初的host头信息，以下配置可以解决：

zuul:
      add-host-header: true #设置为true重定向是会添加host请求头Copy to clipboardErrorCopied

### [查看路由信息][Link 7] ###

> 我们可以通过SpringBoot Actuator来查看Zuul中的路由信息。

*  在pom.xml中添加相关依赖：

<dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>Copy to clipboardErrorCopied

*  修改application.yaml配置文件，开启查看路由的端点：

management:
      endpoints:
        web:
          exposure:
            include: 'routes'Copy to clipboardErrorCopied

*  通过访问[http://localhost:8801/actuator/routes][http_localhost_8801_actuator_routes]查看简单路由信息：

![64cb1965a0879d4586307a027afd92cc.png][]

*  通过访问[http://localhost:8801/actuator/routes/details][http_localhost_8801_actuator_routes]查看详细路由信息：

![fb67d43bdb0f8969f30a28e4601b64a3.png][]

## [过滤器][Link 8] ##

> 路由与过滤是Zuul的两大核心功能，路由功能负责将外部请求转发到具体的服务实例上去，是实现统一访问入口的基础，过滤功能负责对请求过程进行额外的处理，是请求校验过滤及服务聚合的基础。

### [过滤器类型][Link 9] ###

> Zuul中有以下几种典型的过滤器类型。

*  pre：在请求被路由到目标服务前执行，比如权限校验、打印日志等功能；
 *  routing：在请求被路由到目标服务时执行，这是使用Apache HttpClient或Netflix Ribbon构建和发送原始HTTP请求的地方；
 *  post：在请求被路由到目标服务后执行，比如给目标服务的响应添加头信息，收集统计数据等功能；
 *  error：请求在其他阶段发生错误时执行。

### [过滤器的生命周期][Link 10] ###

> 下图描述了一个HTTP请求到达API网关后，如何在各种不同类型的过滤器中流转的过程。

![来自Zuul官网][Zuul 1]

### [自定义过滤器][Link 11] ###

> 接下来我们自定义一个过滤器来演示下过滤器的作用。

[添加PreLogFilter类继承ZuulFilter][PreLogFilter_ZuulFilter]

> 这是一个前置过滤器，用于在请求路由到目标服务前打印请求日志。

/**
     * Created by macro on 2019/9/9.
     */
    @Component
    public class PreLogFilter extends ZuulFilter {
        private Logger LOGGER = LoggerFactory.getLogger(this.getClass());
    
        /**
         * 过滤器类型，有pre、routing、post、error四种。
         */
        @Override
        public String filterType() {
            return "pre";
        }
    
        /**
         * 过滤器执行顺序，数值越小优先级越高。
         */
        @Override
        public int filterOrder() {
            return 1;
        }
    
        /**
         * 是否进行过滤，返回true会执行过滤。
         */
        @Override
        public boolean shouldFilter() {
            return true;
        }
    
        /**
         * 自定义的过滤器逻辑，当shouldFilter()返回true时会执行。
         */
        @Override
        public Object run() throws ZuulException {
            RequestContext requestContext = RequestContext.getCurrentContext();
            HttpServletRequest request = requestContext.getRequest();
            String host = request.getRemoteHost();
            String method = request.getMethod();
            String uri = request.getRequestURI();
            LOGGER.info("Remote host:{},method:{},uri:{}", host, method, uri);
            return null;
        }
    }Copy to clipboardErrorCopied

[过滤器功能演示][Link 12]

添加过滤器后，我们访问[http://localhost:8801/user-service/user/1][http_localhost_8801_user-service_user_1]测试下，会打印如下日志。

2019-10-05 15:13:10.232  INFO 11040 --- [nio-8801-exec-7] com.macro.cloud.filter.PreLogFilter      : Remote host:0:0:0:0:0:0:0:1,method:GET,uri:/user-service/user/1Copy to clipboardErrorCopied

### [核心过滤器][Link 13]【配置上是可禁用的但是出错信息请自行尝试(运行出错但是如何打日志？)，便于日后发生错误可快速定位】 ###

<table> 
 <thead> 
  <tr> 
   <th>过滤器名称</th> 
   <th>过滤类型</th> 
   <th>优先级</th> 
   <th>过滤器的作用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>ServletDetectionFilter</td> 
   <td>pre</td> 
   <td>-3</td> 
   <td>检测当前请求是通过DispatcherServlet处理运行的还是ZuulServlet运行处理的。</td> 
  </tr> 
  <tr> 
   <td>Servlet30WrapperFilter</td> 
   <td>pre</td> 
   <td>-2</td> 
   <td>对原始的HttpServletRequest进行包装。</td> 
  </tr> 
  <tr> 
   <td>FormBodyWrapperFilter</td> 
   <td>pre</td> 
   <td>-1</td> 
   <td>将Content-Type为application/x-www-form-urlencoded或multipart/form-data的请求包装成FormBodyRequestWrapper对象。</td> 
  </tr> 
  <tr> 
   <td>DebugFilter</td> 
   <td>route</td> 
   <td>1</td> 
   <td>根据zuul.debug.request的配置来决定是否打印debug日志。</td> 
  </tr> 
  <tr> 
   <td>PreDecorationFilter</td> 
   <td>route</td> 
   <td>5</td> 
   <td>对当前请求进行预处理以便执行后续操作。</td> 
  </tr> 
  <tr> 
   <td>RibbonRoutingFilter</td> 
   <td>route</td> 
   <td>10</td> 
   <td>通过Ribbon和Hystrix来向服务实例发起请求，并将请求结果进行返回。</td> 
  </tr> 
  <tr> 
   <td>SimpleHostRoutingFilter</td> 
   <td>route</td> 
   <td>100</td> 
   <td>只对请求上下文中有routeHost参数的进行处理，直接使用HttpClient向routeHost对应的物理地址进行转发。</td> 
  </tr> 
  <tr> 
   <td>SendForwardFilter</td> 
   <td>route</td> 
   <td>500</td> 
   <td>只对请求上下文中有forward.to参数的进行处理，进行本地跳转。</td> 
  </tr> 
  <tr> 
   <td>SendErrorFilter</td> 
   <td>post</td> 
   <td>0</td> 
   <td>当其他过滤器内部发生异常时的会由它来进行处理，产生错误响应。</td> 
  </tr> 
  <tr> 
   <td>SendResponseFilter</td> 
   <td>post</td> 
   <td>1000</td> 
   <td>利用请求上下文的响应信息来组织请求成功的响应内容。</td> 
  </tr> 
 </tbody> 
</table>

### [禁用过滤器][Link 14] ###

*  我们可以对过滤器进行禁用的配置，配置格式如下：

zuul:
      filterClassName:
        filter:
          disable: true Copy to clipboardErrorCopied

*  以下是禁用PreLogFilter的示例配置：

zuul:
      PreLogFilter:
        pre:
          disable: true Copy to clipboardErrorCopied

## [Ribbon和Hystrix的支持][Ribbon_Hystrix] ##

> 由于**Zuul自动集成了Ribbon和Hystrix**，所以Zuul天生就有负载均衡和服务容错能力，我们可以通过Ribbon和Hystrix的配置来配置Zuul中的相应功能。

*  可以使用Hystrix的配置来设置路由转发时HystrixCommand的执行超时时间：

hystrix:
      command: #用于控制HystrixCommand的行为
        default:
          execution:
            isolation:
              thread:
                timeoutInMilliseconds: 1000 #配置HystrixCommand执行的超时时间，执行超过该时间会进行服务降级处理Copy to clipboardErrorCopied

*  可以使用Ribbon的配置来设置路由转发时请求连接及处理的超时时间：

ribbon: #全局配置
      ConnectTimeout: 1000 #服务请求连接超时时间（毫秒）
      ReadTimeout: 3000 #服务请求处理超时时间（毫秒）Copy to clipboardErrorCopied

## [常用配置][Link 15] ##

zuul:
      routes: #给服务配置路由
        user-service:
          path: /userService/**
        feign-service:
          path: /feignService/**
      ignored-services: user-service,feign-service #关闭默认路由配置
      prefix: /proxy #给网关路由添加前缀
      sensitive-headers: Cookie,Set-Cookie,Authorization #配置过滤敏感的请求头信息，设置为空就不会过滤
      add-host-header: true #设置为true重定向是会添加host请求头
      retryable: true # 关闭重试机制
      PreLogFilter:
        pre:
          disable: false #控制是否启用过滤器Copy to clipboardErrorCopied

## [使用到的模块][Link 16] ##

springcloud-learning
    ├── eureka-server -- eureka注册中心
    ├── user-service -- 提供User对象CRUD接口的服务
    ├── feign-service -- feign服务调用测试服务
    └── zuul-proxy -- zuul作为网关的测试服务Copy to clipboardErrorCopied

## [项目源码地址][Link 17] ##

[https://github.com/macrozheng/springcloud-learning][https_github.com_macrozheng_springcloud-learning]

[Zuul]: http://www.macrozheng.com/#/cloud/zuul?id=zuul%E7%AE%80%E4%BB%8B
[zuul-proxy]: http://www.macrozheng.com/#/cloud/zuul?id=%E5%88%9B%E5%BB%BA%E4%B8%80%E4%B8%AAzuul-proxy%E6%A8%A1%E5%9D%97
[pom.xml]: http://www.macrozheng.com/#/cloud/zuul?id=%E5%9C%A8pomxml%E4%B8%AD%E6%B7%BB%E5%8A%A0%E7%9B%B8%E5%85%B3%E4%BE%9D%E8%B5%96
[application.yml]: http://www.macrozheng.com/#/cloud/zuul?id=%E5%9C%A8applicationyml%E4%B8%AD%E8%BF%9B%E8%A1%8C%E9%85%8D%E7%BD%AE
[EnableZuulProxy_Zuul_API]: http://www.macrozheng.com/#/cloud/zuul?id=%E5%9C%A8%E5%90%AF%E5%8A%A8%E7%B1%BB%E4%B8%8A%E6%B7%BB%E5%8A%A0enablezuulproxy%E6%B3%A8%E8%A7%A3%E6%9D%A5%E5%90%AF%E7%94%A8zuul%E7%9A%84api%E7%BD%91%E5%85%B3%E5%8A%9F%E8%83%BD
[Link 1]: http://www.macrozheng.com/#/cloud/zuul?id=%E5%B8%B8%E7%94%A8%E5%8A%9F%E8%83%BD
[Link 2]: http://www.macrozheng.com/#/cloud/zuul?id=%E5%90%AF%E5%8A%A8%E7%9B%B8%E5%85%B3%E6%9C%8D%E5%8A%A1
[177267db19c32f73c977fc72cea12e87.png]: /images/20221023/bdcfb3f4775c4bfeb67d783095c629f1.png
[Link 3]: http://www.macrozheng.com/#/cloud/zuul?id=%E9%85%8D%E7%BD%AE%E8%B7%AF%E7%94%B1%E8%A7%84%E5%88%99
[http_localhost_8801_userService_user_1]: http://localhost:8801/userService/user/1
[http_localhost_8801_feignService_user_1]: http://localhost:8801/feignService/user/1
[Link 4]: http://www.macrozheng.com/#/cloud/zuul?id=%E9%BB%98%E8%AE%A4%E8%B7%AF%E7%94%B1%E8%A7%84%E5%88%99
[http_localhost_8801_user-service_user_1]: http://localhost:8801/user-service/user/1
[http_localhost_8801_feign-service_user_1]: http://localhost:8801/feign-service/user/1
[Link 5]: http://www.macrozheng.com/#/cloud/zuul?id=%E8%B4%9F%E8%BD%BD%E5%9D%87%E8%A1%A1%E5%8A%9F%E8%83%BD
[Link 6]: http://www.macrozheng.com/#/cloud/zuul?id=%E9%85%8D%E7%BD%AE%E8%AE%BF%E9%97%AE%E5%89%8D%E7%BC%80
[http_localhost_8801_proxy_user-service_user_1]: http://localhost:8801/proxy/user-service/user/1
[Header_Host]: http://www.macrozheng.com/#/cloud/zuul?id=header%E8%BF%87%E6%BB%A4%E5%8F%8A%E9%87%8D%E5%AE%9A%E5%90%91%E6%B7%BB%E5%8A%A0host
[Link 7]: http://www.macrozheng.com/#/cloud/zuul?id=%E6%9F%A5%E7%9C%8B%E8%B7%AF%E7%94%B1%E4%BF%A1%E6%81%AF
[http_localhost_8801_actuator_routes]: http://localhost:8801/actuator/routes
[64cb1965a0879d4586307a027afd92cc.png]: /images/20221023/4225c70b979947c591651b320c007acd.png
[fb67d43bdb0f8969f30a28e4601b64a3.png]: /images/20221023/c8030ebe0f5848559b332342ad8ab214.png
[Link 8]: http://www.macrozheng.com/#/cloud/zuul?id=%E8%BF%87%E6%BB%A4%E5%99%A8
[Link 9]: http://www.macrozheng.com/#/cloud/zuul?id=%E8%BF%87%E6%BB%A4%E5%99%A8%E7%B1%BB%E5%9E%8B
[Link 10]: http://www.macrozheng.com/#/cloud/zuul?id=%E8%BF%87%E6%BB%A4%E5%99%A8%E7%9A%84%E7%94%9F%E5%91%BD%E5%91%A8%E6%9C%9F
[Zuul 1]: /images/20221023/32c2c834163e466fb7d156c7179d8cf2.png
[Link 11]: http://www.macrozheng.com/#/cloud/zuul?id=%E8%87%AA%E5%AE%9A%E4%B9%89%E8%BF%87%E6%BB%A4%E5%99%A8
[PreLogFilter_ZuulFilter]: http://www.macrozheng.com/#/cloud/zuul?id=%E6%B7%BB%E5%8A%A0prelogfilter%E7%B1%BB%E7%BB%A7%E6%89%BFzuulfilter
[Link 12]: http://www.macrozheng.com/#/cloud/zuul?id=%E8%BF%87%E6%BB%A4%E5%99%A8%E5%8A%9F%E8%83%BD%E6%BC%94%E7%A4%BA
[Link 13]: http://www.macrozheng.com/#/cloud/zuul?id=%E6%A0%B8%E5%BF%83%E8%BF%87%E6%BB%A4%E5%99%A8
[Link 14]: http://www.macrozheng.com/#/cloud/zuul?id=%E7%A6%81%E7%94%A8%E8%BF%87%E6%BB%A4%E5%99%A8
[Ribbon_Hystrix]: http://www.macrozheng.com/#/cloud/zuul?id=ribbon%E5%92%8Chystrix%E7%9A%84%E6%94%AF%E6%8C%81
[Link 15]: http://www.macrozheng.com/#/cloud/zuul?id=%E5%B8%B8%E7%94%A8%E9%85%8D%E7%BD%AE
[Link 16]: http://www.macrozheng.com/#/cloud/zuul?id=%E4%BD%BF%E7%94%A8%E5%88%B0%E7%9A%84%E6%A8%A1%E5%9D%97
[Link 17]: http://www.macrozheng.com/#/cloud/zuul?id=%E9%A1%B9%E7%9B%AE%E6%BA%90%E7%A0%81%E5%9C%B0%E5%9D%80
[https_github.com_macrozheng_springcloud-learning]: https://github.com/macrozheng/springcloud-learning