到底什麼樣的 REST 才是最佳 REST？詳情 - java,rest,springboot 江南一點雨博客

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

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

1. REST 成熟模型

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

Level0：Web 服務單純的使用 HTTP 作為數據傳輸方式，本質上就是遠程方法調用，常見的 SOAP 和 RPC 基本上都屬於這一類。
Level1：在這一級別上，引入了資源的概念，服務端的每一個資源，都有一個對應的操作地址。
Level2：在這一級別上，我們引入了不同的 HTTP 請求方法來描述不同的操作，例如 GET 表示查詢、POST 表示插入、PUT 表示更新、DELETE 表示刪除，並且使用 HTTP 的狀態碼來表示不同的響應結果。一般來説，大家在日常的接口開發中，基本上都能做到這一層級。但是這還不是最佳結果。
Level3：按照 Leonard Richardson 的意思，這一層級的 REST 基於 HATEOAS（Hypertext As The Engine Of Application State），在這一級別上，除了返回資源的 JSON 之外，還會額外返回一組 Link，這組 Link 描述了對於該資源可以做哪些操作，以及具體的該怎麼做。

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

2. Spring HATEOAS

那麼接下來我先用 Spring HATEOAS 寫一個簡單的 REST，然後結合這個案例來和小夥伴們聊一聊到底 Spring HATEOAS 有何不一樣的地方。

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

創建好之後，我們首先創建一個 User 實體類：

public class User extends RepresentationModel {
    private Integer id;
    private String username;
    private String address;
    //省略 getter/setter
}

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

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

查詢所有用户：

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping
    public CollectionModel<User> list() {
        List<User> list = new ArrayList<>();
        User u1 = new User();
        u1.setId(1);
        u1.setUsername("javaboy");
        u1.setAddress("www.javaboy.org");
        u1.add(WebMvcLinkBuilder.linkTo(UserController.class).slash(u1.getId()).withSelfRel());
        list.add(u1);
        User u2 = new User();
        u2.setId(2);
        u2.setUsername("itboy");
        u2.setAddress("www.itboyhub.com");
        u2.add(WebMvcLinkBuilder.linkTo(UserController.class).slash(u2.getId()).withSelfRel());
        list.add(u2);
        CollectionModel<User> users = CollectionModel.of(list);
        users.add(WebMvcLinkBuilder.linkTo(UserController.class).withRel("users"));
        return users;
    }
}

關於這個接口，我來説幾點：

首先，對於這種返回一個集合或者數組的情況，返回的類型都是 CollectionModel<User>。
把集合弄好之後（正常應該去數據庫中查詢，我這裏省事直接創建了），通過 CollectionModel.of(list) 方法去獲取一個 CollectionModel<User> 對象。
對於每一個 user 對象，我都添加了一個 Link 對象，WebMvcLinkBuilder.linkTo(UserController.class).slash(u1.getId()).withSelfRel() 表示生成當前對象的訪問鏈接。
WebMvcLinkBuilder.linkTo(UserController.class).withRel("users") 表示訪問所有數據的鏈接。

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

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

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

public class User extends RepresentationModel {
    private Integer id;
    private String username;
    private String address;

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

可以看到，直接在構造方法中完成即可。此時接口裏就不用那麼複雜了，如下：

@GetMapping
public CollectionModel<User> list() {
    List<User> list = new ArrayList<>();
    User u1 = new User(1);
    u1.setUsername("javaboy");
    u1.setAddress("www.javaboy.org");
    list.add(u1);
    User u2 = new User(2);
    u2.setUsername("itboy");
    u2.setAddress("www.itboyhub.com");
    list.add(u2);
    CollectionModel<User> users = CollectionModel.of(list);
    users.add(WebMvcLinkBuilder.linkTo(UserController.class).withRel("users"));
    return users;
}

那麼對於根據 ID 來查詢用户的需求，我們也應該給一個接口如下：

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping("/{id}")
    public EntityModel<User> getOne(@PathVariable Integer id) throws NoSuchMethodException {
        User u = new User(id);
        u.setUsername("javaboy");
        u.setAddress("深圳");
        u.add(Link.of("http://localhost:8080/users/"+id, "getOne"));
        Link users = WebMvcLinkBuilder.linkTo(UserController.class).withRel("users");
        u.add(users);
        Link link = WebMvcLinkBuilder.linkTo(UserController.class).slash(u.getId()).withSelfRel();
        u.add(link);
        Method method = UserController.class.getMethod("getOne", Integer.class);
        Link link2 = WebMvcLinkBuilder.linkTo(method, id).withSelfRel();
        u.add(link2);
        return EntityModel.of(u);
    }
}

關於這個接口，我説如下幾點：

如果返回類型是一個對象的話，需要使用 EntityModel<User> 類型。
搞好返回的對象之後，通過 EntityModel.of(u) 方法可以獲取到目標數據類型。
這個地方，為了給小夥伴們演示不同的 Link 添加方式，我寫了好多個（單純為了演示不同的 Link 添加方式）：
1. Link.of("http://localhost:8080/users/"+id, "getOne") 這種是自己純手工去生成當前對象的訪問鏈接，很明顯這不是一個很好的方案。當前對象的訪問鏈接建議使用上文中提到的方式。
2. WebMvcLinkBuilder.linkTo(UserController.class).withRel("users") 這個是生成當前這個 Controller 的訪問鏈接，一般就是訪問所有用户對象的鏈接。
3. WebMvcLinkBuilder.linkTo(UserController.class).slash(u.getId()).withSelfRel() 前文已經用過了，不多説了，實際應用中建議使用這種。
4. 也可以根據某一個方法自動生成，像這樣 WebMvcLinkBuilder.linkTo(method, id).withSelfRel()，這個是生成某一個具體方法的訪問鏈接。

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

生成的這段 JSON 我將之標記為了三部分：

第一部分，self，就是自身的訪問鏈接，這三個鏈接分別是 User 的構造方法，以及前面提到的 3.3 和 3.4 的方法生成的。
第二部分，getOne 這個，是前面 3.1 中提到的方法生成的。
第三部分，users 這個，是前面提到的 3.2 方法生成的。

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

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

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

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

簡而言之，現在客户端能幹什麼事情，在服務端返回的 JSON 中都會告訴客户端，客户端從服務端返回的 JSON 中獲取到請求的 URL，然後直接執行即可。如果這個請求地址發生變化的話，客户端也會及時拿到最新的地址。

可能上面的例子小夥伴們感受還不是很明顯，我再給大家看一段 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"
        }
    }
}

這是電商系統下單之後等待支付的過程中返回的 JSON，這裏的 links 給出了三個：

self：訪問這個鏈接可以查看當前訂單信息（GET 請求）。
cancel：訪問這個鏈接可以取消當前訂單（DELETE 請求）。
payment：訪問這個鏈接可以支付當前訂單（POST 請求）。

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

這就是 Spring HATEOAS 的好處。總之一句話，Spring HATEOAS 提倡在響應返回的 Link 中給出對該資源接下來操作的 URL。這種方式解耦了服務端 URI，也可以讓客户端開發者更容易地探索 API。

3. REST 的優缺點

雖然我們現在都鼓勵設計 REST 風格的 API，然而 REST 也不全是優點，事物總是具有兩面性，REST 的優缺點分別如下。

3.1 優點

首先，REST 足夠簡單，有一定 Web 開發經驗的小夥伴都可以快速上手 REST。
REST 風格的接口測試起來也非常方便，利用瀏覽器自帶的一些 REST 插件或者是 POSTMAN 之類的工具，就可以非常方便的實現 REST 接口的測試。
不需要中間代理，簡化了系統的結構。
HTTP 對防火牆比較友好。

3.2 缺點

REST 只支持請求-響應的通信方法，不支持服務端推送消息到客户端。
給請求取一個合適的名字比較困難，特別是有多個相類似的接口時，例如有多個添加接口、多個更新接口等。
由於沒有中間代理，所以請求/響應的時候，服務端和客户端都必須在線。

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

江南一點雨博客

江南一點雨博客

博客 / 詳情