接口数据返回---标准格式
2019-11-27 本文已影响0人
奇点一氪
开发中，如果前端和后端，在没有统一返回数据格式，我们来看一下会发生什么：
后台开发人员A，在接口返回时，习惯返回一个返回码code=0000,然后返回数据；
后台开发人员B，在接口返回时，习惯直接返回一个boolean类型的success=true，然后返回数据；
后台开发人员C，在接口返回时，习惯在接口失败时返回码为code=0000。
可以看到，上面的三个开发人员，都没有大问题，没有谁对谁错，只要给前端接口文档，前端都是可以接上接口的。但是，在项目功能越来越多，接口数量持续增长时，对开发人员而言，就是一种灾难，同一个前端，如果对接A和C，那她接接口时会很崩溃。因为返回的code，同样是0000，但是一个代表成功，一个代表失败，这时前端就会去找两个人沟通，看可不可以统一一下，但是两个人一看，最近写了几十个接口了，还和别人对接过，牵一发动全身，没法做改动了。看，这就是灾难。
所以，在项目开发中，初期搭建框架时，定好通用的接口数据返回格式，定义好全局的状态码，是非常有必要的。一个项目，甚至整个公司，遵循同一套接口返回格式规范，这样可以极大的提高进度，降低沟通成本。
下面的两个类，一个是数据返回格式，是自定义的，很简单，但是可通用，这里分享一下，返回给前端时，根据情况，直接调用此类中的方法做返回值；另一个是状态码，这个可以根据项目实际情况，自己做修改。
接口数据返回格式：
package response;
import domain.ReturnCode;
/**
* Created by lightClouds917
* Date 2017/11/10
* Description:接口统一返回格式
*/
public class ResponseWrapper {
/**是否成功*/
private boolean success;
/**返回码*/
private String code;
/**返回信息*/
private String msg;
/**返回数据*/
private Object data;
/**
* 自定义返回结果
* 建议使用统一的返回结果，特殊情况可以使用此方法
* @param success
* @param code
* @param msg
* @param data
* @return
*/
public static ResponseWrapper markCustom(boolean success,String code,String msg,String data){
ResponseWrapper responseWrapper = new ResponseWrapper();
responseWrapper.setSuccess(success);
responseWrapper.setCode(code);
responseWrapper.setMsg(msg);
responseWrapper.setData(data);
return responseWrapper;
}
/**
* 参数为空或者参数格式错误
* @return
*/
public static ResponseWrapper markParamError(){
ResponseWrapper responseWrapper = new ResponseWrapper();
responseWrapper.setSuccess(false);
responseWrapper.setCode(ReturnCode.PARAMS_ERROR.getCode());
responseWrapper.setMsg(ReturnCode.PARAMS_ERROR.getMsg());
return responseWrapper;
}
/**
* 查询失败
* @return
*/
public static ResponseWrapper markError(){
ResponseWrapper responseWrapper = new ResponseWrapper();
responseWrapper.setSuccess(false);
responseWrapper.setCode(ReturnCode.FEAILED.getCode());
responseWrapper.setMsg(ReturnCode.FEAILED.getMsg());
responseWrapper.setData(null);
return responseWrapper;
}
/**
* 查询成功但无数据
* @return
*/
public static ResponseWrapper markSuccessButNoData(){
ResponseWrapper responseWrapper = new ResponseWrapper();
responseWrapper.setSuccess(true);
responseWrapper.setCode(ReturnCode.NODATA.getCode());
responseWrapper.setMsg(ReturnCode.NODATA.getMsg());
responseWrapper.setData(null);
return responseWrapper;
}
/**
* 查询成功且有数据
* @param data
* @return
*/
public static ResponseWrapper markSuccess(Object data){
ResponseWrapper responseWrapper = new ResponseWrapper();
responseWrapper.setSuccess(true);
responseWrapper.setCode(ReturnCode.SUCCESS.getCode());
responseWrapper.setMsg(ReturnCode.SUCCESS.getMsg());
responseWrapper.setData(data);
return responseWrapper;
}
public boolean isSuccess() {
return success;
}
public void setSuccess(boolean success) {
this.success = success;
}
public Object getData() {
return data;
}
public void setData(Object data) {
this.data = data;
}
public String getMsg() {
return msg;
}
public void setMsg(String msg) {
this.msg = msg;
}
public String getCode() {
return code;
}
public void setCode(String code) {
this.code = code;
}
@Override
public String toString() {
return "ResponseWrapper{" +
"success=" + success +
", code='" + code + '\'' +
", msg='" + msg + '\'' +
", data=" + data +
'}';
}
}
状态码
package domain;
/**
* Created by lightClouds917
* Date 2017/11/10
* Description:接口返回码和返回值
* 结合返回数据封装类ResponseWrapper，统一接口的数据返回格式
*/
public enum ReturnCode {
SUCCESS("0000","查询成功"),
NODATA("0001","查询成功无记录"),
FEAILED("0002","查询失败"),
ACCOUNT_ERROR("1000", "账户不存在或被禁用"),
API_NOT_EXISTS("1001", "请求的接口不存在"),
API_NOT_PER("1002", "没有该接口的访问权限"),
PARAMS_ERROR("1004", "参数为空或格式错误"),
SIGN_ERROR("1005", "数据签名错误"),
AMOUNT_NOT_QUERY("1010", "余额不够，无法进行查询"),
API_DISABLE("1011", "查询权限已被限制"),
UNKNOWN_IP("1099", "非法IP请求"),
SYSTEM_ERROR("9999", "系统异常");
private String code;
private String msg;
public String getCode() {
return code;
}
public String getMsg() {
return msg;
}
ReturnCode(String code, String msg) {
this.code = code;
this.msg = msg;
}
}
返回示例：
ResponseWrapper{success=true, code='0000', msg='查询成功', data=数据}
ResponseWrapper{success=true, code='0001', msg='查询成功无记录', data=null}
ResponseWrapper{success=false, code='0002', msg='查询失败', data=null}
ResponseWrapper{success=false, code='1004', msg='参数为空或格式错误', data=null}
ResponseWrapper{success=true, code='0000', msg='自定义msg', data=这是自定义的数据}
自定义项目状态码
package com.ibg.fund.base.exception.code;
/**
* 错误码列表（注：命名以"C_"开头）
*/
public class CodeConstants {
/** ---------- 系统 ---------- */
public static final Code C_10101000 = new Code("10101000", "系统异常");
public static final Code C_10101001 = new Code("10101001", "%s不能为空");
public static final Code C_10101002 = new Code("10101002", "%s");
public static final Code C_10101003 = new Code("10101003", "%s不能小于零");
public static final Code C_10101004 = new Code("10101004", "%s枚举转化失败");
public static final Code C_10101005 = new Code("10101005", "%s不存在");
public static final Code C_10101006 = new Code("10101006", "%s不正确");
public static final Code C_10101007 = new Code("10101007", "%s不能小于等于零");
public static final Code C_10101008 = new Code("10101008", "%s已存在");
public static final Code C_10101009 = new Code("10101009", "时间戳格式不对");
public static final Code C_10101010 = new Code("10101010", "%s现在是%s状态，不能设置为%s状态");
public static final Code C_10101011 = new Code("10101011", "请勿重复提交");
public static final Code C_10101012 = new Code("10101012", "[%s]长度必须在[%s]到[%s]之间");
public static final Code C_10101013 = new Code("10101013", "%s不能大于%s");
public static final Code C_10101014 = new Code("10101014", "[%s]数据格式不正确");
public static final Code C_10101015 = new Code("10101015", "乐观锁异常");
public static final Code C_10101016 = new Code("10101016", "数据校验失败");
public static final Code C_10121016 = new Code("10121016", "签名错误");
public static final Code C_10121017 = new Code("10121017", "生成请求报文签名异常");
public static final Code C_10121018 = new Code("10121018", "不可处理的逻辑分支");
public static final Code C_10121044 = new Code("10121044", "此用户有互金平台查询记录，不能提交进件");
public static final Code C_10121045 = new Code("10121045", "金额精度不符合要求");
public static final Code C_10121046 = new Code("10121046", "黑暗期，请稍后请求");
/** -----------还款----------- */
public static final Code C_20101000 = new Code("20101000", "重复请求，该笔还款交易已存在");
public static final Code C_20101001 = new Code("20101001", "申请还款金额与实际应还金额不一致");
public static final Code C_20101002 = new Code("20101002", "还款指定的划扣卡未绑定，请先绑卡");
public static final Code C_20101003 = new Code("20101003", "借款已还清，无需再次还款");
public static final Code C_20101004 = new Code("20101004", "快捷支付还款验证码已失效");
public static final Code C_20101005 = new Code("20101005", "快捷支付还款验证码校验失败");
public static final Code C_20101006 = new Code("20101006", "借款已有一笔还款在处理中，请等待上笔处理完成再发起新的还款");
public static final Code C_20101007 = new Code("20101007", "系统正在清算中，请稍后发起还款");
/** ---------- 用户 ---------- */
public static final Code C_30101001 = new Code("30101001", "用户%s资金账户已被禁用");
public static final Code C_30101002 = new Code("30101002", "用户%s可用金额%s不足以扣除金额%s");
public static final Code C_30101003 = new Code("30101003", "用户%s冻结金额%s不足以扣除金额%s");
public static final Code C_30101004 = new Code("30101004", "用户不属于当前渠道");
public static final Code C_30101005 = new Code("30101005", "用户不属于特殊资金账号");
/** --------借款 ---------- */
public static final Code C_40101000 = new Code("40101000", "借款金额[%s]必须为产品单份金额[%s]的整数倍");
public static final Code C_40101001 = new Code("40101001", "[%s]尚不支持");
public static final Code C_40101002 = new Code("40101002", "[%s]必须在[%s]到[%s]之间");
public static final Code C_40101003 = new Code("40101003", "单期综合服务费率不合理,导致服务费为负数");
public static final Code C_40101004 = new Code("40101004", "使用期望总还款额计算出的结果异常");
public static final Code C_40101005 = new Code("40101005", "追加贷%s金额必须为50的整数倍");
public static final Code C_40101006 = new Code("40101006", "借款未放款loanKey=%s");
public static final Code C_40101007 = new Code("40101007", "还款计划同步异常%s");
public static final Code C_40101008 = new Code("40101008", "还款计划每期的还款日均不能小于首期还款日");
public static final Code C_40101009 = new Code("40101009", "新网SDK异常-重试");
/** --------产品 ---------- */
public static final Code C_50101000 = new Code("50101000", "产品文件不能为空");
public static final Code C_50101001 = new Code("50101001", "产品文件导入失败");
public static final Code C_50101002 = new Code("50101002", "文件类型不正确");
/** --------充值／提现 ---------- */
public static final Code C_60101000 = new Code("60101000", "充值上报异常");
public static final Code C_60101001 = new Code("60101001", "充值上报处理中");
public static final Code C_60101002 = new Code("60101002", "提现金额大于账户余额");
/** --------复式记账 ---------- */
public static final Code C_70101000 = new Code("70101000", "复式记账修改账户获取锁失败");
/** --------账单 ---------- */
public static final Code C_80101000 = new Code("80101000", "账单还款不支持部分还款，还款金额不足");
public static final Code C_80101001 = new Code("80101001", "账单[%s]不存在");
public static final Code C_80101002 = new Code("80101002", "账单[%s]还款计划为空");
}
