資訊專欄INFORMATION COLUMN
摘要：表形容詞，意為的具有的。指的是一組架構(gòu)約束條件和原則。協(xié)議要優(yōu)于協(xié)議。的操作方法在中有各自的語義，理解它們的語義至為重要。返回結(jié)果對于不同操作方法和操作對象集合或個體，服務(wù)器返回的結(jié)果應(yīng)該符合以下規(guī)范。附錄該文主要參考理解架構(gòu)設(shè)計指南
前言
近十年，前端高速發(fā)展，整個互聯(lián)網(wǎng)應(yīng)用經(jīng)歷了從輕客戶端到重客戶端的變化，隨著前端規(guī)模越來越大，交互越來越復(fù)雜，前后端分離的設(shè)計開始流行。
移動互聯(lián)網(wǎng)時代的到來，前端開始泛指各種終端和 web 前端，服務(wù)端為多終端提供服務(wù)已然成常態(tài)。
前后端分離后，前端和后端通過雙方協(xié)商好的 API 進行交互，所以設(shè)計一套友好的 API 尤其重要。
RESTful 就是目前最流行的前后端交互 API 設(shè)計范式。
RESTful 釋義顧名思義，先看一下 RESTful 的單詞拆解:
RESTful = Resources + Representation + State + Transfer + ful
我的理解是， RESTful 是指具有 資源表現(xiàn)層 和 狀態(tài)轉(zhuǎn)換 的架構(gòu)設(shè)計。
資源(Resources)資源，是指服務(wù)端向外提供的服務(wù)實體。
資源是一個抽象的概念，可以是應(yīng)用程序?qū)ο蟆?shù)據(jù)庫記錄、算法等等。每一個資源用一個 URI 來唯一標識，客戶端通過這個標識對資源進行訪問、操作或請求服務(wù)。
表現(xiàn)層(Representation)表現(xiàn)層，是指資源的表現(xiàn)形式。
一個資源可以有多種表現(xiàn)形式。例如，文本數(shù)據(jù)可以用 XML 格式、JSON 格式表現(xiàn)，甚至可以用二進制格式表示；圖片可以用 JPG 格式表現(xiàn)，也可以用 PNG 格式表現(xiàn)。
狀態(tài)(State)狀態(tài)，是指資源的某種狀態(tài)。
一個資源可能有多種狀態(tài)。例如，資源空閑的、占用的、共享的、存在的、不存在的等。
轉(zhuǎn)化(Transfer)轉(zhuǎn)化，是指對資源的操作行為。
轉(zhuǎn)化的行為包括兩種:
資源表現(xiàn)層的轉(zhuǎn)化
資源狀態(tài)的轉(zhuǎn)化
ful后綴是英文的一種重要構(gòu)詞法，通過后綴常常可以判斷出一個詞的詞性。
ful 表形容詞，意為“... 的”、“具有 ... 的”。
小結(jié)RESTful 是一種抽象的、與具體程序語言和網(wǎng)絡(luò)協(xié)議無關(guān)的網(wǎng)絡(luò)服務(wù)系統(tǒng)的架構(gòu)樣式。
它把在服務(wù)器端的數(shù)據(jù)和功能設(shè)計成各種的資源，并且通過 URI 定位資源、轉(zhuǎn)化資源表現(xiàn)和狀態(tài)的一種服務(wù)架構(gòu)設(shè)計。
RESTful WEBREST 指的是一組架構(gòu)約束條件和原則。滿足這些約束條件和原則的應(yīng)用程序或設(shè)計就是 RESTful。
目前 RESTful 應(yīng)用最多的是在 web 服務(wù)，在 RESTful Web 服務(wù)中，每個資源都有一個地址(URL)。資源是方法調(diào)用的目標，方法列表對所有資源都是一樣的。這些方法是 Http 標準方法，如 HTTP GET、POST、PUT、DELETE 等。
下面來描述一下 RESTful Web API 的一些設(shè)計原則。
通信協(xié)議數(shù)據(jù)傳輸，安全第一。
HTTPS 協(xié)議要優(yōu)于 HTTP 協(xié)議。
API 的根 URLAPI 的根 URL 很重要，它應(yīng)該設(shè)計成可以輕松區(qū)別于其他非 API 的 URL。
最好的做法是將 API 部署在專有的域名下。
https://api.example.com
退而求其次，分配一個域名一級目錄給 API。
https://example.org/api/版本信息
為了 API 演變和兼容，為 API 加入版本信息是明智之舉。
應(yīng)該為 API 設(shè)定版本號，并把版本號信息加入到 API 的根 URL 的下一級路徑。
https://api.example.com/v1/
或
https://example.org/api/v1/URL 末端
API 的根 URL + 版本信息 + URL 末端 = 資源位置
URL 末端最終明確指定了一個資源或一種資源的集合。URL 末端中不應(yīng)該出現(xiàn)動詞，只能是名詞。如果該資源可以取其集合，對應(yīng)的名詞應(yīng)該采用復(fù)數(shù)形式。
舉個例子，有一組 API 提供公司員工的信息。
那么，獲取所有員工信息，末端應(yīng)該設(shè)計成 /employees, 即:
https://api.example.com/v1/employees
獲取員工編號 007 員工的信息，末端應(yīng)該設(shè)計成 /employees/007, 即:
https://api.example.com/v1/employees/007操作資源
資源的操作無外乎增、刪、改、查，對應(yīng)即是 HTTP 的各個操作方法。
HTTP的操作方法在 RESTful 中有各自的語義，理解它們的語義至為重要。
| 方法 | 語義 | 例子 | 說明 |
|---|---|---|---|
| GET | 選擇、獲取 | GET /employees/007 | 獲取編號 007 員工的信息 |
| POST | 新建 | POST /employees | 新建一個員工的信息 |
| PUT | 更新(完整) | PUT /employees/007 | 更新編號 007 員工的全部信息，客戶端提供該員工的全部信息 |
| PATCH | 更新(局部) | PATCH /employees/007 | 更新編號 007 員工的部分信息，客戶端只提供該員工的部分信息 |
| DELETE | 刪除 | DELETE /employees/007 | 刪除編號 007 員工的信息 |
| HEAD | 獲取(元數(shù)據(jù)) | HEAD /employees/007 | 獲取編號 007 員工的元數(shù)據(jù)，如員工數(shù)據(jù)的哈希值或最后修改時間 |
| OPTIONS | 獲取(權(quán)限信息) | OPTIONS /employees/007 | 獲取客戶端能編號 007 員工進行哪些操作，即操作的權(quán)限 |
本章中，自此以上講述的都是如何描述"資源(Resources)"，而這小節(jié)講述的是"轉(zhuǎn)化(Transfer)"，轉(zhuǎn)化資源的狀態(tài)。
另外，轉(zhuǎn)化還包括資源的"表現(xiàn)層(Representation)"，它是通過 HTTP 頭部 Content Type 指定的。
過濾資源如果資源很多，通常你不會希望服務(wù)端一次性全部的數(shù)據(jù)，API 應(yīng)該提供過濾資源的能力。
這里資源過濾依靠 URL 的查詢參數(shù)，通常放置在 GET 請求的URL中。
?limit=10: 限制返回的資源數(shù)量
?offset=10: 指定返回的資源的開始位置
?sortby=name&order=asc: 對資源按特定屬性進行排序
狀態(tài)碼狀態(tài)碼用以反映資源的操作結(jié)果或所處狀態(tài)。
HTTP 狀態(tài)碼本身是具有語義的，這剛好配對了 RESTful 的狀態(tài)。
以下列舉常用的狀態(tài)碼:
| 狀態(tài)碼 | 語義 | HTTP 方法 | 說明 |
|---|---|---|---|
| 200 | OK | GET | 成功返回用戶請求的數(shù)據(jù) |
| 201 | Created | POST/PUT/PATCH | 用戶新建或修改資源成功 |
| 202 | Accepted | * | 成功發(fā)起一個異步任務(wù) |
| 204 | No Content | DELETE | 刪除資源成功 |
| 400 | INVALID REQUEST | POST/PUT/PATCH | 請求有錯誤，服務(wù)端沒有對資源進行任何操作 |
| 401 | Unauthorized | * | 表示用戶沒有權(quán)限（令牌、用戶名、密碼錯誤） |
| 403 | Forbidden | * | 表示用戶得到授權(quán)（與401錯誤相對），但是訪問是被禁止的 |
| 404 | NOT FOUND | * | 請求對應(yīng)的資源不存在 |
| 406 | Not Acceptable | GET | 用戶請求的格式不可得（比如用戶請求JSON格式，但是只有XML格式）, 即未支持的表現(xiàn)層 |
| 410 | Gone | GET | 用戶請求的資源被永久刪除，且不會再得到的 |
| 422 | Unprocesable entity | POST/PUT/PATCH | 當(dāng)創(chuàng)建一個對象時，發(fā)生一個驗證錯誤 |
如果狀態(tài)碼是4xx，就應(yīng)該向用戶返回出錯信息。一般來說，返回的信息中將error作為鍵名，出錯信息作為鍵值。
{
error: "param error"
}
返回結(jié)果
對于不同操作方法和操作對象(集合或個體)，服務(wù)器返回的結(jié)果應(yīng)該符合以下規(guī)范。
| 示例 | 返回 |
|---|---|
| GET /collection | 返回資源對象的列表（數(shù)組） |
| GET /collection/resource | 返回單個資源對象 |
| POST /collection | 返回新生成的資源對象 |
| PUT /collection/resource | 返回完整的資源對象 |
| PATCH /collection/resource | 返回完整的資源對象 |
| DELETE /collection/resource | 返回一個空文檔 |
另外，返回的數(shù)據(jù)格式(Representation)應(yīng)該盡量使用JSON。
最后在 RESTful WEB 的實現(xiàn)中，使用 URL 定位資源，HTTP 方法操作資源，使得語義明確、結(jié)構(gòu)清晰、易于理解和擴展。
RESTful 的這些優(yōu)勢，使得它成為了目前最流行的一種互聯(lián)網(wǎng)服務(wù)架構(gòu)。
附錄該文主要參考:
Principles of good RESTful API Design
理解RESTful架構(gòu)
RESTful API 設(shè)計指南
文章版權(quán)歸作者所有，未經(jīng)允許請勿轉(zhuǎn)載,若此文章存在違規(guī)行為，您可以聯(lián)系管理員刪除。
轉(zhuǎn)載請注明本文地址：http://specialneedsforspecialkids.com/yun/66953.html
摘要：表形容詞，意為的具有的。指的是一組架構(gòu)約束條件和原則。協(xié)議要優(yōu)于協(xié)議。的操作方法在中有各自的語義，理解它們的語義至為重要。返回結(jié)果對于不同操作方法和操作對象集合或個體，服務(wù)器返回的結(jié)果應(yīng)該符合以下規(guī)范。附錄該文主要參考理解架構(gòu)設(shè)計指南 前言 近十年，前端高速發(fā)展，整個互聯(lián)網(wǎng)應(yīng)用經(jīng)歷了從輕客戶端到重客戶端的變化，隨著前端規(guī)模越來越大，交互越來越復(fù)雜，前后端分離的設(shè)計開始流行。 移動互聯(lián)網(wǎng)...
摘要：其他交互一般會遵循一些數(shù)據(jù)結(jié)構(gòu)協(xié)議或者狀態(tài)值，比如不同的操作結(jié)果對應(yīng)不同的狀態(tài)值，且出錯會返回指定的錯誤信息方便前端進行提示等。 RESTful這種架構(gòu)已經(jīng)具有很長的時間和歷程了，但似乎最近restful這個詞出現(xiàn)的頻率特別高，目前不是很清楚是因為我自個兒現(xiàn)在是以restful風(fēng)格寫程序產(chǎn)生的孕婦效應(yīng)，還是單頁面程序開發(fā)的流行造成的。 其實一開始我也是不想寫這篇文章的，因為網(wǎng)絡(luò)上與re...
摘要：它的理論比較抽象不太具體，理解它主要在于理解這些概念資源表現(xiàn)層狀態(tài)轉(zhuǎn)換。基于原則設(shè)計的，一般稱為，需要遵守以下這些原則。返回結(jié)果，結(jié)果應(yīng)該包括多種情況，異常錯誤信息正確結(jié)果目前而言最好使用格式傳輸數(shù)據(jù)。參考的理解，阮一峰 RESTful API 目前的異步加載橫行的時候，異步請求已經(jīng)遍地都是，而規(guī)定請求接口的時候，如果不能有很好的風(fēng)格的話，很多時候會讓開發(fā)者誤解，一個好的API接口 設(shè)...
showImg(https://segmentfault.com/img/bV6aHV?w=1280&h=800); 社區(qū)優(yōu)秀文章 Laravel 5.5+passport 放棄 dingo 開發(fā) API 實戰(zhàn)，讓 API 開發(fā)更省心 - 自造車輪。 API 文檔神器 Swagger 介紹及在 PHP 項目中使用 - API 文檔撰寫方案 推薦 Laravel API 項目必須使用的 8 個...
摘要：一什么是架構(gòu)即的縮寫，我們把他翻譯為表述性狀態(tài)傳遞，是博士在年他的博士論文中提出來的一種軟件架構(gòu)風(fēng)格。是個無狀態(tài)的協(xié)議，所以狀態(tài)就保存在服務(wù)器端。只要少量的數(shù)據(jù)就可使用，支持和。同時支持，同時提供一系列的查詢方法如。 一、什么是RESTful架構(gòu)？ REST即Representational State Transfer的縮寫，我們把他翻譯為表述性狀態(tài)傳遞，是Roy Fielding博...
閱讀 1571·2021-09-24 10:38
閱讀 1498·2021-09-22 15:15
閱讀 3059·2021-09-09 09:33
閱讀 905·2019-08-30 11:08
閱讀 638·2019-08-30 10:52
閱讀 1253·2019-08-30 10:52
閱讀 2344·2019-08-28 18:01
閱讀 520·2019-08-28 17:55
