SpringBoot 2 超媒体驱动 RESTful Web 服务

开篇词

该指南将引导你使用 Spring 创建 “Hello, World” 超媒体驱动的 REST Web 服务。

超媒体是 REST 的重要体现。它使我们可以构建将客户端和服务器在很大程度上分离并使其独立发展的服务。为 REST 资源返回的展示形式不仅包含数据，而且还包含与相关资源的链接。因此，展示的设计对于整体服务的设计至关重要。

你将创建的应用

我们将使用 Spring HATEOAS 构建超媒体驱动的 REST 服务：一个 API 库，可用于创建指向 Spring MVC 控制器的链接，建立资源展示并控制如何将它们呈现为受支持的超媒体格式（例如 HAL）。

该服务将在 http://localhost:8080/greeting 接受 HTTP GET 请求。

它将以问候语的 JSON 展示形式进行响应，该问候语中包含了最简单的超媒体元素，即指向资源本身的链接。以下清单显示了输出：

{
  "content":"Hello, World!",
  "_links":{
    "self":{
      "href":"http://localhost:8080/greeting?name=World"
    }
  }
}

响应已经表明我们可以使用查询字符串中的可选 name 参数来自定义问候语，如下清单所示：

http://localhost:8080/greeting?name=User

name 参数值将覆盖 World 的默认值，并反映在响应中，如以下清单所示：

{
  "content":"Hello, User!",
  "_links":{
    "self":{
      "href":"http://localhost:8080/greeting?name=User"
    }
  }
}

你将需要的工具

大概 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-rest-hateoas.git
- 切换至 gs-rest-hateoas/initial 目录；
- 跳转至该指南的创建资源展示类。

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

从 Spring Initializr 开始

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

上图显示了选择 Maven 作为构建工具的 Initializr。你也可以使用 Gradle。它还将 com.example 和 rest-hateoas 的值分别显示为 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.2.2.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.example</groupId>
	<artifactId>rest-hateoas</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>rest-hateoas</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-hateoas</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
			<exclusions>
				<exclusion>
					<groupId>org.junit.vintage</groupId>
					<artifactId>junit-vintage-engine</artifactId>
				</exclusion>
			</exclusions>
		</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.2.2.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-hateoas'
	testImplementation('org.springframework.boot:spring-boot-starter-test') {
		exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
	}
}

test {
	useJUnitPlatform()
}

添加 JSON 库

由于我们将使用 JSON 发送和接收信息，所以我们需要一个 JSON 库。在该指南中，我们将使用 Jayway JsonPath 库。

要将库包含在 Maven 构建中，请将以下依赖添加至 pom.xml 文件：

<dependency>
  <groupId>com.jayway.jsonpath</groupId>
  <artifactId>json-path</artifactId>
</dependency>

以下清单显示了完整的 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.2.2.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.example</groupId>
	<artifactId>rest-hateoas</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>rest-hateoas</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-hateoas</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
			<exclusions>
				<exclusion>
					<groupId>org.junit.vintage</groupId>
					<artifactId>junit-vintage-engine</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
	</dependencies>

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

</project>

要将库包含在 Gradle 构建中，请将以下依赖添加至 build.gradle 文件中：

testCompile 'com.jayway.jsonpath:json-path'

以下清单显示了完整的 build.gradle 文件：

plugins {
	id 'org.springframework.boot' version '2.2.2.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-hateoas'
	testImplementation('org.springframework.boot:spring-boot-starter-test') {
		exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
	}
}

test {
	useJUnitPlatform()
}

创建资源展示类

现在我们已经搭建好了项目和构建系统，我们可以创建 Web 服务。

通过考虑服务交互来开始该过程。

该服务将在 /greeting 处公开资源以及处理 GET 请求，还可以选择在查询字符串中使用 name 参数。GET 请求应返回 200 OK 响应，并在正文中使用 JSON 展示问候。

除此之外，_links 属性中的超媒体元素列表将丰富资源的 JSON 展示形式。最基本的形式是指向资源本身的链接。该展示应类似于以下清单：

{
  "content":"Hello, World!",
  "_links":{
    "self":{
      "href":"http://localhost:8080/greeting?name=World"
    }
  }
}

content 是问候语的文字展示。_links 元素包含链接列表（在该情况下，链接列表的关系类型为 rel，href 属性指向所访问的资源）。

要建模问候展示，请创建资源展示类。由于 _links 属性是展示模型的基本属性，因此 Spring HATEOAS 附带了一个基类（称为 ResourceSupport），该基类可让我们添加 Link 实例并确保如前所述显示它们。

创建一个普通的老而好的 Java 对象，该对象扩展了 ResourceSupport 并添加了内容的字段和访问器及构造函数，如下清单（来自 src/main/java/com/example/resthateoas/Greeting.java）所示：

package com.example.resthateoas;

import org.springframework.hateoas.RepresentationModel;

import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;

public class Greeting extends RepresentationModel<Greeting> {

	private final String content;

	@JsonCreator
	public Greeting(@JsonProperty("content") String content) {
		this.content = content;
	}

	public String getContent() {
		return content;
	}
}

@JsonCreator：指示 Jsckson 如何创建该 POJO 的实例；
@JsonProperty：标记 Jackson 应将该构造函数参数放入的字段。

正如我们将在该指南后面部分看到的那样，Spring 将使用 Jackson JSON 库自动将类型 Greeting 的实例转换为 JSON。

接下来，创建将提供这些问候的资源控制器。

创建 REST 控制器

在 Spring 建立 RESTful 网络服务的方法中，HTTP 请求由控制器处理。这些组件由 @RestController 注解标识，该注解结合了 @Controller 和 @ResponseBody 注解。下面的 GreetingController（来自 src/main/java/com/example/resthateoas/GreetingController.java）通过返回 Greeting 类的新实例来处理 GET 请求 /greeting：

package com.example.resthateoas;

import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.*;

import org.springframework.http.HttpEntity;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;

@RestController
public class GreetingController {

	private static final String TEMPLATE = "Hello, %s!";

	@RequestMapping("/greeting")
	public HttpEntity<Greeting> greeting(
		@RequestParam(value = "name", defaultValue = "World") String name) {

		Greeting greeting = new Greeting(String.format(TEMPLATE, name));
		greeting.add(linkTo(methodOn(GreetingController.class).greeting(name)).withSelfRel());

		return new ResponseEntity<>(greeting, HttpStatus.OK);
	}
}

该控制器简洁明了，但是由很多事情要做。我们将其逐步分解。

@RequestMapping 注解可确保将对 /greeting 的 HTTP 请求映射至 greeting() 方法。

上面的示例未指定 GET 与 PUT、POST 等等，因为默认情况下 @RequestMapping 映射所有 HTTP 操作。使用 @GetMapping("/greeting") 缩小该映射范围。在这种情况下，我们还想导入 org.springframework.web.bind.annotation.GetMapping;。

@RequestParam 将查询字符串参数 name 的值绑定至 greeting() 方法的 name 参数中。由于使用 defaultValue 属性，因此隐式不 required 此查询字符串参数。如果其不存在于请求中，则使用 defaultValue 的默认值 World。

因为 @RestController 注解存在于类中，所以将 @ResponseBody 注解隐式添加至 greeting 方法中。这将导致 Spring MVC 将返回的 HTTPEntity 及其结果（Greeting）注解呈现给响应。

方法实现中最有趣的部分是如何创建指向控制器方法的链接以及如何将其添加至表示模型。linkTo(...) 和 methodOn(...) 都是 ControllerLinkBuilder 上的静态方法，可让我们在控制器上伪造方法调用。返回的 LinkBuilder 将检查控制器方法的映射注解，以准确建立该方法映射到的 URI。

Spring HATEOAS 遵从各种 X-FORWARDED- 标头。如果将 Spring HATEOAS 服务放在代理后面，并使用 X-FORWARDED-HOST 标头正确配置它，则将正确格式化结果链接。

对 withSelfRel() 的调用将创建一个 Link 实例，该实例将添加到 Greeting 表示模型中。

@SpringBootApplication 是一个便利的注解，它添加了以下所有内容：

@Configuration：将类标记为应用上下文 Bean 定义的源；
@EnableAutoConfiguration：告诉 Spring Boot 根据类路径配置、其他 bean 以及各种属性的配置来添加 bean。
@ComponentScan：告知 Spring 在 com/example 包中寻找他组件、配置以及服务。

main() 方法使用 Spring Boot 的 SpringApplication.run() 方法启动应用。

构建可执行 JAR

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

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

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

由官网提供的以上这条命令的执行结果与我本地的不一样，我需要这样才能运行：java -jar build/libs/rest-hateoas-0.0.1-SNAPSHOT.jar。

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

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

由官网提供的以上这条命令的执行结果与我本地的不一样，我需要这样才能运行：java -jar target/rest-hateoas-0.0.1-SNAPSHOT.jar。

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

日志记录已输出显示。该服务应在几秒内启动并运行。

测试服务

现在该服务已启动，请访问 http://localhost:8080/greeting，我们应在其中看到以下内容：

{
  "content":"Hello, World!",
  "_links":{
    "self":{
      "href":"http://localhost:8080/greeting?name=World"
    }
  }
}

通过访问以下 URL 并提供 name 查询字符串参数：http://localhost:8080/greeting?name=User。注意 content 属性的值如何从 Hello, World! 变更为 Hello, User! 而 href 属性的 self 链接也反映了这一变化，如下清单所示：

{
  "content":"Hello, User!",
  "_links":{
    "self":{
      "href":"http://localhost:8080/greeting?name=User"
    }
  }
}

该变更说明 GreetingController 中的 @RequestParam 安排按预期工作了。name 参数的默认值为 World，但使用可以通过查询字符串来显式覆盖。

概述

恭喜你！我们刚刚使用 Spring HATEOAS 开发了超媒体驱动的 RESTful Web 服务。

参见

以下指南也可能会有所帮助：

构建 RESTful Web 服务
使用 REST 访问 GemFire 数据（尽请期待～）
使用 REST 访问 MongoDB 数据（尽请期待～）
使用 MySQL 访问数据库（尽请期待～）
使用 REST 访问 JPA 数据（尽请期待～）
使用 REST 访问 Neo4j 数据（尽请期待～）
消费 RESTful Web 服务
使用 AngularJS 消费 RESTful Web 服务（尽请期待～）
使用 jQuery 消费 RESTful Web 服务（尽请期待～）
使用 rest.js 消费 RESTful Web 服务（尽请期待～）
加固 Web 应用
使用 Spring 构建 REST 服务（尽请期待～）
React.js 和 Spring Data REST（尽请期待～）
使用 Spring Boot 构建应用（尽请期待～）
使用 Restdocs 创建 API 文档（尽请期待～）
为 RESTful Web 服务启用跨源请求（尽请期待～）

想看指南的其他内容？请访问该指南的所属专栏：《Spring 官方指南》

来源：CSDN

作者：Snow Hide

链接：https://blog.csdn.net/stevenchen1989/article/details/104165151

标签

超媒体

localhost

restful