作者 | zhanglinblog

責(zé)編 | 劉靜

出品 | CSDN 博客

面試官：了解RESTful嗎？

我：聽說過。

面試官：那什么是RESTful？

我：就是用起來很規(guī)范，挺好的

面試官：是RESTful挺好的，還是自我感覺挺好的

我：都挺好的。

前言

回歸正題，看過很多RESTful相關(guān)的文章總結(jié)，參齊不齊，結(jié)合工作中的使用，非常有必要?dú)w納一下關(guān)于RESTful架構(gòu)方式了，RESTful只是一種架構(gòu)方式的約束，給出一種約定的標(biāo)準(zhǔn)，完全嚴(yán)格遵守RESTful標(biāo)準(zhǔn)并不是很多，也沒有必要。但是在實(shí)際運(yùn)用中，有RESTful標(biāo)準(zhǔn)可以參考，是十分有必要的。

實(shí)際上在工作中對api接口規(guī)范、命名規(guī)則、返回值、授權(quán)驗(yàn)證等進(jìn)行一定的約束，一般的項(xiàng)目api只要易測試、足夠安全、風(fēng)格一致可讀性強(qiáng)、沒有歧義調(diào)用方便我覺得已經(jīng)足夠了，接口是給開發(fā)人員看的，也不是給普通用戶去調(diào)用。

RESTful的來源

REST：Representational State Transfer（表象層狀態(tài)轉(zhuǎn)變），如果沒聽說過REST，你一定以為是rest這個單詞，剛開始我也是這樣認(rèn)為的，后來發(fā)現(xiàn)是這三個單詞的縮寫，即使知道了這三個單詞理解起來仍然非常晦澀難懂。如何理解RESTful架構(gòu)，最好的辦法就是深刻理解消化Representational State Transfer這三個單詞到底意味著什么。

1.每一個URI代表一種資源；

2.客戶端和服務(wù)器之間，傳遞這種資源的某種表現(xiàn)層；

3.客戶端通過四個HTTP動詞（get、post、put、delete），對服務(wù)器端資源進(jìn)行操作，實(shí)現(xiàn)”表現(xiàn)層狀態(tài)轉(zhuǎn)化”。

是由美國計(jì)算機(jī)科學(xué)家Roy Fielding（百度百科沒有介紹，真是尷尬了）。Adobe首席科學(xué)家、Http協(xié)議的首要作者之一、Apache項(xiàng)目聯(lián)合創(chuàng)始人。

RESTful6大原則

REST之父Roy Fielding在論文中闡述REST架構(gòu)的6大原則。

1. C-S架構(gòu)

數(shù)據(jù)的存儲在Server端，Client端只需使用就行。兩端徹底分離的好處使client端代碼的可移植性變強(qiáng)，Server端的拓展性變強(qiáng)。兩端單獨(dú)開發(fā)，互不干擾。

2. 無狀態(tài)

http請求本身就是無狀態(tài)的，基于C-S架構(gòu)，客戶端的每一次請求帶有充分的信息能夠讓服務(wù)端識別。請求所需的一些信息都包含在URL的查詢參數(shù)、header、body，服務(wù)端能夠根據(jù)請求的各種參數(shù)，無需保存客戶端的狀態(tài)，將響應(yīng)正確返回給客戶端。無狀態(tài)的特征大大提高的服務(wù)端的健壯性和可拓展性。

當(dāng)然這總無狀態(tài)性的約束也是有缺點(diǎn)的，客戶端的每一次請求都必須帶上相同重復(fù)的信息確定自己的身份和狀態(tài)（這也是必須的），造成傳輸數(shù)據(jù)的冗余性，但這種確定對于性能和使用來說，幾乎是忽略不計(jì)的。

3.統(tǒng)一的接口

這個才是REST架構(gòu)的核心，統(tǒng)一的接口對于RESTful服務(wù)非常重要。客戶端只需要關(guān)注實(shí)現(xiàn)接口就可以，接口的可讀性加強(qiáng)，使用人員方便調(diào)用。

4.一致的數(shù)據(jù)格式

服務(wù)端返回的數(shù)據(jù)格式要么是XML，要么是Json（獲取數(shù)據(jù)），或者直接返回狀態(tài)碼，有興趣的可以看看博客園的開放平臺的操作數(shù)據(jù)的api，post、put、patch都是返回的一個狀態(tài)碼 。

自我描述的信息，每項(xiàng)數(shù)據(jù)應(yīng)該是可以自我描述的，方便代碼去處理和解析其中的內(nèi)容。比如通過HTTP返回的數(shù)據(jù)里面有 [MIME type ]信息，我們從MIME type里面可以知道數(shù)據(jù)的具體格式，是圖片，視頻還是JSON，客戶端通過body內(nèi)容、查詢串參數(shù)、請求頭和URI（資源名稱）來傳送狀態(tài)。服務(wù)端通過body內(nèi)容，響應(yīng)碼和響應(yīng)頭傳送狀態(tài)給客戶端。這項(xiàng)技術(shù)被稱為超媒體（或超文本鏈接）。

除了上述內(nèi)容外，HATEOS也意味著，必要的時候鏈接也可被包含在返回的body（或頭部）中，以提供URI來檢索對象本身或關(guān)聯(lián)對象。下文將對此進(jìn)行更詳細(xì)的闡述。

如請求一條微博信息，服務(wù)端響應(yīng)信息應(yīng)該包含這條微博相關(guān)的其他URL，客戶端可以進(jìn)一步利用這些URL發(fā)起請求獲取感興趣的信息，再如分頁可以從第一頁的返回?cái)?shù)據(jù)中獲取下一頁的URT也是基于這個原理。

4.系統(tǒng)分層

客戶端通常無法表明自己是直接還是間接與端服務(wù)器進(jìn)行連接，分層時同樣要考慮安全策略。

5.可緩存

在萬維網(wǎng)上，客戶端可以緩存頁面的響應(yīng)內(nèi)容。因此響應(yīng)都應(yīng)隱式或顯式的定義為可緩存的，若不可緩存則要避免客戶端在多次請求后用舊數(shù)據(jù)或臟數(shù)據(jù)來響應(yīng)。管理得當(dāng)?shù)木彺鏁糠值鼗蛲耆爻タ蛻舳撕头?wù)端之間的交互，進(jìn)一步改善性能和延展性。

6.按需編碼、可定制代碼（可選）

服務(wù)端可選擇臨時給客戶端下發(fā)一些功能代碼讓客戶端來執(zhí)行，從而定制和擴(kuò)展客戶端的某些功能。比如服務(wù)端可以返回一些 Java 代碼讓客戶端執(zhí)行，去實(shí)現(xiàn)某些特定的功能。

提示：REST架構(gòu)中的設(shè)計(jì)準(zhǔn)則中，只有按需編碼為可選項(xiàng)。如果某個服務(wù)違反了其他任意一項(xiàng)準(zhǔn)則，嚴(yán)格意思上不能稱之為RESTful風(fēng)格。

RESTful的7個最佳實(shí)踐

1. 版本

如github開放平臺

https://developer.github/v3/

就是將版本放在url，簡潔明了，這個只有用了才知道，一般的項(xiàng)目加版本v1，v2，v3?好吧，這個加版本估計(jì)只有大公司大項(xiàng)目才會去使用，說出來不怕尷尬，我真沒用過。有的會將版本號放在header里面，但是不如url直接了當(dāng)。

https:/ /example/api/v1/

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

query parameter可以采用駝峰命名法，也可以采用下劃線命名的方式，推薦采用下劃線命名的方式，據(jù)說后者比前者的識別度要高，可能是用的人多了吧，因人而異，因團(tuán)隊(duì)規(guī)范而異吧。

https:/ /example/api/users/today_login 獲取今天登陸的用戶

https:/ /example/api/users/today_login&sort=login_desc 獲取今天登陸的用戶、登陸時間降序排列

3.url命名規(guī)范

API 命名應(yīng)該采用約定俗成的方式，保持簡潔明了。在RESTful架構(gòu)中，每個url代表一種資源所以url中不能有動詞，只能有名詞，并且名詞中也應(yīng)該使用復(fù)數(shù)。實(shí)現(xiàn)者應(yīng)使用相應(yīng)的Http動詞GET、POST、PUT、PATCH、DELETE、HEAD來操作這些資源即可

不規(guī)范的的url，冗余沒有意義，形式不固定，不同的開發(fā)者還需要了解文檔才能調(diào)用。

https: //example/api/getallUsers GET 獲取所有用戶

https: //example/api/getuser/1 GET 獲取標(biāo)識為1用戶信息

https: //example/api/user/delete/1 GET/POST 刪除標(biāo)識為1用戶信息

https: //example/api/updateUser/1 POST 更新標(biāo)識為1用戶信息

https: //example/api/User/add POST 添加新的用戶

規(guī)范后的RESTful風(fēng)格的url，形式固定，可讀性強(qiáng)，根據(jù)users名詞和http動詞就可以操作這些資源

https: //example/api/users GET 獲取所有用戶信息

https: //example/api/users/1 GET 獲取標(biāo)識為1用戶信息

https: //example/api/users/1 DELETE 刪除標(biāo)識為1用戶信息

https: //example/api/users/1 Patch 更新標(biāo)識為1用戶部分信息,包含在body中

https: //example/api/users POST 添加新的用戶

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

對于合法的請求應(yīng)該統(tǒng)一返回?cái)?shù)據(jù)格式，這里演示的是json

• code——包含一個整數(shù)類型的HTTP響應(yīng)狀態(tài)碼；
• status——包含文本：”success”，”fail”或”error”。HTTP狀態(tài)響應(yīng)碼在500-599之間為”fail”，在400-499之間為”error”，其它均為”success”（例如：響應(yīng)狀態(tài)碼為1XX、2XX和3XX）。這個根據(jù)實(shí)際情況其實(shí)是可要可不要的；
• message——當(dāng)狀態(tài)值為”fail”和”error”時有效，用于顯示錯誤信息。參照國際化（il8n）標(biāo)準(zhǔn)，它可以包含信息號或者編碼，可以只包含其中一個，或者同時包含并用分隔符隔開；
• data——包含響應(yīng)的body。當(dāng)狀態(tài)值為”fail”或”error”時，data僅包含錯誤原因或異常名稱、或者null也是可以的

返回成功的響應(yīng)json格式

{

"code": 200,

"message": "success",

"data": {

"userName": "123456",

"age": 16,

"address": "beijing"

}

}

返回失敗的響應(yīng)json格式

{

"code": 401,

"message": "error message",

"data": null

}

下面這個ApiResult的泛型類是在項(xiàng)目中用到的，拓展性強(qiáng)，使用方便。返回值使用統(tǒng)一的 ApiResult 或 ApiResult

錯誤返回 使用 ApiResult.Error 進(jìn)行返回；成功返回，要求使用 ApiResult.Ok 進(jìn)行返回

publicclassApiResult: ApiResult

{

publicnew staticApiResult<T> Error(stringmessage)

{

returnnewApiResult<T>

{

Code = 1,

Message = message,

};

}

[ JsonProperty("data")]

publicT Data { get; set; }

}

publicclassApiResult

{

publicstaticApiResult Error(stringmessage)

{

returnnewApiResult

{

Code = 1,

Message = message,

};

}

publicstaticApiResult<T> Ok<T>(T data)

{

returnnewApiResult<T>

{

Code = 0,

Message = "",

Data = data

};

}

///<summary>

///0 是 正常 1 是有錯誤

///</summary>

[ JsonProperty("code")]

publicintCode { get; set; }

[ JsonProperty("msg")]

publicstringMessage { get; set; }

[ JsonIgnore]

publicboolIsSuccess => Code == 0;

}

5. http狀態(tài)碼

在之前開發(fā)的xamarin android博客園客戶端的時候，patch、delete、post操作時body響應(yīng)里面沒有任何信息，僅僅只有http status code。HTTP狀態(tài)碼本身就有足夠的含義，根據(jù)http status code就可以知道刪除、添加、修改等是否成功。(ps:有點(diǎn)linux設(shè)計(jì)的味道哦，沒有返回消息就是最好的消息，表示已經(jīng)成功了)服務(wù)段向用戶返回這些狀態(tài)碼并不是一個強(qiáng)制性的約束。簡單點(diǎn)說你可以指定這些狀態(tài)，但是不是強(qiáng)制的。常用HTTP狀態(tài)碼對照表

HTTP狀態(tài)碼也是有規(guī)律的

• 1**請求未成功；
• 2**請求成功、表示成功處理了請求的狀態(tài)代碼；
• 3**請求被重定向、表示要完成請求，需要進(jìn)一步操作。通常，這些狀態(tài)代碼用來重定向；
• 4** 請求錯誤這些狀態(tài)代碼表示請求可能出錯，妨礙了服務(wù)器的處理；
• 5**（服務(wù)器錯誤）這些狀態(tài)代碼表示服務(wù)器在嘗試處理請求時發(fā)生內(nèi)部錯誤。這些錯誤可能是服務(wù)器本身的錯誤，而不是請求出錯。

6. 合理使用query parameter

在請求數(shù)據(jù)時，客戶端經(jīng)常會對數(shù)據(jù)進(jìn)行過濾和分頁等要求，而這些參數(shù)推薦采用HTTP Query Parameter的方式實(shí)現(xiàn)

比如設(shè)計(jì)一個最近登陸的所有用戶

https: //example/api/users?recently_login_day=3

搜索用戶，并按照注冊時間降序

https: //example/api/users?recently_login_day=3

搜索用戶，并按照注冊時間升序、活躍度降序

https: //example/api/users?q=key&sort=create_title_asc,liveness_desc

關(guān)于分頁，看看博客園開放平臺分頁獲取精華區(qū)博文列表

關(guān)于分頁，看看博客園開放平臺分頁獲取精華區(qū)博文列表

https://apiblogs/api/blogposts/@picked?pageIndex={pageIndex}&pageSize={pageSize}

返回示例：

[

{

“Id”: 1,

“Title”: “sample string 2”,

“Url”: “sample string 3”,

“Deion”: “sample string 4”,

“Author”: “sample string 5”,

“BlogApp”: “sample string 6”,

“Avatar”: “sample string 7”,

“PostDate”: “2017-06-25T20:13:38.892135+08:00”,

“ViewCount”: 9,

“CommentCount”: 10,

“DiggCount”: 11

},

{

“Id”: 1,

“Title”: “sample string 2”,

“Url”: “sample string 3”,

“Deion”: “sample string 4”,

“Author”: “sample string 5”,

“BlogApp”: “sample string 6”,

“Avatar”: “sample string 7”,

“PostDate”: “2017-06-25T20:13:38.892135+08:00”,

“ViewCount”: 9,

“CommentCount”: 10,

“DiggCount”: 11

}

]

7. 多表、多參數(shù)連接查詢?nèi)绾卧O(shè)計(jì)URL

這是一個比較頭痛的問題，在做單個實(shí)體的查詢比較容易和規(guī)范操作，但是在實(shí)際的API并不是這么簡單而已，這其中常常會設(shè)計(jì)到多表連接、多條件篩選、排序等。

比如我想查詢一個獲取在6月份的訂單中大于500元的且用戶地址是北京，用戶年齡在22歲到40歲、購買金額降序排列的訂單列表

https: //example/api/orders?order_month=6&order_amount_greater=500&address_city=北京&sort=order_amount_desc&age_min=22&age_max=40

從這個URL上看，參數(shù)眾多、調(diào)用起來還得一個一個仔細(xì)對著，而且API本身非常不容易維護(hù)，命名看起來不是很容易，不能太長，也不能太隨意。

在 WebAPI總我們可以使用屬性路由，屬性路由就是講路由附加到特定的控制器或操作方法上裝飾Controll及其使用[Route]屬性定義路由的方法稱為屬性路由。

這種好處就是可以精準(zhǔn)地控制URL，而不是基于約定的路由，簡直就是為這種多表查詢量身定制似的的。從webapi 2開發(fā)，現(xiàn)在是RESTful API開發(fā)中最推薦的路由類型。

我們可以在Controll中標(biāo)記Route

[Route(“api /orders/{address}/{month}”)]

Action中的查詢參數(shù)就只有金額、排序、年齡。減少了查詢參數(shù)、API的可讀性和可維護(hù)行增強(qiáng)了。

https: //example/api/orders/beijing/6?order_amount_greater=500&sort=order_amount_desc&age_min=22&age_max=40

這種屬性路由比如在博客園開放的API也有這方面的應(yīng)用，如獲取個人博客隨筆列表

請求方式：GET

請求地址：https://apiblogs/api/blogs/{blogApp}/posts?pageIndex={pageIndex}

(ps:blogApp：博客名)

版權(quán)聲明：本文為CSDN博主「zhanglinblog」的原創(chuàng)文章，版權(quán)歸作者所有。

技術(shù)的道路一個人走著極為艱難？

一身的本領(lǐng)得不施展？

優(yōu)質(zhì)的文章得不到曝光？

別擔(dān)心，

即刻起，CSDN 將為你帶來創(chuàng)新創(chuàng)造創(chuàng)變展現(xiàn)的大舞臺，

歡迎加入 CSDN 「原力計(jì)劃」！

網(wǎng)易回應(yīng)裁撤生病員工；蘋果押寶 5G 手機(jī)；IntelliJ IDEA 2019.3 RC 發(fā)布 | 極客頭條

Google 是如何做 Code Review 的？| 原力計(jì)劃