欧美成人精品手机在线观看_69视频国产_动漫精品第一页_日韩中文字幕网 - 日本欧美一区二区

RESTful是目前最流行的API設(shè)計(jì)規(guī)范，它是用于Web數(shù)據(jù)接口的設(shè)計(jì)。從字面可以看出，他是Rest式的接口，所以我們先了解下什么是Rest。

REST與技術(shù)無(wú)關(guān)，它代表的是一種軟件架構(gòu)風(fēng)格，REST它是 Representational State Transfer的簡(jiǎn)稱(chēng)，中文的含義是: "表征狀態(tài)轉(zhuǎn)移" 或 "表現(xiàn)層狀態(tài)轉(zhuǎn)化"。它是基于HTTP、URI、XML、JSON等標(biāo)準(zhǔn)和協(xié)議，支持輕量級(jí)、跨平臺(tái)、跨語(yǔ)言的架構(gòu)設(shè)計(jì)。

一.理解為什么要使用RESTful API設(shè)計(jì)規(guī)范？

在很久以前，工作時(shí)間長(zhǎng)的同學(xué)肯定經(jīng)歷過(guò)使用velocity語(yǔ)法來(lái)編寫(xiě)html模板代碼，也就是說(shuō)我們的前端頁(yè)面放在服務(wù)器端那邊進(jìn)行編譯的，更準(zhǔn)確的可以理解為 "前后端沒(méi)有進(jìn)行分離"，那么在那個(gè)時(shí)候，頁(yè)面、數(shù)據(jù)及模板渲染操作都是放在服務(wù)器端進(jìn)行的，但是這樣做有一個(gè)很大的缺點(diǎn)是: 后期維護(hù)比較麻煩，前端開(kāi)發(fā)人員還必須掌握velocity相關(guān)的語(yǔ)法。因此為了解決這個(gè)問(wèn)題慢慢就出現(xiàn)了前后端分離的思想: 即后端負(fù)責(zé)數(shù)據(jù)接口, 前端負(fù)責(zé)數(shù)據(jù)渲染, 前端只需要請(qǐng)求下api接口拿到數(shù)據(jù)，然后再將數(shù)據(jù)顯示出來(lái)。因此后端開(kāi)發(fā)人員需要設(shè)計(jì)api接口，因此為了統(tǒng)一規(guī)范: 社區(qū)就出現(xiàn)了 RESTful API 規(guī)范，其實(shí)該規(guī)范很早就有的，只是最近慢慢流行起來(lái)，RESTful API 可以通過(guò)一套統(tǒng)一的接口為所有web相關(guān)提供服務(wù)，實(shí)現(xiàn)前后端分離。

二.Rest設(shè)計(jì)原則

那么怎么樣可以設(shè)計(jì)成REST的架構(gòu)規(guī)范呢? 需要符合如下的一些原則：

• 每一個(gè)URI代表一種資源；
• 同一種資源有多種表現(xiàn)形式(xml/json)；
• 所有的操作都是無(wú)狀態(tài)的；
• 規(guī)范統(tǒng)一接口；
• 返回一致的數(shù)據(jù)格式；
• 可緩存(客戶(hù)端可以緩存響應(yīng)的內(nèi)容)。

符合上述REST原則的架構(gòu)方式被稱(chēng)作為 RESTful 規(guī)范。

理解為什么所有的操作需要無(wú)狀態(tài)呢?

http請(qǐng)求本身是無(wú)狀態(tài)的，它是基于 client-server 架構(gòu)的，客戶(hù)端向服務(wù)器端發(fā)的每一次請(qǐng)求都必須帶有充分的信息能夠讓服務(wù)器端識(shí)別到，請(qǐng)求的一些信息通常會(huì)包含在URL的查詢(xún)參數(shù)中或header中，服務(wù)器端能夠根據(jù)請(qǐng)求的各種參數(shù), 不需要保存客戶(hù)端的狀態(tài), 直接將數(shù)據(jù)返回給客戶(hù)端。無(wú)狀態(tài)的優(yōu)點(diǎn)是：可以大大提高服務(wù)器端的健狀性和可擴(kuò)展性。客戶(hù)端可以通過(guò)token來(lái)標(biāo)識(shí)會(huì)話(huà)狀態(tài)。從而可以讓該用戶(hù)一直保持登錄狀態(tài)。

理解規(guī)范統(tǒng)一的接口

Rest接口約束定義為: 資源識(shí)別；請(qǐng)求動(dòng)作；響應(yīng)信息; 它表示通過(guò)uri表示出要操作的資源，通過(guò)請(qǐng)求動(dòng)作(http method)標(biāo)識(shí)要執(zhí)行的操作，通過(guò)返回的狀態(tài)碼來(lái)表示這次請(qǐng)求的執(zhí)行結(jié)果。

可能看上面的解釋還不夠理解，下面我通過(guò)自己的理解來(lái)解釋下上面的具體含義; 比如說(shuō)，我在未使用Rest規(guī)范之前，我們可能有 增刪改查 等接口，因此我們會(huì)設(shè)計(jì)出類(lèi)似這樣的接口: /xxx/newAdd (新增接口), /xxx/delete(刪除接口), /xxx/query (查詢(xún)接口), /xxx/uddate(修改接口)等這樣的。增刪改查有四個(gè)不同的接口，維護(hù)起來(lái)可能也不好，因此如果我們現(xiàn)在使用Restful規(guī)范來(lái)做的話(huà)，對(duì)于開(kāi)發(fā)設(shè)計(jì)來(lái)說(shuō)可能就只需要一個(gè)接口就可以了，比如設(shè)計(jì)該接口為 /xxx/apis 這樣的一個(gè)接口就可以了，然后請(qǐng)求方式(method)有 GET--查詢(xún)(從服務(wù)器獲取資源); POST---新增(從服務(wù)器中新建一個(gè)資源); PUT---更新(在服務(wù)器中更新資源)，delete---刪除(從服務(wù)器刪除資源)，PATCH---部分更新(從服務(wù)器端更新部分資源) 等這些方式來(lái)做，也就是說(shuō)我們使用RESTful規(guī)范后，我們的接口就變成了一個(gè)了，要執(zhí)行增刪改查操作的話(huà)，我們只需要使用不同的請(qǐng)求動(dòng)作(http method)方式來(lái)做就可以了，然后服務(wù)器端返回的數(shù)據(jù)也可以是相同的，只是我們前端會(huì)根據(jù)狀態(tài)碼來(lái)判斷請(qǐng)求成功或失敗的狀態(tài)值來(lái)判斷。具體有那些狀態(tài)碼我們下面會(huì)講解到。

理解返回一致的數(shù)據(jù)格式

服務(wù)器端返回的數(shù)據(jù)格式可以是XML、或json. 或者直接返回狀態(tài)碼的方式。比如返回錯(cuò)誤的格式j(luò)son數(shù)據(jù)如下：

{
    "code": 401,
    "status": "error",
    "message": '用戶(hù)沒(méi)有權(quán)限',
    "data": null
}

返回正確的數(shù)據(jù)格式的json數(shù)據(jù)一般可以為如下：

{
    "code": 200,
    "status": "success",
    "data": [{
        "userName": "tugenhua",
        "age": 31
    }]
}

三. URL及參數(shù)設(shè)計(jì)規(guī)范

uri設(shè)計(jì)規(guī)范

1. uri末尾不需要出現(xiàn)斜杠/
2. 在uri中使用斜杠/是表達(dá)層級(jí)關(guān)系的。
3. 在uri中可以使用連接符-, 來(lái)提升可讀性。

比如 xxx.com/xx-yy 比 xxx.com/xx_yy中的可讀性更…
4) 在uri中不允許出現(xiàn)下劃線(xiàn)字符_.
5) 在uri中盡量使用小寫(xiě)字符。
6) 在uri中不允許出現(xiàn)文件擴(kuò)展名. 比如接口為 /xxx/api, 不要寫(xiě)成 /xxx/api.php 這樣的是不合法的。
7) 在uri中使用復(fù)數(shù)形式。
具體可以看：（https://blog.restcase.com/7-rules-for-rest-api-uri-design/）

在RESTful架構(gòu)中，每個(gè)uri代表一種資源，因此uri設(shè)計(jì)中不能使用動(dòng)詞，只能使用名詞，并且名詞中也應(yīng)該盡量使用復(fù)數(shù)形式。使用者應(yīng)該使用相應(yīng)的http動(dòng)詞 GET、POST、PUT、PATCH、delete等操作這些資源即可。

那么在我們未使用RESTful規(guī)范之前，我們是如下方式來(lái)定義接口的，形式是不固定的，并且沒(méi)有統(tǒng)一的規(guī)范。比如如下形式:

http://xxx.com/api/getallUsers; // GET請(qǐng)求方式，獲取所有的用戶(hù)信息
http://xxx.com/api/getuser/1;   // GET請(qǐng)求方式，獲取標(biāo)識(shí)為1的用戶(hù)信息
http://xxx.com/api/user/delete/1 // GET、POST 刪除標(biāo)識(shí)為1的用戶(hù)信息
http://xxx.com/api/updateUser/1  // POST請(qǐng)求方式 更新標(biāo)識(shí)為1的用戶(hù)信息
http://xxx.com/api/User/add      // POST請(qǐng)求方式，添加新的用戶(hù)

如上我們可以看到，在未使用Restful規(guī)范之前，接口形式是不固定的，沒(méi)有統(tǒng)一的規(guī)范，下面我們來(lái)看下使用RESTful規(guī)范的接口如下，兩者之間對(duì)比下就可以看到各自的優(yōu)點(diǎn)了。

http://xxx.com/api/users;     // GET請(qǐng)求方式 獲取所有用戶(hù)信息
http://xxx.com/api/users/1;   // GET請(qǐng)求方式 獲取標(biāo)識(shí)為1的用戶(hù)信息
http://xxx.com/api/users/1;   // delete請(qǐng)求方式 刪除標(biāo)識(shí)為1的用戶(hù)信息
http://xxx.com/api/users/1;   // PATCH請(qǐng)求方式，更新標(biāo)識(shí)為1的用戶(hù)部分信息
http://xxx.com/api/users;     // POST請(qǐng)求方式 添加新的用戶(hù)

如上我們可以看到，增刪改成我們都是使用同一個(gè)api接口，只是請(qǐng)求的方式 GET(查詢(xún))、POST(新增)、delete(刪除)、PACTH(部分更新)來(lái)代表的是增刪改查操作的方式。然后開(kāi)發(fā)獲取到該請(qǐng)求的header頭部信息，就可以知道是什么方式來(lái)請(qǐng)求數(shù)據(jù)的了。

HTTP請(qǐng)求規(guī)范

GET (select): 查詢(xún)；從服務(wù)器取出資源.
POST(create): 新增; 在服務(wù)器上新建一個(gè)資源。
PUT(update): 更新; 在服務(wù)器上更新資源(客戶(hù)端提供改變后的完整資源)。
PATCH(update): 更新；在服務(wù)器上更新部分資源(客戶(hù)端提供改變的屬性)。
delete(delete): 刪除; 從服務(wù)器上刪除資源。

參數(shù)命名規(guī)范

參數(shù)推薦采用下劃線(xiàn)命名的方式。比如如下demo:

http://xxx.com/api/today_login // 獲取今天登錄的用戶(hù)。
http://xxx.com/api/today_login&sort=login_desc // 獲取今天登錄的用戶(hù)、登錄時(shí)間降序排序。

四. http狀態(tài)碼相關(guān)的

狀態(tài)碼范圍

客戶(hù)端的每一次請(qǐng)求, 服務(wù)器端必須給出回應(yīng)，回應(yīng)一般包括HTTP狀態(tài)碼和數(shù)據(jù)兩部分。

1xx: 信息，請(qǐng)求收到了，繼續(xù)處理。
2xx: 代表成功. 行為被成功地接收、理解及采納。
3xx: 重定向。
4xx: 客戶(hù)端錯(cuò)誤，請(qǐng)求包含語(yǔ)法錯(cuò)誤或請(qǐng)求無(wú)法實(shí)現(xiàn)。
5xx: 服務(wù)器端錯(cuò)誤.

2xx 狀態(tài)碼

200 OK [GET]: 服務(wù)器端成功返回用戶(hù)請(qǐng)求的數(shù)據(jù)。
201 createD [POST/PUT/PATCH]: 用戶(hù)新建或修改數(shù)據(jù)成功。
202 Accepted 表示一個(gè)請(qǐng)求已經(jīng)進(jìn)入后臺(tái)排隊(duì)(一般是異步任務(wù))。
204 NO CONTENT -[delete]: 用戶(hù)刪除數(shù)據(jù)成功。

4xx狀態(tài)碼

400：Bad Request - [POST/PUT/PATCH]: 用戶(hù)發(fā)出的請(qǐng)求有錯(cuò)誤，服務(wù)器不理解客戶(hù)端的請(qǐng)求，未做任何處理。
401: Unauthorized; 表示用戶(hù)沒(méi)有權(quán)限(令牌、用戶(hù)名、密碼錯(cuò)誤)。
403：Forbidden: 表示用戶(hù)得到授權(quán)了，但是訪(fǎng)問(wèn)被禁止了, 也可以理解為不具有訪(fǎng)問(wèn)資源的權(quán)限。
404：Not Found: 所請(qǐng)求的資源不存在，或不可用。
405：Method Not Allowed: 用戶(hù)已經(jīng)通過(guò)了身份驗(yàn)證, 但是所用的HTTP方法不在它的權(quán)限之內(nèi)。
406：Not Acceptable: 用戶(hù)的請(qǐng)求的格式不可得(比如用戶(hù)請(qǐng)求的是JSON格式，但是只有XML格式)。
410：Gone - [GET]: 用戶(hù)請(qǐng)求的資源被轉(zhuǎn)移或被刪除。且不會(huì)再得到的。
415: Unsupported Media Type: 客戶(hù)端要求的返回格式不支持，比如，API只能返回JSON格式，但是客戶(hù)端要求返回XML格式。
422：Unprocessable Entity: 客戶(hù)端上傳的附件無(wú)法處理，導(dǎo)致請(qǐng)求失敗。
429：Too Many Requests: 客戶(hù)端的請(qǐng)求次數(shù)超過(guò)限額。

5xx 狀態(tài)碼

5xx 狀態(tài)碼表示服務(wù)器端錯(cuò)誤。

500：INTERNAL SERVER ERROR; 服務(wù)器發(fā)生錯(cuò)誤。
502：網(wǎng)關(guān)錯(cuò)誤。
503: Service Unavailable 服務(wù)器端當(dāng)前無(wú)法處理請(qǐng)求。
504：網(wǎng)關(guān)超時(shí)。

五. 統(tǒng)一返回?cái)?shù)據(jù)格式

RESTful規(guī)范中的請(qǐng)求應(yīng)該返回統(tǒng)一的數(shù)據(jù)格式。對(duì)于返回的數(shù)據(jù)，一般會(huì)包含如下字段:

1. code: http響應(yīng)的狀態(tài)碼。
2. status: 包含文本, 比如：'success'(成功), 'fail'(失敗), 'error'(異常) HTTP狀態(tài)響應(yīng)碼在500-599之間為 'fail'; 在400-499之間為 'error', 其他一般都為 'success'。 對(duì)于響應(yīng)狀態(tài)碼為 1xx, 2xx, 3xx 這樣的可以根據(jù)實(shí)際情況可要可不要。

當(dāng)status的值為 'fail' 或 'error'時(shí)，需要添加 message 字段，用于顯示錯(cuò)誤信息。

3. data: 當(dāng)請(qǐng)求成功的時(shí)候, 返回的數(shù)據(jù)信息。 但是當(dāng)狀態(tài)值為 'fail' 或 'error' 時(shí)，data僅僅包含錯(cuò)誤原因或異常信息等。

返回成功的響應(yīng)JSON格式一般為如下:

{
    "code": 200,
    "status": "success",
    "data": [{
        "userName": "tugenhua",
        "age": 31
    }]
}

返回失敗的響應(yīng)json格式為如下:

{
    "code": 401,
    "status": "error",
    "message": '用戶(hù)沒(méi)有權(quán)限',
    "data": null
}