SpringCloud Zuul（三）之常见用法

一、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,Authorizationurl: 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.comsecond:path: /second/**url: forward:/secondthird:path: /third/**url: forward:/3rdlegacy: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: 3000ReadTimeout: 60000

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

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

（3）查询字符串编码

在处理传入请求时，查询参数将被解码，以便可以在Zuul过滤器中进行可能的修改。然后将它们重新编码，在路由过滤器中重建后端请求。如果（例如）使用JavascriptencodeURIComponent()方法对结果进行编码，则结果可能不同于原始输入。尽管这在大多数情况下不会引起问题，但某些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.<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 {@Overridepublic String getRoute() {return "customers";}@Overridepublic 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() {@Overridepublic HttpStatus getStatusCode() throws IOException {return status;}@Overridepublic int getRawStatusCode() throws IOException {return status.value();}@Overridepublic String getStatusText() throws IOException {return status.getReasonPhrase();}@Overridepublic void close() {}@Overridepublic InputStream getBody() throws IOException {return new ByteArrayInputStream("fallback".getBytes());}@Overridepublic HttpHeaders getHeaders() {HttpHeaders headers = new HttpHeaders();headers.setContentType(MediaType.APPLICATION_JSON);return headers;}};}
}

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

zuul:routes:customers: /customers/**

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

class MyFallbackProvider implements FallbackProvider {@Overridepublic String getRoute() {return "*";}@Overridepublic ClientHttpResponse fallbackResponse(String route, Throwable throwable) {return new ClientHttpResponse() {@Overridepublic HttpStatus getStatusCode() throws IOException {return HttpStatus.OK;}@Overridepublic int getRawStatusCode() throws IOException {return 200;}@Overridepublic String getStatusText() throws IOException {return "OK";}@Overridepublic void close() {}@Overridepublic InputStream getBody() throws IOException {return new ByteArrayInputStream("fallback".getBytes());}@Overridepublic 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。您可以配置LocationRewriteFilterZuul过滤器以将Location标头重写为Zuul的URL。它还会添加回去的全局前缀和特定于路由的前缀。以下示例通过使用Spring Configuration文件添加过滤器：

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

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

（9）启用跨源请求

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

@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通过此配置。