簡(jiǎn)單說(shuō)一下代碼重用

　　記得在Ken Rogers的Medium博客里曾經(jīng)見過(guò)這么一句話（原文出自海明威）：

　　我們都是手藝學(xué)徒，沒(méi)有人會(huì)成為大師。

　　在我寫這篇文章的時(shí)候，我不禁笑了起來(lái)，因?yàn)閺倪@件事情的背后看到了一個(gè)偉大的類比，那就是從其他人那里引用了海明威的話。也就是說(shuō)，我不需要為了得到類似的功能和結(jié)果而花費(fèi)精力自己去創(chuàng)建一個(gè)與眾不同的東西，上面提到的海明威的話正是代碼重用在文學(xué)上的例子。

　　但是，我在這里不會(huì)寫代碼包的好處，而是更多地提一些我的感受，這些感受會(huì)在當(dāng)前以及未來(lái)的項(xiàng)目中積極地得到實(shí)現(xiàn)。我還總結(jié)了一套API規(guī)則和原語(yǔ)，包括了功能和實(shí)現(xiàn)細(xì)節(jié)。

　　使用API版本控制

　　如果你要開發(fā)一個(gè)提供客戶端服務(wù)的API，你需要為最后可能的修改而做好準(zhǔn)備。最好的辦法就是通過(guò)為RESTful API提供“版本命名空間”來(lái)實(shí)現(xiàn)。

　　我們只需將版本號(hào)作為前綴添加到所有的URL里即可。

　　然而，在我研究了其他的API實(shí)現(xiàn)之后發(fā)現(xiàn)，我喜歡上了這種較短的URL樣式，它把a(bǔ)pi作為是子域名的一部分，并從路由中刪除了/api，這樣更短、更簡(jiǎn)潔。

　　跨域資源共享（CORS）

　　需要重點(diǎn)關(guān)注的是，如果你打算在www.myservice.com上托管你的前端站點(diǎn)，而將API放在另外一個(gè)不同的子域上，例如api.myservice.com，那么你需要在后端實(shí)現(xiàn)CORS，這樣才能使得AJAX調(diào)用不會(huì)拋出這樣的錯(cuò)誤。

　　使用復(fù)數(shù)形式

　　當(dāng)你從/posts請(qǐng)求多個(gè)帖子的時(shí)候，這樣的URL看起來(lái)更明了：

　　更多有關(guān)混合類型的信息，請(qǐng)看下文：“使用根級(jí)別的‘me’端點(diǎn)（URL）”。

　　避免查詢字符串

　　查詢字符串的作用是對(duì)關(guān)系數(shù)據(jù)庫(kù)返回的記錄集做進(jìn)一步地過(guò)濾。

　　更多信息請(qǐng)看下文：“避免對(duì)嵌套路由的操作”。

　　使用HTTP方法

　　我們可使用下面這些HTTP方法：

　　GET 用于獲取數(shù)據(jù)。

　　POST 用于添加數(shù)據(jù)。

　　PUT 用于更新數(shù)據(jù)（整個(gè)對(duì)象）。

　　PATCH 用于更新數(shù)據(jù)（附帶對(duì)象的部分信息）。

　　DELETE 用于刪除數(shù)據(jù)。

　　補(bǔ)充一點(diǎn)，對(duì)于修改對(duì)象的部分內(nèi)容的請(qǐng)求來(lái)說(shuō)，我認(rèn)為PATCH是減少請(qǐng)求包大小的一個(gè)好的方法，并且它也能很好的跟自動(dòng)提交/自動(dòng)保存字段配合起來(lái)用。

　　一個(gè)很好的例子是Tumblr的“儀表盤設(shè)置”屏幕，其中，“服務(wù)的用戶體驗(yàn)”的一些非關(guān)鍵性選項(xiàng)可以單獨(dú)地編輯和保存，而不需要點(diǎn)最下面的提交按鈕。

　　對(duì)于POST，PUT或PATCH的成功響應(yīng)消息，應(yīng)該返回更新后的對(duì)象，而不是只返回一個(gè)null。

　　有關(guān)響應(yīng)的其他內(nèi)容，請(qǐng)閱讀下文：“JSON格式的響應(yīng)和請(qǐng)求”。

　　使用封包

　　“我不喜歡數(shù)據(jù)封包。它只是引入了另一個(gè)鍵來(lái)瀏覽數(shù)據(jù)樹。元信息應(yīng)該包含在包頭中。”

　　最初，我堅(jiān)持認(rèn)為封包數(shù)據(jù)是不必要的，HTTP協(xié)議已經(jīng)提供了足夠的“封包”來(lái)傳遞響應(yīng)消息。

　　然而，根據(jù)Reddit上的回復(fù)所述，如果不封包為JSON數(shù)組，則可能會(huì)出現(xiàn)各種漏洞和潛在的黑客攻擊。

　　現(xiàn)在建議使用封包，你應(yīng)該把數(shù)據(jù)封包后再應(yīng)答！

　　同樣要重點(diǎn)關(guān)注的是，不像其他語(yǔ)言那樣，Java之類的語(yǔ)言將會(huì)將空對(duì)象認(rèn)為是true！ 因此，在下面這種情況下，不要返回空的對(duì)象來(lái)作為響應(yīng)的一部分：

　　JSON格式的響應(yīng)和請(qǐng)求

　　所有東西都應(yīng)該被序列化成JSON。如果你期待從服務(wù)器上獲取JSON格式的數(shù)據(jù)，那么請(qǐng)客氣一點(diǎn)，請(qǐng)發(fā)送JSON格式的內(nèi)容給服務(wù)器。請(qǐng)兩邊保持一致！

　　某些情況下，如果動(dòng)作執(zhí)行成功（例如DELETE），那我并沒(méi)有什么需要返回的。但是，在某些語(yǔ)言（如Python）中返回一個(gè)空對(duì)象可能被認(rèn)為是false，并且在開發(fā)人員調(diào)試程序的時(shí)候，這種情況并不容易發(fā)現(xiàn)。因此，我喜歡返回“OK”，盡管這是一個(gè)字符串，但是在返回的時(shí)候會(huì)被包裝成一個(gè)簡(jiǎn)單的響應(yīng)對(duì)象。

　　使用HTTP狀態(tài)碼和錯(cuò)誤響應(yīng)

　　因?yàn)槲覀兪褂昧薍TTP方法，所以我們應(yīng)當(dāng)使用HTTP狀態(tài)碼。

　　我喜歡使用這些狀態(tài)碼：

　　對(duì)于數(shù)據(jù)錯(cuò)誤

　　400：請(qǐng)求信息不完整或無(wú)法解析。

　　422：請(qǐng)求信息完整，但無(wú)效。

　　404：資源不存在。

　　409：資源沖突。

　　對(duì)于鑒權(quán)錯(cuò)誤

　　401：訪問(wèn)令牌沒(méi)有提供，或者無(wú)效。

　　403：訪問(wèn)令牌有效，但沒(méi)有權(quán)限。

　　對(duì)于標(biāo)準(zhǔn)狀態(tài)

　　200： 所有的都正確。

　　500： 服務(wù)器內(nèi)部拋出錯(cuò)誤。

　　假設(shè)要?jiǎng)?chuàng)建一個(gè)新帳戶，我們提供了email和password兩個(gè)值。我們希望讓客戶端應(yīng)用程序能夠阻止任何無(wú)效的電子郵件或密碼太短的請(qǐng)求，但外部人員可以像我們的客戶端應(yīng)用程序一樣在需要的時(shí)候直接訪問(wèn)API。

　　如果email字段丟失，則返回400。

　　如果password字段太短，則返回422。

　　如果email字段不是有效的電子郵件，則返回422。

　　如果email已經(jīng)被使用，返回一個(gè)409。

　　從上面這些情況來(lái)看，有兩個(gè)錯(cuò)誤會(huì)返回422，不過(guò)他們的原因是不同的。這就是為什么我們需要一個(gè)錯(cuò)誤碼，甚至是一個(gè)錯(cuò)誤描述。要區(qū)分代碼和描述，我打算將error（代碼）作為機(jī)器可識(shí)別的常量，將deion作為可更改的用于人類識(shí)別的字符串。