如何設計 API 接口，實現(xiàn)統(tǒng)一格式返回？
最適合晚上睡不著看的 8 個網(wǎng)站，建議收藏哦 23 種設計模式的通俗解釋，雖然有點污，但是秒懂 請立即卸載這款 IDEA 插件！ SQL自動檢查神器，再也不用擔心SQL出錯了，自動補全、回滾等功能大全 最新 955 不加班的公司名單（2022版）
來源：老顧聊技術
前言 接口相互作用 返回格式 控制層控制器 美觀美化 優(yōu)雅優(yōu)化 實現(xiàn)方案
前言
在移動互聯(lián)網(wǎng)，分布式，微服務盛行的今天，現(xiàn)在項目絕大部分都采用的微服務框架，前分離分離方式，（題外話：前重新的工作分配越來越明確，現(xiàn)在的前端都稱為大前端，技術棧以及生態(tài)圈都已經(jīng)非常成熟；以前官員人員瞧不起前端人員，那現(xiàn)在高層人員要重新認識一下前端，前端已經(jīng)很成體系了）。
一般系統(tǒng)的大致整體架構圖如下：
需要說明的是，有些小伙伴會回復說，這個架構太簡單了吧，太low了，什么網(wǎng)關啊，緩存啊，消息中間件啊，都沒有。因為老顧介紹主要介紹的是API接口，所以我們聚焦點，其他的模塊小伙伴們自行去補充。
接口相互作用
前端和前端進行交互，前端按約定的請求URL路徑，并合并相關參數(shù)，進入服務器接收請求，進行業(yè)務處理，返回數(shù)據(jù)給前端。
針對URL路徑的restful風格，以及引用參數(shù)的公共請求頭的要求（如：app_version，api_version，device等），老顧這里就不介紹了，小伙伴們可以自行去了解，也比較簡單。
前端服務器如何實現(xiàn)把數(shù)據(jù)返回給前端？
返回格式
最初返回給前端我們一般用JSON體方式，定義如下：
{
??#返回狀態(tài)碼
??code:integer,
??#返回信息描述
??message:string,
??#返回值
??data:object
}
CODE狀態(tài)碼
code返回狀態(tài)碼，一般小伙伴們是在開發(fā)的時候需要什么，就添加什么。
如接口要返回用戶權限異常，我們加一個狀態(tài)碼為101吧，下一次又要加一個數(shù)據(jù)參數(shù)異常，就加一個102的狀態(tài)碼。這樣雖然能夠照常滿足業(yè)務，但狀態(tài)碼太凌亂了
我們應該可以參考HTTP請求返回的狀態(tài)碼
：下面是常見的HTTP狀態(tài)碼：
200?-?請求成功
301?-?資源（網(wǎng)頁等）被永久轉移到其它URL
404?-?請求的資源（網(wǎng)頁等）不存在
500?-?內(nèi)部服務器錯誤
我們可以參考這樣的設計，這樣的好處就把錯誤類型歸類到某個區(qū)間內(nèi)，如果區(qū)間不夠，可以設計成4個數(shù)字。
#1000～1999?區(qū)間表示參數(shù)錯誤
#2000～2999?區(qū)間表示用戶錯誤
#3000～3999?區(qū)間表示接口異常
這樣前端開發(fā)人員在得到返回值后，根據(jù)狀態(tài)碼就可以知道，大概什么錯誤，再根據(jù)消息相關的信息描述，可以快速定位。
資訊
這個相對相對理解比較簡單，就是發(fā)生錯誤時，如何友好的進行提示。一般的設計是和code狀態(tài)碼一起設計，如
再在枚舉中定義，狀態(tài)碼
狀態(tài)碼和信息就會一一對應，比較好維護。
數(shù)據(jù)
返回數(shù)據(jù)體，JSON格式，根據(jù)不同的業(yè)務又不同的JSON體。
我們要設計一個返回體類結果
控制層控制器
我們會在控制器層處理業(yè)務請求，并返回給前端，以orderorder為例
我們看到在獲得訂單對象之后，我們是用的結果構造方法進行包裝賦值，然后進行返回。小伙伴們有沒有發(fā)現(xiàn)，構造方法這樣的包裝是不是很麻煩，我們可以優(yōu)化一下。
美觀美化
我們可以在結果類中，加入靜態(tài)方法，一看就懂
那我們來改造一下Controller
代碼是不是比較簡潔了，也美觀了。
優(yōu)雅優(yōu)化
上面我們看到在結果類中增加了靜態(tài)方法，正確的業(yè)務處理代碼簡潔了。但小伙伴們有沒有發(fā)現(xiàn)這樣有幾個問題：
1，每個方法的返回都是Result封裝對象，沒有業(yè)務含義
2，在業(yè)務代碼中，成功的時候我們調用Result.success，異常錯誤調用Result.failure。是不是很多余
3，上面的代碼，判斷id是否為null，實際上我們可以使用hibernate validate做校驗，沒有必要在方法體中做判斷。
我們最好的方式直接返回真實業(yè)務對象，最好不要改變之前的業(yè)務方式，如下圖
這個和我們平時的代碼是一樣的，非常直觀，直接返回order對象，這樣是不是很完美。那實現(xiàn)方案是什么呢？
實現(xiàn)方案
小伙伴們怎么去實現(xiàn)是不是有點思路，在這個過程中，我們需要做幾個事情
1，定義一個注解@ResponseResult，表示此接口返回的值需要包裝一下
2，攔截請求，判斷此請求是否需要被@ResponseResult注解
3，核心步驟就是實現(xiàn)接口ResponseBodyAdvice和@ControllerAdvice，判斷是否需要包裝返回值，如果需要，就把控制器接口的返回值進行轉換。
注解類
采用標記方法的返回值，是否需要包裝
攔截器
攔截請求，是否此請求返回的值需要包裝，實際上就是運行的時候，解析@ResponseResult注解
此代碼核心思想，就是獲取此請求，是否需要返回值包裝，設置一個屬性標記。
重建返回體
上面的代碼就是肯定肯定判斷是否需要返回值包裝，如果需要就直接包裝。這里我們只處理了正常成功的包裝，如果方法體報異常怎么辦？處理異常也比較簡單，只要判斷body是否為異常類。
怎么做的異常處理，篇幅原因，老顧這里就不做介紹了，只要思路理清楚了，自行改造就行。
改造控制器
在控制器類上或者方法體上加上@ResponseResult注解，這樣就ok了，簡單吧。到此返回的設計思路完成，是不是又簡潔，又優(yōu)雅。
這個方案還有沒有別的優(yōu)化空間，當然是有的。如：每次請求都要反射一下，獲取請求的方法是否需要包裝，其實可以做個緩存，不需要每次都需要解析。當然整體思路了解，小伙伴們就可以在此基礎之上自我擴展
最后，再給大家推薦一個GitHub項目，該項目整理了上千本常用技術PDF，技術書籍都可以在這里找到。
GitHub地址：https://github.com/hello-go-maker/cs-books
電子書已經(jīng)更新好了，拿走不謝，記得點一個star，持續(xù)更新中...
