Spring認證中國教育管理中心-Spring Data REST架構教程二

原标題：Spring認證中國教育管理中心-Spring Data REST架構教程二（Spring中國教育管理中心）

4.2.館藏資源

Spring Data REST 公開了一個以導出存儲庫正在處理的域類的非大寫複數版本命名的集合資源。資源的名稱和路徑都可以通過@RepositoryRestResource在存儲庫界面上使用來自定義。

4.2.1.支援的 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方法傳回集合資源是否可用。它沒有狀态代碼、媒體類型或相關資源。

POST

該POST方法從給定的請求正文建立一個新實體。預設情況下，響應是否包含正文由Accept随請求發送的标頭控制。如果發送了一個，則會建立一個響應正文。如果不是，則響應正文為空，并且可以通過以下Location響應标頭中包含的連結擷取所建立資源的表示。可以通過相應的配置來覆寫此行為

RepositoryRestConfiguration.setReturnBodyOnCreate(…)。

save(…)

該POST方法隻有一個自定義狀态代碼：

405 Method Not Allowed：如果save(…)方法未導出（通過@RestResource(exported = false)）或根本不存在于存儲庫中。

該POST方法支援以下媒體類型：

應用程式/hal+json

應用程式/json

4.3.物品資源

Spring Data REST 将單個集合項的資源公開為集合資源的子資源。

4.3.1.支援的 HTTP 方法

項目資源通常支援GET、PUT、PATCH和DELETE，除非顯式配置阻止（請參閱“關聯資源”了解詳細資訊）。

得到

該GET方法傳回單個實體。

findById(…)

405 Method Not Allowed：如果findOne(…)方法未導出（通過@RestResource(exported = false)）或不存在于存儲庫中。

對于域類型的每個關聯，我們公開以關聯屬性命名的連結。您可以通過@RestResource在屬性上使用來自定義此行為。相關資源為關聯資源類型。

該HEAD方法傳回項目資源是否可用。它沒有狀态代碼、媒體類型或相關資源。

PUT

該PUT方法用提供的請求正文替換目标資源的狀态。預設情況下，響應是否包含正文由Accept随請求發送的标頭控制。如果請求标頭存在，200 OK則傳回響應正文和狀态代碼。如果不存在标頭，則響應正文為空，并且成功的請求将傳回 狀态204 No Content。可以通過相應的配置來覆寫此行為

RepositoryRestConfiguration.setReturnBodyOnUpdate(…)。

該PUT方法隻有一個自定義狀态代碼：

該PUT方法支援以下媒體類型：

PATCH

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

該PATCH方法隻有一個自定義狀态代碼：

405 Method Not Allowed：如果save(…)方法未導出（通過@RestResource(exported = false)）或不存在于存儲庫中。

該PATCH方法支援以下媒體類型：

應用程式/更新檔+json

應用程式/合并更新檔+json

DELETE

該DELETE方法删除暴露的資源。

delete(T)

delete(ID)

delete(Iterable)

該DELETE方法隻有一個自定義狀态代碼：

405 Method Not Allowed：如果delete(…)方法未導出（通過@RestResource(exported = false)）或不存在于存儲庫中。

4.4.協會資源

Spring Data REST 為每個項目資源具有的每個關聯公開每個項目資源的子資源。資源的名稱和路徑預設為關聯屬性的名稱，可以在關聯屬性上使用自定義@RestResource。

4.4.1.支援的 HTTP 方法

關聯資源支援以下媒體類型：

放

郵政

删除

該GET方法傳回關聯資源的狀态。

該PUT方法将給定 URI 指向的資源綁定到關聯資源（請參閱支援的媒體類型）。

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

該PUT方法僅支援一種媒體類型：

text/uri-list：指向要綁定到關聯的資源的 URI。

該POST方法僅支援集合關聯。它向集合中添加了一個新元素。

該POST方法僅支援一種媒體類型：

text/uri-list：指向要添加到關聯的資源的 URI。

該DELETE方法解除關聯。

405 Method Not Allowed：當關聯是非可選的。

4.5.搜尋資源

搜尋資源傳回存儲庫公開的所有查詢方法的連結。可以使用@RestResource方法聲明來修改查詢方法資源的路徑和名稱。

4.5.1.支援的 HTTP 方法

由于搜尋資源是隻讀資源，是以隻支援該GET方法。

該GET方法傳回指向各個查詢方法資源的連結清單。

對于存儲庫中聲明的每個查詢方法，我們公開一個查詢方法資源。如果資源支援分頁，則指向它的 URI 是包含分頁參數的 URI 模闆。

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

4.6.查詢方法資源

查詢方法資源通過存儲庫界面上的單個查詢方法運作公開的查詢。

4.6.1.支援的 HTTP 方法

由于查詢方法資源是隻讀資源，是以GET隻支援。

該GET方法傳回查詢的結果。

如果查詢方法具有分頁功能（在指向資源的 URI 模闆中訓示），則資源采用以下參數：

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

1. 分頁和排序

本節記錄了 Spring Data REST 對 Spring Data Repository 分頁和排序抽象的使用。要熟悉這些功能，請參閱您使用的存儲庫實作（例如 Spring Data JPA）的 Spring Data 文檔。

5.1.分頁

Spring Data REST 不是從大型結果集中傳回所有内容，而是識别一些影響頁面大小和起始頁碼的 URL 參數。

如果您擴充

PagingAndSortingRepository<T, ID>并通路所有實體的清單，您将獲得前 20 個實體的連結。要将頁面大小設定為任何其他數字，請添加一個size參數，如下所示：

http://localhost

:8080/people/?size=5

前面的示例将頁面大小設定為 5。

要在您自己的查詢方法中使用分頁，您需要更改方法簽名以接受附加Pageable參數并傳回 aPage而不是 a List。比如下面的查詢方法導出到

/people/search/nameStartsWith并支援分頁：

@RestResource(path = "nameStartsWith", rel = "nameStartsWith")

public Page findByNameStartsWith(@Param("name") String name, Pageable p);

Spring Data REST 導出器識别傳回Page并在響應正文中為您提供結果，就像處理非分頁響應一樣，但會向資源添加額外的連結以表示資料的上一頁和下一頁。

5.1.1.上一個和下一個連結

每個分頁響應使用 IANA 定義的連結關系prev和next. 但是，如果您目前位于結果的第一頁，則不會prev呈現任何連結。對于結果的最後一頁，不next呈現連結。

考慮以下示例，我們将頁面大小設定為 5：

{

"_links" : {

"self" : {
  "href" : "http://localhost:8080/persons{&sort,page,size}", 
  "templated" : true
},
"next" : {
  "href" : "http://localhost:8080/persons?page=1&size=5{&sort}", 
  "templated" : true
}           

},

"_embedded" : {

… data …           

"page" : {

"size" : 5,
"totalElements" : 50,
"totalPages" : 10,
"number" : 0           

}

在頂部，我們看到_links：

該self連結為整個系列提供了一些選項。

該next連結指向下一頁，假設頁面大小相同。

底部是有關頁面設定的額外資料，包括頁面大小、總元素、總頁數以及您目前檢視的頁碼。

Spring認證中國教育管理中心-Spring Data REST架構教程二

使用curl指令行等工具時，如果&語句中有“&”( )，則需要将整個URI用引号括起來。

請注意，self和nextURI 實際上是 URI 模闆。它們不僅接受size, 還接受page和sort作為可選标志。

如前所述，HAL 文檔的底部包含有關該頁面的詳細資訊集合。這些額外資訊使您可以輕松配置滑塊或訓示器等 UI 工具，以反映使用者在檢視資料時的整體位置。例如，前面示例中的文檔顯示我們正在檢視第一頁（頁碼從 0 開始）。

以下示例顯示了當我們點選next連結時會發生什麼：

$ curl "http://localhost:8080/persons?page=1&size=5"

"self" : {
  "href" : "http://localhost:8080/persons{&sort,projection,page,size}",
  "templated" : true
},
"next" : {
  "href" : "http://localhost:8080/persons?page=2&size=5{&sort,projection}", 
  "templated" : true
},
"prev" : {
  "href" : "http://localhost:8080/persons?page=0&size=5{&sort,projection}", 
  "templated" : true
}           

... data ...           

"size" : 5,
"totalElements" : 50,
"totalPages" : 10,
"number" : 1            

這看起來非常相似，除了以下差異：

該next連結現在指向另一個頁面，表明它與self連結的相對視角。

prev現在出現一個連結，為我們提供上一頁的路徑。

目前編号現在是 1（表示第二頁）。

此功能可讓您将螢幕上的可選按鈕映射到這些超媒體控件，讓您無需對 URI 進行寫死即可實作 UI 體驗的導航功能。事實上，使用者可以從頁面大小清單中進行選擇，動态更改所提供的内容，而無需next在頂部或底部重寫和`prev 控件。