通俗易懂RESTful,如何設計RESTful風格API

REST – REpresentational State Transfer 直譯:表現層狀態轉移。這個中文直譯經常出現在很多文章中。尼瑪,誰聽得懂“表現層狀態轉移”,這是人話嗎?

那就逐個單詞來理解REST名稱
REST – REpresentational State Transfer
首先,之所以晦澀是因爲前面主語被去掉了,全稱是 Resource Representational State Transfer:通俗來講就是:資源在網絡中以某種表現形式進行狀態轉移。分解開來:
Resource:資源,即數據(前面說過網絡的核心)。比如 newsfeed,friends等;
Representational:某種表現形式,比如用JSON,XML,JPEG等;
State Transfer:狀態變化。通過HTTP動詞實現。

爲什麼要用RESTful結構呢?
大家都知道"古代"網頁是前端後端融在一起的,比如之前的PHP,JSP等。在之前的桌面時代問題不大,但是近年來移動互聯網的發展,各種類型的Client層出不窮,RESTful可以通過一套統一的接口爲 Web,iOS和Android提供服務。另外對於廣大平臺來說,比如Facebook platform,微博開放平臺,微信公共平臺等,它們不需要有顯式的前端,只需要一套提供服務的接口,於是RESTful更是它們最好的選擇。
在這裏插入圖片描述
Level 0 - 面向前臺
我們在咖啡店向前臺點了一杯拿鐵,這個過程可以用這段文字來描述:

{
    "addOrder": {
        "orderName": "latte"
    }
}

我們通過這段文字,告訴前臺,新增一筆訂單,訂單是一杯拿鐵咖啡,接着,前臺給我們返回這麼一串回覆:

{
    "orderId": "123456"
}

假設我們有一張會員卡,我們想查詢一下這張會員卡的餘額,這時候,要向前臺發起另一個詢問:

{
    "queryBalance": {
        "cardId": "447031335"
    }
}

查詢卡號爲447031335的卡的餘額,查詢的結果返回來了:

{
    "balance": "0"
}

沒錢……
哈哈,沒錢,現在我們要跟前臺說,這杯咖啡不要了:

{
    "deleteOrder": {
        "orderId": "123456"
    }
}

Level 1 - 面向資源
現在這家咖啡店越做越大,來喝咖啡的人越來越多,單靠前臺顯然是不行的,店主決定進行分工,每個資源都有專人負責,我們可以直接面向資源操作。
比如還是下單,請求的內容不變,但是我們多了一條消息:

/orders
{
    "addOrder": {
        "orderName": "latte"
    }
}

多了一個斜槓和orders,這是什麼意思?
這個表示我們這個請求是發給哪個資源的,訂單是一種資源,我們可以理解爲是咖啡廳專門管理訂單的人,他可以幫我們處理所有有關訂單的操作,包括新增訂單、修改訂單、取消訂單等操作。
接着還是會返回訂單的編號給我們:

{
    "orderId": "123456"
}

下面,我們還是要查詢會員卡餘額,這次請求的資源變成了cards:

/cards
{
    "queryBalance": {
        "cardId": "447031335"
    }
}

接下來是取消訂單:

/orders
{
    "deleteOrder": {
        "orderId": "123456"
    }
}

Level2 - 打上標籤
接下來,店主還想繼續優化他的咖啡廳的服務流程,他發現負責處理訂單的員工,每次都要去訂單內容裏面看是新增訂單還是刪除訂單,還是其他的什麼操作,十分不方便,於是規定,所有新增資源的請求,都在請求上面寫上大大的‘POST’,表示這是一筆新增資源的請求。
其他種類的請求,比如查詢類的,用‘GET’表示,刪除類的,用‘DELETE’表示,修改用PATCH表示。
來,我們再來重複上面那個過程,來一杯拿鐵:

POST /orders
{
    "orderName": "latte"
}

請求的內容簡潔多啦,不用告訴店員是addOrder,看到POST就知道是新增,返回的內容還是一樣:

{
    "orderId": "123456"
}

接着是查詢會員卡餘額,這次也簡化了很多:

GET /cards
{
    "cardId": "447031335"
}

這個請求我們還可以進一步優化爲這樣:

GET /cards/447031335

直接把要查詢的卡號寫在後面了。
沒錯,接着,取消訂單:

DELETE /orders/123456

Level 3 - 完美服務
忽然有一天,有個顧客抱怨說,他買了咖啡後,不知道要怎麼取消訂單,咖啡廳一個店員回了一句,你不會看我們的宣傳單嗎,上面不寫着:
DELETE /orders/{orderId}
顧客反問道,誰會去看那個啊,店員不服,又說到,你瞎了啊你……後面兩人吵着吵着還打了起來…
噗,真是悲劇…
有了這次教訓,店長決定,顧客下了單之後,不僅給他們返回訂單的編號,還給顧客返回所有可以對這個訂單做的操作,比如告訴用戶如何刪除訂單。現在,我們還是發出請求,請求內容和上一次一樣:

POST /orders
{
    "orderName": "latte"
}

但是這次返回時多了些內容:

{
    "orderId": "123456",
    "link": {
        "rel": "cancel",
        "url": "/order/123456"
    }
}

這次返回時多了一項link信息,裏面包含了一個rel屬性和url屬性,rel是relationship的意思,這裏的關係是cancel,url則告訴你如何執行這個cancel操作,接着你就可以這樣子來取消訂單啦:
DELETE /orders/123456
哈哈,這服務真是貼心,以後再也不用擔心店員和顧客打起來了。
Level3的Restful API,給使用者帶來了很大的遍歷,使用者只需要知道如何獲取資源的入口,之後的每個URI都可以通過請求獲得,無法獲得就說明無法執行那個請求。
現在絕大多數的RESTful接口都做到了Level2的層次,做到Level3的比較少。當然,這個模型並不是一種規範,只是用來理解Restful的工具。所以,做到了Level2,也就是面向資源和使用Http動詞,就已經很Restful了。

Levels的意義
Level 1 解釋瞭如何通過分治法(Divide and Conquer)來處理複雜問題,將一個大型的服務端點(Service Endpoint)分解成多個資源。
Level 2 引入了一套標準的動詞,用來以相同的方式應對類似的場景,移除不要的變化。
Level 3 引入了可發現性(Discoverability),它可以使協議擁有自我描述(Self-documenting)的能力。
這一模型幫助我們思考我們想要提供的HTTP服務是何種類型的,同時也勾勒出人們和它進行交互時的期望。

從應用角度來分析:
一、REST描述的是在網絡中client和server的一種交互形式;REST本身不實用,實用的是如何設計 RESTful API(REST風格的網絡接口);
二、Server提供的RESTful API中,URL中只使用名詞來指定資源,原則上不使用動詞。“資源”是REST架構或者說整個網絡處理的核心。
URL定位資源,用HTTP動詞(GET,POST,DELETE,DETC)描述操作。
1、看Url就知道要什麼
2、看http method就知道幹什麼
3、看http status code就知道結果如何
比如:

http://api.qc.com/v1/newsfeed: 獲取某人的新鮮;
http://api.qc.com/v1/friends: 獲取某人的好友列表;
http://api.qc.com/v1/profile: 獲取某人的詳細信息;
三、用HTTP協議裏的動詞來實現資源的添加,修改,刪除等操作。即通過HTTP動詞來實現資源的狀態扭轉:
GET 用來獲取資源,
POST 用來新建資源(也可以用於更新資源),
PUT 用來更新資源,
DELETE 用來刪除資源。
比如:
DELETE http://api.qc.com/v1/friends: 刪除某人的好友 (在http parameter指定好友id)
POST http://api.qc.com/v1/friends: 添加好友
UPDATE http://api.qc.com/v1/profile: 更新個人資料
四、Server和Client之間傳遞某資源的一個表現形式,比如用JSON,XML傳輸文本,或者用JPG,WebP傳輸圖片等。當然還可以壓縮HTTP傳輸時的數據(on-wire data compression)。
五、用 HTTP Status Code傳遞Server的狀態信息。比如最常用的 200 表示成功,500 表示Server內部錯誤等。

好了,理解了RESTful的概念,究竟如何應用,這是個問題。根據項目的需求不同,我們的API設計規範也存在差別,完全看自身理解,滿足自身需求,大的理念不變,根據需求制定項目的API規範就是好的RESTful,下面附上一些設計規範,可自行參考。
引自:https://blog.csdn.net/a78270528/article/details/78469758

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章