Spring认证-了解如何使用Spring创建超媒体驱动的RESTful Web服务 - WXOPEN Club

Spring认证指南-了解如何使用 Spring 创建超媒体驱动的 RESTful Web 服务。（Spring中国教育管理中心）

Spring认证：了解如何使用 Spring 创建超媒体驱动的 RESTful Web 服务
构建超媒体驱动的 RESTful Web 服务
本指南将引导您完成使用 Spring 创建“Hello, World”超媒体驱动的 REST Web 服务的过程。

超媒体是 REST 的一个重要方面。它使您可以构建在很大程度上解耦客户端和服务器的服务，并让它们独立发展。为 REST 资源返回的表示不仅包含数据，还包含指向相关资源的链接。因此，表示的设计对于整体服务的设计至关重要。

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

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

它将以 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：
弹簧工具套件 (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 开始
您可以使用这个预先初始化的项目并单击 Generate 下载 ZIP 文件。此项目配置为适合本教程中的示例。

手动初始化项目：

导航到https://start.spring.io。该服务提取应用程序所需的所有依赖项，并为您完成大部分设置。
选择 Gradle 或 Maven 以及您要使用的语言。本指南假定您选择了 Java。
单击Dependencies并选择Spring HATEOAS。
单击生成。
下载生成的 ZIP 文件，该文件是根据您的选择配置的 Web 应用程序的存档。
如果您的 IDE 具有 Spring Initializr 集成，您可以从您的 IDE 完成此过程。

你也可以从 Github 上 fork 项目并在你的 IDE 或其他编辑器中打开它。

添加 JSON 库
因为您将使用 JSON 来发送和接收信息，所以您需要一个 JSON 库。在本指南中，您将使用 Jayway JsonPath 库。

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

<dependency>
<groupId>com.jayway.jsonpath</groupId>
<artifactId>json-path</artifactId>
<scope>test</scope>
</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.6.3</version>
<relativePath/> 
</parent>
<groupId>com.example</groupId>
<artifactId>rest-hateoas-complete</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>rest-hateoas-complete</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>

	&lt;dependency&gt;
		&lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
		&lt;artifactId&gt;spring-boot-starter-test&lt;/artifactId&gt;
		&lt;scope&gt;test&lt;/scope&gt;
	&lt;/dependency&gt;
&lt;/dependencies&gt;

&lt;build&gt;
	&lt;plugins&gt;
		&lt;plugin&gt;
			&lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
			&lt;artifactId&gt;spring-boot-maven-plugin&lt;/artifactId&gt;
		&lt;/plugin&gt;
	&lt;/plugins&gt;
&lt;/build&gt;

</project>
要在 Gradle 构建中包含该库，请将以下依赖项添加到您的build.gradle文件中：

testCompile 'com.jayway.jsonpath:json-path’复制
以下清单显示了完成的build.gradle文件：

plugins {
id ‘org.springframework.boot’ version '2.6.3’
id ‘io.spring.dependency-management’ version '1.0.11.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’
}

test {
useJUnitPlatform()
}
创建资源表示类
现在您已经设置了项目和构建系统，您可以创建您的 Web 服务。

从考虑服务交互开始这个过程。

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

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

{
“content”:“Hello, World!”,
"_links":{
“self”:{
“href”:“http://localhost:8080/greeting?name=World”
}
}
}
content是问候语的文本表示。该_links元素包含一个链接列表（在这种情况下，正是一个具有关系类型rel和href指向所访问资源的属性的链接）。

要对问候表示建模，请创建一个资源表示类。由于该_links属性是表示模型的基本属性，因此 Spring HATEOAS 附带了一个基类（称为RepresentationModel），它允许您添加实例Link并确保它们如前所示呈现。

创建一个普通的旧 java 对象，该对象扩展RepresentationModel和添加内容的字段和访问器以及构造函数，如以下清单（来自
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](/user/JsonCreator)
public Greeting([@JsonProperty](/user/JsonProperty)("content") String content) {
	this.content = content;
}

public String getContent() {
	return content;
}

}
@JsonCreator：指示杰克逊如何创建此 POJO 的实例。
@JsonProperty：标记杰克逊应该将此构造函数参数放入的字段。
正如您将在本指南后面看到的那样，Spring 将使用 Jackson JSON 库将类型的实例自动编组Greeting为 JSON。

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

创建 REST 控制器
在 Spring 构建 RESTful Web 服务的方法中，HTTP 请求由控制器处理。组件由@RestController注释标识，该注释结合了@Controller和@ResponseBody注释。以下GreetingController（来自）通过返回类的新实例来
src/main/java/com/example/resthateoas/GreetingController.java处理GET请求：/greetingGreeting

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](/user/RequestMapping)("/greeting")
public HttpEntity&lt;Greeting&gt; greeting(
	[@RequestParam](/user/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&lt;&gt;(greeting, HttpStatus.OK);
}

}
这个控制器简洁明了，但是有很多事情要做。我们一步一步分解。

@RequestMapping注释确保 HTTP 请求/greeting映射到greeting()方法。

上面的例子没有指定GETvs. PUT,POST等等，因为默认@RequestMapping映射所有的 HTTP 操作。用于@GetMapping("/greeting")缩小此映射。在这种情况下，您还想import
org.springframework.web.bind.annotation.GetMapping;.

@RequestParam将查询字符串参数的值绑定name到方法的name参数中greeting()。这个查询字符串参数隐含不是required因为使用了defaultValue属性。如果请求中不存在，则使用defaultValueof World。

因为@RestController注释存在于类上，所以将隐式@ResponseBody注释添加到greeting方法中。这会导致 Spring MVC 将返回HttpEntity的及其有效负载 (the 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。例如，如果spring-webmvc位于类路径上，则此注释将应用程序标记为 Web 应用程序并激活关键行为，例如设置DispatcherServlet.
@ComponentScan: 告诉 Spring 在包中查找其他组件、配置和服务com/example，让它找到控制器。
该main()方法使用 Spring Boot 的SpringApplication.run()方法来启动应用程序。您是否注意到没有一行 XML？也没有web.xml文件。这个 Web 应用程序是 100% 纯 Java，您不必处理任何管道或基础设施的配置。

构建一个可执行的 JAR
您可以使用 Gradle 或 Maven 从命令行运行应用程序。您还可以构建一个包含所有必要依赖项、类和资源的单个可执行 JAR 文件并运行它。构建可执行 jar 可以在整个开发生命周期、跨不同环境等中轻松地作为应用程序交付、版本化和部署服务。

如果您使用 Gradle，则可以使用./gradlew bootRun. 或者，您可以使用构建 JAR 文件./gradlew build，然后运行 JAR 文件，如下所示：

java -jar build/libs/gs-rest-hateoas-0.1.0.jar
如果您使用 Maven，则可以使用./mvnw spring-boot:run. 或者，您可以使用构建 JAR 文件，./mvnw clean package然后运行该 JAR 文件，如下所示：

java -jar 目标/gs-rest-hateoas-0.1.0.jar
此处描述的步骤创建了一个可运行的 JAR。您还可以构建经典的 WAR 文件。

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

测试服务
现在服务已经启动，访问
http://localhost:8080/greeting，您应该会看到以下内容：

{
“content”:“Hello, World!”,
"_links":{
“self”:{
“href”:“http://localhost:8080/greeting?name=World”
}
}
}
name通过访问以下 URL提供查询字符串参数：
http://localhost:8080/greeting?name=User。请注意属性的值如何content从Hello, World!to更改，Hello, User!并且链接的href属性也self反映了该更改，如以下清单所示：

{
“content”:“Hello, User!”,
"_links":{
“self”:{
“href”:“http://localhost:8080/greeting?name=User”
}
}
}
这一变化表明，@RequestParam安排GreetingController按预期工作。该name参数已被赋予默认值，World但始终可以通过查询字符串显式覆盖。

概括
恭喜！您刚刚使用 Spring HATEOAS 开发了一个超媒体驱动的 RESTful Web 服务。