非常全面的講解SpringCloud中Zuul網關原理及其配置，看它就夠了！

2020 年 10 月 26 日
筆記

Zuul是spring cloud中的微服務網關。網關：是一個網路整體系統中的前置門戶入口。請求首先通過網關，進行路徑的路由，定位到具體的服務節點上。

Zuul是一個微服務網關，首先是一個微服務。也是會在Eureka註冊中心中進行服務的註冊和發現。也是一個網關，請求應該通過Zuul來進行路由。

Zuul網關不是必要的。是推薦使用的。

使用Zuul，一般在微服務數量較多（多於10個）的時候推薦使用，對服務的管理有嚴格要求的時候推薦使用，當微服務許可權要求嚴格的時候推薦使用。

一、Zuul網關的作用

網關有以下幾個作用：

統一入口：未全部為服務提供一個唯一的入口，網關起到外部和內部隔離的作用，保障了後台服務的安全性。
鑒權校驗：識別每個請求的許可權，拒絕不符合要求的請求。
動態路由：動態的將請求路由到不同的後端集群中。
減少客戶端與服務端的耦合：服務可以獨立發展，通過網關層來做映射。

二、Zuul網關的應用

1、網關訪問方式

通過zuul訪問服務的，URL地址默認格式為：//zuulHostIp:port/要訪問的服務名稱/服務中的URL

服務名稱：properties配置文件中的spring.application.name。

服務的URL：就是對應的服務對外提供的URL路徑監聽。

2、網關依賴注入

<!-- spring cloud Eureka Client 啟動器 -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-eureka</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-zuul</artifactId>
</dependency>
<!-- zuul網關的重試機制，不是使用ribbon內置的重試機制
   是藉助spring-retry組件實現的重試
   開啟zuul網關重試機制需要增加下述依賴
 -->
<dependency>
   <groupId>org.springframework.retry</groupId>
   <artifactId>spring-retry</artifactId>
</dependency>

3、網關啟動器

/**
 * @EnableZuulProxy - 開啟Zuul網關。
 *  當前應用是一個Zuul微服務網關。會在Eureka註冊中心中註冊當前服務。並發現其他的服務。
 *  Zuul需要的必要依賴是spring-cloud-starter-zuul。
 */
@SpringBootApplication
@EnableZuulProxy
public class ZuulApplication {
    public static void main(String[] args) {
        SpringApplication.run(ZuulApplication.class, args);
    }
}

4、網關全局變數配置

4.1 URL路徑匹配

# URL pattern
# 使用路徑方式匹配路由規則。
# 參數key結構：zuul.routes.customName.path=xxx
# 用於配置路徑匹配規則。
# 其中customName自定義。通常使用要調用的服務名稱，方便後期管理
# 可使用的通配符有： * ** ?
# ? 單個字元
# * 任意多個字元，不包含多級路徑
# ** 任意多個字元，包含多級路徑
zuul.routes.eureka-application-service.path=/api/**
# 參數key結構：zuul.routes.customName.url=xxx
# url用於配置符合path的請求路徑路由到的服務地址。
zuul.routes.eureka-application-service.url=//127.0.0.1:8080/

4.2 服務名稱匹配

# service id pattern 通過服務名稱路由
# key結構 ：zuul.routes.customName.path=xxx
# 路徑匹配規則
zuul.routes.eureka-application-service.path=/api/**
# key結構 ：zuul.routes.customName.serviceId=xxx
# serviceId用於配置符合path的請求路徑路由到的服務名稱。
zuul.routes.eureka-application-service.serviceId=eureka-application-service

服務名稱匹配也可以使用簡化的配置：

# simple service id pattern 簡化配置方案
# 如果只配置path，不配置serviceId。則customName相當於服務名稱。
# 符合path的請求路徑直接路由到customName對應的服務上。
zuul.routes.eureka-application-service.path=/api/**

4.3 路由排除配置

# ignored service id pattern
# 配置不被zuul管理的服務列表。多個服務名稱使用逗號','分隔。
# 配置的服務將不被zuul代理。
zuul.ignored-services=eureka-application-service
# 此方式相當於給所有新發現的服務默認排除zuul網關訪問方式，只有配置了路由網關的服務才可以通過zuul網關訪問
# 通配方式配置排除列表。
zuul.ignored-services=*
# 使用服務名稱匹配規則配置路由列表，相當於只對已配置的服務提供網關代理。
zuul.routes.eureka-application-service.path=/api/**

# 通配方式配置排除網關代理路徑。所有符合ignored-patterns的請求路徑都不被zuul網關代理。
zuul.ignored-patterns=/**/test/**
zuul.routes.eureka-application-service.path=/api/**

4.4 路由前綴配置

# prefix URL pattern 前綴路由匹配
# 配置請求路徑前綴，所有基於此前綴的請求都由zuul網關提供代理。
zuul.prefix=/api
# 使用服務名稱匹配方式配置請求路徑規則。
# 這裡的配置將為：//ip:port/api/appservice/**的請求提供zuul網關代理，可以將要訪問服務進行前綴分類。
# 並將請求路由到服務eureka-application-service中。
zuul.routes.eureka-application-service.path=/appservice/**

5 Zuul網關配置總結

網關配置方式有多種，默認、URL、服務名稱、排除|忽略、前綴。

網關配置沒有優劣好壞，應該在不同的情況下選擇合適的配置方案。

zuul網關其底層使用ribbon來實現請求的路由，並內置Hystrix，可選擇性提供網關fallback邏輯。使用zuul的時候，並不推薦使用Feign作為application client端的開發實現。畢竟Feign技術是對ribbon的再封裝，使用Feign本身會提高通訊消耗，降低通訊效率，只在服務相互調用的時候使用Feign來簡化程式碼開發就夠了。而且商業開發中，使用Ribbon+RestTemplate來開發的比例更高。

三、Zuul網關過濾器

Zuul中提供了過濾器定義，可以用來過濾代理請求，提供額外功能邏輯。如：許可權驗證，日誌記錄等。

Zuul提供的過濾器是一個父類。父類是ZuulFilter。通過父類中定義的抽象方法filterType，來決定當前的Filter種類是什麼。有前置過濾、路由後過濾、後置過濾、異常過濾。

前置過濾：是請求進入Zuul之後，立刻執行的過濾邏輯。
路由後過濾：是請求進入Zuul之後，並Zuul實現了請求路由後執行的過濾邏輯，路由後過濾，是在遠程服務調用之前過濾的邏輯。
後置過濾：遠程服務調用結束後執行的過濾邏輯。
異常過濾：是任意一個過濾器發生異常或遠程服務調用無結果回饋的時候執行的過濾邏輯。無結果回饋，就是遠程服務調用超時。

3.1 過濾器實現方式

繼承父類ZuulFilter。在父類中提供了4個抽象方法，分別是：filterType, filterOrder, shouldFilter, run。其功能分別是：

filterType：方法返回字元串數據，代表當前過濾器的類型。可選值有-pre, route, post, error。

pre – 前置過濾器，在請求被路由前執行，通常用於處理身份認證，日誌記錄等；
route – 在路由執行後，服務調用前被調用；
error – 任意一個filter發生異常的時候執行或遠程服務調用沒有回饋的時候執行（超時），通常用於處理異常；
post – 在route或error執行後被調用，一般用於收集服務資訊，統計服務性能指標等，也可以對response結果做特殊處理。

filterOrder：返回int數據，用於為同filterType的多個過濾器訂製執行順序，返回值越小，執行順序越優先。

shouldFilter：返回boolean數據，代表當前filter是否生效。

run：具體的過濾執行邏輯。如pre類型的過濾器，可以通過對請求的驗證來決定是否將請求路由到服務上；如post類型的過濾器，可以對服務響應結果做加工處理（如為每個響應增加footer數據）。Java知音公眾號內回復「後端面試」，送你一份Java面試題寶典

3.2 過濾器的生命周期

3.3 程式碼示例

/**
 * Zuul過濾器，必須繼承ZuulFilter父類。
 * 當前類型的對象必須交由Spring容器管理。使用@Component註解描述。
 * 繼承父類後，必須實現父類中定義的4個抽象方法。
 * shouldFilter、 run、 filterType、 filterOrder
 */
@Component
public class LoggerFilter extends ZuulFilter {

    private static final Logger logger = LoggerFactory.getLogger(LoggerFilter.class);
    
    /**
     * 返回boolean類型。代表當前filter是否生效。
     * 默認值為false。
     * 返回true代表開啟filter。
     */
    @Override
    public boolean shouldFilter() {
        return true;
    }

    /**
     * run方法就是過濾器的具體邏輯。
     * return 可以返回任意的對象，當前實現忽略。（spring-cloud-zuul官方解釋）
     * 直接返回null即可。
     */
    @Override
    public Object run() throws ZuulException {
        // 通過zuul，獲取請求上下文
        RequestContext rc = RequestContext.getCurrentContext();
        HttpServletRequest request = rc.getRequest();

        logger.info("LogFilter1.....method={},url={}",
                request.getMethod(),request.getRequestURL().toString());
        // 可以記錄日誌、鑒權，給維護人員記錄提供定位協助、統計性能
        return null;
    }

    /**
     * 過濾器的類型。可選值有：
     * pre - 前置過濾
     * route - 路由後過濾
     * error - 異常過濾
     * post - 遠程服務調用後過濾
     */
    @Override
    public String filterType() {
        return "pre";
    }

    /**
     * 同種類的過濾器的執行順序。
     * 按照返回值的自然升序執行。
     */
    @Override
    public int filterOrder() {
        return 0;
    }
}

四、Zuul網關的容錯（與Hystrix的無縫結合）

在spring cloud中，Zuul啟動器中包含了Hystrix相關依賴，在Zuul網關工程中，默認是提供了Hystrix Dashboard服務監控數據的(hystrix.stream)，但是不會提供監控面板的介面展示。可以說，在spring cloud中，zuul和Hystrix是無縫結合的。

4.1 Zuul中的服務降級處理

在Edgware版本之前，Zuul提供了介面ZuulFallbackProvider用於實現fallback處理。從Edgware版本開始，Zuul提供了ZuulFallbackProvider的子介面FallbackProvider來提供fallback處理。

Zuul的fallback容錯處理邏輯，只針對timeout異常處理，當請求被Zuul路由後，只要服務有返回（包括異常），都不會觸發Zuul的fallback容錯邏輯。

因為對於Zuul網關來說，做請求路由分發的時候，結果由遠程服務運算的。那麼遠程服務回饋了異常資訊，Zuul網關不會處理異常，因為無法確定這個錯誤是否是應用真實想要回饋給客戶端的。Java知音公眾號內回復「後端面試」，送你一份Java面試題寶典

4.2 程式碼示例

/**
 * 如果需要在Zuul網關服務中增加容錯處理fallback，需要實現介面ZuulFallbackProvider
 * spring-cloud框架，在Edgware版本(包括)之後，聲明介面ZuulFallbackProvider過期失效，
 * 提供了新的ZuulFallbackProvider的子介面 - FallbackProvider
 * 在老版本中提供的ZuulFallbackProvider中，定義了兩個方法。
 *  - String getRoute()
 *    當前的fallback容錯處理邏輯處理的是哪一個服務。可以使用通配符『*』代表為全部的服務提供容錯處理。
 *    如果只為某一個服務提供容錯，返回對應服務的spring.application.name值。
 *  - ClientHttpResponse fallbackResponse()
 *    當服務發生錯誤的時候，如何容錯。
 * 新版本中提供的FallbackProvider提供了新的方法。
 *  - ClientHttpResponse fallbackResponse(Throwable cause)
 *    如果使用新版本中定義的介面來做容錯處理，容錯處理邏輯，只運行子介面中定義的新方法。也就是有參方法。
 *    是為遠程服務發生異常的時候，通過異常的類型來運行不同的容錯邏輯。
 */
@Component
public class TestFallBbackProvider implements FallbackProvider {

    /**
     * return - 返回fallback處理哪一個服務。返回的是服務的名稱
     * 推薦 - 為指定的服務定義特性化的fallback邏輯。
     * 推薦 - 提供一個處理所有服務的fallback邏輯。
     * 好處 - 服務某個服務發生超時，那麼指定的fallback邏輯執行。如果有新服務上線，未提供fallback邏輯，有一個通用的。
     */
    @Override
    public String getRoute() {
        return "eureka-application-service";
    }

    /**
     * fallback邏輯。在早期版本中使用。
     * Edgware版本之後，ZuulFallbackProvider介面過期，提供了新的子介面FallbackProvider
     * 子介面中提供了方法ClientHttpResponse fallbackResponse(Throwable cause)。
     * 優先調用子介面新定義的fallback處理邏輯。
     */
    @Override
    public ClientHttpResponse fallbackResponse() {
        System.out.println("ClientHttpResponse fallbackResponse()");
        
        List<Map<String, Object>> result = new ArrayList<>();
        Map<String, Object> data = new HashMap<>();
        data.put("message", "服務正忙，請稍後重試");
        result.add(data);
        
        ObjectMapper mapper = new ObjectMapper();
        
        String msg = "";
        try {
            msg = mapper.writeValueAsString(result);
        } catch (JsonProcessingException e) {
            msg = "";
        }
        
        return this.executeFallback(HttpStatus.OK, msg, 
                "application", "json", "utf-8");
    }

    /**
     * fallback邏輯。優先調用。可以根據異常類型動態決定處理方式。
     */
    @Override
    public ClientHttpResponse fallbackResponse(Throwable cause) {
        System.out.println("ClientHttpResponse fallbackResponse(Throwable cause)");
        if(cause instanceof NullPointerException){
            
            List<Map<String, Object>> result = new ArrayList<>();
            Map<String, Object> data = new HashMap<>();
            data.put("message", "網關超時，請稍後重試");
            result.add(data);
            
            ObjectMapper mapper = new ObjectMapper();
            
            String msg = "";
            try {
                msg = mapper.writeValueAsString(result);
            } catch (JsonProcessingException e) {
                msg = "";
            }
            
            return this.executeFallback(HttpStatus.GATEWAY_TIMEOUT, 
                    msg, "application", "json", "utf-8");
        }else{
            return this.fallbackResponse();
        }
    }
    
    /**
     * 具體處理過程。
     * @param status 容錯處理後的返回狀態，如200正常GET請求結果，201正常POST請求結果，404資源找不到錯誤等。
     *  使用spring提供的枚舉類型對象實現。HttpStatus
     * @param contentMsg 自定義的響應內容。就是回饋給客戶端的數據。
     * @param mediaType 響應類型，是響應的主類型， 如：application、text、media。
     * @param subMediaType 響應類型，是響應的子類型， 如：json、stream、html、plain、jpeg、png等。
     * @param charsetName 響應結果的字符集。這裡只傳遞字符集名稱，如：utf-8、gbk、big5等。
     * @return ClientHttpResponse 就是響應的具體內容。
     *  相當於一個HttpServletResponse。
     */
    private final ClientHttpResponse executeFallback(final HttpStatus status, 
            String contentMsg, String mediaType, String subMediaType, String charsetName) {
        return new ClientHttpResponse() {

            /**
             * 設置響應的頭資訊
             */
            @Override
            public HttpHeaders getHeaders() {
                HttpHeaders header = new HttpHeaders();
                MediaType mt = new MediaType(mediaType, subMediaType, Charset.forName(charsetName));
                header.setContentType(mt);
                return header;
            }

            /**
             * 設置響應體
             * zuul會將本方法返回的輸入流數據讀取，並通過HttpServletResponse的輸出流輸出到客戶端。
             */
            @Override
            public InputStream getBody() throws IOException {
                String content = contentMsg;
                return new ByteArrayInputStream(content.getBytes());
            }

            /**
             * ClientHttpResponse的fallback的狀態碼 返回String
             */
            @Override
            public String getStatusText() throws IOException {
                return this.getStatusCode().getReasonPhrase();
            }

            /**
             * ClientHttpResponse的fallback的狀態碼 返回HttpStatus
             */
            @Override
            public HttpStatus getStatusCode() throws IOException {
                return status;
            }

            /**
             * ClientHttpResponse的fallback的狀態碼 返回int
             */
            @Override
            public int getRawStatusCode() throws IOException {
                return this.getStatusCode().value();
            }

            /**
             * 回收資源方法
             * 用於回收當前fallback邏輯開啟的資源對象的。
             * 不要關閉getBody方法返回的那個輸入流對象。
             */
            @Override
            public void close() {
            }
        };
    }
}

五、Zuul網關的限流保護

Zuul網關組件也提供了限流保護。當請求並發達到閥值，自動觸發限流保護，返回錯誤結果。只要提供error錯誤處理機制即可。

Zuul的限流保護需要額外依賴spring-cloud-zuul-ratelimit組件。

<dependency>
    <groupId>com.marcosbarbero.cloud</groupId>
    <artifactId>spring-cloud-zuul-ratelimit</artifactId>
    <version>1.3.4.RELEASE</version>
</dependency>

5.1 全局限流配置

使用全局限流配置，zuul會對代理的所有服務提供限流保護。

# 開啟限流保護
zuul.ratelimit.enabled=true
# 60s內請求超過3次，服務端就拋出異常，60s後可以恢復正常請求
zuul.ratelimit.default-policy.limit=3
zuul.ratelimit.default-policy.refresh-interval=60
# 針對IP進行限流，不影響其他IP
zuul.ratelimit.default-policy.type=origin

5.2 局部限流配置

使用局部限流配置，zuul僅針對配置的服務提供限流保護。

# 開啟限流保護
zuul.ratelimit.enabled=true
# hystrix-application-client服務60s內請求超過3次，服務拋出異常。
zuul.ratelimit.policies.hystrix-application-client.limit=3
zuul.ratelimit.policies.hystrix-application-client.refresh-interval=60
# 針對IP限流。
zuul.ratelimit.policies.hystrix-application-client.type=origin

5.3 限流參數簡介

六、Zuul網關性能調優：網關的兩層超時調優

使用Zuul的spring cloud微服務結構圖：

從上圖中可以看出。整體請求邏輯還是比較複雜的，在沒有zuul網關的情況下，app client請求app service的時候，也有請求超時的可能。那麼當增加了zuul網關的時候，請求超時的可能就更明顯了。

當請求通過zuul網關路由到服務，並等待服務返迴響應，這個過程中zuul也有超時控制。zuul的底層使用的是Hystrix+ribbon來實現請求路由。結構如下：

zuul中的Hystrix內部使用執行緒池隔離機制提供請求路由實現，其默認的超時時長為1000毫秒。ribbon底層默認超時時長為5000毫秒。如果Hystrix超時，直接返回超時異常。如果ribbon超時，同時Hystrix未超時，ribbon會自動進行服務集群輪詢重試，直到Hystrix超時為止。如果Hystrix超時時長小於ribbon超時時長，ribbon不會進行服務集群輪詢重試。

那麼在zuul中可配置的超時時長就有兩個位置：Hystrix和ribbon。具體配置如下：

# 開啟zuul網關重試
zuul.retryable=true
# hystrix超時時間設置
# 執行緒池隔離，默認超時時間1000ms
hystrix.command.default.execution.isolation.thread.timeoutInMilliseconds=8000

# ribbon超時時間設置：建議設置比Hystrix小
# 請求連接的超時時間: 默認5000ms
ribbon.ConnectTimeout=5000
# 請求處理的超時時間: 默認5000ms
ribbon.ReadTimeout=5000
# 重試次數：MaxAutoRetries表示訪問服務集群下原節點（同路徑訪問）；MaxAutoRetriesNextServer表示訪問服務集群下其餘節點（換台伺服器）
ribbon.MaxAutoRetries=1
ribbon.MaxAutoRetriesNextServer=1
# 開啟重試
ribbon.OkToRetryOnAllOperations=true

Spring-cloud中的zuul網關重試機制是使用spring-retry實現的。工程必須依賴下述資源：

<dependency>
  <groupId>org.springframework.retry</groupId>
  <artifactId>spring-retry</artifactId>
</dependency>