本指南将引导您逐步了解如何使用Spring Cloud Gateway

你会建立什么

您将使用Spring Cloud Gateway构建一个网关。

你需要什么

如何完成本指南

像大多数Spring入门指南一样，您可以从头开始并完成每个步骤，也可以绕过您已经熟悉的基本设置步骤。无论哪种方式，您最终都可以使用代码。

要从头开始，请继续使用Gradle构建。

要跳过基础知识，请执行以下操作：

完成后，您可以根据中的代码检查结果gs-gateway/complete。

用Gradle构建

用Gradle构建

首先，您设置一个基本的构建脚本。在使用Spring构建应用程序时，可以使用任何喜欢的构建系统，但是此处包含使用Gradle和Maven所需的代码。如果您都不熟悉，请参阅使用Gradle构建Java项目或使用Maven构建Java项目。

创建目录结构

在您选择的项目目录中，创建以下子目录结构；例如，mkdir -p src/main/java/hello在* nix系统上：

└──src
    main──主要
        └──java
            └──你好

创建一个Gradle构建文件

以下是最初的Gradle构建文件。

build.gradle

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:2.1.7.RELEASE")
    }
}

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'idea'
apply plugin: 'org.springframework.boot'
apply plugin: 'io.spring.dependency-management'

bootJar {
    baseName = 'gs-gateway'
    version =  '0.1.0'
}

repositories {
    mavenCentral()
}

sourceCompatibility = 1.8
targetCompatibility = 1.8

dependencyManagement {
    imports {
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:Greenwich.SR2"
    }
}

dependencies {
    compile("org.springframework.cloud:spring-cloud-starter-gateway")
    compile("org.springframework.cloud:spring-cloud-starter-netflix-hystrix")
    compile("org.springframework.cloud:spring-cloud-starter-contract-stub-runner"){
        exclude group: "org.springframework.boot", module: "spring-boot-starter-web"
    }
    testCompile("org.springframework.boot:spring-boot-starter-test")
}

在Spring的Gradle启动插件提供了许多便捷的功能：

  • 它收集类路径上的所有jar，并构建一个可运行的单个“über-jar”，这使执行和传输服务更加方便。

  • 它搜索public static void main()要标记为可运行类的方法。

  • 它提供了一个内置的依赖项解析器，用于设置版本号以匹配Spring Boot依赖项。您可以覆盖所需的任何版本，但是它将默认为Boot选择的一组版本。

用Maven编译

用Maven编译

首先，您设置一个基本的构建脚本。使用Spring构建应用程序时，可以使用任何喜欢的构建系统，但是此处包含了使用Maven所需的代码。如果您不熟悉Maven，请参阅使用Maven构建Java项目。

创建目录结构

在您选择的项目目录中，创建以下子目录结构；例如，mkdir -p src/main/java/hello在* nix系统上：

└──src
    main──主要
        └──java
            └──你好

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.springframework</groupId>
    <artifactId>gs-gateway</artifactId>
    <version>0.1.0</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.7.RELEASE</version>
    </parent>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>Greenwich.SR2</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-gateway</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-netflix-hystrix</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-contract-stub-runner</artifactId>
            <exclusions>
                <exclusion>
                    <artifactId>spring-boot-starter-web</artifactId>
                    <groupId>org.springframework.boot</groupId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

在Spring启动Maven插件提供了许多便捷的功能：

  • 它收集类路径上的所有jar，并构建一个可运行的单个“über-jar”，这使执行和传输服务更加方便。

  • 它搜索public static void main()要标记为可运行类的方法。

  • 它提供了一个内置的依赖项解析器，用于设置版本号以匹配Spring Boot依赖项。您可以覆盖所需的任何版本，但是它将默认为Boot选择的一组版本。

使用您的IDE进行构建

使用您的IDE进行构建

创建一条简单的路线

Spring Cloud Gateway使用路由来处理对下游服务的请求。在本指南中，我们会将所有请求路由到HTTPBin。可以通过多种方式配置路由，但对于本指南，我们将使用网关提供的Java API。

要开始，创建一个新的Bean类型的RouteLocator在Application.java。

src/main/java/gateway/Application.java

@Bean
public RouteLocator myRoutes(RouteLocatorBuilder builder) {
    return builder.routes().build();
}

上面的myRoutes方法采用RouteLocatorBuilder，可以轻松地用于创建路由。除了仅创建路由外，还RouteLocatorBuilder允许您在路由中添加谓词和过滤器，以便您可以根据特定条件路由句柄，并根据需要更改请求/响应。

让我们创建一条路由，将请求https://httpbin.org/get发送到处的网关/get。在此路由的配置中，我们将添加一个过滤器，该过滤器将在路由请求之前将请求标头Hello和该值添加到请求中World。

src/main/java/gateway/Application.java

@Bean
public RouteLocator myRoutes(RouteLocatorBuilder builder) {
    return builder.routes()
        .route(p -> p
            .path("/get")
            .filters(f -> f.addRequestHeader("Hello", "World"))
            .uri("http://httpbin.org:80"))
        .build();
}

要测试我们非常简单的网关，只需运行Application.java它，它应该在port上运行8080。应用程序运行后，向发出请求http://localhost:8080/get。您可以通过在终端中发出以下命令来使用cURL进行此操作。

$ curl http://localhost:8080/get

您应该会收到类似以下的回复

{
  "args": {},
  "headers": {
    "Accept": "*/*",
    "Connection": "close",
    "Forwarded": "proto=http;host=\"localhost:8080\";for=\"0:0:0:0:0:0:0:1:56207\"",
    "Hello": "World",
    "Host": "httpbin.org",
    "User-Agent": "curl/7.54.0",
    "X-Forwarded-Host": "localhost:8080"
  },
  "origin": "0:0:0:0:0:0:0:1, 73.68.251.70",
  "url": "http://localhost:8080/get"
}

请注意，HTTPBin显示Hello具有该值的标头World已在请求中发送。

使用Hystrix

现在，让我们做一些更有趣的事情。由于网关后面的服务可能会对客户产生不良影响，因此我们可能希望将在断路器中创建的路由包装起来。您可以使用Hystrix在Spring Cloud Gateway中执行此操作。这是通过可以添加到请求中的简单过滤器实现的。让我们创建另一条路线来证明这一点。

在此示例中，我们将利用HTTPBin的延迟API，该API在发送响应之前等待一定秒数。由于此API可能会花费很长时间来发送其响应，因此我们可以将使用此API的路由包装到HystrixCommand。向我们的RouteLocator对象添加一条新路由，如下所示

src/main/java/gateway/Application.java

@Bean
public RouteLocator myRoutes(RouteLocatorBuilder builder) {
    return builder.routes()
        .route(p -> p
            .path("/get")
            .filters(f -> f.addRequestHeader("Hello", "World"))
            .uri("http://httpbin.org:80"))
        .route(p -> p
            .host("*.hystrix.com")
            .filters(f -> f.hystrix(config -> config.setName("mycmd")))
            .uri("http://httpbin.org:80")).
        build();
}

此新路由配置与我们创建的上一个路由配置之间存在一些差异。首先，我们使用主机谓词而不是路径谓词。这意味着只要是主机，hystrix.com我们就将请求路由到HTTPBin并将该请求包装在HystrixCommand。我们通过对路由应用过滤器来做到这一点。Hystrix过滤器可以使用配置对象进行配置。在此示例中，我们仅给出HystrixCommand名称mycmd。

让我们测试一下这条新路线。启动应用程序，但是这次我们要向发出请求/delay/3。同样重要的是，我们要包含一个Host标头，该标头具有的主机，hystrix.com否则该请求将不会被路由。在cURL中，这看起来像

$ curl --dump-header - --header 'Host: www.hystrix.com' http://localhost:8080/delay/3
我们--dump-header用来查看响应标头，-之后--dump-header是告诉cURL将标头打印到stdout。

执行此命令后，您应该在终端中看到以下内容

HTTP/1.1 504 Gateway Timeout
content-length: 0

如您所见，Hystrix等待HTTPBin的响应超时。当Hystrix超时时，我们可以选择提供一个后备选项，这样客户不仅会收到a504而是更有意义的东西。例如，在生产场景中，您可能会从缓存中返回一些数据，但是在我们的简单示例中，我们将只返回带有主体的响应fallback。

为此，让我们修改Hystrix过滤器以提供一个URL，以便在超时的情况下进行调用。

src/main/java/gateway/Application.java

@Bean
public RouteLocator myRoutes(RouteLocatorBuilder builder) {
    return builder.routes()
        .route(p -> p
            .path("/get")
            .filters(f -> f.addRequestHeader("Hello", "World"))
            .uri("http://httpbin.org:80"))
        .route(p -> p
            .host("*.hystrix.com")
            .filters(f -> f.hystrix(config -> config
                .setName("mycmd")
                .setFallbackUri("forward:/fallback")))
            .uri("http://httpbin.org:80"))
        .build();
}

现在，当Hystrix包装的路由超时时，它将/fallback在Gateway应用程序中调用。让我们将/fallback端点添加到我们的应用程序中。

在Application.java添加类级别注释中@RestController，然后将以下内容添加@RequestMapping到该类中。

src/main/java/gateway/Application.java

@RequestMapping("/fallback")
public Mono<String> fallback() {
  return Mono.just("fallback");
}

要测试此新的后备功能，请重新启动应用程序，然后再次发出以下cURL命令

$ curl --dump-header - --header 'Host: www.hystrix.com' http://localhost:8080/delay/3

回退到位后，我们现在看到200响应主体为的网关提供了回退fallback。

HTTP/1.1 200 OK
transfer-encoding: chunked
Content-Type: text/plain;charset=UTF-8

fallback

写作测试

作为一名优秀的开发人员，我们应该编写一些测试以确保我们的网关能够按预期运行。在大多数情况下，我们希望限制对外部资源的依赖，尤其是在单元测试中，因此我们不应该依赖HTTPBin。解决此问题的一种方法是使路由中的URI可配置，因此我们可以根据需要轻松更改URI。

在Application.java创建一个名为的新类UriConfiguration。

@ConfigurationProperties
class UriConfiguration {
  
  private String httpbin = "http://httpbin.org:80";

  public String getHttpbin() {
    return httpbin;
  }

  public void setHttpbin(String httpbin) {
    this.httpbin = httpbin;
  }
}

为此，ConfigurationProperties我们还需要向添加一个类级别的注释Application.java。

@EnableConfigurationProperties(UriConfiguration.class)

有了新的配置类后，就可以在myRoutes方法中使用它。

src/main/java/gateway/Application.java

@Bean
public RouteLocator myRoutes(RouteLocatorBuilder builder, UriConfiguration uriConfiguration) {
  String httpUri = uriConfiguration.getHttpbin();
  return builder.routes()
    .route(p -> p
      .path("/get")
      .filters(f -> f.addRequestHeader("Hello", "World"))
      .uri(httpUri))
    .route(p -> p
      .host("*.hystrix.com")
      .filters(f -> f
        .hystrix(config -> config
          .setName("mycmd")
          .setFallbackUri("forward:/fallback")))
      .uri(httpUri))
    .build();
}

如您所见，我们不是从URL硬编码为HTTPBin，而是从新的配置类获取URL。

以下是的完整内容Application.java。

src/main/java/gateway/Application.java

@SpringBootApplication
@EnableConfigurationProperties(UriConfiguration.class)
@RestController
public class Application {

  public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
  }

  @Bean
  public RouteLocator myRoutes(RouteLocatorBuilder builder, UriConfiguration uriConfiguration) {
    String httpUri = uriConfiguration.getHttpbin();
    return builder.routes()
      .route(p -> p
        .path("/get")
        .filters(f -> f.addRequestHeader("Hello", "World"))
        .uri(httpUri))
      .route(p -> p
        .host("*.hystrix.com")
        .filters(f -> f
          .hystrix(config -> config
            .setName("mycmd")
            .setFallbackUri("forward:/fallback")))
        .uri(httpUri))
      .build();
  }

  @RequestMapping("/fallback")
  public Mono<String> fallback() {
    return Mono.just("fallback");
  }
}

@ConfigurationProperties
class UriConfiguration {
  
  private String httpbin = "http://httpbin.org:80";

  public String getHttpbin() {
    return httpbin;
  }

  public void setHttpbin(String httpbin) {
    this.httpbin = httpbin;
  }
}

创建一个名为新类ApplicationTest在src/main/test/java/gateway。在新类中添加以下内容。

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT,
    properties = {"httpbin=http://localhost:${wiremock.server.port}"})
@AutoConfigureWireMock(port = 0)
public class ApplicationTest {

  @Autowired
  private WebTestClient webClient;

  @Test
  public void contextLoads() throws Exception {
    //Stubs
    stubFor(get(urlEqualTo("/get"))
        .willReturn(aResponse()
          .withBody("{\"headers\":{\"Hello\":\"World\"}}")
          .withHeader("Content-Type", "application/json")));
    stubFor(get(urlEqualTo("/delay/3"))
      .willReturn(aResponse()
        .withBody("no fallback")
        .withFixedDelay(3000)));

    webClient
      .get().uri("/get")
      .exchange()
      .expectStatus().isOk()
      .expectBody()
      .jsonPath("$.headers.Hello").isEqualTo("World");

    webClient
      .get().uri("/delay/3")
      .header("Host", "www.hystrix.com")
      .exchange()
      .expectStatus().isOk()
      .expectBody()
      .consumeWith(
        response -> assertThat(response.getResponseBody()).isEqualTo("fallback".getBytes()));
  }
}

我们的测试实际上是利用Spring Cloud Contract中的WireMock来建立可以模拟HTTPBin API的服务器。首先要注意的是的使用@AutoConfigureWireMock(port = 0)。此注释将为我们在随机端口上启动WireMock。

接下来，请注意我们正在利用我们的UriConfiguration类并将注释中的httpbin属性设置为在@SpringBootTest本地运行的WireMock服务器。然后，在测试中，我们为通过网关调用的HTTPBin API设置“存根”，并模拟我们期望的行为。最后，我们使用WebTestClient实际向网关发出请求并验证响应。

概括

恭喜你！您刚刚构建了第一个Spring Coud Gateway应用程序！

是否要编写新指南或为现有指南做出贡献？查看我们的贡献准则。

所有指南均以代码的ASLv2许可证和写作的Attribution，NoDerivatives创用CC许可证发布。