書接上文???

是什么讓一些東西變得 RESTful？

到目前為止，您擁有一個(gè)基于 Web 服務(wù)來處理涉及員工數(shù)據(jù)的核心操作。但這還不足以讓事情變得“RESTful”。

• 漂亮的 URL/employees/3不是 REST。
• 僅使用GET,POST等不是 REST。
• 安排好所有的 CRUD 操作不當(dāng) REST。

事實(shí)上，到目前為止，我們構(gòu)建的更好地描述為RPC（遠(yuǎn)程過程調(diào)用）。那是因?yàn)闆]有辦法知道如何與這個(gè)服務(wù)器交互。如果您今天發(fā)布了此內(nèi)容，您還必須編寫文檔或在某個(gè)地方托管開發(fā)人員的門戶，其中包含所有詳細(xì)信息。

Roy Fielding 的這一陳述可能會(huì)進(jìn)一步為REST和RPC之間的區(qū)別提供線索：

我對(duì)將任何基于 HTTP 的接口稱為 REST API 的人數(shù)感到沮喪。今天的例子是 SocialSite REST API。那就是RPC。它尖叫 RPC。展示的耦合太多了，應(yīng)該給它一個(gè) X 評(píng)級(jí)。

要做些什么來使用 REST 架構(gòu)風(fēng)格清楚地認(rèn)識(shí)到超文本是一種約束？換句話說，應(yīng)用程序狀態(tài)引擎（以及 API）不是由超文本驅(qū)動(dòng)的，那么它就不能是 RESTful 并且不能是 REST API。時(shí)期。是否有一些損壞的手冊(cè)需要修復(fù)？

— 羅伊菲爾丁

https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

在我們的表示中不包括超媒體的副作用是客戶端必須硬編碼 URI 來導(dǎo)航 API。這導(dǎo)致了與網(wǎng)絡(luò)電子商務(wù)興起之前相同的脆弱性。這表明我們的 JSON 輸出需要一點(diǎn)幫助。

介紹Spring HATEOAS，這是一個(gè) Spring 項(xiàng)目，旨在幫助您編寫超媒體驅(qū)動(dòng)的輸出。要將您的服務(wù)升級(jí)為 RESTful，請(qǐng)將其添加到您的構(gòu)建中：

將 Spring HATEOAS 添加dependencies到pom.xml

org.springframework.bootspring-boot-starter-hateoas復(fù)制

這個(gè)小型庫將為我們提供定義 RESTful 服務(wù)的結(jié)構(gòu)，然后以可接受的格式呈現(xiàn)它以供客戶使用。

任何 RESTful 服務(wù)的一個(gè)關(guān)鍵要素是添加指向相關(guān)操作的鏈接。要使您的控制器更加 RESTful，請(qǐng)?zhí)砑尤缦骆溄樱?/span>

獲取單個(gè)項(xiàng)目的資源

@GetMapping("/employees/{id}")EntityModel one(@PathVariable Long id) {  Employee employee = repository.findById(id) //      .orElseThrow(() -> new EmployeeNotFoundException(id));  return EntityModel.of(employee, //      linkTo(methodOn(EmployeeController.class).one(id)).withSelfRel(),      linkTo(methodOn(EmployeeController.class).all()).withRel("employees"));}

本教程基于 Spring MVC 并使用靜態(tài)輔助方法WebMvcLinkBuilder來構(gòu)建這些鏈接。如果您在項(xiàng)目中使用 Spring WebFlux，則必須改用WebFluxLinkBuilder.

這與我們之前的情況非常相似，但有一些變化：

• 該方法的返回類型已從 更改Employee為EntityModel。EntityModel是來自 Spring HATEOAS 的通用容器，它不僅包含數(shù)據(jù)，還包含鏈接集合。
• linkTo(methodOn(EmployeeController.class).one(id)).withSelfRel()要求 Spring HATEOAS 建立到EmployeeController'one()方法的鏈接，并將其標(biāo)記為自鏈接。
• linkTo(methodOn(EmployeeController.class).all()).withRel("employees")要求 Spring HATEOAS 建立到聚合根的鏈接all()，并將其稱為“員工”。

“建立鏈接”是什么意思？Spring HATEOAS 的核心類型之一是Link. 它包括一個(gè)URI和一個(gè)rel（關(guān)系）。鏈接是賦予網(wǎng)絡(luò)權(quán)力的東西。在萬維網(wǎng)之前，其他文檔系統(tǒng)會(huì)呈現(xiàn)信息或鏈接，但正是將文檔與這種關(guān)系元數(shù)據(jù)鏈接在一起，才將網(wǎng)絡(luò)縫合在一起。

Roy Fielding 鼓勵(lì)使用使 Web 成功的相同技術(shù)構(gòu)建 API，鏈接就是其中之一。

如果您重新啟動(dòng)應(yīng)用程序并查詢Bilbo的員工記錄，您將得到與之前略有不同的響應(yīng)：

冰壺更漂亮

當(dāng)你的 curl 輸出變得更復(fù)雜時(shí)，它可能變得難以閱讀。使用這個(gè)或其他技巧來美化 curl 返回的 json：

# 指示部分將輸出通過管道傳輸?shù)?json_pp 并要求它使您的 JSON 更漂亮。（或者使用任何你喜歡的工具?。?/p>

# v------------------v

curl -v localhost:8080/employees/1 | json_pp

單個(gè)員工的 RESTful 表示

{

"id": 1,

"name": "Bilbo Baggins",

"role": "burglar",

"_links": {

"self": {

"href": "http://localhost:8080/employees/1"

},

"employees": {

"href": "http://localhost:8080/employees"

}

}

}

這個(gè)解壓縮的輸出不僅顯示了您之前看到的數(shù)據(jù)元素（id和name）role，而且還顯示了一個(gè)_links包含兩個(gè) URI 的條目。整個(gè)文檔使用HAL進(jìn)行格式化。

HAL 是一種輕量級(jí)媒體類型，它不僅可以編碼數(shù)據(jù)，還可以編碼超媒體控件，提醒消費(fèi)者注意他們可以導(dǎo)航的 API 的其他部分。在這種情況下，有一個(gè)“自我”鏈接（有點(diǎn)像this代碼中的語句）以及一個(gè)返回聚合根的鏈接。

為了使聚合根 ALSO 更加 RESTful，您希望包括頂級(jí)鏈接，同時(shí)還包括其中的任何 RESTful 組件。

所以我們把這個(gè)

獲取聚合根

@GetMapping("/employees")List all() {  return repository.findAll();}

進(jìn)入這個(gè)

獲取聚合根源

@GetMapping("/employees")CollectionModel> all() {  List> employees = repository.findAll().stream()      .map(employee -> EntityModel.of(employee,          linkTo(methodOn(EmployeeController.class).one(employee.getId())).withSelfRel(),          linkTo(methodOn(EmployeeController.class).all()).withRel("employees")))      .collect(Collectors.toList());  return CollectionModel.of(employees, linkTo(methodOn(EmployeeController.class).all()).withSelfRel());}

哇！曾經(jīng)的那個(gè)方法，repository.findAll()都長(zhǎng)大了！不用擔(dān)心。讓我們打開它。

CollectionModel<>是另一個(gè) Spring HATEOAS 容器；它旨在封裝資源集合，而不是像EntityModel<>之前那樣封裝單個(gè)資源實(shí)體。CollectionModel<>，也可以讓您包含鏈接。

不要讓第一個(gè)聲明溜走。“封裝集合”是什么意思？員工收藏？

不完全的。

由于我們談?wù)摰氖?REST，它應(yīng)該封裝員工資源的集合。

這就是為什么您獲取所有員工，然后將它們轉(zhuǎn)換為EntityModel對(duì)象列表的原因。（感謝 Java 8 流?。?/p>

如果您重新啟動(dòng)應(yīng)用程序并獲取聚合根，您可以看到它現(xiàn)在的樣子。

員工資源集合的 RESTful 表示

{  "_embedded": {    "employeeList": [      {        "id": 1,        "name": "Bilbo Baggins",        "role": "burglar",        "_links": {          "self": {            "href": "http://localhost:8080/employees/1"          },          "employees": {            "href": "http://localhost:8080/employees"          }        }      },      {        "id": 2,        "name": "Frodo Baggins",        "role": "thief",        "_links": {          "self": {            "href": "http://localhost:8080/employees/2"          },          "employees": {            "href": "http://localhost:8080/employees"          }        }      }    ]  },  "_links": {    "self": {      "href": "http://localhost:8080/employees"    }  }}復(fù)制

對(duì)于提供員工資源集合的聚合根，有一個(gè)頂級(jí)“自我”鏈接?！?span style="color:rgb(25,30,30);">集合”列在“_embedded”部分下方；這就是 HAL 表示集合的方式。

并且集合的每個(gè)單獨(dú)成員都有他們的信息以及相關(guān)鏈接。

添加所有這些鏈接有什么意義？它使得隨著時(shí)間的推移發(fā)展 REST 服務(wù)成為可能?？梢跃S護(hù)現(xiàn)有鏈接，而將來可以添加新鏈接。新客戶可以利用新鏈接，而舊客戶可以在舊鏈接上維持自己的生命。如果服務(wù)被重新定位和移動(dòng)，這將特別有用。只要保持鏈接結(jié)構(gòu)，客戶端仍然可以找到事物并與之交互。

簡(jiǎn)化鏈接創(chuàng)建

在前面的代碼中，您是否注意到單個(gè)員工鏈接創(chuàng)建中的重復(fù)？為員工提供單個(gè)鏈接以及創(chuàng)建到聚合根的“員工”鏈接的代碼顯示了兩次。如果這引起了您的關(guān)注，很好！有一個(gè)解決方案。

簡(jiǎn)單地說，你需要定義一個(gè)將Employee對(duì)象轉(zhuǎn)換為EntityModel對(duì)象的函數(shù)。雖然您可以輕松地自己編寫此方法，但在實(shí)現(xiàn) Spring HATEOAS 的
RepresentationModelAssembler接口的道路上也有好處——它將為您完成工作。

進(jìn)化
/src/main/java/payroll/EmployeeModelAssembler.java

package payroll;import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.*;import org.springframework.hateoas.EntityModel;import org.springframework.hateoas.server.RepresentationModelAssembler;import org.springframework.stereotype.Component;@Componentclass EmployeeModelAssembler implements RepresentationModelAssembler> {  @Override  public EntityModel toModel(Employee employee) {    return EntityModel.of(employee, //        linkTo(methodOn(EmployeeController.class).one(employee.getId())).withSelfRel(),        linkTo(methodOn(EmployeeController.class).all()).withRel("employees"));  }}復(fù)制,>

這個(gè)簡(jiǎn)單的接口有一個(gè)方法：toModel(). 它基于將非模型對(duì)象 ( Employee) 轉(zhuǎn)換為基于模型的對(duì)象 ( EntityModel)。

您之前在控制器中看到的所有代碼都可以移到此類中。并且通過應(yīng)用 Spring Framework 的@Component注解，將在應(yīng)用程序啟動(dòng)時(shí)自動(dòng)創(chuàng)建匯編程序。

Spring HATEOAS 的所有模型的抽象基類是RepresentationModel. 但是為了簡(jiǎn)單起見，我建議使用EntityModel作為您的機(jī)制來輕松地將所有 POJO 包裝為模型。

要利用此匯編器，您只需EmployeeController通過在構(gòu)造函數(shù)中注入?yún)R編器來更改 。

將 EmployeeModelAssembler 注入控制器

@RestControllerclass EmployeeController {  private final EmployeeRepository repository;  private final EmployeeModelAssembler assembler;  EmployeeController(EmployeeRepository repository, EmployeeModelAssembler assembler) {    this.repository = repository;    this.assembler = assembler;  }  ...}

從這里，您可以在單項(xiàng)員工方法中使用該匯編程序：

使用匯編程序獲取單項(xiàng)資源

@GetMapping("/employees/{id}")EntityModel one(@PathVariable Long id) {  Employee employee = repository.findById(id) //      .orElseThrow(() -> new EmployeeNotFoundException(id));  return assembler.toModel(employee);}

這段代碼幾乎是一樣的，除了不是在EntityModel這里創(chuàng)建實(shí)例，而是將它委托給匯編器。也許這看起來并不多。

在聚合根控制器方法中應(yīng)用相同的東西更令人印象深刻：

使用匯編程序獲取聚合根資源

@GetMapping("/employees")CollectionModel> all() {  List> employees = repository.findAll().stream() //      .map(assembler::toModel) //      .collect(Collectors.toList());  return CollectionModel.of(employees, linkTo(methodOn(EmployeeController.class).all()).withSelfRel());}

同樣，代碼幾乎相同，但是您可以將所有EntityModel創(chuàng)建邏輯替換為map(assembler::toModel). 由于 Java 8 方法引用，插入它并簡(jiǎn)化您的控制器非常容易。

Spring HATEOAS 的一個(gè)關(guān)鍵設(shè)計(jì)目標(biāo)是讓 The Right Thing? 變得更容易。在這種情況下：將超媒體添加到您的服務(wù)中，而無需對(duì)事物進(jìn)行硬編碼。

在這個(gè)階段，您已經(jīng)創(chuàng)建了一個(gè)實(shí)際生成超媒體驅(qū)動(dòng)內(nèi)容的 Spring MVC REST 控制器！不講 HAL 的客戶端可以在使用純數(shù)據(jù)時(shí)忽略額外的位。使用 HAL 的客戶可以瀏覽您授權(quán)的 API。

但這并不是使用 Spring 構(gòu)建真正的 RESTful 服務(wù)所需的唯一內(nèi)容。

......未完待續(xù)......

審核編輯：湯梓紅