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,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过滤器中进行可能的修改。然后将它们重新编码,在路由过滤器中重建后端请求。如果(例如)使用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 {
@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/**
如果您想为所有路由提供默认的回退,则可以创建一个类型为beanFallbackProvider
的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:errorCause:statusCode
。
还没有评论,来说两句吧...