到底什么樣的REST才是最佳REST？

說起 REST API，小伙伴們多多少少都有聽說過，但是如果讓你詳細(xì)介紹一下什么是 REST，估計會有很多人講不出來，或者只講出來其中一部分。

今天松哥就來和大家一起來聊一聊到底什么是 REST，順便再來看下 Spring HATEOAS 的用法。

1. REST 成熟模型

首先關(guān)于 REST，有一個大佬 Leonard Richardson 為 REST 定義了一個成熟度模型，他一共定義了四個不同的層次，分別如下：

Level0：Web 服務(wù)單純的使用 HTTP 作為數(shù)據(jù)傳輸方式，本質(zhì)上就是遠(yuǎn)程方法調(diào)用，常見的 SOAP 和 RPC 基本上都屬于這一類。

Level1：在這一級別上，引入了資源的概念，服務(wù)端的每一個資源，都有一個對應(yīng)的操作地址。

Level2：在這一級別上，我們引入了不同的 HTTP 請求方法來描述不同的操作，例如 GET 表示查詢、POST 表示插入、PUT 表示更新、DELETE 表示刪除，并且使用 HTTP 的狀態(tài)碼來表示不同的響應(yīng)結(jié)果。一般來說，大家在日常的接口開發(fā)中，基本上都能做到這一層級。但是這還不是最佳結(jié)果。

Level3：按照 Leonard Richardson 的意思，這一層級的 REST 基于 HATEOAS（Hypertext As The Engine Of Application State），在這一級別上，除了返回資源的 JSON 之外，還會額外返回一組 Link，這組 Link 描述了對于該資源可以做哪些操作，以及具體的該怎么做。

在日常的開發(fā)中，我們一般都是只實現(xiàn)到 Level2 這一層級，真正做到 Level3 的估計很少，不過雖然在工作中一般不會做到 Level3 這一層級，但是，我相信很多小伙伴應(yīng)該是見過 Level3 層級的 REST 是啥樣子的，特別是看過 vhr 視頻的小伙伴，松哥在其中講過，通過 Spring Data Jpa+Spring Rest Repositories 實現(xiàn)的 CURD 接口，其實就是一個達(dá)到了 Level3 層級的 REST。

2. Spring HATEOAS

那么接下來我先用 Spring HATEOAS 寫一個簡單的 REST，然后結(jié)合這個案例來和小伙伴們聊一聊到底 Spring HATEOAS 有何不一樣的地方。

首先我們創(chuàng)建一個 Spring Boot 工程，引入 Web 和 Spring HATEOAS 依賴，如下：

創(chuàng)建好之后，我們首先創(chuàng)建一個 User 實體類：

publicclassUserextendsRepresentationModel{
privateIntegerid;
privateStringusername;
privateStringaddress;
//省略getter/setter
}

注意這個 User 實體類需要繼承自 RepresentationModel，以方便后續(xù)添加不同的 Link（以前舊的版本需要繼承自 ResourceSupport）。

接下來寫一個簡單的測試接口。

查詢所有用戶：

@RestController
@RequestMapping("/users")
publicclassUserController{

@GetMapping
publicCollectionModellist(){
Listlist=newArrayList<>();
Useru1=newUser();
u1.setId(1);
u1.setUsername("javaboy");
u1.setAddress("www.javaboy.org");
u1.add(WebMvcLinkBuilder.linkTo(UserController.class).slash(u1.getId()).withSelfRel());
list.add(u1);
Useru2=newUser();
u2.setId(2);
u2.setUsername("itboy");
u2.setAddress("www.itboyhub.com");
u2.add(WebMvcLinkBuilder.linkTo(UserController.class).slash(u2.getId()).withSelfRel());
list.add(u2);
CollectionModelusers=CollectionModel.of(list);
users.add(WebMvcLinkBuilder.linkTo(UserController.class).withRel("users"));
returnusers;
}
}

關(guān)于這個接口，我來說幾點：

首先，對于這種返回一個集合或者數(shù)組的情況，返回的類型都是 CollectionModel。

把集合弄好之后（正常應(yīng)該去數(shù)據(jù)庫中查詢，我這里省事直接創(chuàng)建了），通過 CollectionModel.of(list) 方法去獲取一個 CollectionModel 對象。

對于每一個 user 對象，我都添加了一個 Link 對象，WebMvcLinkBuilder.linkTo(UserController.class).slash(u1.getId()).withSelfRel() 表示生成當(dāng)前對象的訪問鏈接。

WebMvcLinkBuilder.linkTo(UserController.class).withRel("users") 表示訪問所有數(shù)據(jù)的鏈接。

好了，這個接口寫完之后，我們訪問看下：

可以看到，返回的每一個 user 對象中，都有一個鏈接表示如何單獨訪問這個對象。最下面還有一個訪問所有對象的鏈接。

對于上面這個案例，可能有小伙伴會質(zhì)疑，難道我們從數(shù)據(jù)庫中查詢出來的 List 集合都要遍歷一遍，然后給每一個 User 添加一個 Link 嗎？其實不必，添加 Link 這個事可以直接在 User 類中完成，如下：

publicclassUserextendsRepresentationModel{
privateIntegerid;
privateStringusername;
privateStringaddress;

publicUser(Integerid){
super(WebMvcLinkBuilder.linkTo(UserController.class).slash(id).withSelfRel());
this.id=id;
}
//省略getter/setter
}

可以看到，直接在構(gòu)造方法中完成即可。此時接口里就不用那么復(fù)雜了，如下：

@GetMapping
publicCollectionModellist(){
Listlist=newArrayList<>();
Useru1=newUser(1);
u1.setUsername("javaboy");
u1.setAddress("www.javaboy.org");
list.add(u1);
Useru2=newUser(2);
u2.setUsername("itboy");
u2.setAddress("www.itboyhub.com");
list.add(u2);
CollectionModelusers=CollectionModel.of(list);
users.add(WebMvcLinkBuilder.linkTo(UserController.class).withRel("users"));
returnusers;
}

那么對于根據(jù) ID 來查詢用戶的需求，我們也應(yīng)該給一個接口如下：

@RestController
@RequestMapping("/users")
publicclassUserController{

@GetMapping("/{id}")
publicEntityModelgetOne(@PathVariableIntegerid)throwsNoSuchMethodException{
Useru=newUser(id);
u.setUsername("javaboy");
u.setAddress("深圳");
u.add(Link.of("http://localhost:8080/users/"+id,"getOne"));
Linkusers=WebMvcLinkBuilder.linkTo(UserController.class).withRel("users");
u.add(users);
Linklink=WebMvcLinkBuilder.linkTo(UserController.class).slash(u.getId()).withSelfRel();
u.add(link);
Methodmethod=UserController.class.getMethod("getOne",Integer.class);
Linklink2=WebMvcLinkBuilder.linkTo(method,id).withSelfRel();
u.add(link2);
returnEntityModel.of(u);
}
}

關(guān)于這個接口，我說如下幾點：

如果返回類型是一個對象的話，需要使用 EntityModel 類型。

搞好返回的對象之后，通過 EntityModel.of(u) 方法可以獲取到目標(biāo)數(shù)據(jù)類型。

這個地方，為了給小伙伴們演示不同的 Link 添加方式，我寫了好多個（單純?yōu)榱搜菔静煌?Link 添加方式）：

Link.of("http://localhost:8080/users/"+id, "getOne") 這種是自己純手工去生成當(dāng)前對象的訪問鏈接，很明顯這不是一個很好的方案。當(dāng)前對象的訪問鏈接建議使用上文中提到的方式。

WebMvcLinkBuilder.linkTo(UserController.class).withRel("users") 這個是生成當(dāng)前這個 Controller 的訪問鏈接，一般就是訪問所有用戶對象的鏈接。

WebMvcLinkBuilder.linkTo(UserController.class).slash(u.getId()).withSelfRel() 前文已經(jīng)用過了，不多說了，實際應(yīng)用中建議使用這種。

也可以根據(jù)某一個方法自動生成，像這樣 WebMvcLinkBuilder.linkTo(method, id).withSelfRel()，這個是生成某一個具體方法的訪問鏈接。

好了，現(xiàn)在我們來看下這個接口生成的 JSON，如下：

生成的這段 JSON 我將之標(biāo)記為了三部分：

第一部分，self，就是自身的訪問鏈接，這三個鏈接分別是 User 的構(gòu)造方法，以及前面提到的 3.3 和 3.4 的方法生成的。

第二部分，getOne 這個，是前面 3.1 中提到的方法生成的。

第三部分，users 這個，是前面提到的 3.2 方法生成的。

當(dāng)然，其實這塊還有很多其他的生成鏈接的玩法，但是我就不一一介紹了，小伙伴們可以參考官方文檔：

https://docs.spring.io/spring-hateoas/docs/current/reference/html

從上面 Spring HATEOAS 中返回的 JSON 我們大致上可以看到它的特點：

當(dāng)我們使用了 Spring HATEOAS，此時，客戶端就會通過服務(wù)端返回的 Link Rel 來獲取請求的 URI（如果沒有使用 Spring HATEOAS，則客戶端訪問的 URI 都是提前在客戶端硬編碼的），現(xiàn)在我們就可以做到服務(wù)端在不破壞客戶端實現(xiàn)的情況下動態(tài)的完成 URI 的修改，從而進(jìn)一步解耦客戶端和服務(wù)端。

簡而言之，現(xiàn)在客戶端能干什么事情，在服務(wù)端返回的 JSON 中都會告訴客戶端，客戶端從服務(wù)端返回的 JSON 中獲取到請求的 URL，然后直接執(zhí)行即可。如果這個請求地址發(fā)生變化的話，客戶端也會及時拿到最新的地址。

可能上面的例子小伙伴們感受還不是很明顯，我再給大家看一段 JSON：

{
"tracking_id":"666",
"status":"WAIT_PAYMENT",
"items":[
{
"name":"book",
"quantity":1
}
],
"_Links":{
"self":{
"href":"http://localhost:8080/orders/666"
},
"cancel":{
"href":"http://localhost:8080/orders/666"
},
"payment":{
"href":"http://localhost:8080/orders/666/payments"
}
}
}

這是電商系統(tǒng)下單之后等待支付的過程中返回的 JSON，這里的 links 給出了三個：

self：訪問這個鏈接可以查看當(dāng)前訂單信息（GET 請求）。

cancel：訪問這個鏈接可以取消當(dāng)前訂單（DELETE 請求）。

payment：訪問這個鏈接可以支付當(dāng)前訂單（POST 請求）。

這個例子就很直白了，就是在返回的 JSON 中，直接告訴你接下來能做哪些操作，對應(yīng)的 URL 分別是什么，前端拿到之后直接操作，如果這些操作路徑發(fā)生了變化，前端也會立馬拿到最新的路徑。

這就是 Spring HATEOAS 的好處?？傊痪湓?，Spring HATEOAS 提倡在響應(yīng)返回的 Link 中給出對該資源接下來操作的 URL。這種方式解耦了服務(wù)端 URI，也可以讓客戶端開發(fā)者更容易地探索 API。

3. REST 的優(yōu)缺點

雖然我們現(xiàn)在都鼓勵設(shè)計 REST 風(fēng)格的 API，然而 REST 也不全是優(yōu)點，事物總是具有兩面性，REST 的優(yōu)缺點分別如下。

3.1 優(yōu)點

首先，REST 足夠簡單，有一定 Web 開發(fā)經(jīng)驗的小伙伴都可以快速上手 REST。

REST 風(fēng)格的接口測試起來也非常方便，利用瀏覽器自帶的一些 REST 插件或者是 POSTMAN 之類的工具，就可以非常方便的實現(xiàn) REST 接口的測試。

不需要中間代理，簡化了系統(tǒng)的結(jié)構(gòu)。

HTTP 對防火墻比較友好。

3.2 缺點

REST 只支持請求-響應(yīng)的通信方法，不支持服務(wù)端推送消息到客戶端。

給請求取一個合適的名字比較困難，特別是有多個相類似的接口時，例如有多個添加接口、多個更新接口等。

由于沒有中間代理，所以請求/響應(yīng)的時候，服務(wù)端和客戶端都必須在線。

好啦，跟小伙伴們聊了 REST 和 Spring HATEOAS，感興趣的小伙伴可以去試試哦～