外观
接口标准&异常规范
接口标准
接口分为两类，内部接口和HTTP REST接口
内部接口
内部接口为模块(ab-xxx-api)下所定义的，它的调用者为其他模块。
规范
- 方法的入参和出参禁止定义为Map类型。
- 接口内的方法应编写对应的注释。
- 接口方法参数过长应使用对象封装。
- 参数对象属性类型禁止使用枚举。
HTTP REST 接口
应用对外暴露的接口，外部通过HTTP远程调用提交和获取数据。
规范
- POST方式提交的数据，统一为对象并用
@RequestBody标记接收。 - 接口响应统一使用
ApiResponse包装。 - 接口声明响应数据类型。
示例
@PostMapping(value = "/xxx", produces = MediaType.APPLICATION_JSON_VALUE)
public ApiResponse<Void> xxx(@RequestBody Xxx xxx){
return ApiResponse.success(xxx);
}
ApiResponse 数据结构
json
{
"isOk":false, // 请求结果
"code":"token_invalid", // 请求状态码
"message":"登录超时", // 状态描述
"data": T // 返回数据结构
}
接口状态码
描述接口执行出错预知状态封装，各模块都应有自己的状态码定义，统一实现基础接口com.dstz.base.common.codes.IBaseCode。
状态码（code）规范:
- 多单词驼峰命名，单词首字母大写。
- 取名应有含义。
全局状态码
public enum GlobalApiCodes implements IBaseCode {
/**
* 操作成功
*/
SUCCESS("Success", "操作成功"),
/**
* Illegal parameters.
*/
PARAMETER_INVALID("ParameterInvalid", "Illegal parameters {}"),
/**
* Parameter unallowed.
*/
PARAMETER_UNALLOWED("ParameterUnallowed", "Parameter not allowed {}"),
private final String code;
private final String message;
GlobalApiCodes(String code, String message) {
this.code = code;
this.message = message;
}
@Override
public String getCode() {
return code;
}
@Override
public String getMessage() {
return message;
}
}
异常规范
系统定义了两类异常，业务异常（BusinessException）、业务信息（BusinessMessage）。
业务异常（BusinessException）
业务逻辑性执行出错，可预料到的错误。例如：流程表单缺失。
业务消息（BusinessMessage）
反馈给用户的信息提示，例如：某账户已存在
注意
上述的异常抛出，代码都会中断执行，并回滚当前事务。
异常的捕获处理在Controller层，对于业务消息(BusinessMesage)类，系统不做异常记录，在解析状态码后直接返回给调用方。