一、命名约定
1.1 类命名约定
实体对象命名
数据对象类：DO后缀 例如：UserDO
传输对象类：DTO后缀 例如：UserDTO
传输请求参数类：ReqDTO后缀 例如：UserReqDTO
传输返回结果类：RspDTO后缀 例如：UserRspDTO
视图对象类：VO后缀 例如：UserVO
视图请求类：ReqVO后缀 例如：UserReqVO
视图返回结果类：RspVO后缀 例如：UserRspVO
控制器类命名
查询类控制器：QryController后缀 例如：UserQryController
操作类控制器：CmdController后缀 例如：UserCmdController
类型转换器类命名：Convertor后缀 例如：UserConvertor
验证器类命名：Validator后缀 例如 : AuthValidator
数据库映射类命名：Mapper后缀 例如：UserMapper
服务接口类命名：Service后缀 例如：UserService
服务接口实现类命名：ServiceImpl后缀 例如：UserServiceImpl
远程调用类命名：Remote后缀 例如：UserRemote
1.2 方法命名约定
CRUD方法命名约定如下
新增：create 例如：createAuthRecord
添加：add 例如：addUser
删除：remove、delete 例如：removeUser
修改：update 例如：updateUser
查询(单个)：get 例如：getById
查询(列表)：list 例如：listByType
查询(分页)：page 例如：pageRecord
统计：count 例如：countByDay
1.3 常量约定
代码中禁止使用魔法值如：1，2，3,"01",如需要使用特定值，定义成常量或枚举 例如：
private static final Integer SYS_ADMIN = 1;
1.4 错误码约定
系统错误码使用枚举或常量，优先使用枚举 如:SysCodeEnum
数据库错误以DB开头 如：
DB_INSERT_ERROR(1101001, "DB_INSERT_ERROR", "DB插入数据失败")
参数错误以PARAM开头 如:
PARAM_AUTH_NULL_ERROR(1301000, "PARAM_AUTH_NULL_ERROR", "认证信息为空"),
业务错误以业务名称开头 如：
USER_UNAUTH_ERROR(1201000, "USER_UNAUTH_ERROR", "用户不能进行再次认证"),
二、代码约定
2.1 服务调用链
网关(gateway)->业务聚合(business)->微服务(microservice)
2.2 代码结构
2.2.1 业务聚合服务
controller：控制器
service：业务聚合服务接口
service.impl：业务聚合服务实现
vo：视图对象
convertor：转换器
validator：验证器
util：工具类
integration：三方二方接口
interceptor：拦截器
2.2.2 原子服务
controller：控制器
service：业务聚合服务接口
service.impl：业务聚合服务实现
entity：数据库对象
convertor：转换器
validator：验证器
util：工具类
integration：三方二方接口
mapper：数据库映射
下面为复杂业务需要聚合原子service简单服务无需使用
biz.core：聚合多个底层service
biz.service：提供复杂业务实现
biz.facede：对外统一接口
2.3 代码编写约定
2.3.1 VO、DTO、DO使用
VO：前端传输使用主要应用于business服务中的Controller类
DTO：业务聚合服务调用原子服务时使用,多为原子服务Controller类的请求参数和返回结果
DO：数据映射类Mapper类使用
2.3.2 服务调用约定
服务方返回：Response<T>
示例：
@RequestMapping(value = MemberConstants.MEMBER_AUTH_LONGINFO_REQ_PATH, method = RequestMethod.POST)
public Response<AuthUserRspDTO> getAuthUser(@RequestParam(value = "phone", required = true)String phone){
String serviceName = "AuthQryController.getAuthUser";
return webActionTemplate.execute(new AbstractWebAction<AuthUserRspDTO, String>(serviceName,phone) {
@Override
public void validateParams(String param) throws BizException {
AuthQryValidator.doValidQryParam(param);
}
@Override
public AuthUserRspDTO doAction(String param) throws BizException {
AuthUserBO authUserBO = authUserQryService.getAuthUser(param);
AuthUserRspDTO rspDTO = AuthUserConvertor.bo2DTO(authUserBO);
return rspDTO;
}
});
}
调用方处理：
public AuthUserRspDTO getAuthUser(String phone) {
Response<AuthUserRspDTO> rspRst = authRemote.getAuthUser(phone);
if(rspRst == null){
throw new RuntimeException("用户服务获取认证用户信息远程调用返回异常");
}
if(!rspRst.isSuccess()){
throw new RuntimeException("用户服务获取认证用户信息远程调用失败");
}
return rspRst.getData();
}
2.3.3 常见的业务处理步骤可参考如下，实际处理根据业务需要酌情修改
public Integer createAuth(AuthUserBO userBo) {
Map<String, Object> bizData = new HashMap<>();
//业务验证
doVaildAuth(userBo, bizData);
//防重验证
doCheckRepeat(userBo);
//组装处理数据
doHandleData(userBo, bizData);
//三方服务调用
doInvokeRemote(userBo, bizData);
//数据库处理
doCommitDBAuth(bizData);
//事件发送
doPublishEvent(bizData);
return SUCCESS_CODE;
}
2.3.4 通用的业务处理模板可参考如下，实际处理根据业务需要酌情修改
public FacadeResponse doTrigger(FacadeRequest req) {
FacadeResponse response = new FacadeResponse();
Map<String,Object> bizMap = new HashMap<>();
//参数验证
doCheck(req);
//防重验证
boolean reapet = doRepeat(req);
if(reapet){
response.setSuccess(true);
logger.info("[AbstractActionFacade.doReapet] request:{},response:{}"
,JSON.toJSONString(req),JSON.toJSONString(response));
return response;
}
//业务验证
boolean checkBizRst = doCheckBiz(req,bizMap);
if(!checkBizRst){
response.setSuccess(false);
logger.info("[AbstractActionFacade.doCheckBiz] check fail request:{},response:{}"
, JSON.toJSONString(req),JSON.toJSONString(response));
return response;
}
try {
//数据组装
doAssemble(req, bizMap);
//三方调用
doInvokeRemote(req, bizMap);
//数据库提交
transactionTemplate.execute(new TransactionCallbackWithoutResult() {
@Override
protected void doInTransactionWithoutResult(TransactionStatus status) {
doCommitDatabase(req, bizMap);
}
});
//发布事件
doPublishEvent(req, bizMap);
//通知
doNotify(req, bizMap);
response.setSuccess(true);
}catch (BizException ex) {
doPublishErrorEvent(req, bizMap);
response.setSuccess(false);
logger.error("[AbstractActionFacade.BizException] message:{}", ExceptionTracker.trace(ex));
throw ex;
}catch (TransactionSystemException ex){
logger.error("[AbstractActionFacade.TransactionSystemException] transaction error message:{}",ExceptionTracker.trace(ex));
throw new BizException(SysCodeEnum.DB_TRANSACTION_ERROR);
}catch (RuntimeException ex){
doPublishErrorEvent(req, bizMap);
response.setSuccess(false);
logger.error("[AbstractActionFacade.RuntimeException] message:{}",ExceptionTracker.trace(ex));
throw ex;
}catch (Exception ex){
doPublishErrorEvent(req, bizMap);
response.setSuccess(false);
logger.error("[AbstractActionFacade.Exception] message:{}",ExceptionTracker.trace(ex),ex);
throw ex;
}
return response;
}
protected abstract boolean doRepeat(FacadeRequest req) throws BizException;
protected abstract boolean doCheckBiz(FacadeRequest req,Map<String,Object> bizMap)throws BizException;
protected abstract void doAssemble(FacadeRequest req,Map<String,Object> bizMap)throws BizException;
protected abstract void doInvokeRemote(FacadeRequest req,Map<String,Object> bizMap)throws BizException;
protected abstract void doCommitDatabase(FacadeRequest req,Map<String,Object> bizMap)throws BizException;
protected abstract void doPublishEvent(FacadeRequest req,Map<String,Object> bizMap)throws BizException;
protected abstract void doNotify(FacadeRequest req,Map<String,Object> bizMap)throws BizException;
protected abstract void doPublishErrorEvent(FacadeRequest req,Map<String,Object> bizMap);
三、错误处理
3.1 定时任务
3.1.1 业务需要逐条处理的定时任务酌情增加重试次数，防止定时任务无效轮询或任务被阻塞
3.2 远程调用
3.2.1 比较重要的远程调用特定的出错场景增加重试功能
四、数据库约定
4.1 多表关联
SQL编写时不建议多表关联，优先单表查询应用程序中进行组装
五、日志约定
日志使用SLF4J中的API不要使用log4j、logbak这些具体的API
