文章來源于公眾號:Java旅途
前言
在移動互聯(lián)網(wǎng),分布式、微服務(wù)盛行的今天,現(xiàn)在項目絕大部分都采用的微服務(wù)框架,前后端分離方式,(題外話:前后端的工作職責(zé)越來越明確,現(xiàn)在的前端都稱之為大前端,技術(shù)棧以及生態(tài)圈都已經(jīng)非常成熟;以前后端人員瞧不起前端人員,那現(xiàn)在后端人員要重新認(rèn)識一下前端,前端已經(jīng)很成體系了)。
一般系統(tǒng)的大致整體架構(gòu)圖如下:
需要說明的是,有些小伙伴會回復(fù)說,這個架構(gòu)太簡單了吧,太low了,什么網(wǎng)關(guān)啊,緩存啊,消息中間件啊,都沒有。因為老顧這篇主要介紹的是API接口,所以我們聚焦點,其他的模塊小伙伴們自行去補(bǔ)充。
接口交互
前端和后端進(jìn)行交互,前端按照約定請求URL路徑,并傳入相關(guān)參數(shù),后端服務(wù)器接收請求,進(jìn)行業(yè)務(wù)處理,返回數(shù)據(jù)給前端。
針對URL路徑的restful風(fēng)格,以及傳入?yún)?shù)的公共請求頭的要求(如:app_version,api_version,device等),老顧這里就不介紹了,小伙伴們可以自行去了解,也比較簡單。
后端服務(wù)器如何實現(xiàn)把數(shù)據(jù)返回給前端?
返回格式
后端返回給前端我們一般用 JSON 體方式,定義如下:
{
#返回狀態(tài)碼
code:integer,
#返回信息描述
message:string,
#返回值
data:object
}
CODE狀態(tài)碼
code 返回狀態(tài)碼,一般小伙伴們是在開發(fā)的時候需要什么,就添加什么。
如接口要返回用戶權(quán)限異常,我們加一個狀態(tài)碼為101吧,下一次又要加一個數(shù)據(jù)參數(shù)異常,就加一個102的狀態(tài)碼。這樣雖然能夠照常滿足業(yè)務(wù),但狀態(tài)碼太凌亂了
我們應(yīng)該可以參考 HTTP 請求返回的狀態(tài)碼
:下面是常見的HTTP狀態(tài)碼:
200 - 請求成功
301 - 資源(網(wǎng)頁等)被永久轉(zhuǎn)移到其它URL
404 - 請求的資源(網(wǎng)頁等)不存在
500 - 內(nèi)部服務(wù)器錯誤
我們可以參考這樣的設(shè)計,這樣的好處就把錯誤類型歸類到某個區(qū)間內(nèi),如果區(qū)間不夠,可以設(shè)計成4位數(shù)。
#1000~1999 區(qū)間表示參數(shù)錯誤
#2000~2999 區(qū)間表示用戶錯誤
#3000~3999 區(qū)間表示接口異常
這樣前端開發(fā)人員在得到返回值后,根據(jù)狀態(tài)碼就可以知道,大概什么錯誤,再根據(jù) message 相關(guān)的信息描述,可以快速定位。
Message
這個字段相對理解比較簡單,就是發(fā)生錯誤時,如何友好的進(jìn)行提示。一般的設(shè)計是和code狀態(tài)碼一起設(shè)計,如
再在枚舉中定義,狀態(tài)碼
狀態(tài)碼和信息就會一一對應(yīng),比較好維護(hù)。
Data
返回數(shù)據(jù)體,JSON 格式,根據(jù)不同的業(yè)務(wù)又不同的 JSON 體。
我們要設(shè)計一個返回體類 Result
控制層Controller
我們會在controller
層處理業(yè)務(wù)請求,并返回給前端,以order
訂單為例
我們看到在獲得 order 對象之后,我們是用的 Result 構(gòu)造方法進(jìn)行包裝賦值,然后進(jìn)行返回。小伙伴們有沒有發(fā)現(xiàn),構(gòu)造方法這樣的包裝是不是很麻煩,我們可以優(yōu)化一下。
美觀美化
我們可以在 Result 類中,加入靜態(tài)方法,一看就懂
那我們來改造一下 Controller
代碼是不是比較簡潔了,也美觀了。
優(yōu)雅優(yōu)化
上面我們看到在 Result 類中增加了靜態(tài)方法,使得業(yè)務(wù)處理代碼簡潔了。但小伙伴們有沒有發(fā)現(xiàn)這樣有幾個問題:
1、每個方法的返回都是Result封裝對象,沒有業(yè)務(wù)含義
2、在業(yè)務(wù)代碼中,成功的時候我們調(diào)用Result.success,異常錯誤調(diào)用Result.failure。是不是很多余
3、上面的代碼,判斷id是否為null,其實我們可以使用hibernate validate做校驗,沒有必要在方法體中做判斷。
我們最好的方式直接返回真實業(yè)務(wù)對象,最好不要改變之前的業(yè)務(wù)方式,如下圖
這個和我們平時的代碼是一樣的,非常直觀,直接返回 order 對象,這樣是不是很完美。那實現(xiàn)方案是什么呢?
實現(xiàn)方案
小伙伴們怎么去實現(xiàn)是不是有點思路,在這個過程中,我們需要做幾個事情
1、定義一個注解@ResponseResult,表示這個接口返回的值需要包裝一下
2、攔截請求,判斷此請求是否需要被@ResponseResult注解
3、核心步驟就是實現(xiàn)接口ResponseBodyAdvice和@ControllerAdvice,判斷是否需要包裝返回值,如果需要,就把Controller接口的返回值進(jìn)行重寫。
注解類
用來標(biāo)記方法的返回值,是否需要包裝
攔截器
攔截請求,是否此請求返回的值需要包裝,其實就是運(yùn)行的時候,解析 @ResponseResult 注解
此代碼核心思想,就是獲取此請求,是否需要返回值包裝,設(shè)置一個屬性標(biāo)記。
重寫返回體
上面代碼就是判斷是否需要返回值包裝,如果需要就直接包裝。這里我們只處理了正常成功的包裝,如果方法體報異常怎么辦?處理異常也比較簡單,只要判斷 body 是否為異常類。
怎么做全局的異常處理,篇幅原因,老顧這里就不做介紹了,只要思路理清楚了,自行改造就行。
重寫Controller
在控制器類上或者方法體上加上 @ResponseResult 注解,這樣就 ok 了,簡單吧。到此返回的設(shè)計思路完成,是不是又簡潔,又優(yōu)雅。
這個方案還有沒有別的優(yōu)化空間,當(dāng)然是有的。如:每次請求都要反射一下,獲取請求的方法是否需要包裝,其實可以做個緩存,不需要每次都需要解析。當(dāng)然整體思路了解,小伙伴們就可以在此基礎(chǔ)上面自行擴(kuò)展。
以上就是W3Cschool編程獅
關(guān)于API 接口,統(tǒng)一格式返回!你學(xué)到了么的相關(guān)介紹了,希望對大家有所幫助。