API介面開發（一）：介面開發返回結果解決方案
摘要
採用前後端分離的方式進行專案開發，那麼前後端互動比較好的方式是採用HTTP+JSON。如何介面返回結果更加簡潔，更加優雅，也更加合理，並且讓前端開發人員看得明白，後端開發者也並不會因此而增加工作量呢？
正文開始
Hello，各位，好久不見了。一直在籌劃個人網站2020版本改版的事情，所以，本篇文章，也是2019年最後一篇了，當然，也得花一些心思，爭取把我想要說的話，都一一說出來，說明白，說透徹。
採用前後端分離的方式進行專案開發，那麼前後端互動比較好的方式是採用HTTP+JSON。如何介面返回結果更加簡潔，更加優雅，也更加合理，並且讓前端開發人員看得明白，後端開發者也並不會因此而增加工作量呢？
為此，我寫了一套關於API介面開發返回結果解決方案， ，已將其開源，並上傳到，歡迎各位批評和指正。
API講解
實體類
提供了滿足各場景使用的實體類，如下：
ResultModel
這個類是基礎實體類，有如下屬性：
success：返回結果標識，是一個布林值，true / false（成功 / 失敗）
message：描述資訊，錯誤時，可以在這裡填寫錯誤的詳細資訊
data：資料，是一個泛型，可以是陣列或者物件等等，成功並且需要返回資料時，才有該引數
ApiResultModel
結構關係如下：
ResultModel
└── ApiResultModel
在這個類裡面增加了 code 屬性，也是一個泛型，你可以自定義你的返回碼型別，可以是整數，或者字串。
PageResultModel
結構關係如下：
ResultModel
└── PageResultModel
這個類主要主要分頁返回結果，所以，增加了以下屬性：
total：資料總條數，Long型
size：每頁條數，整數
pages：總頁數，Long型
current：當前頁，Long型
Helper工具類
幫助我們操作實體類，具體有哪些helper呢？如下：
ResultHelper
ResultHelper是與ResultModel對應的
success(String message)
成功，攜帶描述資訊
success(String message, T data)
成功，攜帶描述資訊和資料
error(String message)
錯誤，攜帶詳細的描述資訊
ApiResultHelper
ApiResultHelper是與ApiResultModel對應的
success(S code, String message)
成功，攜帶返回碼和描述資訊
success(S code, String message, T data)
成功，攜帶返回碼、描述資訊和資料
error(S code, String message)
錯誤，攜帶錯誤碼和詳細描述資訊
PageResultHelper
PageResultHelper是與PageResultModel對應的
success(String message)
成功，攜帶描述資訊
success(String message, T data)
成功，攜帶描述資訊和資料
success(String message, T data, long total, int size, long pages, long current)
成功，攜帶描述資訊、資料、總數、每頁條數、總頁數、當前頁
error(String message)
錯誤，攜帶詳細的描述資訊
快速入門
我們為你提供了三個實體類，以滿足不同場景，ResultModel適用於通常返回結果，ApiResultModel適用於介面開發返回結果，PageResultModel適用於分頁返回結果。也分別為這三個實體類提供了各自的Helper，所以，你可以直接使用這些Helper進行返回。當然，我推薦的使用方式是，先為各Helper編寫工具類，再透過工具類進行返回，這樣可能更加合理定製自己的返回工具類。
利用Helper進行返回
首先我們來看一個簡單的示例程式碼：
/**
* 新增方法示例
* @return {@link ResultModel}
*/
@ApiOperation(value = "新增方法示例")
@PostMapping
public ResultModel<?> add() {
return ResultHelper.success("新增成功");
}
返回結果：
{
"success": true,
"message": "新增成功"
}
注：這只是一個介面返回示例，而不是說新增介面應該這樣寫。
編寫返回結果工具類
比如，我們可以寫一個ResultUtils工具類來操作ResultHelper。如下示例：
/**
* 成功示例
* @return {@link ResultModel}
*/
public static ResultModel <?> success() {
return ResultHelper.success("Success");
}
使用返回結果工具類
我門就可以呼叫ResultUtils類裡面的方法，如下示例：
/**
* 成功示例
* @return {@link ResultModel}
*/
@ApiOperation(value = "成功示例")
@DeleteMapping
public ResultModel<?> success() {
return ResultUtils.success();
}
印象結果：
{
"success": true,
"message": "Success"
}
使用示例
示例圖
測試介面預覽
Models
返回成功結果示例
/**
* 刪除方法示例
* @return {@link ResultModel}
*/
@ApiOperation(value = "刪除方法示例")
@DeleteMapping
public ResultModel<?> delete() {
return ResultUtils.success();
}
響應結果：
{
"success": true,
"message": "Success"
}
返回失敗結果示例
如果操作出錯了，我們怎麼返回呢？我們來看一下：
/**
* 修改方法示例
* @return {@link ResultModel}
*/
@ApiOperation(value = "修改方法示例")
@PutMapping
public ResultModel<?> update() {
return ResultUtils.error("修改失敗");
}
返回結果：
{
"success": false,
"message": "修改失敗"
}
返回查詢結果示例
值得一提的話，就是查詢方法了，我們看一下吧
/**
* 查詢方法示例
* @return {@link ResultModel}
*/
@ApiOperation(value = "查詢方法示例")
@GetMapping
public ResultModel<?> get() {
List<Map<String, String>> list = new ArrayList<>();
Map<String, String> map1 = new HashMap<>();
map1.put("name", "張飛");
map1.put("desc", "燕人張飛");
list.add(map1);
Map<String, String> map2 = new HashMap<>();
map2.put("name", "趙雲");
map2.put("desc", "常山趙子龍");
list.add(map2);
Map<String, String> map3 = new HashMap<>();
map3.put("name", "關羽");
map3.put("desc", "溫酒斬華雄");
list.add(map3);
return ResultUtils.success(list);
}
看一下響應結果吧，是否如你所願：
{
"success": true,
"message": "Success",
"data": [
{
"name": "張飛",
"desc": "燕人張飛"
},
{
"name": "趙雲",
"desc": "常山趙子龍"
},
{
"name": "關羽",
"desc": "溫酒斬華雄"
}
]
}
介面返回資料示例
/**
* 介面返回資料示例
* @return {@link ApiResultModel}
*/
@ApiOperation(value = "介面返回資料示例")
@GetMapping("/api-data")
public ApiResultModel<Integer, ?> apiData() {
return ApiResultUtils.success(getData());
}
響應結果：
{
"success": true,
"message": "Success",
"data": [
{
"name": "張飛",
"desc": "燕人張飛"
},
{
"name": "趙雲",
"desc": "常山趙子龍"
},
{
"name": "關羽",
"desc": "溫酒斬華雄"
}
],
"code": 0
}
介面返回失敗結果示例
/**
* API介面錯誤返回示例
* @return {@link ApiResultModel}
*/
@ApiOperation(value = "API介面錯誤返回示例")
@GetMapping("/api-error")
public ApiResultModel<Integer, ?> apiError() {
return ApiResultUtils.error(1101, "API介面錯誤返回示例");
}
響應結果：
{
"success": false,
"message": "API介面錯誤返回示例",
"code": 1101
}
分頁返回資料示例
/**
* 分頁返回資料示例
* @return {@link ApiResultModel}
*/
@ApiOperation(value = "分頁返回資料示例")
@GetMapping("/page")
public PageResultModel<?> page() {
return PageResultUtils.success(getData(), 100, 10, 10, 1);
}
響應結果：
{
"success": true,
"message": "Success",
"data": [
{
"name": "張飛",
"desc": "燕人張飛"
},
{
"name": "趙雲",
"desc": "常山趙子龍"
},
{
"name": "關羽",
"desc": "溫酒斬華雄"
}
],
"total": 100,
"size": 10,
"pages": 10,
"current": 1
}
工具類示例
返回結果工具類
package com.fengwenyi.api_example.util;
import com.fengwenyi.api_result.helper.ResultHelper;
import com.fengwenyi.api_result.model.ResultModel;
/**
* 返回結果封裝工具類
* @author Erwin Feng[xfsy_2015@163.com]
* @since 2019/11/30 13:54
*/
public class ResultUtils {
/**
* 成功
* @return {@link ResultModel}
*/
public static ResultModel <?> success() {
return ResultHelper.success("Success");
}
/**
* 成功，攜帶資料
* @param data 資料
* @param <T> 資料的型別
* @return {@link ResultModel}
*/
public static <T> ResultModel <T> success(T data) {
return ResultHelper.success("Success", data);
}
/**
* 錯誤，攜帶詳細的錯誤描述資訊
* @param message 詳細的錯誤描述資訊
* @return {@link ResultModel}
*/
public static ResultModel <?> error(String message) {
return ResultHelper.error(message);
}
}
API介面返回結果工具類
package com.fengwenyi.api_example.util;
import com.fengwenyi.api_result.helper.ApiResultHelper;
import com.fengwenyi.api_result.model.ApiResultModel;
/**
* API介面返回結果工具類
* @author Erwin Feng[xfsy_2015@163.com]
* @since 2019/12/1 20:10
*/
public class ApiResultUtils {
/**
* 成功，攜帶返回碼和描述資訊
* @return {@link ApiResultModel}
*/
public static ApiResultModel<Integer, ?> success() {
return ApiResultHelper.success(0, "Success");
}
/**
* 成功，攜帶返回碼、描述資訊和資料
* @param data 資料
* @param <T> 資料的型別
* @return {@link ApiResultModel}
*/
public static <T> ApiResultModel<Integer, T> success(T data) {
return ApiResultHelper.success(0, "Success", data);
}
/**
* 出錯，攜帶錯誤嗎和詳細描述資訊
* @param code 返回碼
* @param message 相信描述資訊
* @return {@link ApiResultModel}
*/
public static ApiResultModel<Integer, ?> error(int code, String message) {
return ApiResultHelper.error(code, message);
}
}
分頁返回結果工具類
package com.fengwenyi.api_example.util;
import com.fengwenyi.api_result.helper.PageResultHelper;
import com.fengwenyi.api_result.model.PageResultModel;
/**
* 分頁返回結果工具類
* @author Erwin Feng[xfsy_2015@163.com]
* @since 2019/12/1 20:32
*/
public class PageResultUtils {
/**
* 成功，攜帶分頁相關資料以及資訊
* @param data 資料
* @param total 資料總條數
* @param size 每頁條數
* @param pages 總頁數
* @param current 當前頁
* @param <T> 資料型別
* @return {@link PageResultModel}
*/
public static <T> PageResultModel<T> success(T data, long total, int size, long pages, long current) {
return PageResultHelper.success("Success", data, total, size, pages, current);
}
}
解析返回結果示例
這裡補充一下，關於如何解析返回的json字串，談談我的看法吧。返回的是一個json格式的字串，這裡我用fastjson來寫解析示例。我們通常會將請求資料封裝為一個通用方法或者工具類，只需要返回資料，當然，如果失敗，或者出現異常，都在這裡處理。
常用返回結果解析示例
/**
* 解析常用返回結果示例
* @return 資料
*/
public Object parseResult() {
String result = "";
ResultModel<?> resultModel = JSON.parseObject(result, ResultModel.class);
Boolean success = resultModel.getSuccess();
if (success != null && success) {
return resultModel.getData();
} else {
// 異常資訊
String message = resultModel.getMessage();
// 異常處理
throw new DataParseException(message);
}
}
介面返回結果解析示例
/**
* 解析介面返回結果示例
* @return 資料
*/
public Object parseApiResult() {
String apiResult = "";
ApiResultModel<?, ?> apiResultModel = JSON.parseObject(apiResult, ApiResultModel.class);
Boolean success = apiResultModel.getSuccess();
if (success != null && success) {
return apiResultModel.getData();
} else {
Object code = apiResultModel.getCode();
String message = apiResultModel.getMessage();
// 根據介面錯誤碼分別進行處理
// ...
return null;
}
}
分頁返回結果解析示例
這裡與上面略有不同，因為，增加了一些欄位，所以，我們可以藉助bean來返回。
/**
* 解析分頁返回結果示例
* @return {@link PageResultDataBean}
*/
public PageResultDataBean parsePageResult() {
String pageResult = "";
PageResultModel<List<?>> pageResultModel = JSON.parseObject(pageResult, PageResultModel.class);
Boolean success = pageResultModel.getSuccess();
if (success != null && success) {
List<?> data = pageResultModel.getData();
Long total = pageResultModel.getTotal();
Integer size = pageResultModel.getSize();
Long pages = pageResultModel.getPages();
Long current = pageResultModel.getCurrent();
return new PageResultDataBean()
.setTotal(total)
.setSize(size)
.setPages(pages)
.setCurrent(current)
.setData(data);
} else {
// 異常資訊
String message = pageResultModel.getMessage();
// 異常處理
throw new DataParseException(message);
}
}
以上，這一切都是否如你所願呢？歡迎評論留言告訴我。
連結
[1]
[2]
[3]
[4]
來自 “ ITPUB部落格 ” ，連結：http://blog.itpub.net/4830/viewspace-2824394/，如需轉載，請註明出處，否則將追究法律責任。
相關文章
- API介面開發規範API
- Laravel 使用 passport 開發 API 介面LaravelPassportAPI
- 微信開發介面API協議API協議
- API介面開發簡述示例API
- 智慧手錶開發API介面API
- F5 api介面開發實戰（一）API
- 專案開發必備API介面API
- 快速開始api開發（三）第一個介面-註冊API
- 使用Express開發小說API介面服務1.0（一）ExpressAPI
- 淺談 PHP 與手機 APP 開發（API 介面開發）PHPAPPAPI
- Laravel RESTFul API 模組化開發解決方案LaravelRESTAPI
- 尋找寫程式碼感覺（六）之列表查詢介面開發及返回結果的統一處理
- Spring Boot入門(四)：開發Web Api介面常用註解總結Spring BootWebAPI
- 好用的API介面，開發效率的利器API
- 用express+mongoose快速開發API介面ExpressGoAPI
- 開發常用的好用api介面彙總API
- 專案開發必備API介面集合API
- 介面開發-restfulREST
- fiddler 修改請求介面的返回結果
- 示例淺談PHP與手機APP開發，即API介面開發PHPAPPAPI
- 淺談使用 PHP 進行手機 APP 開發（API 介面開發）PHPAPPAPI
- SpringBoot整合Redis開發RESTful API介面Spring BootRedisRESTAPI
- 淘寶 API 介面：助力電商應用快速開發API
- 熱門免費API介面助力快速開發API
- python 開發介面Python
- 用 Django 開發介面Django
- 免費API介面：讓開發更簡單更快API
- 使用Express開發小說API介面服務1.0(二)ExpressAPI
- 使用Express開發小說API介面服務1.0（三）ExpressAPI
- 介面返回[object,Object]解決方法Object
- 物流APP開發解決方案APP
- 高併發下的介面冪等性解決方案！
- 微信開發之JSSDK介面開發（Java）JSJava
- 商城系統API定製開發_商城API介面設計_OctShopAPI
- F5 api介面開發實戰手冊（二）API
- PHP開發api介面，如何做才算是安全的PHPAPI
- 線上支付介面申請和開發(一)
- 04.開發REST 介面REST