Java 如何設計 API 接口,實現統一格式返回? [復制鏈接]

2019-11-11 10:35
小小CTO 閱讀:317 評論:0 贊:0
Tag:  Java API

前言

在移動互聯網,分布式、微服務盛行的今天,現在項目絕大部分都采用的微服務框架,前后端分離方式,

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

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

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

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

接口交互

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

針對URL路徑的restful風格,以及傳入參數的公共請求頭的要求(如:app_version,api_version,device等),老顧這里就不介紹了,小伙伴們可以自行去了解,也比較簡單。

后端服務器如何實現把數據返回給前端?

返回格式

后端返回給前端我們一般用JSON體方式,定義如下:

CODE狀態碼

code返回狀態碼,一般小伙伴們是在開發的時候需要什么,就添加什么。

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

我們應該可以參考HTTP請求返回的狀態碼

Java 如何設計 API 接口,實現統一格式返回?

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

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

Message

這個字段相對理解比較簡單,就是發生錯誤時,如何友好的進行提示。一般的設計是和code狀態碼一起設計,如:

Java 如何設計 API 接口,實現統一格式返回?

再在枚舉中定義,狀態碼

Java 如何設計 API 接口,實現統一格式返回?

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

Data

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

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

Java 如何設計 API 接口,實現統一格式返回?

控制層Controller

我們會在controller層處理業務請求,并返回給前端,以order訂單為例

Java 如何設計 API 接口,實現統一格式返回?

我們看到在獲得order對象之后,我們是用的Result構造方法進行包裝賦值,然后進行返回。小伙伴們有沒有發現,構造方法這樣的包裝是不是很麻煩,我們可以優化一下。

美觀美化

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

Java 如何設計 API 接口,實現統一格式返回?

那我們來改造一下Controller

Java 如何設計 API 接口,實現統一格式返回?

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

優雅優化

上面我們看到在Result類中增加了靜態方法,使得業務處理代碼簡潔了。但小伙伴們有沒有發現這樣有幾個問題:

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

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

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

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

Java 如何設計 API 接口,實現統一格式返回?

這個和我們平時的代碼是一樣的,非常直觀,直接返回order對象,這樣是不是很完美。

那實現方案是什么呢?

實現方案

小伙伴們怎么去實現是不是有點思路,在這個過程中,我們需要做幾個事情

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

攔截請求,判斷此請求是否需要被@ResponseResult注解

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

注解類

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

Java 如何設計 API 接口,實現統一格式返回?

攔截器

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

Java 如何設計 API 接口,實現統一格式返回?

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

重寫返回體

Java 如何設計 API 接口,實現統一格式返回?

上面代碼就是判斷是否需要返回值包裝,如果需要就直接包裝。

這里我們只處理了正常成功的包裝,如果方法體報異常怎么辦?處理異常也比較簡單,只要判斷body是否為異常類。

Java 如何設計 API 接口,實現統一格式返回?

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

重寫Controller

Java 如何設計 API 接口,實現統一格式返回?

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

這個方案還有沒有別的優化空間,當然是有的。

如:每次請求都要反射一下,獲取請求的方法是否需要包裝,其實可以做個緩存,不需要每次都需要解析。當然整體思路了解,小伙伴們就可以在此基礎上面自行擴展。


我來說兩句
您需要登錄后才可以評論 登錄 | 立即注冊
facelist
所有評論(0)
領先的中文移動開發者社區
18620764416
7*24全天服務
意見反饋:[email protected]

掃一掃關注我們

Powered by Discuz! X3.2© 2001-2019 Comsenz Inc.( 粵ICP備15117877號 )

重庆时时彩开奖模拟器 超级水果拉霸25线 股票涨跌对上市公司有什么影响 qq新快3 彩票计划挂机软件手机版 安徽快3形态走势图 网上游戏棋牌 喜马拉雅听书录制能赚钱吗 超神pk10计划 3d今日试机后推荐汇总 重庆时时计划手机软件下载 网上任务赚钱 彩票托怎么聊天的