RESTful風格學習小記

2022-03-06 06:53:43 字數 3793 閱讀 7871

參考資料:(1)  (3)

restful不是一種技術,而只是一種api介面設計規範。凡是符合該規範的設計,都可以認為restful風格的服務。

但是由於各開發人員對restful的理解存在誤區或者業務特殊場景,因此實際生產的環境中真正完全滿足restful風格的服務並不多,也沒有必要。但是在實際的應用中,有restful標準可以參考,是十分有必要的。

實際上在工作中,只要對api的介面規範、命名規則、返回值、授權驗證等進行一定的約束,一般的專案api只要滿足 除錯、足夠安全、風格一致可讀性強、對於呼叫端沒有歧義、我覺得就夠了。介面是個開放人員看的,而不是給普通使用者去呼叫的。

rest:即表徵狀態轉移,是一種網際網路軟體的架構原則。如果乙個架構符合rest原則,那麼它就是restful架構

要理解restful就要好好的理解下rest的具體含義。

(1)資源(resource)

rest的名稱「表現層狀態轉移」中的,表現層其實指的的是「資源(resource)」的表現層。

所謂的資源其實就是,網路上的乙個實體,或者是網路上的乙個具體資訊。可以是一段文字、一張、一首歌曲、一種服務。你可以使用乙個uri(統一資源定位符)指向它。每種資源對應乙個特定的uri。

所謂的「上網」,就是與網際網路上的一系列「資源」互動,呼叫他的uri。

(2)表現層

「資源」是一種資訊實體,可以多種外在的表現形式。我們將「資源」具體呈現出來的形式,叫做它的「表現層」(representational )

uri只代表資源的實體位置,而不代表他的展現形式。嚴格的說,有些網頁最後的".html"字尾名, 其實是不必要的,因為這個字尾名表示格式,屬於」表現層「的範疇。因此它的具體表現形式應該在http的請求頭資訊中用acceptcontent-type字段指定。

這兩個欄位才是對表現層的描述。

(3)狀態轉化(state transfer)

訪問乙個**,就代表客戶端和伺服器的乙個互動過程,在這個過程中勢必涉及到資料和狀態的變化。

http協議是乙個無狀態的協議。這也就意味著,所有的狀態都存放在服務端。因此客戶要想操作伺服器,就必須以某種手段,讓伺服器發生狀態轉化(state transfer)。而這種轉化是建立在表現層之上的,所以就是」表現層狀態轉化「。

客戶端用到的手段嗎,只能是http協議。具體來說就是,使用http協議裡的四個表示操作方式的動詞:get、post、put、delete。他們分別對應四種基本操作。get(獲取資源)、post(新建或者更新資源資源,新建時不具備冪等性)、put(更新資源)。

delete(刪除資源)

綜上2.1所述:總結一下什麼是restful架構

(1)每一種uri代表一種資源

(2)客戶端與服務端之間,具備傳遞這種資源的表現層

(3)客戶端通過http的四個動詞,對伺服器資源進行操作。實現表現層的狀態轉化。

也即是rest之父闡述的rest六大原則

(1)c-s架構

資料儲存在c-s端,c端只需要使用就可以。兩端徹底分離的好處使得c端**的可移植性變強,server端額可拓展性變強。兩端獨立開發,互不干擾。

(2)無狀態

http請求本身就是無狀態的,基於c-s架構,客戶端的每一次請求帶有充分的資訊能夠讓服務端識別。請求所需的一些資訊都包含在url的查詢引數、header、div,服務端能夠根據請求的各種引數,無需儲存客戶端的狀態,將響應正確返回給客戶端。無狀態的特徵大大提高的服務端的健壯性和可拓展性。

當然這總無狀態性的約束也是有缺點的,客戶端的每一次請求都必須帶上相同重複的資訊確定自己的身份和狀態(這也是必須的),造成傳輸資料的冗餘性,但這種確定對於效能和使用來說,幾乎是忽略不計的。、

(3)統一的介面

這個才是rest架構的核心,統一的介面對於restful服務非常重要。客戶端只需要關注實現介面就可以,介面的可讀性加強,使用人員方便呼叫。

(4)一致的資料格式

服務端返回的資料格式要麼是xml,要麼是json(獲取資料),或者直接返回狀態碼,有興趣的可以看看的開放平台的運算元據的api,post、put、patch都是返回的乙個狀態碼 。

除了上述內容外,hateos也意味著,必要的時候鏈結也可被包含在返回的div(或頭部)中,以提供uri來檢索物件本身或關聯物件。下文將對此進行更詳細的闡述。

(5)可快取

在全球資訊網上,客戶端可以快取頁面的響應內容。因此響應都應隱式或顯式的定義為可快取的,若不可快取則要避免客戶端在多次請求後用舊資料或髒資料來響應。管理得當的快取會部分地或完全地除去客戶端和服務端之間的互動,進一步改善效能和延展性。

(6)按需編碼、可定製**(可選)(1)版本

如github開放平台

就是將版本放在url,簡潔明瞭,這個只有用了才知道,一般的專案加版本v1,v2,v3?好吧,這個加版本估計只有大公司大專案才會去使用。但是一般是將請求版本號放在header裡面

(2)引數命名規範

query引數可以採用駝峰命名方法,也可以採用下劃線的命名方式。

例如: 獲取今天登陸的使用者

&sort=login_desc 獲取今天登陸的使用者、登陸時間降序排列

(3)url命名規範

api 命名應該採用約定俗成的方式,保持簡潔明瞭。在restful架構中,每個url代表一種資源所以url中不能有動詞,只能有名詞,並且名詞中也應該使用複數。實現者應使用相應的http動詞get、post、put、patch、delete、head來操作這些資源即可

不規範的的url,冗餘沒有意義,形式不固定,不同的開發者還需要了解文件才能呼叫。

但是一般實踐中,像管理後台經常通過在url末尾加上add/delete/update/list方式來區分介面(這樣也有一定的可讀性)

如:

規範化後的restful風格的url,形式固定,可讀性強。根據名詞以及http請求動詞就可以判斷與操作這些資源

(4)返回的資料格式統一

對於合法的請求應該統一返回資料格式,這裡演示的是json

返回成功的響應json格式

返回失敗的響應json格式

當然,也可以根據自己業務的實際情況進行擴充套件,筆者所在的業務部門,統一的返回格式如下:

這個可以在後端**中進行相應的封裝,在controller層返回的時候呼叫例項化包裝物件即可。

(5)http狀態碼

一般通過response響應頭中的狀態碼也可以知道自己的請求是否成功。(4)中統一返回的狀態碼是對http狀態碼的乙個細分。

常見的http狀態碼如下:

5**(伺服器錯誤)這些狀態**表示伺服器在嘗試處理請求時發生內部錯誤。這些錯誤可能是伺服器本身的錯誤,而不是請求出錯。 

(6) 合理使用query parameter

在請求資料時,客戶端經常會對資料進行過濾和分頁等要求,而這些引數推薦採用http query parameter的方式實現

關於分頁,看看開放平台分頁獲取精華區博文列表

返回示例:[ ,

]

Restful風格學習筆記

rest架構風格最重要的架構約束有6個 通訊只能由客戶端單方面發起,表現為請求 響應的形式。通訊的會話狀態 session state 應該全部由客戶端負責維護。響應內容可以在通訊鏈的某處被快取,以改善網路效率。通訊鏈的元件之間通過統一的介面相互通訊,以提高互動的可見性。通過限制元件的行為 即,每個...

Restful風格學習經驗

restful風格是目前來說最流行的網際網路軟體架構,它並不是一種標準,而是乙個開發架構的思想風格。那麼究竟怎麼樣的風格算是rest呢,查了一些資料有了一些了解,寫了乙個demo參考一下。首先說一下rest,它的全稱是representational state transfer,翻譯過來是表現層或...

設計風格 Restful

rest是設計風格而不是標準,只提供了一組設計原則和約束條件 資源由uri來指定 uri 統一資源識別符號 對資源的包括包括獲取 建立 修改 和刪除資源 這些操作正好對應http協議提供的get post put和delete方法 通過操作資源的表現形式來操作資源 非rest風格url http q...