接口规范

基础接口规范前言

该接口规范旨在达到以下目的

  • 接口请求参数规范
  • 接口响应参数规范
  • 请求参数校验规范
  • 通用异常处理规范

适用场景

  • 模块间服务接口调用
  • 前端 REST 服务接口调用

接口返回值规范

所有对外服务接口必须使用 Result Bean 封装响应的结果

响应基类BaseResult

public class BaseResult<T> implements IResult {
private Boolean isSuccess;// 本次调用是否成功
private IStatusCode code;// 状态编码
private String message = "";//
private String stackTrace = "";
...
}

通用响应类

public class ResultMsg<T> extends BaseResult<T>{
private T data = null; // 返回数据
/**成功,有结果数据 * @param data */
public ResultMsg(T result){
this.setIsSuccess(true);
this.setData(result);
}
...
}

分页类型响应类

public class PageResult<T> extends BaseResult<T>{
private Integer pageSize = 0;//分页大小
private Integer page = 1;//当前页
private Integer total = 0;//总条数
private List rows = null;//分页列表数据
...

响应码规范

响应需要有对应的响应码,对于业务异常、系统可预知异常需要定义好异常码,并使用 包装异常 ,不同模块需要定义自身的异常枚举,并实现接口IStatusCode

/**
* @说明 系统状态码定义抽象接口<br>
* 子模块或者系统需要定义自己的系统状态码<br>
* @StatusCode 为基础模块定义的基本码值,1~500 目前已经被占用
* @author jeef
*
*/
public interface IStatusCode {
/**
* 状态码
* @return
*/
public String getCode() ;
/**
* 异常信息
* @return
*/
public String getMsg() ;

/**
* 系统编码
* @return
*/
public String getSystem() ;

}

基础响应码实现

/**
* @说明 基础系统状态码定义
*/
public enum StatusCode implements IStatusCode{

SUCCESS("200","成功"),
SYSTEM_ERROR("500","系统异常"),
TIMEOUT("401","访问超时"),
NO_ACCESS("403","访问受限"),
PARAM_ILLEGAL("100","参数校验不通过");

private String code;
private String msg;
private String system;

StatusCode(String code,String msg){
this.setCode(code);
this.setMsg(msg);
this.setSystem("BASE");
}

public String getCode() {
return code;
}
....
}

异常定义规范

AgileBPM 异常定义均在 com.dstz.base.api.exception 包,各个业务模块不需要定义特殊的异常类,均通过异常码来标识异常!
异常分三种

  • 业务消息 BusinessMessage
  • 业务异常 BusinessException
  • 系统异常BusinessError

业务消息异常

通常为直接通知用户 业务消息,通常用于业务代码反馈,非系统异常!
如,保存用户时,后端校验 账号已存在 ,可以直接抛出业务异常 BusinessMessage ,并返回定义好的状态码

普通异常

业务逻辑异常,常常为可预料异常情况的抛出或者非法操作的信息提示。比如: 流程表单丢失!

系统异常

BusinessError 系统异常,常常用于强制捕获的异常的包装,是相对紧急程度高或者比较严重异常

所有异常均会中断事务,业务消息不会记录异常堆栈、日志 ,会直接提示到前端用户错误信息
其他则会详细记录请求信息、堆栈信息,并返回异常码,不会返回具体异常信息,前端应给予“系统服务异常”的提示