SpringBoot 消费 RESTful Web 服务

开篇词

该指南将引导你结合 Spring 来逐步完成一个消费 RESTful Web 服务的应用。

你将创建的应用

你将借助 Spring 的 RestTemplate 构建一个用以从 https://gturnquist-quoters.cfapps.io/api/random 获取一个随机 Spring Boot 引句的应用。

你将需要的工具

大概 15 分钟左右；
你最喜欢的文本编辑器或集成开发环境（IDE）
JDK 1.8 或更高版本；
Gradle 4+ 或 Maven 3.2+
你还可以将代码直接导入到 IDE 中：
- Spring Too Suite (STS)
- IntelliJ IDEA

如何完成这个指南

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

要从头开始，移步至从 Spring Initializr 开始；
要跳过基础，执行以下操作：
- 下载并解压缩该指南将用到的源代码，或借助 Git 来对其进行克隆操作：git clone https://github.com/spring-guides/gs-consuming-rest.git
- 切换至 gs-consuming-rest/initial 目录；
- 跳转至该指南的获取一个 REST 资源。

待一切就绪后，可以检查一下 gs-consuming-rest/complete 目录中的代码。

从 Spring Initializr 开始

对于所有的 Spring 应用来说，你应该从 Spring Initializr 开始。Initializr 提供了一种快速的方法来提取应用程序所需的依赖，并为你完成许多设置。该示例仅需要 Spring Web 依赖项。下图显示了此示例项目的 Initializr 设置：
Spring Initializr 界面

上图显示了选择 Maven 作为构建工具的 Initializr。你也可以使用 Gradle。它还将 com.example 和 consuming-rest 的值分别显示为 Group 和 Artifact。在本示例的其余部分，将用到这些值。

以下清单显示了选择 Maven 时创建的 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>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.1.7.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.example</groupId>
	<artifactId>consuming-rest</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>consuming-rest</name>
	<description>Demo project for Spring Boot</description>

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

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
	</dependencies>

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

</project>

以下清单显示了在选择 Gradle 时创建的 build.gradle 文件：

plugins {
	id 'org.springframework.boot' version '2.1.7.RELEASE'
	id 'io.spring.dependency-management' version '1.0.8.RELEASE'
	id 'java'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '1.8'

repositories {
	mavenCentral()
}

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-web'
	testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

获取一个 REST 资源

完成项目设置后，我们可以创建一个用以消费 RESTful 服务的简单应用。

RESTful 服务已在 https://gturnquist-quoters.cfapps.io/api/random 上开放了。它随机获取 Spring Boot 的引句，并将其作为 JSON 文档返回。

如果你通过浏览器或 curl 请求该地址，则会收到一个类似于以下内容的 JSON 文档：

{
   type: "success",
   value: {
      id: 10,
      quote: "Really loving Spring Boot, makes stand alone Spring apps easy."
   }
}

Spring 提供了一个方面的模版类，叫做 RestTemplate。它以简单的方式与多大多数的 RESTful 服务进行交互。它甚至可以将该数据绑定到自定义域类型。

首先，我们需要创建一个包含所需数据的域类。以下清单显示了 Quote 类，我们可以将其用作域类：
src/main/java/com/example/consumingrest/Quote.java

package com.example.consumingrest;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;

@JsonIgnoreProperties(ignoreUnknown = true)
public class Quote {

  private String type;
  private Value value;

  public Quote() {
  }

  public String getType() {
    return type;
  }

  public void setType(String type) {
    this.type = type;
  }

  public Value getValue() {
    return value;
  }

  public void setValue(Value value) {
    this.value = value;
  }

  @Override
  public String toString() {
    return "Quote{" +
        "type='" + type + '\'' +
        ", value=" + value +
        '}';
  }
}

这个简单的 Java 类具有一些属性以及对应的 getter 方法。它用来自 Jackson JSON 处理库的 @JsonIgnoreProperties 进行注解，以指示应该忽略此类型中未绑定的任何属性。

译者注：言外之意就是只接收类中定义了的两个属性，type 和 value。

要将数据直接绑定到自定义类型，我们需要指定变量名称，使其与从 API 返回的 JSON 文档中的键完全相同。如果我们的变量名称与 JSON 文档中的键名不匹配，则可以使用 @JsonProperty 注解来指定 JSON 文档的确切键名。（此示例每个变量名与其所对应的 JSON 键名匹配，因此不需要该注解。）

我们还需要一个附加的类来潜入内部引句本身。Value 类满足了需求，并显示在以下清单中（在 src/main/java/com/example/consumingrest/Value.java 中）：

package com.example.consumingrest;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;

@JsonIgnoreProperties(ignoreUnknown = true)
public class Value {

  private Long id;
  private String quote;

  public Value() {
  }

  public Long getId() {
    return this.id;
  }

  public String getQuote() {
    return this.quote;
  }

  public void setId(Long id) {
    this.id = id;
  }

  public void setQuote(String quote) {
    this.quote = quote;
  }

  @Override
  public String toString() {
    return "Value{" +
        "id=" + id +
        ", quote='" + quote + '\'' +
        '}';
  }
}

这使用相同的注解，但映射到其他数据字段。

完善应用

Initializr 创建了一个拥有 main() 方法的类。下面清单显示了 Initializr 创建的类（位于 src/main/java/com/example/consumingrest/ConsumingRestApplication.java）：

package com.example.consumingrest;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class ConsumingRestApplication {

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

}

现在，我们需要向 ConsumingRestApplication 类添加一些其他内容，以使其显示来自 RESTful 源的引句。我们需要添加：

一个日志器，用于将输出发送到日志（在此示例中为控制台）；
RestTemplate，它使用 Jackson JSON 处理库来处理传入的数据；
一个在启动时运行 RestTemplate（然后，从而获取我们的引句）的 CommandLineRunner。

以下清单显示了最终的 ConsumingRestApplication 类（位于 src/main/java/com/example/consumingrest/ConsumingRestApplication.java）：

package com.example.consumingrest;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.web.client.RestTemplate;

@SpringBootApplication
public class ConsumingRestApplication {

	private static final Logger log = LoggerFactory.getLogger(ConsumingRestApplication.class);

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

	@Bean
	public RestTemplate restTemplate(RestTemplateBuilder builder) {
		return builder.build();
	}

	@Bean
	public CommandLineRunner run(RestTemplate restTemplate) throws Exception {
		return args -> {
			Quote quote = restTemplate.getForObject(
					"https://gturnquist-quoters.cfapps.io/api/random", Quote.class);
			log.info(quote.toString());
		};
	}
}

运行应用

我们可以结合 Gradle 或 Maven 来从命令行运行该应用。我们还可以构建一个包含所有必须依赖项、类以及资源的可执行 JAR 文件，然后运行该文件。在整个开发生命周期中，跨环境等等情况下，构建可执行 JAR 可以轻松地将服务作为应用进行发布、版本化以及部署。

如果使用 Gradle，则可以借助 ./gradlew bootRun 来运行应用。或通过借助 ./gradlew build 来构建 JAR 文件，然后运行 JAR 文件，如下所示：

java -jar build/libs/gs-consuming-rest-0.1.0.jar

如果使用 Maven，则可以借助 ./mvnw spring-boot:run 来运行该用。或可以借助 ./mvnw clean package 来构建 JAR 文件，然后运行 JAR 文件，如下所示：

java -jar target/gs-consuming-rest-0.1.0.jar

我们还可以构建一个经典的 WAR 文件。

我们应该看到类似于以下内容的输出，但引句是随机的：

2019-08-22 14:06:46.506  INFO 42940 --- [           main] c.e.c.ConsumingRestApplication           : Quote{type='success', value=Value{id=1, quote='Working with Spring Boot is like pair-programming with the Spring developers.'}}