資訊專欄INFORMATION COLUMN
摘要：互聯網通信協議協議，是一個無狀態協議。具體來說，就是協議里面，四個表示操作方式的動詞。版本號的版本號和客戶端的版本號是毫無關系的，不要讓將它們用于提交應用市場的版本號傳遞到服務器，而是提供類似于之類的版本號。版本號拼接在中。
為什么要用 RESTful
RESTful 給我的最大感覺就是規范、易懂和優雅，一個結構清晰、易于理解的 API 完全可以省去許多無意義的溝通和文檔。并且 RESTful 現在越來越流行，
在開始介紹 RESTful API 之前，先介紹一下 RESTful 架構。
RESTful 架構REST，即Representational State Transfer 的縮寫。意為 " 表現層狀態轉化 " 。
要理解RESTful架構，最好的方法就是去理解 Representational State Transfer 這個詞組到底是什么意思，它的每一個詞代表了什么涵義。如果把這個名稱搞懂了，也就不難體會 REST 是一種什么樣的設計。
資源 （Resources）REST的名稱"表現層狀態轉化"中，省略了主語。"表現層"其實指的是"資源"（Resources）的"表現層"。
所謂"資源"，就是網絡上的一個實體，或者說是網絡上的一個具體信息。它可以是一段文本、一張圖片、一首歌曲、一種服務，總之就是一個具體的實在。你可以用一個 URI（統一資源定位符）指向它，每種資源對應一個特定的 URI 。要獲取這個資源，訪問它的 URI 就可以，因此 URI 就成了每一個資源的地址或獨一無二的識別符。所謂"上網"，就是與互聯網上一系列的"資源"互動，調用它的 URI 。
表現層（Representation）"資源"是一種信息實體，它可以有多種外在表現形式。我們把"資源"具體呈現出來的形式，叫做它的"表現層"（Representation）。
比如，文本可以用 txt 格式表現，也可以用 HTML 格式、 XML 格式、JSON 格式表現，甚至可以采用二進制格式；圖片可以用 JPG 格式表現，也可以用 PNG 格式表現。
URI 只代表資源的實體，不代表它的形式。嚴格地說，有些網址最后的" .html "后綴名是不必要的，因為這個后綴名表示格式，屬于"表現層"范疇，而 URI 應該只代表"資源"的位置。它的具體表現形式，應該在 HTTP 請求的頭信息中用 Accept 和 Content-Type 字段指定，這兩個字段才是對"表現層"的描述。
訪問一個網站，就代表了客戶端和服務器的一個互動過程。在這個過程中，勢必涉及到數據和狀態的變化。
互聯網通信協議 HTTP 協議，是一個無狀態協議。這意味著，所有的狀態都保存在服務器端。因此，如果客戶端想要操作服務器，必須通過某種手段，讓服務器端發生"狀態轉化"（State Transfer）。而這種轉化是建立在表現層之上的，所以就是"表現層狀態轉化"。
客戶端用到的手段，只能是HTTP協議。具體來說，就是HTTP協議里面，四個表示操作方式的動詞：GET 、 POST 、 PUT 、 DELETE 。 它們分別對應四種基本操作： GET 用來獲取資源， POST 用來新建資源，PUT 用來更新資源，DELETE 用來刪除資源。
總結一下什么是RESTful架構：
每一個URI代表一種資源；
客戶端和服務器之間，傳遞這種資源的某種表現層；
客戶端通過四個HTTP動詞，對服務器端資源進行操作，實現"表現層狀態轉化"。
RESTful API 的設計介紹完 RESTful 的含義，再說說 RESTful API 的設計。
協議如果能全站 HTTPS 當然是最好的，不能的話也請盡量將登錄、注冊等涉及密碼的接口使用 HTTPS。
域名應該盡量將API部署在專用域名之下。如：
https://api.example.com
如果確定API很簡單，不會有進一步擴展，可以考慮放在主域名下。
https://example.org/api/版本號
API 的版本號和客戶端 APP 的版本號是毫無關系的，不要讓 APP 將它們用于提交應用市場的版本號傳遞到服務器，而是提供類似于v1、v2之類的 API 版本號。
版本號拼接在 URL 中。如：
api.example.com/v1/users
或是放在 Header 中:
api.xxx.com/users version=v1請求
一般來說 API 的外在形式無非就是增刪改查（當然具體的業務邏輯肯定要復雜得多），而查詢又分為詳情和列表兩種，在 RESTful 中這就相當于通用的模板。例如針對文章（Article）設計 API，那么最基礎的 URL 就是這幾種：
GET /articles： 文章列表
GET /articles/id：文章詳情
POST /articles/： 創建文章
PUT /articles/id：修改文章
DELETE /articles/id：刪除文章
Token 和 SignAPI 需要設計成無狀態，所以客戶端在每次請求時都需要提供有效的 Token 和 Sign，在我看來它們的用途分別是：
Token 用于證明請求所屬的用戶，一般都是服務端在登錄后隨機生成一段字符串（UUID）和登錄用戶進行綁定，再將其返回給客戶端。Token 的狀態保持一般有兩種方式實現：一種是在用戶每次操作都會延長或重置 TOKEN 的生存時間（類似于緩存的機制），另一種是 Token 的生存時間固定不變，但是同時返回一個刷新用的 Token，當 Token 過期時可以將其刷新而不是重新登錄。
Sign 用于證明該次請求合理，所以一般客戶端會把請求參數拼接后并加密作為 Sign 傳給服務端，這樣即使被抓包了，對方只修改參數而無法生成對應的 Sign 也會被服務端識破。當然也可以將時間戳、請求地址和 Token 也混入 Sign，這樣 Sign 也擁有了所屬人、時效性和目的地。
業務參數在 RESTful 的標準中，PUT 和 PATCH 都可以用于修改操作，它們的區別是 PUT 需要提交整個對象，而 PATCH 只需要提交修改的信息。但是在我看來實際應用中不需要這么麻煩，所以我一律使用 PUT，并且只提交修改的信息。
另一個問題是在 POST 創建對象時，究竟該用表單提交更好些還是用 JSON 提交更好些。其實兩者都可以，在我看來它們唯一的區別是 JSON 可以比較方便的表示更為復雜的結構（有嵌套對象）。另外無論使用哪種，請保持統一，不要兩者混用。
還有一個建議是最好將過濾、分頁和排序的相關信息全權交給客戶端，包括過濾條件、頁數或是游標、每頁的數量、排序方式、升降序等，這樣可以使 API 更加靈活。但是對于過濾條件、排序方式等，不需要支持所有方式，只需要支持目前用得上的和以后可能會用上的方式即可，并通過字符串枚舉解析，這樣可見性要更好些。例如：
搜索，客戶端只提供關鍵詞，具體搜索的字段，和搜索方式（前綴、全文、精確）由服務端決定：
/users/?query=ScienJus
過濾，只需要對已有的情況進行支持：
/users/?gender=1
分頁：
/users/?page=2&pre_page=20響應
盡量使用 HTTP 狀態碼，常用的有：
200：請求成功
201：創建、修改成功
204：刪除成功
400：參數錯誤
401：未登錄
403：禁止訪問
404：未找到
500：系統錯誤
但是有些時候僅僅使用 HTTP 狀態碼沒有辦法明確的表達錯誤信息，所以也可以在里面再包一層自定義的返回碼，例如：
成功時：
{
"code": 100,
"msg": "成功",
"data": {}
}
{
"code": -1000,
"msg": "用戶名或密碼錯誤"
}
data是真正需要返回的數據，并且只會在請求成功時才存在，msg只用在開發環境，并且只為了開發人員識別。客戶端邏輯只允許識別code，并且不允許直接將msg的內容展示給用戶。如果這個錯誤很復雜，無法使用一段話描述清楚，也可以在添加一個doc字段，包含指向該錯誤的文檔的鏈接。
返回數據JSON 比 XML 可視化更好，也更加節約流量，所以盡量不要使用 XML。
創建和修改操作成功后，需要返回該資源的全部信息。
返回數據不要和客戶端界面強耦合，不要在設計 API 時就考慮少查詢一張關聯表或是少查詢 / 返回幾個字段能帶來多大的性能提升。并且一定要以資源為單位，即使客戶端一個頁面需要展示多個資源，也不要在一個接口中全部返回，而是讓客戶端分別請求多個接口。
最好將返回數據進行加密和壓縮，尤其是壓縮在移動應用中還是比較重要的。
文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。
轉載請注明本文地址：http://specialneedsforspecialkids.com/yun/26204.html
摘要：其他交互一般會遵循一些數據結構協議或者狀態值，比如不同的操作結果對應不同的狀態值，且出錯會返回指定的錯誤信息方便前端進行提示等。 RESTful這種架構已經具有很長的時間和歷程了，但似乎最近restful這個詞出現的頻率特別高，目前不是很清楚是因為我自個兒現在是以restful風格寫程序產生的孕婦效應，還是單頁面程序開發的流行造成的。 其實一開始我也是不想寫這篇文章的，因為網絡上與re...
showImg(https://segmentfault.com/img/bV6aHV?w=1280&h=800); 社區優秀文章 Laravel 5.5+passport 放棄 dingo 開發 API 實戰，讓 API 開發更省心 - 自造車輪。 API 文檔神器 Swagger 介紹及在 PHP 項目中使用 - API 文檔撰寫方案 推薦 Laravel API 項目必須使用的 8 個...
摘要：狀態碼狀態碼范圍信息，請求收到，繼續處理。范圍的狀態碼是保留給服務器端錯誤用的。當收到響應時，客戶端不可能知道服務器的狀態，所以這類狀態碼是要盡可能的避免。服務器向用戶返回的狀態碼和提示信息，常見的有以下一些方括號中是該狀態碼對應的動詞。 這篇 文章主要是借鑒他人，但是自己很想總結出一套規范，以供向我這樣的新手使用，用來規范代碼，如果有什么好的提議，請不吝賜教，本篇文章長期更新！ 一、...
摘要：滿足這些約束條件和原則的應用程序或設計就是。需要注意的是，是設計風格而不是標準。同一個路徑，因為請求方式的不同，而去找尋不同的接口，完成對資源狀態的轉變。一個符合風格的就可以稱之一個的接口。 RESTful 相信在座的各位對于RESTful都是略有耳聞，那么RESTful到底是什么呢？ REST（Representational State Transfer）表述性狀態轉移是一組架構約...
摘要：則是目前比較成熟的一套互聯網應用程序的設計理論。則允許操作，不一樣，報錯返回或者加入黑名單。再看下我們的數據庫中的用戶信息，值也被存入了進來，便于我們之后進行權限驗證。訪問同時將我們的值在中以傳入正確獲得用戶名則表示我們訪問請求通過了驗證。 showImg(https://segmentfault.com/img/remote/1460000008629635?w=800&h=534)...
閱讀 1209·2021-11-23 09:51
閱讀 1986·2021-10-08 10:05
閱讀 2344·2019-08-30 15:56
閱讀 1904·2019-08-30 15:55
閱讀 2643·2019-08-30 15:55
閱讀 2493·2019-08-30 13:53
閱讀 3504·2019-08-30 12:52
閱讀 1255·2019-08-29 10:57
