![封面圖 封面圖](http://static.javashuo.com/static/loading.gif)
前端程序員在開發完頁面後老是要對接口的,跟後端聯調有時候還佔用蠻大的時間的,那麼你瞭解你和後端對的接口都是什麼風格嗎,大家公司接口設計的如何,你使用愉快嗎?本身在寫Node服務時你遇到如何定義好接口的問題嗎?下面介紹一種API架構風格,也是目前主流的API設計風格,你或許一直在使用。php
REST是什麼?
若是有人這麼問你,你能夠很是言簡意賅的告訴他:「REST是一個風格!」,用英文說就是 Style,那他是什麼風格呢?它是萬維網軟件架構風格。html
風格這個詞是很是關鍵的,由於它告訴咱們,REST 不是協議,也不是什麼硬性的規範,僅僅就是一種架構風格而已。是一組架構約束條件和設計指導原則,一種基於HTTP、URI、XML 等現有協議與標準的開發方式。前端
爲什麼叫REST?
REST並非REST這個單詞休息的意思,而是 Representational State Transfer 的縮寫,表示表述性狀態轉移,這個說明比較晦澀抽象,難以理解。接下來拆開解釋。程序員
- Representational:在整個詞語中表示「數據的表現形式」,如(JSON、XML......),REST其實對數據的傳輸是不作任何限制的,儘管它不作任何限制,但咱們在寫REST服務時的最佳實踐仍是用JSON比較多。
- State:當前狀態或者數據。什麼意思呢?好比說咱們寫了一個用戶接口,一個用戶列表或單個用戶的數據,好比說姓名性別這些都是 State 都是數據,在 REST 這個詞組裏爲何要用 State 來表明這些數據呢?由於若是咱們對數據進行增刪改查那麼數據就變了,在變化的每個階段它都是一種狀態,從狀態1變到狀態2等等,用狀態來描述數據更好的顯示了數據是會變化的是會被我咱們所修改的。
- Transfer:數據傳輸。在 REST 這個詞組裏它表明的是數據在互聯網上進行傳輸,好比從服務端傳輸到客戶端。面試
其實 REST 的字面意思是很難表達它的精髓的,接下來咱們經過 REST 的 6 個限制來詳細瞭解它。這6個限制是REST的精髓,是它的重中之重,在面試中會常常考到。後端
REST的六個限制
REST給出了6種約束條件,通訊兩端在遵循這些約束後,就能提升工做效率,改善系統的可伸縮性、可靠性和交互的可見性,還能促進服務解耦。api
客戶端-服務器(Client-Server)
這個限制其實已經很是常見了,如今幾乎沒有什麼不是CS架構的,因此它也是沒有任何爭議的,值得一提的是這個限制的本質實際上是一種軟件架構思想,叫作分離關注點,所謂關注點分離,用大白話說其實就是各掃門前雪,本身管好本身的事。這裏是指服務端專一數據存儲,提高了簡單性;前端專一於用戶界面,提高了可移植性。緩存
無狀態(Sateless)
所謂無狀態就是全部用戶會話信息都保存在客戶端,意思就是全部的會話信息服務端都無論,不要妄想讓服務端存着你的用戶信息、用戶會話信息、當前所處的狀態,服務端都不知道,由於服務端無論事了,因此每次請求必須包括全部信息,不能依賴上下文信息。安全
無狀態有什麼好處?好處就是服務端不用保存會話信息,提高了簡單些、可靠性、可見性。服務器
- 簡單性。服務端少了不少代碼天然就簡單了。
- 可靠性。可靠性是指一個軟件的穩定程度,以及它從依次故障中恢復正常的能力。爲何說它提高了可靠性呢?由於若是服務端要管用戶的會話信息的話,一旦服務端出錯出現故障用戶會話信息就會徹底丟失,想要恢復起來機會是不可能的,因此說它的可靠性就會不好,但若是服務端無論你用戶會話信息的話,那麼從故障中恢復起來就回很是的容易。
- 可見性。是指在軟件工程中這些模塊、接口之間的透明程度。爲何說提高了可見性了呢?由於每次請求都必須包括全部信息,因此說接口之間就更加透明瞭。
緩存(Cache)
這個很好理解。是指全部服務端響應都要被標爲可緩存或不可緩存,響應的資源能夠被標記爲可緩存或禁止緩存,若是能夠緩存,那麼客戶端能夠減小與服務器通訊的次數,下降延遲、提升效率。
統一接口(Uniform Interface)
這個限制是全部限制中最重要的一個,別的限制若是不是在 REST 裏面也能夠遵循,好比CS架構,如今生活中幾乎都是CS架構 了,也不必定是REST風格,好比緩存,別的風格也能夠用到緩存。可是隻有統一接口凸出了REST的特色,區別於其餘架構風格的核心特徵。(後面詳細講解)
統一接口是什麼意思呢,咱們分開來看:
- 統一。所謂統一指的是接口設計儘量通用統一,遵循同一個規範,提高了簡單性、可見性。
- 接口。接口與實現解耦,使先後端能夠獨立開發迭代。
分層系統(Layers)
這個限制的意思是,軟件架構是分不少層的,並且每一層只知道相鄰額有一層,後面隱藏的就不知道了,好比客戶端不知道本身是在和代理仍是在和真實的服務器通訊,這裏的代理就是軟件分層中的一層,其它層好比:安全層、負載均衡層、緩存層等。
按需代碼(Code-On-Demand 可選)
這是一條可選的限制,也不是很重要。所謂按需代碼是指客戶端能夠下載運行服務端傳來的代碼(好比JS),按需代碼的好處是經過減小一些功能,簡化了客戶端。
統一接口的限制詳細
統一接口的限制的風格到底長什麼樣?下面說一下這個限制的子限制,接口定義包括4個部分。
- 資源的標識。資源是任何能夠命名的事物,好比用戶、評論等。REST整個都是圍繞資源展開的,不像其它一些風格多是以動詞形式,REST裏面的資源都是一些名詞,不只如此,每一個資源均可以被URI惟一的標識。
- 經過表述對資源執行操做。表述就是 Representational ,好比JSON、XML等。反過來理解,客戶端不能直接操做(好比SQL)服務端資源,客戶端只能經過表述(好比JSON)來操做資源,我以爲這個很好理解。
- 自描述的消息。每一個請求或響應必須提供足夠的信息讓接受者理解,這些消息是指好比媒體類型、HTTP方法、是否緩存
- 超媒體做爲應用狀態引擎。超媒體:帶文字的連接,應用狀態:一個網頁;引擎:驅動、跳轉,其實意思就是點擊連接跳轉到另外一個網頁或者另外一個JSON。
RESTful API 設計最佳實踐
請求設計規範
- URI 使用名詞,儘可能用複數,如
/users
- URI 使用嵌套標識關聯關係,如
/users/12/repos/5
- 使用正確的HTTP方法,如
GET/POST/PUT/DELETE
- 不符合 CRUD 的狀況:
POST/action/子資源
響應設計規範
- 查詢。意思是每個響應都是能夠被查詢的、都是能夠被過濾的,咱們給接口加上一些限制條件就只能返回符合這些條件的結果。
- 分頁。本質上也是一種查詢,若是列表信息很是長的話應該加上分頁信息
- 字段過濾。只返回你指定的字段,可參閱《RESTful API 設計指南》第六節
- 狀態碼。選擇正確的狀態做爲返回狀態
- 錯誤處理。若是你的請求是錯的,那麼應用盡可能把錯誤信息給返回,並按照一個規範通用的格式
安全
開發者友好
常見筆試題:什麼是 RESTful API,如何設計RESTful API?
答案: RESTful API。爲了使得接口安全、易用、可維護以及可擴展,通常設計 RESTful API須要考慮如下幾個方面:
- 通訊用HTPS安全協議。
- 在URL中加入版本號,例如"vl/animals"
- URL中的路徑(endpoint)不能有動詞,只能用名詞。
- 用HTTP方法對資源進行增刪改查的操做。
- 用HTTP狀態碼傳達執行結果和失敗緣由。
- 爲集合提供過濾、排序、分頁等功能。
- 用查詢字符串或HTTP首部進行內容協商,指定返回結果的數據格式。
- 及時更新文檔,每一個接口都有對應的說明。
RESTful API 示例
下面是我是真實API截圖,用Swagger管理,基本遵循RESTful API架構風格
![RESTful API 示例 RESTful API 示例](http://static.javashuo.com/static/loading.gif)
路徑
HTTP動詞
- GET(SELECT):從服務器取出資源(一項或多項)。
- POST(CREATE):在服務器新建一個資源。
- PUT(UPDATE):在服務器更新資源(客戶端提供改變後的完整資源)。
- PATCH(UPDATE):在服務器更新資源(客戶端提供改變的屬性)。
- DELETE(DELETE):從服務器刪除資源。
- HEAD:獲取資源的元數據。
- OPTIONS:獲取信息,關於資源的哪些屬性是客戶端能夠改變的。
下面是一些例子
- GET
/zoos
:列出全部動物園
- POST
/zoos
:新建一個動物園
- GET
/zoos/ID
:獲取某個指定動物園的信息
- PUT
/zoos/ID
:更新某個指定動物園的信息(提供該動物園的所有信息)
- PATCH
/zoos/ID
:更新某個指定動物園的信息(提供該動物園的部分信息)
- DELETE
/zoos/ID
:刪除某個動物園
- GET
/zoos/ID/animals
:列出某個指定動物園的全部動物
- DELETE
/zoos/ID/animals/ID
:刪除某個指定動物園的指定動物
狀態碼,服務器向用戶返回的狀態碼和提示信息,常見的有如下一些(方括號中是該狀態碼對應的HTTP動詞)。
- 200 OK - [GET]:服務器成功返回用戶請求的數據,該操做是冪等的(Idempotent)。
- 201 CREATED - [POST/PUT/PATCH]:用戶新建或修改數據成功。
- 202 Accepted - [*]:表示一個請求已經進入後臺排隊(異步任務)
- 204 NO CONTENT - [DELETE]:用戶刪除數據成功。
- 400 INVALID REQUEST,POST/PUT/PATCH 用戶發出的請求有錯誤,服務器沒有進行新建或修改數據的操做,該操做是冪等的。
- 401 Unauthorized,表示用戶沒有權限(令牌、用戶名、密碼錯誤)。
- 403 Forbidden,表示用戶獲得受權(與401錯誤相對),可是訪問是被禁止的。
- 404 NOT FOUND,用戶發出的請求針對的是不存在的記錄,服務器沒有進行操做,該操做是冪等的。
- 406 Not Acceptable,GET 用戶請求的格式不可得(好比用戶請求JSON格式,可是隻有XML格式)。
- 410 Gone,GET 用戶請求的資源被永久刪除,且不會再獲得的。
- 422 Unprocesable entity,POST/PUT/PATCH 當建立一個對象時,發生一個驗證錯誤。
- 500 INTERNAL SERVER ERROR,服務器發生錯誤,用戶將沒法判斷髮出的請求是否成功。
狀態碼的徹底列表參見這裏。
傳統接口寫法與Restful API 區別
這裏再區分如下傳統接口寫法與Restful API 的區別
一個文件操做接口,傳統模式:
-
api/getfile.php
- 獲取文件信息,下載文件
-
api/uploadfile.php
- 上傳建立文件
-
api/deletefile.php
- 刪除文件
RESTfu,api/file
只須要這一個接口:
-
GET
方式請求 api/file
- 獲取文件信息,下載文件
-
POST
方式請求 api/file
- 上傳建立文件
-
DELETE
方式請求 api/file
- 刪除某個文件
你的公司使用的是RESTful API嗎?若是不是能夠考慮辭職了,太落伍了!RESTful API 如今也要讓位新寵 GraphQL 了,一種更高效、強大和靈活的數據提供方式。
![GraphQL GraphQL](http://static.javashuo.com/static/loading.gif)
相關推薦:
參考文章: