API接口开发(一):接口开发回来作用解决方案

摘要

选用前后端别离的办法来进行项目开发,那么前后端交互比较好的办法是选用HTTP+JSON。怎样接口回来作用愈加简练,愈加高雅,也愈加合理,而且让前端开发人员看得了解,后端开发者也并不会因此而增加作业量呢?

正文开始

Hello,各位,良久不见了。一直在策划个人网站2020版别改版的作业,所以,本篇文章,也是2019年毕竟一篇了,当然,也得花一些心思,争夺把我想要说的话,都逐个说出来,说了解,说透彻。

选用前后端别离的办法来进行项目开发,那么前后端交互比较好的办法是选用HTTP+JSON。怎样接口回来作用愈加简练,愈加高雅,也愈加合理,而且让前端开发人员看得了解,后端开发者也并不会因此而增加作业量呢?

为此,我写了一套关于API接口开发回来作用解决方案, api-result,已将其开源,并上传到中心库房,欢迎各位批判和纠正。

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"
}

运用示例

示例图

查验接口预览

API接口开发(一):接口开发回来作用解决方案

Models

API接口开发(一):接口开发回来作用解决方案

回来成功作用示例

/**
* 删去办法示例
* @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] api-result源码 | github

[2] api-result源码 | 码云

[3] api-result中心库房

[4] 查验示例代码