瞧瞧,人家那後端API接口寫得多優雅!

「

在移動網際網路，分布式、微服務盛行的今天，現在項目絕大部分都採用的微服務框架，前後端分離方式。

圖片來自 Pexels

題外話：前後端的工作職責越來越明確，現在的前端都稱之為大前端，技術棧以及生態圈都已經非常成熟；以前後端人員瞧不起前端人員，那現在後端人員要重新認識一下前端，前端已經很成體系了。

一般系統的大致整體架構圖如下：

需要說明的是，有些小夥伴會回覆說，這個架構太簡單了吧，太 low 了，什麼網關啊，緩存啊，消息中間件啊，都沒有。

因為這篇我主要介紹的是 API 接口，所以我們聚焦點，其他的模塊小夥伴們自行去補充。

接口交互

前端和後端進行交互，前端按照約定請求 URL 路徑，並傳入相關參數，後端伺服器接收請求，進行業務處理，返回數據給前端。

針對 URL 路徑的 restful 風格，以及傳入參數的公共請求頭的要求（如：app_version，api_version，device 等），這裡我就不介紹了，小夥伴們可以自行去了解，也比較簡單。

我著重介紹一下後端伺服器如何實現把數據返回給前端？

返回格式

後端返回給前端我們一般用 JSON 體方式，定義如下：

CODE 狀態碼

Code 返回狀態碼，一般小夥伴們是在開發的時候需要什麼，就添加什麼。

如接口要返回用戶權限異常，我們加一個狀態碼為 101 吧，下一次又要加一個數據參數異常，就加一個 102 的狀態碼。這樣雖然能夠照常滿足業務，但狀態碼太凌亂了。

我們應該可以參考 HTTP 請求返回的狀態碼，下面是常見的 HTTP 狀態碼：

我們可以參考這樣的設計，這樣的好處就把錯誤類型歸類到某個區間內，如果區間不夠，可以設計成 4 位數。

這樣前端開發人員在得到返回值後，根據狀態碼就可以知道，大概什麼錯誤，再根據 Message 相關的信息描述，可以快速定位。

Message

這個欄位相對理解比較簡單，就是發生錯誤時，如何友好的進行提示。一般的設計是和 Code 狀態碼一起設計，如：

再在枚舉中定義，狀態碼：

狀態碼和信息就會一一對應，比較好維護。

Data

返回數據體，JSON 格式，根據不同的業務又不同的 JSON 體。

我們要設計一個返回體類 Result：

控制層 Controller

我們會在 Controller 層處理業務請求，並返回給前端，以 Order 訂單為例：

我們看到在獲得 Order 對象之後，我們是用的 Result 構造方法進行包裝賦值，然後進行返回。

小夥伴們有沒有發現，構造方法這樣的包裝是不是很麻煩，我們可以優化一下。

美觀優化

我們可以在 Result 類中，加入靜態方法，一看就懂：

那我們來改造一下 Controller：

代碼是不是比較簡潔了，也美觀了。

優雅優化

上面我們看到在 Result 類中增加了靜態方法，使得業務處理代碼簡潔了。

但小夥伴們有沒有發現這樣有幾個問題：

每個方法的返回都是 Result 封裝對象，沒有業務含義。

在業務代碼中，成功的時候我們調用 Result.success，異常錯誤調用 Result.failure。是不是很多餘。

上面的代碼，判斷 id 是否為 null，其實我們可以使用 hibernate validate 做校驗，沒有必要在方法體中做判斷。

我們最好的方式直接返回真實業務對象，最好不要改變之前的業務方式，如下圖：

這個和我們平時的代碼是一樣的，非常直觀，直接返回 order 對象，這樣是不是很完美。那實現方案是什麼呢？

實現方案

小夥伴們怎麼去實現是不是有點思路，在這個過程中，我們需要做幾個事情：

定義一個註解 @ResponseResult，表示這個接口返回的值需要包裝一下。

攔截請求，判斷此請求是否需要被 @ResponseResult 註解。

核心步驟就是實現接口 ResponseBodyAdvice 和 @ControllerAdvice，判斷是否需要包裝返回值，如果需要，就把 Controller 接口的返回值進行重寫。

註解類

用來標記方法的返回值，是否需要包裝：

攔截器

攔截請求，是否此請求返回的值需要包裝，其實就是運行的時候，解析 @ResponseResult 註解。

此代碼核心思想，就是獲取此請求，是否需要返回值包裝，設置一個屬性標記。

重寫返回體

上面代碼就是判斷是否需要返回值包裝，如果需要就直接包裝。這裡我們只處理了正常成功的包裝，如果方法體報異常怎麼辦？處理異常也比較簡單，只要判斷 body 是否為異常類。

怎麼做全局的異常處理，篇幅原因，老顧這裡就不做介紹了，只要思路理清楚了，自行改造就行。

重寫 Controller

在控制器類上或者方法體上加上 @ResponseResult 註解，這樣就 OK 了，簡單吧。到此返回的設計思路完成，是不是又簡潔，又優雅。

總結

這個方案還有沒有別的優化空間，當然是有的。如：每次請求都要反射一下，獲取請求的方法是否需要包裝，其實可以做個緩存，不需要每次都需要解析。

當然整體思路了解，小夥伴們就可以在此基礎上面自行擴展。謝謝！！！

作者：老顧

編輯：陶家龍

出處：https://www.toutiao.com/i6694404645827117572