Part1介紹

RESTFull 接口設(shè)計(jì)目前廣泛應(yīng)用于各種軟件系統(tǒng)中，特別是前后端分離架構(gòu)的web應(yīng)用。相信各位web應(yīng)用的開發(fā)者對(duì)這個(gè)概念并不陌生，但是我們經(jīng)常會(huì)遇到幾個(gè)這樣的疑惑或者問(wèn)題：

1. 為什么這個(gè)接口只設(shè)計(jì)了GET和POST兩種請(qǐng)求類型？
2. 為什么這個(gè)接口無(wú)論是否請(qǐng)求成功，HTTP狀態(tài)碼永遠(yuǎn)只會(huì)是200?
3. 當(dāng)一個(gè)查詢的結(jié)果為空的時(shí)候，為什么有的接口設(shè)計(jì)會(huì)返回異常（HTTP狀態(tài)碼404或其他），有的則是會(huì)返回請(qǐng)求成功（HTTPS狀態(tài)碼200），但是返回結(jié)果是空數(shù)組或者null等表示結(jié)果為空的標(biāo)識(shí)？

以上這幾個(gè)問(wèn)題，哪些是對(duì)的哪些是錯(cuò)的呢？答案是：沒(méi)有對(duì)錯(cuò)

在我們?cè)噲D搞清楚以上幾個(gè)問(wèn)題之前，首先需要讀者了解或者閱讀過(guò)關(guān)于RESTfull的定義，這類定義百度一搜一大把這里就不重復(fù)贅述了。接著是最好你實(shí)踐過(guò)這類風(fēng)格設(shè)計(jì)的接口，如果你心中也同樣有這幾個(gè)問(wèn)題或者疑問(wèn)那就更好了，當(dāng)然最后這兩點(diǎn)要求并不是必須。

如果你已經(jīng)閱讀過(guò)關(guān)于RESTfull的相關(guān)定義，你就會(huì)發(fā)現(xiàn)RESTfull是一種接口設(shè)計(jì)風(fēng)格，它制定了一些原則條件，只要你遵守了，就算是RESTful風(fēng)格的接口設(shè)計(jì)。

那么問(wèn)題就來(lái)了，這里面就存在很多靈活空間了，比如說(shuō)我部分遵守，部分不遵守，可以嗎？可以。或者說(shuō)我在遵守的基礎(chǔ)上，再自定義一些行為，可以嗎？可以。

各種諸如此類的實(shí)踐路線導(dǎo)致了我們很難在開發(fā)生涯中真的看到有兩個(gè)或更多的接口實(shí)現(xiàn)了一模一樣的RESTfull風(fēng)格接口，即便他們的業(yè)務(wù)是一樣的。這是因?yàn)镽ESTfull本身既然是一種設(shè)計(jì)風(fēng)格，那么風(fēng)格發(fā)揮的主動(dòng)權(quán)自然就是在開發(fā)者身上，而且絕大多數(shù)的項(xiàng)目所開發(fā)的API接口都是對(duì)內(nèi)或者有限對(duì)外開放的，所以對(duì)于RESTfull的實(shí)踐是否合格更多取決于內(nèi)部團(tuán)隊(duì)老大的看法。

說(shuō)到這里讀者們可能會(huì)覺(jué)得，既然如此那這個(gè)真是太糟糕了，完全做不到統(tǒng)一，你完全想象不到別人設(shè)計(jì)出什么魔幻風(fēng)格的RESTfull接口，為什么RESTfull依然能成為主流的接口設(shè)計(jì)風(fēng)格呢？

這里我個(gè)人覺(jué)得有一部分原因是同行襯托，RESTfull基于HTTP協(xié)議,采用json格式的字符串作為傳輸內(nèi)容，相對(duì)于過(guò)去的SOAP協(xié)議，采用XML格式標(biāo)記語(yǔ)言來(lái)說(shuō)，RESTfull無(wú)論從開發(fā)成本或者網(wǎng)絡(luò)傳輸來(lái)說(shuō)都顯得輕量太多太多。而前面提到的，關(guān)于實(shí)際開發(fā)出來(lái)的RESTfull接口風(fēng)格迥異的問(wèn)題實(shí)際上并沒(méi)有太糟糕，為什么這么說(shuō)呢？因?yàn)樽钇鸫a的一點(diǎn)是無(wú)論實(shí)際設(shè)計(jì)出來(lái)的接口再奇葩，總歸是基于HTTP協(xié)議和使用JSON字符串來(lái)傳遞數(shù)據(jù)，這最起碼保證了我們?cè)谡{(diào)用別人設(shè)計(jì)好的接口的時(shí)候足夠簡(jiǎn)單。

當(dāng)然，能調(diào)用跟實(shí)際交互還有一段很長(zhǎng)的距離，而中間這個(gè)過(guò)程你是否舒適，有一部分就體現(xiàn)在接口細(xì)節(jié)設(shè)計(jì)上了。按照一般的經(jīng)驗(yàn)，像這種”標(biāo)準(zhǔn)化“的設(shè)計(jì)，我們會(huì)封裝一些基礎(chǔ)方法來(lái)實(shí)現(xiàn)接口的調(diào)用和數(shù)據(jù)接收，但現(xiàn)實(shí)卻是無(wú)法實(shí)現(xiàn)的。因?yàn)镽ESfull接口的具體實(shí)現(xiàn)細(xì)節(jié)上是因人而異的，這就導(dǎo)致了我們封裝的調(diào)用或者解析代碼未必能夠完全復(fù)用，很典型的例子就是我們一開始拋出來(lái)的那幾個(gè)問(wèn)題。

這時(shí)候讀者們肯定想說(shuō)，還是想吐槽，是的，我們可以吐槽一個(gè)接口設(shè)計(jì)得很糟心，讓我們調(diào)用起來(lái)很難受，但是我們又不可否認(rèn)他確實(shí)遵守了RESTfull的基本規(guī)定，你可以發(fā)送一個(gè)HTTP請(qǐng)求,通過(guò)JSON來(lái)提交和接收數(shù)據(jù)，你完全拿對(duì)方?jīng)]辦法。所以這也就是為什么我們一開始給出的答案是：沒(méi)有對(duì)錯(cuò)。我們可以吐槽一個(gè)接口設(shè)計(jì)得非常糟糕，但是不能說(shuō)這個(gè)接口不是RESTfull接口，但是，我們可以評(píng)判一個(gè)接口是否嚴(yán)格遵循了RESTfull風(fēng)格設(shè)計(jì)以及遵循的程度有多高。

我們可以從開局的幾個(gè)問(wèn)題入手來(lái)嘗試評(píng)判下相應(yīng)的接口設(shè)計(jì)是否很好的遵循了RESTfull風(fēng)格設(shè)計(jì)。

Part2為什么接口只設(shè)計(jì)了GET和POST兩種請(qǐng)求方法類型？

解析：HTTP協(xié)常用的請(qǐng)求方法類型有GET、POST、PUT、PATCH、delete，其中毫無(wú)疑問(wèn)GET和POST是最最最常用的，而且每個(gè)請(qǐng)求方法類型都有各自的描述：

從上面的表格可以看出，不同類型的請(qǐng)求方法有著自己明確的含義，在理想的情況下，我們可以通過(guò)一個(gè)請(qǐng)求類型+請(qǐng)求地址的形式，直觀的看出一個(gè)接口的作用，比如：

// 猜猜阿克蘇我想干嘛
GET https://tinywan.com/users

delete  https://tinywan.com/users/69

這里讀者可以嘗試做一個(gè)閱讀理解。

那么這里問(wèn)題就來(lái)了，既然HTTP的請(qǐng)求方法類型有助于我們理解一個(gè)接口的作用，為什么在有些接口中唯獨(dú)只會(huì)使用GET和POST呢？這里面我覺(jué)得原因有很多，有些可能我也想不到也猜不到，但是我從個(gè)人開發(fā)經(jīng)驗(yàn)上嘗試猜測(cè)一下。

原因我覺(jué)得可能是一是懶，二是覺(jué)得沒(méi)必要，三是根本不會(huì)設(shè)計(jì)。

坦白說(shuō)，除了查詢請(qǐng)求這種無(wú)可爭(zhēng)議的使用GET之外，其他的全部歸為POST無(wú)疑是一件很方便的事。你不需要花時(shí)間去考慮接口的行為然后決定要定義成什么請(qǐng)求方法類型，反正具體的實(shí)現(xiàn)邏輯都是一樣的，而且POST方法的描述也似乎能涵蓋到其他幾個(gè)類型的請(qǐng)求方法。但這里讀者可能會(huì)說(shuō)，在某些場(chǎng)景下會(huì)有歧義，比如說(shuō)我們要調(diào)用一個(gè)接口實(shí)現(xiàn)刪除一個(gè)用戶：

  // 猜猜我想干嘛
  POST https://tinywan.com/users/69

這里我們復(fù)用了前面其中一道閱讀理解題并把類型改成了POST。這里第一眼看上去確實(shí)不能很好的表達(dá)接口的意圖，但是我們有接口文檔呀，我在相應(yīng)的接口名稱中寫清楚再放大字體說(shuō)這個(gè)接口是刪除用戶用的不就完事了？這么一聽好像也有道理。所以綜合看來(lái)，細(xì)分各個(gè)方法請(qǐng)求類型似乎變成一件很多余的事，吃力不討好，干脆就GET/POST一把梭了。

說(shuō)到這里，我們?cè)倩剡^(guò)頭來(lái)看看問(wèn)題本身，做錯(cuò)了嗎？沒(méi)有。那嚴(yán)格遵循了RESTfull風(fēng)格設(shè)計(jì)了嗎，那倒是并沒(méi)有。

RESTfull是基于HTTP協(xié)議的，HTTP協(xié)議里面清清楚楚明明白白提供了這些方法類型，那么從嚴(yán)謹(jǐn)?shù)慕嵌壬蟻?lái)說(shuō)，我們確實(shí)是需要清楚的定義好每個(gè)請(qǐng)求的類型是什么。這不僅是有利于提高接口語(yǔ)義化，其實(shí)對(duì)接口地址定義也有些好處，比如說(shuō)我們要定義一套對(duì)用戶進(jìn)行CRUD的接口。

遵循 RESTfull

// 遵循RESTfull
GET     https://tinywan.com/users

GET     https://tinywan.com/users/1

POST    https://tinywan.com/users
Body:   "{"username":"Tinywan","password":123446}"

PUT     https://tinywan.com/users/1
Body:   "{"username":"阿克蘇","password":wt@123465}"

PATCH   https://tinywan.com/users/69
Body:   "{"password":999999}"

delete  https://tinywan.com/users/1

不遵循RESTfull

GET     https://tinywan.com/users

GET     https://tinywan.com/users/1

POST    https://tinywan.com/users
Body:   "{"username":"Tinywan","password":123446}"

POST    https://tinywan.com/put/users/1
Body:   "{"username":"阿克蘇","password":wt@123465}"

POST    https://tinywan.com/patch/user/69
Body:   "{"password":999999}"

POST    https://tinywan.com/delete/user/1

注意：在不遵循RESTfull風(fēng)格的情況下，因?yàn)槌薌ET以外都是POST類型請(qǐng)求，我們需要為相同POST請(qǐng)求的接口定義不同的路由地址，這里示例中的路由地址只是為了體現(xiàn)這一點(diǎn)，真實(shí)開發(fā)場(chǎng)景中如何命名各有各發(fā)揮。

從這里的示例可以看出，在不遵循RESTfull風(fēng)格設(shè)計(jì)的情況下我們難免需要在接口URL地址中增加一些描述性的單詞，這會(huì)導(dǎo)致路由接口地址變得很冗長(zhǎng)和不夠優(yōu)雅，當(dāng)然如果你覺(jué)得這不是什么問(wèn)題那也是沒(méi)錯(cuò)的，對(duì)，你沒(méi)錯(cuò)。

最后總結(jié)一下這個(gè)問(wèn)題就是，你可以不遵循RESTfull風(fēng)格設(shè)計(jì)里面關(guān)于對(duì)請(qǐng)求方法類型的區(qū)分定義，但需要在路由地址上花心思，那么在真實(shí)開發(fā)場(chǎng)景中，我們?cè)撊绾芜x擇呢？我的建議是如果你能做主，而且覺(jué)得有必要，就嚴(yán)格遵循，反之，領(lǐng)導(dǎo)說(shuō)就啥吧。

Part3為什么接口是否請(qǐng)求成功，HTTP狀態(tài)碼永遠(yuǎn)只會(huì)是200？

解析：常見的HTTP狀態(tài)碼有如下幾種：

從上面表格可以看出，HTTP碼是用于標(biāo)識(shí)本次請(qǐng)求響應(yīng)的結(jié)果狀態(tài),通過(guò)HTTP狀態(tài)我們可以直觀的判斷出本請(qǐng)求是不是成功的，但是為什么有些接口設(shè)計(jì)的情況是無(wú)論成功與否都只會(huì)返回200的狀態(tài)碼呢？

這里的原因和第1點(diǎn)的問(wèn)題大致相同，就是懶和覺(jué)得沒(méi)必要。但相對(duì)于明確方法請(qǐng)求類型來(lái)說(shuō)，明確接口響應(yīng)的HTTP狀態(tài)碼卻是大有意義。

首先假設(shè)我們把所有請(qǐng)求響應(yīng)的HTTP狀態(tài)碼都標(biāo)識(shí)為200，那么我們必然需要在響應(yīng)內(nèi)容中增加一些字段來(lái)描述本次錯(cuò)誤，例如：

// 200
{
  // 定義一個(gè)錯(cuò)誤碼
  "code": 1024,
  // 錯(cuò)誤碼對(duì)應(yīng)的錯(cuò)誤信息描述
  "message": "密碼不正確"
}

這里大家可能會(huì)覺(jué)得，我們已經(jīng)有code和message字段來(lái)描述本次請(qǐng)求的錯(cuò)誤了，完全不需要HTTP狀態(tài)碼。這里乍一看是沒(méi)有問(wèn)題的，前端也能在統(tǒng)一異常處理的層面很好的捕獲異常。

但是，當(dāng)你的系統(tǒng)到了一定的規(guī)模（這個(gè)很容易達(dá)到，并不要求需要多大的規(guī)模體量，只要不是demo項(xiàng)目），你的錯(cuò)誤類型就會(huì)有很多種，往往我們的錯(cuò)誤碼清單會(huì)很長(zhǎng)，當(dāng)然這對(duì)于后端開發(fā)來(lái)說(shuō)不是啥問(wèn)題，因?yàn)檫@個(gè)信息其實(shí)是給前端開發(fā)者處理的，但是前端開發(fā)者在處理這些錯(cuò)誤的時(shí)候就難受了。

難受在哪？假設(shè)我們現(xiàn)在有10個(gè)關(guān)于賬戶異常的錯(cuò)誤碼，10個(gè)關(guān)于業(yè)務(wù)A的錯(cuò)誤碼，10個(gè)關(guān)于業(yè)務(wù)B的錯(cuò)誤碼，一共30個(gè)。這里面有個(gè)業(yè)務(wù)需求，就是某些特定的錯(cuò)誤碼需要前端做出特定的行為，比如說(shuō)跳轉(zhuǎn)到指定頁(yè)面，或者強(qiáng)制退出啥等等。那么這時(shí)候前端在統(tǒng)一異常處理的時(shí)候咋做？那就是各種if/else和switch判斷。

看起來(lái)似乎也問(wèn)題不大嘛，是的，接著我們需求變了，和原來(lái)不一樣了，原來(lái)的分支判斷條件可能不適用了，錯(cuò)誤碼改了，含義不一樣了，或者又增加了30個(gè)新的錯(cuò)誤碼，那么這時(shí)候前端開發(fā)者就炸了。

所以從這里可以看出，單純依靠錯(cuò)誤碼來(lái)實(shí)現(xiàn)前端統(tǒng)一異常處理依然會(huì)存在重復(fù)編碼問(wèn)題，那么如果我們嚴(yán)格遵循RESTfull風(fēng)格設(shè)計(jì)的話，增加HTTP狀態(tài)碼的區(qū)分定義，同時(shí)保留原來(lái)的錯(cuò)誤響應(yīng)信息結(jié)果會(huì)是如何？這時(shí)候前端開發(fā)者在做統(tǒng)一異常處理的時(shí)候，先按狀態(tài)碼做一層大范圍的分支處理，再有針對(duì)性的對(duì)這個(gè)狀態(tài)碼類型下的某些錯(cuò)誤碼做特殊處理即可。

這兩種方式的區(qū)別在于，通過(guò)HTTP狀態(tài)碼相當(dāng)于給錯(cuò)誤碼做了一個(gè)歸類，這也符合真實(shí)開發(fā)場(chǎng)景的異常處理情況。多數(shù)情況下前端在對(duì)異常做統(tǒng)一處理的時(shí)候，同一類型的異常往往后續(xù)的處理行為是一致的。

比如說(shuō)給后端傳遞了錯(cuò)誤的參數(shù)，這種一般后端在校驗(yàn)不通過(guò)的時(shí)候，會(huì)返回的HTTP狀態(tài)碼是400。這類提示信息是需要把具體錯(cuò)誤信息展示給用戶作為警告提示的，那么前端開發(fā)者在統(tǒng)一異常處理的時(shí)候，只需要判斷HTTP狀態(tài)碼是不是400，是的話直接把具體內(nèi)容以各種彈出提示的形式展示即可，不用關(guān)心具體的錯(cuò)誤碼又是什么（需要特殊處理的除外）。還有一種是401和**403 **HTTP狀態(tài)碼的錯(cuò)誤，這兩種都是跟權(quán)限有關(guān)的錯(cuò)誤，前端開發(fā)者在做統(tǒng)一異常處理的時(shí)候也可以進(jìn)行針對(duì)性的統(tǒng)一捕獲處理。

從上面舉的一些例子可以看出，相同的HTTP狀態(tài)碼，前端的處理行為往往是一致的，但錯(cuò)誤碼未必。

相對(duì)于單純依靠錯(cuò)誤碼，HTTP狀態(tài)碼+錯(cuò)誤碼的方式讓前端開發(fā)者更容易實(shí)現(xiàn)封裝和統(tǒng)一處理，前端開發(fā)者根據(jù)HTTP狀態(tài)碼定義不同的響應(yīng)處理，可以大大減少開發(fā)工程量和降低溝通成本。但是這里讀者們可能會(huì)說(shuō)，我們可以把錯(cuò)誤碼按范圍劃分，實(shí)現(xiàn)比如1~99是代表XX類型錯(cuò)誤，100~199是XX類型錯(cuò)誤。這個(gè)確實(shí)可以，但是這等于是換了條路開倒車，其實(shí)還是會(huì)有一開始的提到的痛點(diǎn)問(wèn)題出現(xiàn)。而且錯(cuò)誤碼因?yàn)槭菆F(tuán)隊(duì)定義的，如果維護(hù)不善會(huì)導(dǎo)致各種前后端開發(fā)者信息不同步的問(wèn)題，既然通過(guò)HTTP狀態(tài)碼的定義就能解決大部分問(wèn)題了為什么不用呢？

最后總結(jié)一下這個(gè)問(wèn)題就是，強(qiáng)烈建議嚴(yán)格按照HTTP狀態(tài)碼的定義區(qū)分接口響應(yīng)的HTTP狀態(tài)碼，錯(cuò)誤碼作為一種細(xì)分的補(bǔ)充。

Part4HTTP狀態(tài)碼不存在，返回 200 還是 404 ？

問(wèn)題： 當(dāng)一個(gè)查詢的結(jié)果為空的時(shí)候，為什么有的接口設(shè)計(jì)會(huì)返回異常（HTTP狀態(tài)碼404或其他），有的則是會(huì)返回請(qǐng)求成功（HTTPS狀態(tài)碼200），但是返回結(jié)果是空數(shù)組或者null等表示結(jié)果為空的標(biāo)識(shí)？

解析：這個(gè)問(wèn)題情況有點(diǎn)特殊，理論上來(lái)說(shuō)，當(dāng)我們查詢了資源然后結(jié)果是不存在的時(shí)候，這個(gè)時(shí)候用404的HTTP狀態(tài)碼來(lái)標(biāo)識(shí)本次請(qǐng)求的響應(yīng)狀態(tài)是一點(diǎn)問(wèn)題都沒(méi)有的，也是非常規(guī)范的做法。但是這是建立在業(yè)務(wù)場(chǎng)景規(guī)定，查詢結(jié)果為空的時(shí)候?qū)儆诋惓５那疤嵘稀?/p>

1返回HTTP狀態(tài)碼 200

當(dāng)我們查詢一個(gè)資源但是結(jié)果為空，到底要不要把本次請(qǐng)求視為一個(gè)404的異常是取決于業(yè)務(wù)場(chǎng)景。如果說(shuō)業(yè)務(wù)場(chǎng)景認(rèn)為”空“是允許的，那么就不應(yīng)該讓本次響應(yīng)是一個(gè)404的HTTP狀態(tài)碼，因?yàn)橛行I(yè)務(wù)場(chǎng)景下，“空”也是有它的業(yè)務(wù)含義的

比如我們要查詢一個(gè)月內(nèi)連續(xù)登陸10天的用戶列表，結(jié)果是沒(méi)有用戶滿足這個(gè)條件，那么我返回的結(jié)果自然是空的，并不能視為一個(gè)異常，這時(shí)候返回一個(gè)200的HTTP狀態(tài)碼，然后在響應(yīng)結(jié)果里面明確結(jié)果是空的才是正確的做法。

2返回HTTP狀態(tài)碼 404

那么什么場(chǎng)景下”空“是不允許的呢？比如說(shuō)我們要修改指定的某個(gè)用戶的個(gè)人信息，那么通常情況下我們后端的處理邏輯是這樣的：查詢這個(gè)用戶是否存在，如果存在則進(jìn)行更新操作，如果不存在，拋出一個(gè)異常提示要修改的用戶不存在。在這種場(chǎng)景下，這個(gè)異常就會(huì)是一個(gè)404異常，我們嘗試修改一個(gè)并不存在的用戶。

最后總結(jié)一下這個(gè)問(wèn)題，當(dāng)請(qǐng)求的結(jié)果為空時(shí)，是不是屬于異常要考慮業(yè)務(wù)場(chǎng)景，并且這個(gè)劃分定義也是很有必要的，可以避免潛在的業(yè)務(wù)理解偏差導(dǎo)致的程序執(zhí)行邏輯問(wèn)題，因?yàn)槿绻且粋€(gè)異常，那么會(huì)更早的被前端在統(tǒng)一異常處理里面的捕獲并處理，有利于前、后端開發(fā)人員開發(fā)出更健壯的系統(tǒng)。