前言:
之前寒假做互联网+项目的时候,看到组长的后端api接口写得那叫一个优雅;
在分布式、微服务盛行的今天，绝大部分项目都采用的微服务框架，前后端分离方式。题外话：前后端的工作职责越来越明确，现在的前端都称之为大前端，技术栈以及生态圈都已经非常成熟；以前后端人员瞧不起前端人员，那现在后端人员要重新认识一下前端，前端已经很成体系了。
现代系统架构:
一般系统的大致整体架构图如下：
接口交互
前端和后端进行交互，前端按照约定请求URL路径，并传入相关参数，后端服务器接收请求，进行业务处理，返回数据给前端。
针对URL路径的restful风格，以及传入参数的公共请求头的要求（如：app_version,api_version,device等），老顾这里就不介绍了，小伙伴们可以自行去了解，也比较简单。
着重介绍一下后端服务器如何实现把数据返回给前端？
返回格式
后端返回给前端我们一般用JSON体方式，定义如下：
{
#返回状态码
code:integer,
#返回信息描述
message:string,
#返回值
data:object
}CODE状态码
code返回状态码，一般小伙伴们是在开发的时候需要什么，就添加什么。
如接口要返回用户权限异常，我们加一个状态码为101吧，下一次又要加一个数据参数异常，就加一个102的状态码。这样虽然能够照常满足业务，但状态码太凌乱了
我们应该可以参考HTTP请求返回的状态码，下面是常见的HTTP状态码传送门：
200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。分类 | 区间 | 分类描述 |
100 | 100~199 | 信息，服务器收到请求，需要请求者这执行操作 |
200 | 200~299 | 成功，操作被成功接受并处理 |
300 | 300~399 | 重定向，需要进一步的操作以完成请求 |
400 | 400~499 | 客户端错误，请求包含语法错误或无法完成请求 |
500 | 500~599 | 服务器的错误，服务器在处理请求的过程中发生了错误 |
规定:
#1表示成功
#1001～1999 区间表示参数错误
#2001～2999 区间表示用户错误
#3001～3999 区间表示接口异常这样前端开发人员在得到返回值后，根据状态码就可以知道，大概什么错误，再根据message相关的信息描述，可以快速定位。
Message
这个字段相对理解比较简单，就是发生错误时，如何友好的进行提示。一般的设计是和code状态码一起设计，如
import lombok.experimental.Accessors;
/**
* 规定:
* #1表示成功
* #1001～1999 区间表示参数错误
* #2001～2999 区间表示用户错误
* #3001～3999 区间表示接口异常
* 统一错误枚举类
*/
@Accessors(chain = true)
public enum ResultCode {
/* 成功 */
SUCCESS(200, "成功"),
/* 默认失败 */
COMMON_FAIL(999, "失败"),
CUSTOM_FAIL(9999, "自定义错误"),
/* 参数错误：1000～1999 */
PARAM_NOT_VALID(1001, "参数无效"),
PARAM_IS_BLANK(1002, "参数为空"),
PARAM_TYPE_ERROR(1003, "参数类型错误"),
PARAM_NOT_COMPLETE(1004, "参数缺失"),
FAIL_COPY_PROPERTIES(1076, "创建对象失败或拷贝对象属性失败"),
/* 微信小程序登录 */
WEI_XIN_CODE_ERROR(3001, "携带code向小程序请求失败"),
WEI_XIN_SKEY_VALID(3002, "skey无效"),
/* 用户错误 */
USER_NOT_LOGIN(2001, "用户未登录"),
USER_ACCOUNT_EXPIRED(2002, "账号已过期"),
USER_CREDENTIALS_ERROR(2003, "密码错误"),
USER_CREDENTIALS_EXPIRED(2004, "密码过期"),
USER_ACCOUNT_DISABLE(2005, "账号不可用"),
USER_ACCOUNT_LOCKED(2006, "账号被锁定"),
USER_ACCOUNT_NOT_EXIST(2007, "账号不存在"),
USER_ACCOUNT_ALREADY_EXIST(2008, "账号已存在"),
USER_ACCOUNT_USE_BY_OTHERS(2009, "账号下线"),
USER_IS_EMPTY(2010, "用户为空"),
/*Token错误*/
TOKEN_EXPIRED(4001, "登陆信息过期"),
TOKEN_ERROR(4002, "信息被更改,请重新登陆"),
/* 业务错误 */
NO_PERMISSION(5001, "没有权限"),
/*订单错误*/
EXISTED_ORDER(6001, "该商品的订单已存在，请支付或取消后再重新下单"),
/*商品错误*/
EXISTED_GOOD(7001, "已存在该商品"),
EXISTED_GOOD_INCART(7002,"购物车中已经存在该商品"),
/*招投标错误*/
EXISTED_SUBMISSION(8001,"已经存在该投标了"),
EXISTED_INVITATION(8002,"已经存在该招标了");
private Integer code;
private String message;
ResultCode(Integer code, String message) {
this.code = code;
this.message = message;
}
public Integer getCode() {
return code;
}
public ResultCode setCode(Integer code) {
this.code = code;
return this;
}
public String getMessage() {
return message;
}
public ResultCode setMessage(String message) {
this.message = message;
return this;
}
/**
* 根据code获取message
*
* @param code 状态码
* @return String
*/
public static String getMessageByCode(Integer code) {
for (ResultCode ele : values()) {
if (ele.getCode().equals(code)) {
return ele.getMessage();
}
}
return null;
}
}状态码和信息就会一一对应，比较好维护。
DATA
返回数据体，JSON格式，根据不同的业务又不同的JSON体。
我们要设计一个返回体类Result
import java.io.Serializable;
public class CommonResult<T> implements Serializable {
private Boolean succeed;
private Integer code;
private String message;
private T data;
public CommonResult() {
}
public CommonResult(boolean succeed) {
this.succeed = succeed;
this.code = succeed ? ResultCode.SUCCESS.getCode() : ResultCode.COMMON_FAIL.getCode();
this.message = succeed ? ResultCode.SUCCESS.getMessage() : ResultCode.COMMON_FAIL.getMessage();
}
public CommonResult(boolean succeed, ResultCode resultEnum) {
this.succeed = succeed;
this.code = succeed ? ResultCode.SUCCESS.getCode() : (resultEnum == null ? ResultCode.COMMON_FAIL.getCode() : resultEnum.getCode());
this.message = succeed ? ResultCode.SUCCESS.getMessage() : (resultEnum == null ? ResultCode.COMMON_FAIL.getMessage() : resultEnum.getMessage());
}
public CommonResult(boolean succeed, T data) {
this.succeed = succeed;
this.code = succeed ? ResultCode.SUCCESS.getCode() : ResultCode.COMMON_FAIL.getCode();
this.message = succeed ? ResultCode.SUCCESS.getMessage() : ResultCode.COMMON_FAIL.getMessage();
this.data = data;
}
public CommonResult(boolean succeed, ResultCode resultEnum, T data) {
//如多成功true,就走成功的code和message,否者就看传进来的resultEnum
this.succeed = succeed;
this.code = succeed ? ResultCode.SUCCESS.getCode() : (resultEnum == null ? ResultCode.COMMON_FAIL.getCode() : resultEnum.getCode());
this.message = succeed ? ResultCode.SUCCESS.getMessage() : (resultEnum == null ? ResultCode.COMMON_FAIL.getMessage() : resultEnum.getMessage());
this.data = data;
}
public Boolean getSucceed() {
return succeed;
}
public void setSucceed(Boolean succeed) {
this.succeed = succeed;
}
public Integer getCode() {
return code;
}
public void setCode(Integer code) {
this.code = code;
}
public String getMessage() {
return message;
}
public void setMessage(String message) {
this.message = message;
}
public T getData() {
return data;
}
public void setData(T data) {
this.data = data;
}
@Override
public String toString() {
return "CommonResult{" +
"succeed=" + succeed +
", code=" + code +
", message='" + message + '\'' +
", data=" + data +
'}';
}
}控制层Controller
我们会在controller层处理业务请求，并返回给前端，以下面的材料查询为例:
@GetMapping("/details/{id}")
public CommonResult<GoodDetailInfoVO> getDetailsByGoodId(@PathVariable Long id) {
GoodDetailInfoVO goodDetailInfoVO = goodService.getGoodDetailById(id);
CommonResult<GoodDetailInfoVO> result = new CommonResult<>(true,ResultCode.SUCCESS,goodDetailInfoVO);
return result;
}如果加上结果封装类ResultUtil类:
public class ResultUtil {
public static CommonResult success() {
return new CommonResult(true);
}
public static <T> CommonResult<T> success(T data) {
return new CommonResult(true, data);
}
public static CommonResult fail() {
return new CommonResult(false);
}
public static CommonResult fail(ResultCode resultEnum) {
return new CommonResult(false, resultEnum);
}
}材料查询就可以变成这样(更加简洁了):
@GetMapping("/detail/{id}")
public CommonResult<GoodDetailInfoVO> getDetailByGoodId(@PathVariable Long id) {
return ResultUtil.success(goodService.getGoodDetailById(id));
}代码比较简洁了，也美观了。
到这里一般都满足日常开发的需求了如果还需要更简洁的话,可以参考以下内容:
优雅优化
上面我们看到在Result类中增加了静态方法，使得业务处理代码简洁了。但小伙伴们有没有发现这样有几个问题：
1、每个方法的返回都是Result封装对象，没有业务含义
2、在业务代码中，成功的时候我们调用Result.success，异常错误调用Result.failure。是不是很多余
3、上面的代码，判断id是否为null，其实我们可以使用hibernate validate做校验，没有必要在方法体中做判断。
我们最好的方式直接返回真实业务对象，最好不要改变之前的业务方式，如下图
实现方案
小伙伴们怎么去实现是不是有点思路，在这个过程中，我们需要做几个事情
- 1、定义一个注解@ResponseResult，表示这个接口返回的值需要包装一下
- 2、拦截请求，判断此请求是否需要被@ResponseResult注解
- 3、核心步骤就是实现接口ResponseBodyAdvice和@ControllerAdvice，判断是否需要包装返回值，如果需要，就把Controller接口的返回值进行重写。
注解类
用来标记方法的返回值，是否需要包装
拦截器
拦截请求，是否此请求返回的值需要包装，其实就是运行的时候，解析@ResponseResult注解
此代码核心思想，就是获取此请求，是否需要返回值包装，设置一个属性标记。
重写返回体
上面代码就是判断是否需要返回值包装，如果需要就直接包装。这里我们只处理了正常成功的包装，如果方法体报异常怎么办？处理异常也比较简单，只要判断body是否为异常类。
怎么做全局的异常处理，篇幅原因，这里就不做介绍了，只要思路理清楚了，自行改造就行。
重写Controller
在控制器类上或者方法体上加上@ResponseResult注解，这样就ok了，简单吧。到此返回的设计思路完成，是不是又简洁，又优雅。
总结
这个方案还有没有别的优化空间，当然是有的。如：每次请求都要反射一下，获取请求的方法是否需要包装，其实可以做个缓存，不需要每次都需要解析。当然整体思路了解，小伙伴们就可以在此基础上面自行扩展。谢谢！！！
欢迎点赞关注哦！
