构建超媒体驱动的 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或以后
• 格拉德尔 4+​或梅文 3.2+
• 您也可以将代码直接导入到 IDE 中：

• 弹簧工具套件 （STS）
• 智能理念
• VSCode

如何完成本指南

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

要从头开始，请继续从 Spring 初始化开始.

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

• 下载并解压缩本指南的源存储库，或使用吉特:git clone https://github.com/spring-guides/gs-rest-hateoas.git
• 光盘成gs-rest-hateoas/initial
• 跳转到创建资源表示类.

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

从 Spring 初始化开始

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

手动初始化项目：

导航到https://start.spring.io.此服务拉入应用程序所需的所有依赖项，并为您完成大部分设置。

选择 Gradle 或 Maven 以及您要使用的语言。本指南假定您选择了 Java。

单击“依赖项”，然后选择“Spring HATEOAS”。

单击生成。

下载生成的 ZIP 文件，该文件是配置了您选择的 Web 应用程序的存档。

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

您也可以从 Github 分叉项目，然后在 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>3.0.0</version> <relativePath/> <!-- lookup parent from repository --> </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>17</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> </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 '3.0.0' id 'io.spring.dependency-management' version '1.1.0' id 'java'}group = 'com.example'version = '0.0.1-SNAPSHOT'sourceCompatibility = '17'repositories { mavenCentral()}dependencies { implementation 'org.springframework.boot:spring-boot-starter-hateoas' testImplementation 'org.springframework.boot:spring-boot-starter-test'}test { useJUnitPlatform()}

创建资源表示类

设置项目和生成系统后，可以创建 Web 服务了。

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

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

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

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

是问候语的文本表示形式。该元素包含一个链接列表（在本例中，恰好是一个具有关系类型和指向所访问资源的属性的链接）。​​content​​​​_links​​​​rel​​​​href​​

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

创建一个普通的旧 java 对象，该对象扩展并添加内容的字段和访问器以及构造函数，如以下列表 （from ） 所示：​​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 public Greeting(@JsonProperty("content") String content) { this.content = content; } public String getContent() { return content; }}

• @JsonCreator：指示杰克逊如何创建此 POJO 的实例。
• @JsonProperty：标记杰克逊应将此构造函数参数放入的字段。

正如您将在本指南后面看到的那样，Spring 将使用 Jackson JSON 库自动将类型的实例编组到 JSON 中。​​Greeting​​

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

创建 REST 控制器

在Spring构建RESTful Web服务的方法中，HTTP请求由控制器处理。组件由@RestController注释，它结合了@Controller和@ResponseBody附注。以下 （from ） 通过返回类的新实例来处理请求：​​GreetingController​​​​src/main/java/com/example/resthateoas/GreetingController.java​​​​GET​​​​/greeting​​​​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;@RestControllerpublic 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); }}

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

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

上面的示例未指定 vs. 、 等，因为默认情况下会映射所有 HTTP 操作。用于缩小此映射范围。在这种情况下，您还需要 .​​GET​​​​PUT​​​​POST​​​​@RequestMapping​​​​@GetMapping("/greeting")​​​​import org.springframework.web.bind.annotation.GetMapping;​​

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

由于类上存在注释，因此隐式​​@RestController​​@ResponseBody批注将添加到方法中。这会导致 Spring MVC 将返回的内容及其有效负载 （） 直接呈现给响应。​​greeting​​​​HttpEntity​​​​Greeting​​

方法实现中最有趣的部分是如何创建指向控制器方法的链接以及如何将其添加到表示模型中。两者都是静态方法，可让您伪造控制器上的方法调用。返回的将检查控制器方法的映射注释，以准确构建方法映射到的 URI。​​linkTo(…)​​​​methodOn(…)​​​​ControllerLinkBuilder​​​​LinkBuilder​​

Spring HATEOAS 尊重各种标头。如果您将Spring HATEOAS服务放在代理后面，并使用标头正确配置它，则生成的链接将被正确格式化。​​X-FORWARDED-​​​​X-FORWARDED-HOST​​

调用 创建添加到表示模型的实例。​​withSelfRel()​​​​Link​​​​Greeting​​

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

• ​​@Configuration​​：将类标记为应用程序上下文的 Bean 定义源。
• ​​@EnableAutoConfiguration​​：告诉 Spring 引导根据类路径设置、其他 bean 和各种属性设置开始添加 bean。例如，如果 在类路径上，则此注释会将应用程序标记为 Web 应用程序并激活关键行为，例如设置 .spring-webmvcDispatcherServlet
• ​​@ComponentScan​​：告诉 Spring 在包中查找其他组件、配置和服务，让它找到控制器。com/example

该方法使用 Spring Boot 的方法启动应用程序。您是否注意到没有一行 XML？也没有文件。此 Web 应用程序是 100% 纯 Java，您无需处理配置任何管道或基础结构。​​main()​​​​SpringApplication.run()​​​​web.xml​​

构建可执行的 JAR

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

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

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

如果使用 Maven，则可以使用 运行应用程序。或者，您可以使用 JAR 文件生成 JAR 文件，然后运行该文件，如下所示：​​./mvnw spring-boot:run​​​​./mvnw clean package​​

java -jar target/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" } }}

通过访问以下 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" } }}

此更改表明 中的排列按预期工作。参数的默认值为 ，但始终可以通过查询字符串显式重写。​​@RequestParam​​​​GreetingController​​​​name​​​​World​​

总结

祝贺！您刚刚使用 Spring HATEOS 开发了一个超媒体驱动的 RESTful Web 服务。