SpringCloud Zuul（三）之常见用法

向右看齐 2022-10-29 09:28 109阅读 0赞

### 一、route配置 ###

（1）Zuul Http客户端

Zuul使用的默认HTTP客户端现在由Apache HTTP客户端而不是不推荐使用的Ribbon支持`RestClient`。要使用`RestClient`或`okhttp3.OkHttpClient`设置`ribbon.restclient.enabled=true`或`ribbon.okhttp.enabled=true`。如果要自定义Apache HTTP客户端或OK HTTP客户端，请提供类型为`CloseableHttpClient`或的Bean `OkHttpClient`。

（2）Cookie和sensitiveHeaders

您可以在同一系统中的服务之间共享标头，但是您可能不希望敏感标头泄漏到下游到外部服务器中。您可以在路由配置中指定忽略的标头列表。Cookies发挥着特殊的作用，因为它们在浏览器中具有定义明确的语义，并且始终将它们视为敏感内容。如果代理的使用者是浏览器，那么下游服务的cookie也会给用户带来麻烦，因为它们都混杂在一起（所有下游服务看起来都来自同一位置）。

如果您对服务的设计很谨慎（例如，如果只有一个下游服务设置cookie），则可以让它们从后端一直流到调用者。另外，如果您的代理设置cookie，并且所有后端服务都属于同一系统，则自然可以简单地共享它们（例如，使用Spring Session将其链接到某些共享状态）。除此之外，由下游服务设置的任何cookie可能对调用者都没有用，因此建议您（至少）将`Set-Cookie`其`Cookie`放入不属于域的路由的敏感标头中。即使对于属于您网域的路由，在让Cookie在它们与代理之间流动之前，也应仔细考虑其含义。

可以将敏感头配置为每个路由的逗号分隔列表，如以下示例所示：

**application.yml**

zuul:
      routes:
        users:
          path: /myusers/**
          sensitiveHeaders: Cookie,Set-Cookie,Authorization
          url: https://downstream

注：**这是的默认值sensitiveHeaders，因此除非您希望其与众不同，否则无需进行设置。这是Spring Cloud Netflix 1.1中的新增功能（在1.0中，用户无法控制标题，并且所有cookie都双向流动）。**

该`sensitiveHeaders`是一个黑名单，默认是不为空。因此，要使Zuul发送所有标头（`ignored`那些标头除外），必须将其显式设置为空列表。如果要将Cookie或授权标头传递到后端，则必须这样做。

以下示例显示如何使用`sensitiveHeaders`：

**application.yml**

zuul:
      routes:
        users:
          path: /myusers/**
          sensitiveHeaders:
          url: https://downstream

您还可以通过设置设置敏感的标题`zuul.sensitiveHeaders`。如果`sensitiveHeaders`在路径上设置了，则它将覆盖全局`sensitiveHeaders`设置。

（3）zuul.ignoredHeaders

除了路由敏感的标头之外，您还可以设置一个称为`zuul.ignoredHeaders`值的全局值（请求和响应），在与下游服务进行交互时应将其丢弃。默认情况下，如果Spring Security不在类路径中，则它们为空。否则，它们将被初始化为Spring Security指定的一组众所周知的“安全”标头（例如，涉及缓存）。在这种情况下，假设下游服务也可以添加这些标头，但是我们需要来自代理的值。要在Spring Security位于类路径上时不丢弃这些众所周知的安全标头，可以设置`zuul.ignoreSecurityHeaders`为`false`。如果您在Spring Security中禁用了HTTP Security响应标头并需要下游服务提供的值，则这样做很有用。

### 二、管理终端 ###

默认情况下，如果`@EnableZuulProxy`与Spring Boot Actuator一起使用，则启用两个附加端点：

*  路线
 *  筛选器

（1）路线终点

到路由端点的GET`/routes`返回映射的路由列表：

**GET /路线**

{
      /stores/**: "http://localhost:8081"
    }

可以通过向中添加`?format=details`查询字符串来请求其他路线详细信息`/routes`。这样做会产生以下输出：

**GET /路线/细节**

{
      "/stores/**": {
        "id": "stores",
        "fullPath": "/stores/**",
        "location": "http://localhost:8081",
        "path": "/**",
        "prefix": "/stores",
        "retryable": false,
        "customSensitiveHeaders": false,
        "prefixStripped": true
      }
    }

一`POST请求`到`/routes`暴力刷新现有路由（例如，当在服务目录进行了变更）。您可以通过设置`endpoints.routes.enabled`为禁用此端点`false`。

注：**路由应该自动响应服务目录中的更改，但是`POST请求`到 `/routes`是一种使更改立即发生的方法。**

（2）过滤端点

`GET请求`到过滤器端点的`/filters`按类型返回Zuul过滤器的映射。对于地图中的每种过滤器类型，您将获得该类型的所有过滤器的列表以及它们的详细信息。

### 三、zuul其他配置 ###

（1）扼杀模式和本地转发

迁移现有应用程序或API时，常见的模式是“扼杀”旧的端点，并用不同的实现方式慢慢替换它们。Zuul代理是一个有用的工具，因为您可以使用它来处理来自旧端点客户端的所有流量，但可以将某些请求重定向到新请求。

以下示例显示“扼杀”方案的配置详细信息：

**application.yml**

zuul:
      routes:
        first:
          path: /first/**
          url: https://first.example.com
        second:
          path: /second/**
          url: forward:/second
        third:
          path: /third/**
          url: forward:/3rd
        legacy:
          path: /**
          url: https://legacy.example.com

在前面的示例中，我们扼杀了“旧版”应用程序，该应用程序映射到与其他模式之一不匹配的所有请求。输入的路径`/first/**`已使用外部URL提取到新服务中。`/second/**`转发路径，以便可以在本地处理它们（例如，使用常规Spring `@RequestMapping`）。中的路径`/third/**`也被转发，但是具有不同的前缀（`/third/foo`转发到`/3rd/foo`）。

注：**被忽略的模式不会被完全忽略，它们不会由代理处理（因此它们也可以在本地有效转发）。**

（2）通过Zuul上传文件

如果使用`@EnableZuulProxy`，则可以使用代理路径上载文件，只要文件很小，它就可以工作。对于大文件`DispatcherServlet`，“ / zuul / \*”中有一个替代路径绕过Spring （以避免进行多部分处理）。换句话说，如果您有`zuul.routes.customers=/customers/**`，则可以将`POST`大文件添加到`/zuul/customers/*`。servlet路径通过外部化`zuul.servletPath`。如果代理路由带您通过功能区负载平衡器，则极大的文件也需要提高的超时设置，如以下示例所示：

**application.yml**

hystrix.command.default.execution.isolation.thread.timeoutInMilliseconds: 60000
    ribbon:
      ConnectTimeout: 3000
      ReadTimeout: 60000

请注意，要使流技术处理大文件，您需要在请求中使用分块编码（某些浏览器默认不这样做），如以下示例所示：

$ curl -v -H "Transfer-Encoding: chunked" \
        -F "file=@mylarge.iso" localhost:9999/zuul/simple/file

（3）查询字符串编码

在处理传入请求时，查询参数将被解码，以便可以在Zuul过滤器中进行可能的修改。然后将它们重新编码，在路由过滤器中重建后端请求。如果（例如）使用Javascript`encodeURIComponent()`方法对结果进行编码，则结果可能不同于原始输入。尽管这在大多数情况下不会引起问题，但某些Web服务器可能对复杂查询字符串的编码很挑剔。

为了强制对查询字符串进行原始编码，可以将一个特殊标志传递给，`ZuulProperties`以便使用该`HttpServletRequest::getQueryString`方法按原样使用查询字符串，如以下示例所示：

**application.yml**

zuul:
      forceOriginalQueryStringEncoding: true

注：**此特殊标志仅适用于`SimpleHostRoutingFilter`。此外，您松散了使用轻松覆盖查询参数的功能`RequestContext.getCurrentContext().setRequestQueryParams(someOverriddenParameters)`，因为现在直接在原始上获取查询字符串`HttpServletRequest`。**

（4）请求URI编码

处理传入请求时，在将请求URI与路由匹配之前，先对其进行解码。然后在路由过滤器中重建后端请求时，将对请求URI进行重新编码。如果您的URI包含编码的“ /”字符，则可能导致某些意外行为。

要使用原始请求URI，可以向'ZuulProperties'传递一个特殊标志，以便该URI与该`HttpServletRequest::getRequestURI`方法一样被使用，如以下示例所示：

**application.yml**

zuul:
      decodeUrl: false

注： **如果使用requestURIRequestContext属性覆盖请求URI，并且此标志设置为false，则不会对在请求上下文中设置的URL进行编码。确保URL已被编码是您的责任。**

（5）普通嵌入式Zuul

如果您使用`@EnableZuulServer`（而不是`@EnableZuulProxy`），也可以运行Zuul服务器而不进行代理或有选择地打开代理平台的某些部分。您添加到类型应用程序中的所有bean都会`ZuulFilter`自动安装（与一起使用`@EnableZuulProxy`），但是不会自动添加任何代理过滤器。

在这种情况下，仍然可以通过配置“ zuul.routes.\*”来指定进入Zuul服务器的路由，但是没有服务发现，也没有代理。因此，将忽略“ serviceId”和“ url”设置。以下示例将“ / api / \*\*”中的所有路径映射到Zuul过滤器链：

**application.yml**

zuul:
      routes:
        api: /api/**

（5）禁用Zuul过滤器

Zuul for Spring Cloud附带了许多`ZuulFilter`在代理和服务器模式下默认启用的bean。有关可启用的过滤器列表，请参见[Zuul过滤器包][Zuul]。如果要禁用一个，请设置`zuul.<SimpleClassName>.<filterType>.disable=true`。按照惯例，后面的包`filters`是Zuul过滤器类型。

例如禁用`org.springframework.cloud.netflix.zuul.filters.post.SendResponseFilter`，设置`zuul.SendResponseFilter.post.disable=true`。

（6）为路由提供Hystrix回退

当Zuul中给定路由的环路阻断时，您可以通过创建type的bean提供后备响应`FallbackProvider`。在此bean中，您需要指定回退的路由ID，并提供一个`ClientHttpResponse`作为回退的返回。以下示例显示了一个相对简单的`FallbackProvider`实现：

class MyFallbackProvider implements FallbackProvider {
    
        @Override
        public String getRoute() {
            return "customers";
        }
    
        @Override
        public ClientHttpResponse fallbackResponse(String route, final Throwable cause) {
            if (cause instanceof HystrixTimeoutException) {
                return response(HttpStatus.GATEWAY_TIMEOUT);
            } else {
                return response(HttpStatus.INTERNAL_SERVER_ERROR);
            }
        }
    
        private ClientHttpResponse response(final HttpStatus status) {
            return new ClientHttpResponse() {
                @Override
                public HttpStatus getStatusCode() throws IOException {
                    return status;
                }
    
                @Override
                public int getRawStatusCode() throws IOException {
                    return status.value();
                }
    
                @Override
                public String getStatusText() throws IOException {
                    return status.getReasonPhrase();
                }
    
                @Override
                public void close() {
                }
    
                @Override
                public InputStream getBody() throws IOException {
                    return new ByteArrayInputStream("fallback".getBytes());
                }
    
                @Override
                public HttpHeaders getHeaders() {
                    HttpHeaders headers = new HttpHeaders();
                    headers.setContentType(MediaType.APPLICATION_JSON);
                    return headers;
                }
            };
        }
    }

以下示例显示了上一个示例的路由配置可能如何显示：

zuul:
      routes:
        customers: /customers/**

如果您想为所有路由提供默认的回退，则可以创建一个类型为bean`FallbackProvider`的`getRoute`方法，使其具有return`*`或`null`，如下面的示例所示：

class MyFallbackProvider implements FallbackProvider {
        @Override
        public String getRoute() {
            return "*";
        }
    
        @Override
        public ClientHttpResponse fallbackResponse(String route, Throwable throwable) {
            return new ClientHttpResponse() {
                @Override
                public HttpStatus getStatusCode() throws IOException {
                    return HttpStatus.OK;
                }
    
                @Override
                public int getRawStatusCode() throws IOException {
                    return 200;
                }
    
                @Override
                public String getStatusText() throws IOException {
                    return "OK";
                }
    
                @Override
                public void close() {
    
                }
    
                @Override
                public InputStream getBody() throws IOException {
                    return new ByteArrayInputStream("fallback".getBytes());
                }
    
                @Override
                public HttpHeaders getHeaders() {
                    HttpHeaders headers = new HttpHeaders();
                    headers.setContentType(MediaType.APPLICATION_JSON);
                    return headers;
                }
            };
        }
    }

（7）Zuul超时

如果要为通过Zuul代理的请求配置套接字超时和读取超时，则根据您的配置，有两种选择：

*  如果Zuul使用服务发现，则需要使用`ribbon.ReadTimeout`和`ribbon.SocketTimeout`功能区属性配置这些超时 。

如果通过指定URL配置了Zuul路由，则需要使用 `zuul.host.connect-timeout-millis`和`zuul.host.socket-timeout-millis`。

（8）重写Location header

如果Zuul在Web应用程序的前面，则`Location`当Web应用程序通过HTTP状态代码重定向时，您可能需要重新编写标头`3XX`。否则，浏览器将重定向到Web应用程序的URL，而不是Zuul URL。您可以配置`LocationRewriteFilter`Zuul过滤器以将`Location`标头重写为Zuul的URL。它还会添加回去的全局前缀和特定于路由的前缀。以下示例通过使用Spring Configuration文件添加过滤器：

import org.springframework.cloud.netflix.zuul.filters.post.LocationRewriteFilter;
    ...
    
    @Configuration
    @EnableZuulProxy
    public class ZuulConfig {
        @Bean
        public LocationRewriteFilter locationRewriteFilter() {
            return new LocationRewriteFilter();
        }
    }

注：小心使用此过滤器。筛选器作用于Location所有3XX响应代码的标头，这可能不适用于所有情况，例如将用户重定向到外部URL时。

（9）启用跨源请求

默认情况下，Zuul将所有跨源请求（CORS）路由到服务。如果您想让Zuul处理这些请求，可以通过提供自定义`WebMvcConfigurer`bean来完成：

@Bean
    public WebMvcConfigurer corsConfigurer() {
        return new WebMvcConfigurer() {
            public void addCorsMappings(CorsRegistry registry) {
                registry.addMapping("/path-1/**")
                        .allowedOrigins("https://allowed-origin.com")
                        .allowedMethods("GET", "POST");
            }
        };
    }

在上面的示例中，我们允许`GET`和`POST`方法从`allowed-origin.com`将跨域请求发送到以开头的端点`path-1`。您可以使用`/**`映射将CORS配置应用于特定的路径模式，也可以全局应用于整个应用程序。您可以自定义属性：`allowedOrigins`，`allowedMethods`，`allowedHeaders`，`exposedHeaders`，`allowCredentials`并`maxAge`通过此配置。

（10）监控指标

Zuul将在执行器指标端点下提供指标，以解决路由请求时可能发生的任何故障。您可以点击来查看这些指标`/actuator/metrics`。指标将具有格式为的名称 `ZUUL::EXCEPTION:errorCause:statusCode`。

[Zuul]: https://github.com/spring-cloud/spring-cloud-netflix/tree/master/spring-cloud-netflix-zuul/src/main/java/org/springframework/cloud/netflix/zuul/filters