知識庫 / Spring / Spring Data RSS 訂閱

1. 概述

本文將解釋 Spring Data REST 的基本概念，並演示如何使用它來構建一個簡單的 REST API。

通常情況下，Spring Data REST 構建在 Spring Data 項目之上，並簡化了構建基於 hypermedia 的 REST Web 服務，這些服務連接到 Spring Data 存儲庫——所有這些都使用 HAL 作為驅動 hypermedia 類型的機制。

它消除了與此類任務相關的許多手動工作，並使構建 Web 應用程序的基本 CRUD 功能變得非常簡單。

2. Maven 依賴

以下 Maven 依賴項對於我們的簡單應用程序是必需的：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId
    <artifactId>spring-boot-starter-data-rest</artifactId></dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
</dependency>

我們決定使用 Spring Boot 作為本示例，但傳統的 Spring 也可以正常工作。我們還選擇使用嵌入式 H2 數據庫，以避免額外的配置，但該示例可以應用於任何數據庫。

3. 編寫應用程序

我們將首先編寫一個領域對象來表示我們網站上的用户:

@Entity
public class WebsiteUser {

    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    private long id;

    private String name;
    private String email;

    // standard getters and setters
}

每個用户都擁有一個姓名和電子郵件地址，以及一個自動生成的 ID。現在我們可以編寫一個簡單的倉庫：

@RepositoryRestResource(collectionResourceRel = "users", path = "users")
public interface UserRepository extends PagingAndSortingRepository<WebsiteUser, Long> {
    List<WebsiteUser> findByName(@Param("name") String name);
}

這是一個接口，允許您執行各種操作，與 WebsiteUser 對象相關。我們還定義了一個自定義查詢，用於根據給定的名稱提供用户列表。

@RepositoryRestResource 註解是可選的，用於自定義 REST 端點。如果決定省略它，Spring 將會自動創建一個端點，即 “websiteUsers”，而不是 “users”。

最後，我們將編寫一個標準的 Spring Boot 主類來初始化應用程序：

@SpringBootApplication
public class SpringDataRestApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringDataRestApplication.class, args);
    }
}

這就是全部！我們現在擁有一個功能完整的 REST API。讓我們來觀察它的實際運行情況。

4. 訪問 REST API

如果運行應用程序並訪問 http://localhost:8080/ 在瀏覽器中，我們將收到以下 JSON 數據：

{
  "_links" : {
    "users" : {
      "href" : "http://localhost:8080/users{?page,size,sort}",
      "templated" : true
    },
    "profile" : {
      "href" : "http://localhost:8080/profile"
    }
  }
}

如您所見，有一個“/users”端點可用，並且它已經具有“?page”、“?size”和“?sort”選項。

還有一個標準的“/profile”端點，它提供應用程序元數據。需要注意的是，響應結構符合REST架構風格的約束。具體來説，它提供了一個統一的接口和自描述的消息。這意味着每個消息都包含足夠的信息來描述如何處理該消息。

目前我們的應用程序中還沒有用户，因此訪問 http://localhost:8080/users 只是會顯示一個空的用户列表。我們使用 curl 添加一個用户。

$ curl -i -X POST -H "Content-Type:application/json" -d '{  "name" : "Test", \ 
"email" : "[email protected]" }' http://localhost:8080/users
{
  "name" : "test",
  "email" : "[email protected]",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/users/1"
    },
    "websiteUser" : {
      "href" : "http://localhost:8080/users/1"
    }
  }
}

讓我們來查看一下響應頭信息：

HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
Location: http://localhost:8080/users/1
Content-Type: application/hal+json;charset=UTF-8
Transfer-Encoding: chunked

您會注意到返回的內容類型是“application/hal+json”。HAL 是一種簡單格式，它提供了一種一致且易於使用的機制，用於在您的 API 之間建立資源之間的鏈接。該標題自動包含 Location 標題，這是我們用於訪問新創建的用户的新地址。

現在，我們可以通過 http://localhost:8080/users/1

{
  "name" : "test",
  "email" : "[email protected]",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/users/1"
    },
    "websiteUser" : {
      "href" : "http://localhost:8080/users/1"
    }
  }
}

您還可以使用 curl 或任何其他 REST 客户端發出 PUT、PATCH 和 DELETE 請求。 此外，請注意 Spring Data REST 自動遵循 HATEOAS 的原則。 HATEOAS 是 REST 架構風格中的一種約束，這意味着應使用超文本來導航 API。

最後，讓我們嘗試訪問我們之前編寫的自定義查詢，並查找所有名稱為“test”的用户。 這通過訪問 http://localhost:8080/users/search/findByName?name=test 完成。

{
  "_embedded" : {
    "users" : [ {
      "name" : "test",
      "email" : "[email protected]",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/users/1"
        },
        "websiteUser" : {
          "href" : "http://localhost:8080/users/1"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/users/search/findByName?name=test"
    }
  }
}

5. 結論

本教程介紹了使用 Spring Data REST 創建簡單 REST API 的基本知識。