入门 | 使用 RESTful Web 服务

您将构建什么

您将构建一个应用程序，该应用程序使用 Spring 的RestTemplate从https://127.0.0.1:8080/api/random检索随机的 Spring Boot 引用。

您需要什么

大约 15 分钟
您喜欢的文本编辑器或 IDE
Java 17 或更高版本
Gradle 7.5+ 或 Maven 3.5+
您也可以将代码直接导入到您的 IDE 中

如何完成本指南

与大多数 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 开始

您可以使用此预初始化项目，然后单击“生成”以下载 ZIP 文件。此项目已配置为适合本教程中的示例。

要手动初始化项目

导航到https://start.spring.io。此服务将引入应用程序所需的所有依赖项，并为您完成大部分设置工作。
选择 Gradle 或 Maven 以及您要使用的语言。本指南假设您选择了 Java。
单击依赖项并选择Spring Web。
单击生成。
下载生成的 ZIP 文件，该文件是使用您选择的选项配置的 Web 应用程序的存档。

如果您的 IDE 集成了 Spring Initializr，则可以从 IDE 中完成此过程。

您也可以从 Github 分叉项目，并在您的 IDE 或其他编辑器中打开它。

获取 REST 资源

项目设置完成后，您可以创建一个使用 RESTful 服务的简单应用程序。

在执行此操作之前，您需要一个 REST 资源源。我们在https://github.com/spring-guides/quoters提供了此类服务的示例。您可以在单独的终端中运行该应用程序，并在https://127.0.0.1:8080/api/random访问结果。该地址随机获取关于 Spring Boot 的引用，并将其作为 JSON 文档返回。其他有效地址包括https://127.0.0.1:8080/api/（所有引用）和https://127.0.0.1:8080/api/1（第一个引用），https://127.0.0.1:8080/api/2（第二个引用），依此类推（目前最多 10 个）。

如果您通过 Web 浏览器或 curl 请求该 URL，您将收到如下所示的 JSON 文档

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

这很容易，但通过浏览器或 curl 获取时并不十分有用。

使用 REST Web 服务的一种更有用的方法是通过编程方式。为了帮助您完成此任务，Spring 提供了一个名为RestTemplate的便捷模板类。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 record Quote(String type, Value value) { }

这个简单的 Java 记录类使用来自 Jackson JSON 处理库的@JsonIgnoreProperties进行注释，以指示应忽略在此类型中未绑定的任何属性。

要将数据直接绑定到自定义类型，您需要将变量名称指定为与 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 record Value(Long id, String 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 处理库来处理传入的数据。
一个CommandLineRunner，在启动时运行RestTemplate（并因此获取我们的引用）。

以下清单显示了已完成的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.context.annotation.Profile;
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
	@Profile("!test")
	public CommandLineRunner run(RestTemplate restTemplate) throws Exception {
		return args -> {
			Quote quote = restTemplate.getForObject(
					"https://127.0.0.1:8080/api/random", Quote.class);
			log.info(quote.toString());
		};
	}
}

最后，您需要设置服务器端口。quoters 应用程序使用默认服务器端口 8080，因此此应用程序也不能使用相同的端口。您可以通过将以下行添加到应用程序属性（Initializr 为您创建）来将服务器端口设置为 8081

server.port=8081

运行应用程序

您可以使用 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

此处描述的步骤创建了一个可运行的 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.'}}

如果您看到一条错误消息，内容为“无法提取响应：找不到适合响应类型 [class com.example.consumingrest.Quote] 的 HttpMessageConverter”，则您可能处于无法连接到后端服务（如果可以访问，则会发送 JSON）的环境中。也许您位于公司代理后面。尝试将http.proxyHost和http.proxyPort系统属性设置为适合您环境的值。

总结

恭喜！您刚刚使用 Spring Boot 开发了一个简单的 REST 客户端。

另请参阅

以下指南可能也有帮助

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

所有指南均以 ASLv2 许可证发布代码，并以署名-非衍生作品创作共用许可证发布写作内容。

使用 RESTful Web 服务