如何用Spring框架构建基于超媒体的Hello, WorldRESTful Web服务？

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

本指南将引导您完成使用Spring创建Hello, World超媒体驱动的REST 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 服务。