儲存庫資源

基本原理

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（預設情況下為 null），則 HTTP Accept 標頭的存在用於判斷回應碼。在集合和項目資源的詳細描述中閱讀更多相關資訊。

資源可探索性

HATEOAS 的核心原則是，資源應透過發布指向可用資源的連結來進行探索。關於如何在 JSON 中表示連結，存在一些相互競爭的事實標準。預設情況下，Spring Data REST 使用 HAL 來呈現回應。HAL 定義了要包含在傳回文件屬性中的連結。

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

例如，若要探索應用程式根目錄下有哪些可用資源，請向根 URL 發出 HTTP GET，如下所示

curl -v https://127.0.0.1:8080/

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

{ "_links" : {
    "orders" : {
      "href" : "https://127.0.0.1:8080/orders"
    },
    "profile" : {
      "href" : "https://127.0.0.1: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 方法傳回查詢方法資源是否可用。