倉庫資源

基礎

Spring Data REST 的核心功能是為 Spring Data 倉庫匯出資源。因此，需要檢視並可能自定義匯出方式的核心構件是倉庫介面。考慮以下倉庫介面

public interface OrderRepository extends CrudRepository<Order, Long> { }

對於此倉庫，Spring Data REST 在 /orders 處暴露一個集合資源。該路徑派生自所管理領域類的未首字母大寫、複數形式的簡單類名。它還在 URI 模板 /orders/{id} 下為倉庫管理的每個項暴露一個項資源。

預設情況下，與這些資源互動的 HTTP 方法對映到 CrudRepository 的相應方法。有關更多資訊，請參閱 集合資源 和 項資源 部分。

倉庫方法暴露

針對特定倉庫暴露哪些 HTTP 資源主要取決於倉庫的結構。換句話說，資源暴露將遵循您在倉庫上暴露的方法。如果您擴充套件 CrudRepository，通常會暴露所有預設情況下我們可以註冊的所有 HTTP 資源所需的方法。下面列出的每個資源將定義哪些方法需要存在，以便為每個資源暴露特定的 HTTP 方法。這意味著，未暴露這些方法（無論是根本未宣告還是顯式使用 @RestResource(exported = false)）的倉庫將不會在這些資源上暴露這些 HTTP 方法。

有關如何調整預設方法暴露或單獨調整特定 HTTP 方法的詳細資訊，請參見自定義支援的 HTTP 方法。

預設狀態碼

對於暴露的資源，我們使用一組預設狀態碼

  • 200 OK: 用於普通的 GET 請求。

  • 201 Created: 用於建立新資源的 POST 和 PUT 請求。

  • 204 No Content: 當配置設定為不對資源更新返回響應體時，用於 PUT, PATCH 和 DELETE 請求 (RepositoryRestConfiguration.setReturnBodyOnUpdate(…))。如果配置值設定為包含 PUT 的響應，則更新返回 200 OK，透過 PUT 建立資源返回 201 Created。

如果配置值 (RepositoryRestConfiguration.returnBodyOnUpdate(…) 和 RepositoryRestConfiguration.returnBodyCreate(…)) 被顯式設定為 null — 這是預設值 --，則使用 HTTP Accept 頭部的存在來確定響應碼。有關更多資訊，請閱讀集合資源和項資源的詳細描述。

資源可發現性

HATEOAS 的核心原則是資源應該透過釋出指向可用資源的連結來發現。在 JSON 中表示連結有一些競爭性的事實標準。預設情況下，Spring Data REST 使用 HAL 來渲染響應。HAL 定義了連結應包含在返回文件的一個屬性中。

資源發現從應用程式的頂層開始。透過向部署 Spring Data REST 應用程式的根 URL 發出請求，客戶端可以從返回的 JSON 物件中提取一組連結，這些連結表示客戶端可用的下一級資源。

例如，要發現應用程式根目錄下可用的資源，請向根 URL 發出 HTTP GET 請求，如下所示

curl -v https://:8080/

< HTTP/1.1 200 OK
< Content-Type: application/hal+json

{ "_links" : {
    "orders" : {
      "href" : "https://:8080/orders"
    },
    "profile" : {
      "href" : "https://:8080/api/alps"
    }
  }
}

結果文件的屬性是一個物件，包含表示關係型別的鍵，以及 HAL 中指定的巢狀連結物件。

有關 profile 連結的更多詳細資訊，請參見 應用程式級概要語義 (ALPS)。

集合資源

Spring Data REST 暴露一個集合資源，其名稱源自匯出的倉庫處理的領域類的未首字母大寫、複數形式。資源的名稱和路徑都可以透過在倉庫介面上使用 @RepositoryRestResource 來自定義。

支援的 HTTP 方法

集合資源支援 GET 和 POST。所有其他 HTTP 方法會導致 405 Method Not Allowed。

GET

透過其 findAll(…) 方法返回倉庫服務的所有實體。如果倉庫是分頁倉庫，我們會根據需要包含分頁連結和額外的頁面元資料。

用於呼叫的方法

如果存在，則使用以下方法（降序排列）

  • findAll(Pageable)

  • findAll(Sort)

  • findAll()

有關預設方法暴露的更多資訊，請參見倉庫方法暴露。

引數

如果倉庫具有分頁能力，資源接受以下引數

  • page: 要訪問的頁碼（從 0 開始索引，預設為 0）。

  • size: 請求的頁面大小（預設為 20）。

  • sort: 排序指令集合，格式為 ($propertyname,)+[asc|desc]?。

自定義狀態碼

GET 方法只有一個自定義狀態碼

  • 405 Method Not Allowed: 如果 findAll(…) 方法未被匯出（透過 @RestResource(exported = false)）或不在倉庫中。

支援的媒體型別

GET 方法支援以下媒體型別

  • application/hal+json

  • application/json

GET 方法支援用於發現相關資源的單個連結

  • search: 如果後端倉庫暴露了查詢方法，則暴露一個搜尋資源。

HEAD

HEAD 方法返回集合資源是否可用。它沒有狀態碼、媒體型別或相關資源。

用於呼叫的方法

如果存在，則使用以下方法（降序排列）

  • findAll(Pageable)

  • findAll(Sort)

  • findAll()

有關預設方法暴露的更多資訊，請參見倉庫方法暴露。

POST

POST 方法根據給定的請求體建立一個新實體。預設情況下，響應是否包含響應體由請求傳送的 Accept 頭控制。如果傳送了該頭部，則建立響應體。否則，響應體為空，並且可以透過跟隨 Location 響應頭中包含的連結來獲取建立資源的表示形式。此行為可以透過相應地配置 RepositoryRestConfiguration.setReturnBodyOnCreate(…) 來覆蓋。

用於呼叫的方法

如果存在，則使用以下方法（降序排列）

  • save(…)

有關預設方法暴露的更多資訊，請參見倉庫方法暴露。

自定義狀態碼

POST 方法只有一個自定義狀態碼

  • 405 Method Not Allowed: 如果 save(…) 方法未被匯出（透過 @RestResource(exported = false)）或完全不在倉庫中。

支援的媒體型別

POST 方法支援以下媒體型別

  • application/hal+json

  • application/json

項資源

Spring Data REST 暴露一個資源，用於單個集合項作為集合資源的子資源。

支援的 HTTP 方法

項資源通常支援 GET, PUT, PATCH 和 DELETE，除非顯式配置阻止了這一點（詳細資訊請參見“關聯資源”）。

GET

GET 方法返回單個實體。

用於呼叫的方法

如果存在，則使用以下方法（降序排列）

  • findById(…)

有關預設方法暴露的更多資訊，請參見倉庫方法暴露。

自定義狀態碼

GET 方法只有一個自定義狀態碼

  • 405 Method Not Allowed: 如果 findOne(…) 方法未被匯出（透過 @RestResource(exported = false)）或不在倉庫中。

支援的媒體型別

GET 方法支援以下媒體型別

  • application/hal+json

  • application/json

相關資源

對於領域型別的每個關聯，我們暴露以關聯屬性命名的連結。您可以透過在屬性上使用 @RestResource 來自定義此行為。相關資源是 關聯資源 型別。

HEAD

HEAD 方法返回項資源是否可用。它沒有狀態碼、媒體型別或相關資源。

用於呼叫的方法

如果存在，則使用以下方法（降序排列）

  • findById(…)

有關預設方法暴露的更多資訊，請參見倉庫方法暴露。

PUT

PUT 方法用提供的請求體替換目標資源的狀態。預設情況下，響應是否包含響應體由請求傳送的 Accept 頭控制。如果請求頭存在，則返回響應體和狀態碼 200 OK。如果請求頭不存在，響應體為空，成功請求返回狀態碼 204 No Content。此行為可以透過相應地配置 RepositoryRestConfiguration.setReturnBodyOnUpdate(…) 來覆蓋。

用於呼叫的方法

如果存在，則使用以下方法（降序排列）

  • save(…)

有關預設方法暴露的更多資訊，請參見倉庫方法暴露。

自定義狀態碼

PUT 方法只有一個自定義狀態碼

  • 405 Method Not Allowed: 如果 save(…) 方法未被匯出（透過 @RestResource(exported = false)）或完全不在倉庫中。

支援的媒體型別

PUT 方法支援以下媒體型別

  • application/hal+json

  • application/json

PATCH

PATCH 方法與 PUT 方法類似，但部分更新資源狀態。

用於呼叫的方法

如果存在，則使用以下方法（降序排列）

  • save(…)

有關預設方法暴露的更多資訊，請參見倉庫方法暴露。

自定義狀態碼

PATCH 方法只有一個自定義狀態碼

  • 405 Method Not Allowed: 如果 save(…) 方法未被匯出（透過 @RestResource(exported = false)）或不在倉庫中。

支援的媒體型別

PATCH 方法支援以下媒體型別

DELETE

DELETE 方法刪除暴露的資源。預設情況下，響應是否包含響應體由請求傳送的 Accept 頭控制。如果請求頭存在，則返回響應體和狀態碼 200 OK。如果請求頭不存在，響應體為空，成功請求返回狀態碼 204 No Content。此行為可以透過相應地配置 RepositoryRestConfiguration.setReturnBodyOnDelete(…) 來覆蓋。

用於呼叫的方法

如果存在，則使用以下方法（降序排列）

  • delete(T)

  • delete(ID)

  • delete(Iterable)

有關預設方法暴露的更多資訊，請參見倉庫方法暴露。

自定義狀態碼

DELETE 方法只有一個自定義狀態碼

  • 405 Method Not Allowed: 如果 delete(…) 方法未被匯出（透過 @RestResource(exported = false)）或不在倉庫中。

關聯資源

Spring Data REST 為每個項資源暴露其擁有的每個關聯的子資源。資源的名稱和路徑預設為關聯屬性的名稱，可以透過在關聯屬性上使用 @RestResource 來自定義。

支援的 HTTP 方法

關聯資源支援以下媒體型別

  • GET

  • PUT

  • POST

  • DELETE

GET

GET 方法返回關聯資源的狀態。

支援的媒體型別

GET 方法支援以下媒體型別

  • application/hal+json

  • application/json

PUT

PUT 方法將給定 URI 指向的資源繫結到關聯資源（參見支援的媒體型別）。

自定義狀態碼

PUT 方法只有一個自定義狀態碼

  • 400 Bad Request: 當為一對一關聯提供了多個 URI 時。

支援的媒體型別

PUT 方法只支援一種媒體型別

  • text/uri-list: 指向要繫結到關聯的資源的 URI。

POST

POST 方法僅支援集合關聯。它向集合中新增一個新元素。

支援的媒體型別

POST 方法只支援一種媒體型別

  • text/uri-list: 指向要新增到關聯的資源的 URI。

DELETE

DELETE 方法解除關聯繫結。

自定義狀態碼

POST 方法只有一個自定義狀態碼

  • 405 Method Not Allowed: 當關聯非可選時。

搜尋資源

搜尋資源返回倉庫暴露的所有查詢方法的連結。可以使用 @RestResource 在方法宣告上修改查詢方法資源的路徑和名稱。

支援的 HTTP 方法

由於搜尋資源是隻讀資源，它只支援 GET 方法。

GET

GET 方法返回指向各個查詢方法資源的連結列表。

支援的媒體型別

GET 方法支援以下媒體型別

  • application/hal+json

  • application/json

相關資源

對於倉庫中宣告的每個查詢方法，我們暴露一個查詢方法資源。如果資源支援分頁，指向它的 URI 是包含分頁引數的 URI 模板。

HEAD

HEAD 方法返回搜尋資源是否可用。返回碼 404 表示沒有可用的查詢方法資源。

查詢方法資源

查詢方法資源透過倉庫介面上的單個查詢方法執行暴露的查詢。

支援的 HTTP 方法

由於查詢方法資源是隻讀資源，它只支援 GET。

GET

GET 方法返回查詢結果。

引數

如果查詢方法具有分頁能力（在指向資源的 URI 模板中指示），資源接受以下引數

  • page: 要訪問的頁碼（從 0 開始索引，預設為 0）。

  • size: 請求的頁面大小（預設為 20）。

  • sort: 排序指令集合，格式為 ($propertyname,)+[asc|desc]?。

支援的媒體型別

GET 方法支援以下媒體型別

  • application/hal+json

  • application/json

HEAD

HEAD 方法返回查詢方法資源是否可用。