本指南將引導您完成使用 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分鐘最喜歡的文本編輯器或 IDEJDK 1.8或以后格拉德爾 4+?或梅文 3.2+您也可以將代碼直接導入到 IDE 中：彈簧工具套件 （STS）智能理念VSCode

如何完成本指南

像大多數春天一樣入門指南，您可以從頭開始并完成每個步驟，也可以繞過您已經熟悉的基本設置步驟。無論哪種方式，您最終都會得到工作代碼。

要從頭開始，請繼續從 Spring 初始化開始.

要跳過基礎知識，請執行以下操作：

下載并解壓縮本指南的源存儲庫，或使用吉特:git clonehttps://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??

  com.jayway.jsonpath  json-path  test

以下清單顯示了完成的文件：??pom.xml??

  4.0.0      org.springframework.boot    spring-boot-starter-parent    3.0.0         com.example  rest-hateoas-complete  0.0.1-SNAPSHOT  rest-hateoas-complete  Demo project for Spring Boot      17              org.springframework.boot      spring-boot-starter-hateoas              org.springframework.boot      spring-boot-starter-test      test                          org.springframework.boot        spring-boot-maven-plugin            

要在 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 {  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(    @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 服務。