如何使用Spring構(gòu)建REST服務(wù)(五)

書接上文???

在 REST API 中構(gòu)建鏈接

到目前為止，您已經(jīng)使用基本鏈接構(gòu)建了一個可進(jìn)化的 API。為了發(fā)展您的 API 并更好地為您的客戶服務(wù)，您需要接受超媒體作為應(yīng)用程序狀態(tài)引擎的概念。

這意味著什么？在本節(jié)中，您將詳細(xì)探討它。

業(yè)務(wù)邏輯不可避免地會建立涉及流程的規(guī)則。此類系統(tǒng)的風(fēng)險在于我們經(jīng)常將此類服務(wù)器端邏輯帶入客戶端并建立強(qiáng)耦合。REST 就是要打破這種連接并最小化這種耦合。

為了展示如何在不觸發(fā)客戶端中斷更改的情況下應(yīng)對狀態(tài)變化，想象一下添加一個履行訂單的系統(tǒng)。

第一步，定義一條Order記錄：

鏈接
/src/main/java/payroll/Order.java

package payroll;import java.util.Objects;import javax.persistence.Entity;import javax.persistence.GeneratedValue;import javax.persistence.Id;import javax.persistence.Table;@Entity@Table(name = "CUSTOMER_ORDER")class Order {  private @Id @GeneratedValue Long id;  private String description;  private Status status;  Order() {}  Order(String description, Status status) {    this.description = description;    this.status = status;  }  public Long getId() {    return this.id;  }  public String getDescription() {    return this.description;  }  public Status getStatus() {    return this.status;  }  public void setId(Long id) {    this.id = id;  }  public void setDescription(String description) {    this.description = description;  }  public void setStatus(Status status) {    this.status = status;  }  @Override  public boolean equals(Object o) {    if (this == o)      return true;    if (!(o instanceof Order))      return false;    Order order = (Order) o;    return Objects.equals(this.id, order.id) && Objects.equals(this.description, order.description)        && this.status == order.status;  }  @Override  public int hashCode() {    return Objects.hash(this.id, this.description, this.status);  }  @Override  public String toString() {    return "Order{" + "id=" + this.id + ", description='" + this.description + '\'' + ", status=" + this.status + '}';  }}復(fù)制

• 該類需要 JPA@Table注釋將表的名稱更改為，CUSTOMER_ORDER因?yàn)?span style="color:rgb(0,0,153);">ORDER它不是表的有效名稱。
• 它包括一個description字段以及一個status字段。

從客戶提交訂單到完成或取消訂單時，訂單必須經(jīng)歷一系列狀態(tài)轉(zhuǎn)換。這可以捕獲為 Java enum：

鏈接
/src/main/java/payroll/Status.java

package payroll;enum Status {  IN_PROGRESS, //  COMPLETED, //  CANCELLED}復(fù)制

這enum捕獲了一個Order可以占據(jù)的各種狀態(tài)。對于本教程，讓我們保持簡單。

要支持與數(shù)據(jù)庫中的訂單交互，必須定義相應(yīng)的 Spring Data 存儲庫：

Spring Data JPA 的JpaRepository基本接口

interface OrderRepository extends JpaRepository {}復(fù)制,>

有了這個，您現(xiàn)在可以定義一個基本的OrderController：

鏈接
/src/main/java/payroll/OrderController.java

@RestControllerclass OrderController {  private final OrderRepository orderRepository;  private final OrderModelAssembler assembler;  OrderController(OrderRepository orderRepository, OrderModelAssembler assembler) {    this.orderRepository = orderRepository;    this.assembler = assembler;  }  @GetMapping("/orders")  CollectionModel> all() {    List> orders = orderRepository.findAll().stream() //        .map(assembler::toModel) //        .collect(Collectors.toList());    return CollectionModel.of(orders, //        linkTo(methodOn(OrderController.class).all()).withSelfRel());  }  @GetMapping("/orders/{id}")  EntityModel one(@PathVariable Long id) {    Order order = orderRepository.findById(id) //        .orElseThrow(() -> new OrderNotFoundException(id));    return assembler.toModel(order);  }  @PostMapping("/orders")  ResponseEntity> newOrder(@RequestBody Order order) {    order.setStatus(Status.IN_PROGRESS);    Order newOrder = orderRepository.save(order);    return ResponseEntity //        .created(linkTo(methodOn(OrderController.class).one(newOrder.getId())).toUri()) //        .body(assembler.toModel(newOrder));  }}復(fù)制

• 它包含與您迄今為止構(gòu)建的控制器相同的 REST 控制器設(shè)置。
• 它同時注入OrderRepositorya 和 a (not yet built) OrderModelAssembler。
• 前兩個 Spring MVC 路由處理聚合根以及單個項(xiàng)目Order資源請求。
• 第三條 Spring MVC 路由通過在IN_PROGRESS狀態(tài)中啟動它們來處理創(chuàng)建新訂單。
• 所有控制器方法都返回 Spring HATEOAS 的RepresentationModel子類之一以正確呈現(xiàn)超媒體（或圍繞此類類型的包裝器）。

在構(gòu)建 之前OrderModelAssembler，讓我們討論需要發(fā)生的事情。您正在對 、 和 之間的狀態(tài)流Status.IN_PROGRESS進(jìn)行Status.COMPLETED建模Status.CANCELLED。向客戶端提供此類數(shù)據(jù)時，一件很自然的事情是讓客戶端根據(jù)此有效負(fù)載決定它可以做什么。

但那是錯誤的。

當(dāng)您在此流程中引入新狀態(tài)時會發(fā)生什么？UI 上各種按鈕的放置可能是錯誤的。

如果您更改了每個州的名稱，可能是在編碼國際支持并顯示每個州的區(qū)域設(shè)置特定文本時會怎樣？這很可能會破壞所有客戶。

輸入HATEOAS或超媒體作為應(yīng)用程序狀態(tài)引擎。與其讓客戶端解析有效負(fù)載，不如為它們提供鏈接以發(fā)出有效操作的信號。將基于狀態(tài)的操作與數(shù)據(jù)負(fù)載分離。換句話說，當(dāng)CANCEL和COMPLETE是有效操作時，將它們動態(tài)添加到鏈接列表中。客戶端只需要在鏈接存在時向用戶顯示相應(yīng)的按鈕。

這使客戶端不必知道此類操作何時有效，從而降低了服務(wù)器及其客戶端在狀態(tài)轉(zhuǎn)換邏輯上不同步的風(fēng)險。

已經(jīng)接受了 Spring HATEOAS
RepresentationModelAssembler組件的概念，將這樣的邏輯放入其中OrderModelAssembler將是捕獲此業(yè)務(wù)規(guī)則的完美位置：

鏈接
/src/main/java/payroll/OrderModelAssembler.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 OrderModelAssembler implements RepresentationModelAssembler> {  @Override  public EntityModel toModel(Order order) {    // Unconditional links to single-item resource and aggregate root    EntityModel orderModel = EntityModel.of(order,        linkTo(methodOn(OrderController.class).one(order.getId())).withSelfRel(),        linkTo(methodOn(OrderController.class).all()).withRel("orders"));    // Conditional links based on state of the order    if (order.getStatus() == Status.IN_PROGRESS) {      orderModel.add(linkTo(methodOn(OrderController.class).cancel(order.getId())).withRel("cancel"));      orderModel.add(linkTo(methodOn(OrderController.class).complete(order.getId())).withRel("complete"));    }    return orderModel;  }}復(fù)制,>

此資源組裝器始終包含指向單項(xiàng)資源的自身鏈接以及返回聚合根的鏈接。但它也包括兩個條件鏈接OrderController.cancel(id)以及OrderController.complete(id)（尚未定義）。這些鏈接僅在訂單狀態(tài)為 時顯示Status.IN_PROGRESS。

如果客戶可以采用 HAL 和讀取鏈接的能力，而不是簡單地讀取普通的舊 JSON 數(shù)據(jù)，他們可以交換對訂單系統(tǒng)領(lǐng)域知識的需求。這自然減少了客戶端和服務(wù)器之間的耦合。它打開了調(diào)整訂單履行流程的大門，而不會在流程中破壞客戶。

要完成訂單履行，請將以下內(nèi)容添加到OrderController操作中cancel：

在 OrderController 中創(chuàng)建“取消”操作

@DeleteMapping("/orders/{id}/cancel")ResponseEntity cancel(@PathVariable Long id) {  Order order = orderRepository.findById(id) //      .orElseThrow(() -> new OrderNotFoundException(id));  if (order.getStatus() == Status.IN_PROGRESS) {    order.setStatus(Status.CANCELLED);    return ResponseEntity.ok(assembler.toModel(orderRepository.save(order)));  }  return ResponseEntity //      .status(HttpStatus.METHOD_NOT_ALLOWED) //      .header(HttpHeaders.CONTENT_TYPE, MediaTypes.HTTP_PROBLEM_DETAILS_JSON_VALUE) //      .body(Problem.create() //          .withTitle("Method not allowed") //          .withDetail("You can't cancel an order that is in the " + order.getStatus() + " status"));}復(fù)制

Order它在允許取消之前檢查狀態(tài)。如果它不是一個有效的狀態(tài)，它會返回一個RFC-7807 Problem，一個支持超媒體的錯誤容器。如果轉(zhuǎn)換確實(shí)有效，則將 轉(zhuǎn)換Order為CANCELLED。

并將其添加到OrderController訂單完成中：

在 OrderController 中創(chuàng)建“完整”操作

@PutMapping("/orders/{id}/complete")ResponseEntity complete(@PathVariable Long id) {  Order order = orderRepository.findById(id) //      .orElseThrow(() -> new OrderNotFoundException(id));  if (order.getStatus() == Status.IN_PROGRESS) {    order.setStatus(Status.COMPLETED);    return ResponseEntity.ok(assembler.toModel(orderRepository.save(order)));  }  return ResponseEntity //      .status(HttpStatus.METHOD_NOT_ALLOWED) //      .header(HttpHeaders.CONTENT_TYPE, MediaTypes.HTTP_PROBLEM_DETAILS_JSON_VALUE) //      .body(Problem.create() //          .withTitle("Method not allowed") //          .withDetail("You can't complete an order that is in the " + order.getStatus() + " status"));}復(fù)制

這實(shí)現(xiàn)了類似的邏輯以防止Order狀態(tài)完成，除非處于正確的狀態(tài)。

讓我們更新LoadDatabase以預(yù)加載一些Orders 以及Employee它之前加載的 s。

更新數(shù)據(jù)庫預(yù)加載器

package payroll;import org.slf4j.Logger;import org.slf4j.LoggerFactory;import org.springframework.boot.CommandLineRunner;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;@Configurationclass LoadDatabase {  private static final Logger log = LoggerFactory.getLogger(LoadDatabase.class);  @Bean  CommandLineRunner initDatabase(EmployeeRepository employeeRepository, OrderRepository orderRepository) {    return args -> {      employeeRepository.save(new Employee("Bilbo", "Baggins", "burglar"));      employeeRepository.save(new Employee("Frodo", "Baggins", "thief"));      employeeRepository.findAll().forEach(employee -> log.info("Preloaded " + employee));            orderRepository.save(new Order("MacBook Pro", Status.COMPLETED));      orderRepository.save(new Order("iPhone", Status.IN_PROGRESS));      orderRepository.findAll().forEach(order -> {        log.info("Preloaded " + order);      });          };  }}復(fù)制

現(xiàn)在你可以測試了！

要使用新生成的訂單服務(wù)，只需執(zhí)行一些操作：

$ curl -v http://localhost:8080/orders{  “_嵌入”：{    “訂單”： [      {        “身份證”：3，        “描述”：“MacBook Pro”，        “狀態(tài)”：“已完成”，        “_鏈接”：{          “自己”： {            "href": "http://localhost:8080/orders/3"          },          “訂單”： {            "href": "http://localhost:8080/orders"          }        }      },      {        “身份證”：4，        “描述”：“iPhone”，        “狀態(tài)”：“IN_PROGRESS”，        “_鏈接”：{          “自己”： {            "href": "http://localhost:8080/orders/4"          },          “訂單”： {            "href": "http://localhost:8080/orders"          },          “取消”： {            "href": "http://localhost:8080/orders/4/cancel"          },          “完全的”： {            "href": "http://localhost:8080/orders/4/complete"          }        }      }    ]  },  “_鏈接”：{    “自己”： {      "href": "http://localhost:8080/orders"    }  }}

此 HAL 文檔會根據(jù)其當(dāng)前狀態(tài)立即顯示每個訂單的不同鏈接。

• 第一個訂單，即COMPLETED只有導(dǎo)航鏈接。未顯示狀態(tài)轉(zhuǎn)換鏈接。
• 第二個訂單，即 IN_PROGRESS還具有取消鏈接和完整鏈接。

嘗試取消訂單：

$ curl -v -X 刪除 http://localhost:8080/orders/4/cancel> 刪除 /orders/4/cancel HTTP/1.1> 主機(jī)：本地主機(jī)：8080> 用戶代理：curl/7.54.0> 接受：*/*>< HTTP/1.1 200< 內(nèi)容類型：application/hal+json;charset=UTF-8< 傳輸編碼：分塊< 日期：2018 年 8 月 27 日星期一 15:02:10 GMT<{  “身份證”：4，  “描述”：“iPhone”，  “狀態(tài)”：“取消”，  “_鏈接”：{    “自己”： {      "href": "http://localhost:8080/orders/4"    },    “訂單”： {      "href": "http://localhost:8080/orders"    }  }}

此響應(yīng)顯示一個HTTP 200狀態(tài)代碼，表明它是成功的。響應(yīng) HAL 文檔顯示該訂單處于新狀態(tài) ( CANCELLED)。改變狀態(tài)的鏈接消失了。

如果再次嘗試相同的操作……

$ curl -v -X 刪除 http://localhost:8080/orders/4/cancel* TCP_NODELAY 設(shè)置* 連接到 localhost (::1) 端口 8080 (#0)> 刪除 /orders/4/cancel HTTP/1.1> 主機(jī)：本地主機(jī)：8080> 用戶代理：curl/7.54.0> 接受：*/*>< HTTP/1.1 405< 內(nèi)容類型：應(yīng)用程序/問題+json< 傳輸編碼：分塊< 日期：2018 年 8 月 27 日星期一 15:03:24 GMT<{  "title": "方法不允許",  "detail": "您不能取消處于 CANCELED 狀態(tài)的訂單"}

…?您會看到HTTP 405 Method Not Allowed響應(yīng)。DELETE已成為無效操作。Problem響應(yīng)對象清楚地表明您不能“取消”已經(jīng)處于“CANCELLED”狀態(tài)的訂單。

此外，嘗試完成相同的訂單也會失?。?/span>

$ curl -v -X PUT localhost:8080/orders/4/complete* TCP_NODELAY 設(shè)置* 連接到 localhost (::1) 端口 8080 (#0)> PUT /orders/4/完成 HTTP/1.1> 主機(jī)：本地主機(jī)：8080> 用戶代理：curl/7.54.0> 接受：*/*>< HTTP/1.1 405< 內(nèi)容類型：應(yīng)用程序/問題+json< 傳輸編碼：分塊< 日期：2018 年 8 月 27 日星期一 15:05:40 GMT<{  "title": "方法不允許",  "detail": "您無法完成處于 CANCELED 狀態(tài)的訂單"}

有了這一切，您的訂單履行服務(wù)就能夠有條件地顯示可用的操作。它還可以防止無效操作。

通過利用超媒體和鏈接協(xié)議，客戶端可以構(gòu)建得更堅(jiān)固，并且不太可能僅僅因?yàn)閿?shù)據(jù)的變化而崩潰。Spring HATEOAS 可以輕松構(gòu)建您需要為客戶提供服務(wù)的超媒體。

概括

在本教程中，您使用了各種策略來構(gòu)建 REST API。事實(shí)證明，REST 不僅僅是漂亮的 URI 和返回 JSON 而不是 XML。

相反，以下策略有助于降低您的服務(wù)破壞您可能控制或可能無法控制的現(xiàn)有客戶的可能性：

• 不要刪除舊字段。相反，支持他們。
• 使用基于 rel 的鏈接，這樣客戶端就不必?fù)?dān)心 URI 進(jìn)行硬編碼。
• 盡可能長時間地保留舊鏈接。即使您必須更改 URI，也要保留 rels，以便舊客戶端可以使用新功能。
• 當(dāng)各種狀態(tài)驅(qū)動操作可用時，使用鏈接而不是有效負(fù)載數(shù)據(jù)來指示客戶端。

RepresentationModelAssembler為每種資源類型構(gòu)建實(shí)現(xiàn)并在所有控制器中使用這些組件似乎需要一些努力。但是這種額外的服務(wù)器端設(shè)置（感謝 Spring HATEOAS 使之變得容易）可以確保您控制的客戶端（更重要的是，您不控制的客戶端）可以隨著您的 API 隨著發(fā)展而輕松升級。

我們關(guān)于如何使用 Spring 構(gòu)建 RESTful 服務(wù)員的教程到此結(jié)束。本教程的每個部分都在單個 github 存儲庫中作為單獨(dú)的子項(xiàng)目進(jìn)行管理：

• nonrest — 沒有自媒體的簡單 Spring MVC 應(yīng)用程序
• rest — Spring MVC + Spring HATEOAS 應(yīng)用程序，每個資源的 HAL 表示
• 進(jìn)化- REST 應(yīng)用程序，其中一個字段已進(jìn)化但保留舊數(shù)據(jù)以實(shí)現(xiàn)向后兼容性
• 鏈接- REST 應(yīng)用程序，其中條件鏈接用于向客戶端發(fā)出有效狀態(tài)更改信號

要查看使用 Spring HATEOAS 的更多示例，請參閱Spring中國教育管理中心

審核編輯：湯梓紅