接口数据返回---标准格式

Posted 2021-10-19 jpfss

开发中，如果前端和后端，在没有统一返回数据格式，我们来看一下会发生什么：

后台开发人员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=这是自定义的数据}