Spring Cloud Gateway文档翻译

Spring Cloud Gateway

以下是这个地址的翻译：

https://cloud.spring.io/spring-cloud-gateway/reference/html/#gateway-starter

3.0.0-SNAPSHOT

This project provides an API Gateway built on top of the Spring Ecosystem, including: Spring 5, Spring Boot 2 and Project Reactor. Spring Cloud Gateway aims to provide a simple, yet effective way to route to APIs and provide cross cutting concerns to them such as: security, monitoring/metrics, and resiliency.

翻译

该项目提供了一个建立在Spring生态系统之上的API网关，包括：Spring 5、Spring Boot 2和project Reactor。Spring Cloud Gateway旨在提供一种简单而有效的方法来路由到API，并为它们提供跨领域的关注点，例如：安全性、监控指标和弹性。

1.How to Include Spring Cloud Gateway

如何包含Spring Cloud Gateway

To include Spring Cloud Gateway in your project, use the starter with a group ID of org.springframework.cloud and an artifact ID of spring-cloud-starter-gateway. See the Spring Cloud Project page for details on setting up your build system with the current Spring Cloud Release Train.

If you include the starter, but you do not want the gateway to be enabled, set spring.cloud.gateway.enabled=false.

翻译

要在您的项目中包括Spring Cloud Gateway，请使用组ID为org.springframework.Cloud和工件ID为Spring Cloud starter Gateway的启动器。有关使用当前Spring Cloud Release Train设置构建系统的详细信息，请参阅Spring Cloud Project页面。如果包含启动器，但不希望启用网关，请将spring.cloud.gateway.enabled设置为false。

 	Spring Cloud Gateway is built on Spring Boot 2.x, Spring WebFlux, and Project Reactor. As a consequence, many of the familiar synchronous libraries (Spring Data and Spring Security, for example) and patterns you know may not apply when you use Spring Cloud Gateway. If you are unfamiliar with these projects, we suggest you begin by reading their documentation to familiarize yourself with some of the new concepts before working with Spring Cloud Gateway.

翻译

Spring Cloud Gateway构建在Spring Boot 2.x、Spring WebFlux和Project Reactor上。因此，当您使用Spring Cloud Gateway时，您所知道的许多熟悉的同步库（例如，Spring Data和Spring Security）和模式可能不适用。如果您不熟悉这些项目，我们建议您在使用Spring Cloud Gateway之前，先阅读它们的文档，熟悉一些新概念。

 Spring Cloud Gateway requires the Netty runtime provided by Spring Boot and Spring Webflux. It does not work in a traditional Servlet Container or when built as a WAR.

翻译

Spring Cloud Gateway需要Spring Boot和Spring Webflux提供的Netty运行时。它不能在传统的Servlet容器中工作，也不能作为WAR构建。

2. Glossary

术语汇编

    Route: The basic building block of the gateway. It is defined by an ID, a destination URI, a collection of predicates, and a collection of filters. A route is matched if the aggregate predicate is true.

    Predicate: This is a Java 8 Function Predicate. The input type is a Spring Framework ServerWebExchange. This lets you match on anything from the HTTP request, such as headers or parameters.

    Filter: These are instances of Spring Framework GatewayFilter that have been constructed with a specific factory. Here, you can modify requests and responses before or after sending the downstream request.

翻译

路线：网关的基本构建块。它由一个ID、一个目标URI、一组谓词和一组筛选器定义。如果聚合谓词为true，则匹配路由。谓词：这是一个Java 8函数谓词。输入类型为Spring Framework ServerWebExchange。这允许您匹配HTTP请求中的任何内容，例如标头或参数。Filter：这些是使用特定工厂构建的Spring Framework GatewayFilter的实例。在这里，您可以在发送下游请求之前或之后修改请求和响应。

3.How It Works

它的工作原理

The following diagram provides a high-level overview of how Spring Cloud Gateway works:

翻译

下图提供了Spring Cloud Gateway如何工作的高级概述：


Clients make requests to Spring Cloud Gateway. If the Gateway Handler Mapping determines that a request matches a route, it is sent to the Gateway Web Handler. This handler runs the request through a filter chain that is specific to the request. The reason the filters are divided by the dotted line is that filters can run logic both before and after the proxy request is sent. All “pre” filter logic is executed. Then the proxy request is made. After the proxy request is made, the “post” filter logic is run.

翻译

客户端向Spring Cloud Gateway发出请求。如果网关处理程序映射确定请求与路由匹配，则会将其发送到网关Web处理程序。此处理程序通过特定于请求的筛选器链来运行请求。过滤器被虚线分隔的原因是过滤器可以在发送代理请求之前和之后运行逻辑。执行所有“预”过滤器逻辑。然后进行代理请求。在发出代理请求后，将运行“post”过滤器逻辑。

 URIs defined in routes without a port get default port values of 80 and 443 for the HTTP and HTTPS URIs, respectively.

翻译

在没有端口的路由中定义的URI分别获得HTTP和HTTPS URI的默认端口值80和443。

4.Configuring Route Predicate Factories and Gateway Filter Factories

配置路由谓词工厂和网关筛选器工厂

There are two ways to configure predicates and filters: shortcuts and fully expanded arguments. Most examples below use the shortcut way.

The name and argument names will be listed as code in the first sentance or two of the each section. The arguments are typically listed in the order that would be needed for the shortcut configuration.

翻译

有两种方法可以配置谓词和筛选器：快捷方式和完全展开的参数。下面的大多数示例都使用快捷方式。名称和参数名称将作为代码列在每个部分的第一个或两个符号中。参数通常按快捷方式配置所需的顺序列出。

4.1Shortcut Configuration

快捷方式配置

Shortcut configuration is recognized by the filter name, followed by an equals sign (=), followed by argument values separated by commas (,).

翻译

快捷方式配置由筛选器名称识别，后跟等号（=），后跟用逗号分隔的参数值（，）。

application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: after_route
        uri: https://example.org
        predicates:
        - Cookie=mycookie,mycookievalue

The previous sample defines the Cookie Route Predicate Factory with two arguments, the cookie name, mycookie and the value to match mycookievalue.

翻译

上一个示例使用两个参数定义Cookie路由谓词工厂，即Cookie名称、mykokie和匹配mykokievalue的值。

4.2Fully Expanded Arguments

完全展开的参数

Fully expanded arguments appear more like standard yaml configuration with name/value pairs. Typically, there will be a name key and an args key. The args key is a map of key value pairs to configure the predicate or filter.

翻译

完全展开的参数看起来更像带有名称值对的标准yaml配置。通常，会有一个名称键和一个args键。args键是用于配置谓词或筛选器的键值对的映射。

application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: after_route
        uri: https://example.org
        predicates:
        - name: Cookie
          args:
            name: mycookie
            regexp: mycookievalue

This is the full configuration of the shortcut configuration of the Cookie predicate shown above.

翻译

这是上面显示的Cookie谓词的快捷方式配置的完整配置。

5.Route Predicate Factories

路线谓词工厂

Spring Cloud Gateway matches routes as part of the Spring WebFlux HandlerMapping infrastructure. Spring Cloud Gateway includes many built-in route predicate factories. All of these predicates match on different attributes of the HTTP request. You can combine multiple route predicate factories with logical and statements.

翻译

Spring Cloud Gateway将路由作为Spring WebFlux HandlerMapping基础设施的一部分进行匹配。Spring Cloud Gateway包括许多内置的路由谓词工厂。所有这些谓词在HTTP请求的不同属性上匹配。您可以将多个路由谓词工厂与逻辑和语句相结合。

5.1The After Route Predicate Factory

后路由谓词工厂


The After route predicate factory takes one parameter, a datetime (which is a java ZonedDateTime). This predicate matches requests that happen after the specified datetime. The following example configures an after route predicate:

翻译

After路由谓词工厂接受一个参数，一个日期时间（它是一个javaZonedDateTime）。此谓词匹配在指定日期时间之后发生的请求。以下示例配置路由后谓词：

Example 1. application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: after_route
        uri: https://example.org
        predicates:
        - After=2017-01-20T17:42:47.789-07:00[America/Denver]

This route matches any request made after Jan 20, 2017 17:42 Mountain Time (Denver).

此路线符合2017年1月20日17:42山地时间（丹佛）之后提出的任何请求。

5.2 The Before Route Predicate Factory

路由前谓词工厂

The Before route predicate factory takes one parameter, a datetime (which is a java ZonedDateTime). This predicate matches requests that happen before the specified datetime. The following example configures a before route predicate:

翻译

Before路由谓词工厂接受一个参数，一个日期时间（它是一个javaZonedDateTime）。此谓词匹配在指定日期时间之前发生的请求。以下示例配置路由前谓词：

Example 2. application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: before_route
        uri: https://example.org
        predicates:
        - Before=2017-01-20T17:42:47.789-07:00[America/Denver]

This route matches any request made before Jan 20, 2017 17:42 Mountain Time (Denver).

此路线符合2017年1月20日17:42山地时间（丹佛）之前提出的任何请求。

5.3 The Between Route Predicate Factory

路由间谓词工厂

The Between route predicate factory takes two parameters, datetime1 and datetime2 which are java ZonedDateTime objects. This predicate matches requests that happen after datetime1 and before datetime2. The datetime2 parameter must be after datetime1. The following example configures a between route predicate:

翻译

Between路由谓词工厂接受两个参数，datetime1和datetime2，它们是javaZonedDateTime对象。此谓词匹配发生在datetime1之后和datetime2之前的请求。datetime2参数必须在datetime1之后。以下示例配置路由之间的谓词：

Example 3. application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: between_route
        uri: https://example.org
        predicates:
        - Between=2017-01-20T17:42:47.789-07:00[America/Denver], 2017-01-21T17:42:47.789-07:00[America/Denver]

This route matches any request made after Jan 20, 2017 17:42 Mountain Time (Denver) and before Jan 21, 2017 17:42 Mountain Time (Denver). This could be useful for maintenance windows.

此路线符合2017年1月20日17:42山地时间（丹佛）之后至2017年1日21日17:42山区时间（丹佛市）之前提出的任何请求。这可能对维护窗口很有用。

Cookie路由谓词工厂

The Cookie route predicate factory takes two parameters, the cookie name and a regexp (which is a Java regular expression). This predicate matches cookies that have the given name and whose values match the regular expression. The following example configures a cookie route predicate factory:

翻译

Cookie路由谓词工厂接受两个参数，即Cookie名称和regexp（这是一个Java正则表达式）。此谓词匹配具有给定名称且其值与正则表达式匹配的cookie。以下示例配置cookie路由谓词工厂：

Example 4. application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: cookie_route
        uri: https://example.org
        predicates:
        - Cookie=chocolate, ch.p

This route matches requests that have a cookie named chocolate whose value matches the ch.p regular expression.

此路由匹配具有名为chocolate的cookie的请求，该cookie的值与ch.p正则表达式匹配。

5.5 the Header Route Predicate Factory

标题路由谓词工厂

The Header route predicate factory takes two parameters, the header name and a regexp (which is a Java regular expression). This predicate matches with a header that has the given name whose value matches the regular expression. The following example configures a header route predicate:

翻译

Header路由谓词工厂接受两个参数，即标头名称和regexp（这是一个Java正则表达式）。此谓词与具有给定名称的标头匹配，该名称的值与正则表达式匹配。以下示例配置标头路由谓词：

Example 5. application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: header_route
        uri: https://example.org
        predicates:
        - Header=X-Request-Id, \d+

This route matches if the request has a header named X-Request-Id whose value matches the \d+ regular expression (that is, it has a value of one or more digits).

翻译

如果请求的标头名为X-request-Id，其值与\d+正则表达式匹配（即，其值为一个或多个数字），则此路由匹配。

5.6 The Host Route Predicate Factory

主机路由谓词工厂

The Host route predicate factory takes one parameter: a list of host name patterns. The pattern is an Ant-style pattern with . as the separator. This predicates matches the Host header that matches the pattern. The following example configures a host route predicate:

翻译

Host路由谓词工厂接受一个参数：主机名模式列表。该模式是Ant样式的模式。作为分离器。此谓词与匹配模式的Host标头相匹配。以下示例配置主机路由谓词：

Example 6. application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: host_route
        uri: https://example.org
        predicates:
        - Host=**.somehost.org,**.anotherhost.org


URI template variables (such as {sub}.myhost.org) are supported as well.

This route matches if the request has a Host header with a value of www.somehost.org or beta.somehost.org or www.anotherhost.org.

This predicate extracts the URI template variables (such as sub, defined in the preceding example) as a map of names and values and places it in the ServerWebExchange.getAttributes() with a key defined in ServerWebExchangeUtils.URI_TEMPLATE_VARIABLES_ATTRIBUTE. Those values are then available for use by GatewayFilter factories

翻译

URI模板变量（如{sub}.myhost.org）也受支持。如果请求的Host标头的值为www.somehost.org或beta.somehost.org或www.anotherhost.org，则此路由匹配。此谓词提取URI模板变量（如前面示例中定义的sub）作为名称和值的映射，并将其放置在ServerWebExchange.getAttributes（）中，其中包含ServerWebExchangeUtils.URI_template_ARIABLES_ATTRIBUTE中定义的键。然后这些值可供GatewayFilter工厂使用

5.7 The Method Route Predicate Factory

方法路由谓词工厂

The Method Route Predicate Factory takes a methods argument which is one or more parameters: the HTTP methods to match. The following example configures a method route predicate:

翻译

方法路由谓词工厂接受一个方法参数，该参数是一个或多个参数：要匹配的HTTP方法。以下示例配置方法路由谓词：

Example 7. application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: method_route
        uri: https://example.org
        predicates:
        - Method=GET,POST


This route matches if the request method was a GET or a POST.


该路由匹配请求方法是GET还是POST。

5.8 The Path Route Predicate Factory

路径路由谓词工厂

The Path Route Predicate Factory takes two parameters: a list of Spring PathMatcher patterns and an optional flag called matchOptionalTrailingSeparator. The following example configures a path route predicate:

翻译

路径路由谓词工厂采用两个参数：Spring PathMatcher模式列表和名为matchOptionalTrailingSeparator的可选标志。以下示例配置路径路由谓词：

Example 8. application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: path_route
        uri: https://example.org
        predicates:
        - Path=/red/{segment},/blue/{segment}


This route matches if the request path was, for example: /red/1 or /red/blue or /blue/green.

This predicate extracts the URI template variables (such as segment, defined in the preceding example) as a map of names and values and places it in the ServerWebExchange.getAttributes() with a key defined in ServerWebExchangeUtils.URI_TEMPLATE_VARIABLES_ATTRIBUTE. Those values are then available for use by GatewayFilter factories

A utility method (called get) is available to make access to these variables easier. The following example shows how to use the get method:

翻译

如果请求路径为，则此路由匹配，例如：red1、redblue或bluegreen。此谓词提取URI模板变量（如前面示例中定义的段）作为名称和值的映射，并将其放置在ServerWebExchange.getAttributes（）中，其中包含ServerWebExchangeUtils.URI_template_ARIABLES_ATTRIBUTE中定义的键。然后，GatewayFilter工厂可以使用这些值。可以使用一个实用程序方法（称为get）来更容易地访问这些变量。以下示例显示了如何使用get方法：

Map<String, String> uriVariables = ServerWebExchangeUtils.getPathPredicateVariables(exchange);

String segment = uriVariables.get("segment");

5.9 the Query Route Predicate Factory

查询路由谓词工厂

The Query route predicate factory takes two parameters: a required param and an optional regexp (which is a Java regular expression). The following example configures a query route predicate:

翻译

Query路由谓词工厂接受两个参数：一个必需的param和一个可选的regexp（它是Java正则表达式）。以下示例配置查询路由谓词：

Example 9. application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: query_route
        uri: https://example.org
        predicates:
        - Query=green

The preceding route matches if the request contained a green query parameter.

如果请求包含“绿色”查询参数，则前面的路由匹配。

application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: query_route
        uri: https://example.org
        predicates:
        - Query=red, gree.

The preceding route matches if the request contained a red query parameter whose value matched the gree. regexp, so green and greet would match.

翻译

如果请求包含一个值与gree匹配的红色查询参数，则前面的路由匹配。regexp，因此绿色和问候语将匹配。

5.10 The RemoteAddr Route Predicate Factory

RemoteAddr路由谓词工厂

The RemoteAddr route predicate factory takes a list (min size 1) of sources, which are CIDR-notation (IPv4 or IPv6) strings, such as 192.168.0.1/16 (where 192.168.0.1 is an IP address and 16 is a subnet mask). The following example configures a RemoteAddr route predicate:

翻译

RemoteAddr路由谓词工厂获取源的列表（最小大小为1），这些源是CIDR表示法（IPv4或IPv6）字符串，例如192.168.0.116（其中192.168.0.1是IP地址，16是子网掩码）。以下示例配置RemoteAddr路由谓词：

Example 10. application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: remoteaddr_route
        uri: https://example.org
        predicates:
        - RemoteAddr=192.168.1.1/24


This route matches if the remote address of the request was, for example, 192.168.1.10.

翻译

如果请求的远程地址是192.168.1.10，则此路由匹配。

5.11 The Weight Route Predicate Factory

重量路线谓词工厂


The Weight route predicate factory takes two arguments: group and weight (an int). The weights are calculated per group. The following example configures a weight route predicate:

翻译

Weight路由谓词工厂接受两个参数：group和Weight（一个int）。重量按每组计算。以下示例配置权重路由谓词：

Example 11. application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: weight_high
        uri: https://weighthigh.org
        predicates:
        - Weight=group1, 8
      - id: weight_low
        uri: https://weightlow.org
        predicates:
        - Weight=group1, 2

这条路线将约80%的流量转发到weighthigh.org，约20%的流量转发给weightlow.org

5.11.1 Modifying the Way Remote Addresses Are Resolved

修改远程地址的解析方式


By default, the RemoteAddr route predicate factory uses the remote address from the incoming request. This may not match the actual client IP address if Spring Cloud Gateway sits behind a proxy layer.

You can customize the way that the remote address is resolved by setting a custom RemoteAddressResolver. Spring Cloud Gateway comes with one non-default remote address resolver that is based off of the X-Forwarded-For header, XForwardedRemoteAddressResolver.

XForwardedRemoteAddressResolver has two static constructor methods, which take different approaches to security:

    XForwardedRemoteAddressResolver::trustAll returns a RemoteAddressResolver that always takes the first IP address found in the X-Forwarded-For header. This approach is vulnerable to spoofing, as a malicious client could set an initial value for the X-Forwarded-For, which would be accepted by the resolver.

    XForwardedRemoteAddressResolver::maxTrustedIndex takes an index that correlates to the number of trusted infrastructure running in front of Spring Cloud Gateway. If Spring Cloud Gateway is, for example only accessible through HAProxy, then a value of 1 should be used. If two hops of trusted infrastructure are required before Spring Cloud Gateway is accessible, then a value of 2 should be used.

Consider the following header value:

翻译

默认情况下，RemoteAddr路由谓词工厂使用传入请求的远程地址。如果Spring Cloud Gateway位于代理层后面，则这可能与实际的客户端IP地址不匹配。您可以通过设置自定义RemoteAddressResolver来自定义解析远程地址的方式。Spring Cloud Gateway附带了一个基于X-Forwarded-For标头XForwardedRemoveAddressResolver的非默认远程地址解析程序。XForwardedRemoveAddressResolver有两个静态构造函数方法，它们采用不同的安全方法：XForwarded RemoveAddressResolver:：trustAll返回一个RemoteAddressResolver，它总是采用X-Forwarded-For标头中找到的第一个IP地址。这种方法很容易受到欺骗，因为恶意客户端可能会设置X-Forwarded-for的初始值，该值将被解析程序接受。XForwardedRemoveAddressResolver:：maxTrustedIndex获取一个索引，该索引与Spring Cloud Gateway前面运行的受信任基础设施的数量相关。例如，如果Spring Cloud Gateway只能通过HAProxy访问，则应使用值1。如果在访问Spring Cloud Gateway之前需要两跳可信基础设施，则应使用值2。考虑以下标头值：


X-Forwarded-For: 0.0.0.1, 0.0.0.2, 0.0.0.3




The following maxTrustedIndex values yield the following remote addresses:


以下maxTrustedIndex值产生以下远程地址：
maxTrustedIndex result
[Integer.MIN_VALUE,0] (invalid, IllegalArgumentException during initialization)
1 0.0.0.3
2 0.0.0.2
3 0.0.0.1
[4, Integer.MAX_VALUE] 0.0.0.1 

The following example shows how to achieve the same configuration with Java:

翻译

以下示例显示了如何使用Java实现相同的配置：

Example 12. GatewayConfig.java

RemoteAddressResolver resolver = XForwardedRemoteAddressResolver
    .maxTrustedIndex(1);

...

.route("direct-route",
    r -> r.remoteAddr("10.1.1.1", "10.10.1.1/24")
        .uri("https://downstream1")
.route("proxied-route",
    r -> r.remoteAddr(resolver, "10.10.1.1", "10.10.1.1/24")
        .uri("https://downstream2")
)
posted @ 2023-08-02 14:17  三号小玩家  阅读(131)  评论(0)    收藏  举报
Title
快
乐
三号小玩家的 Mail: 17612457115@163.com, 联系QQ: 1359720840 微信: QQ1359720840