如何构建基于超媒体的RESTful网络服务架构？

本文共计2261个文字，预计阅读时间需要10分钟。

本指南将引导您完成使用Spring创建Hello, WorldREST Web服务的步骤。REST是RESTful Web服务的简称，是REST架构风格的一个重要方面。它允许您在很大的范围内分离客户端和服务端，从而构建高度可扩展的应用程序。

本指南将引导您完成使用 Spring 创建“Hello， World”超媒体驱动的 REST Web 服务的过程。

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

您将构建什么

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

该服务将接受位于 的 HTTP GET 请求。​​localhost:8080/greeting​​

它将使用问候语的 JSON 表示形式进行响应，该问候语使用最简单的超媒体元素（指向资源本身的链接）进行丰富。以下清单显示了输出：

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

响应已指示您可以使用查询字符串中的可选参数自定义问候语，如以下清单所示：​​name​​

localhost:8080/greeting?name=User

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

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

你需要什么

• 约15分钟
• 最喜欢的文本编辑器或 IDE
• JDK 1.8或以后
• 格拉德尔 4+​或梅文 3.2+
• 您也可以将代码直接导入到 IDE 中：

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

如何完成本指南

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

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

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

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

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

从 Spring 初始化开始

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

手动初始化项目：

导航到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="maven.apache.org/POM/4.0.0" xmlns:xsi="www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="maven.apache.org/POM/4.0.0 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":"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.localhost:8080/greeting​​，您应该在其中看到以下内容：

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

通过访问以下 URL 提供查询字符串参数：。请注意属性的值如何从 更改为 以及链接的属性如何反映该更改，如以下清单所示：​​name​​​​localhost:8080/greeting?name=User​​​​content​​​​Hello, World!​​​​Hello, User!​​​​href​​​​self​​

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

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

总结

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