Java后端微服务研发规范

·  阅读 1414

技术栈说明

在编写研发规范时,需要一定的技术栈说明,我们这里明确使用到的技术有:JDK8、SpringBoot、Dubbo、Zookeeper、MySQL5.7、MyBatis/MyBatisPlus、Redis、RabbitMQ、MongoDB、ELK、Sentry。

项目分层说明

项目分层说明

  • 前后端分离
  1. 前端采用AntDesign for Vuejs Pro
  2. 微前端架构:在一个基座上承载多个SPA应用,基座上有一些基础的能力,每个应用还可以导出组件和能力。
  • 后端微服务
  1. interfaces:包含dto\enums\publicservice-interface。其中enums中放本模块中的所有枚举类。如果不需要向外界提供RPC服务,就没有dto和publicservice
  2. services: 传统单体应用所有内容,包含vo, entity, controller, serviceInterface, serviceImpl,repository, dao, mapper, RabbitMQ\Redis\ES,publicserviceImpl。
    • vo: 定义前端接口的输入输出。
    • entity: 定义表的实体类,和数据库表一一对应。这里使用MyBatisPlus减少简单SQL的编写,提高开发效率。
    • controller: MVC controller层。
    • serviceInterface: 定义单体服务层接口。
    • serviceImpl: 单体服务层实现
    • dao: MyBatisPlus接口层。
    • repository: MyBatisPlus数据访问实现层,避免在单体服务层出现大量dao层的操作代码。也可以是RabbitMQ\Redis\ES操作数据的Repository实现类。
    • mapper: MyBatisPlus复杂查询的SQL Map。

项目分层编码说明

采用自上而下的逻辑说明每一个逻辑分层的主要职责。

  • 配置层:Web层相关配置、各自框架的JavaConfig、业务配置BusinessConfig等配置类。
  • Controller层:负责登录状态验证、权限验证、统一异常处理、统一返回值包装、LoginUser信息赋值、HTTP层缓存处理、输入验证等。只有此层可以从Cookie或Token中获取登录用户的状态,其他层只能依赖上层传递过来的入参来处理。
  • Dubbo Service层:Dubbo接口放在interfaces中,实现放在publicservice中,供其他领域服务调用。
  • 单体Service层:分接口和实现两个类,比如SystemUserService\SystemUserServiceImpl。主要负责业务逻辑处理、本地缓存或Redis缓存处理。如果是数据库资源操作相关代码比较多,建议下沉封装到Repository层,确保服务层主要描述业务逻辑。
  • Repository层: Dao接口或Redis, ES, MongoDB的包装,将相关资源操作逻辑代码封装在这里。
  • Dao层:MyBatisPlus层的接口。
  • Mapper: MyBatisPlus的Mapper文件,主要是需要定制化的一些SQL。使用了MyBatisPlus后,另一部分简单的CRUD操作不需要编写SQL。
  • Entity:放在services实现层中,定义表的实体类,和数据库表一一对应。
  • DTO: 放在interfaces接口层。只有需要向其他领域暴露服务的才有interfaces层。
  • VO: 放在services实现层,负责Web层的输入输出。该层可以按领域来划分包,做到清晰明了。

Web 层规范

在Web层,我们最需要处理的就是登录校验(@HasAuth)、权限校验(@HasFuction)、数据绑定(@RequestBody, @RequestParam)、数据校验(SpringValidation+HibernateValidator, @Validated, @Valid)、登录信息注入下传(@ControllerAdrivce+@InitBinder)、统一异常处理(@ControllerAdrivce+@ExceptionHandler)、统一返回结果DtoResult(@ControllerAdvice+ ResponseBodyAdvice)。

DubboService(publicservice)层规范

命名规范

  • 实体命名规范

Service/DAO & 领域模型等命名规约:XxxDTO, XxxEntity, XxxEnum, XxxConstants, XxxService, XxxServiceImpl, XxxServiceProxy dto:XxxDTO entity: XxxEntity 查询条件:XxxQueryFilter 分页查询条件: XxxPageQueryFilter 复合查询结果:XxxQueryResult

  • 方法命名规范:

    1. 分页查询列表时方法使用pageList开头,查询总数使用pageCount开头。
    2. 不分页查询列表使用list开头。
    3. 查询单个数据可以使用get开头,如getXX。
    4. 指定某个属性进行操作可以使用getByXX、deleteByXX、updateByXX。
  • 数据库命名规范

  1. 通用字段: 数据表必须有的几个字段:Id, CommonStatus, InUserId, InUserName, InDate, EditUserId, EditUserName, EditUserDate。CommonStatus标记数据有效性 0:无效,1:有效
  2. 数据表名用小写+下划线分割,字段名用UpperCamelCase风格命名(大驼峰法,单词首字母大写,比如通用字段CommonStatus)
  3. 业务逻辑唯一的字段或字段组织必须增加唯一索引确保唯一性,比如项目应用关联关系表project_intelli_app(Id, ProjectId, AppId, ..., CommonStatus,InUserId, InUserName, InDate, EditUserId, EditUserName, EditUserDate)中的字段组合ProjectId+AppId+CommonStatus必须唯一,那么一定要加上唯一索引UIX_ProjectId_AppId_CommonStatus(ProjectId,AppId,CommonStatus)
  4. 尽量做到字段不为空。让代码逻辑更清楚,比如避免OR\UNION ALL等。

尽量做到字段不为空

基类实体定义

  • 基类BaseVO
# 当前登录人的信息
Long userId
String userName
String userOrganizatonId;
String userOrganizatonCode;
复制代码
  • 基类UpdateStatusVO:BaseVO
# 单据系统编号
Long Id
# 数据状态
CommonStatusEnum commonStatus
复制代码
  • 分页查询基础QueryFilterVO
复制代码
  • 基类BaseEntity
# 单据系统编号
Long Id
# 数据状态
CommonStatusEnum commonStatus

# 操作人的信息
Long inUserId
String inUserName
Long editUserId
String editUserName
复制代码

其中的commonStatus\inUserId\inUserName\editUserId\editUserName使用MyBatisPlus的自动填充机制进行填充。

现在的项目都是前后端分离的。关于VO\DTO是否需要同时存在,我一直比较纠结。最终我发现,他们两个存在一定的重复性,我建议还是不要VO, 统一保留DTO和Entity两个概念就可以了。

项目具体结构

Maven Module 一般分为:

  1. xxx-xx-business #业务逻辑和数据访问层
  2. xxx-xx-interface #微服务相关
  3. xxx-xx-protal #前端相关
  4. xxx-xx-job #定时任务
  • Business Module
src/main/java/com/xxx/xxx/.../business #包目录 根据业务定义路径
  /config #配置类目录
	...
  /constant #常量类 存放业务定义的各种常量
	...
  /dao #存放数据访问层接口
	...
  /mapper #Mybatis Mapper文件
	...
  /entity #实体类目录 存放和数据库表结构一直的实体类
	...
  /enums #枚举类目录
	...
  /sevice # service层目录 存放service接口和实现
    /impl #存放接口实现类
	...
  /util #工具类目录
  	...
  /dto #存放dto类
    XXXQueryFilter #dao层查询使用的QueryFilter类,`*XXX*`和对应实体类命名一致
    XXXQueryResult #dao层查询返回结果包装类,`XXX`和对应实体类命名一致
    XXXVo #前端与Controller交互的Vo类,`XXX`和对应实体类命名一致
	...
复制代码
  • Interface Module
src/main/java/com/xxx/xxx/.../interfaces #包目录 根据业务定义路径
  /dto #数据传输对象目录,用于微服务间数据传输
    ...
  /constant #常量类,接口使用的常量
    ...
  /enums #枚举类目录,接口使用的枚举
    ...
  /service #微服务接口目录
	...
复制代码
  • Portal Module
src/main/java/com/xxx/xxx/.../portal #包目录 根据业务定义路径
 /config #配置类目录
  	...
 /controller #Controller层目录,按业务划分子目录,url前面需要带上路径 /api/XX XX为应用简称
	...
 /microservice #微服务接口的实现,url前面需要带上路径 /ms/XX
	...
 /mobile # 移动端api目录,按业务划分子目录,url前面需要带上路径 /m/XX 
	...
 /filter #过滤器
	...
 /interceptor #拦截器
   	...
src/test/ #测试用例目录
src/main/resources #存放配置文件或其他非Java类资源
复制代码
  • Job Module
src/main/java/com/xxx/xxx/.../job #包目录 根据业务定义路径
  /config #配置类目录
  	...
  /task #定时任务目录,根据业务定义子目录
 	...
src/test/ #测试用例目录
src/main/resources #存放配置文件或其他非Java类资源
复制代码

异常处理

在Web层统一处理,不允许直接吞掉异常。 线上常出现的异常主要有以下几种 NullPointerException: SQLSyntaxErrorException: SQLIntegrityConstraintViolationException:Column 'EntryApprove' cannot be null MysqlDataTruncation:Data truncation: Data too long for column 'ApprovalDesc' at row 1 TooManyResultsException:Expected one result (or null) to be returned by selectOne(), but found: 2 TimeoutException: 最难搞的是Zookeeper、Appollo、Netty等通信类异常。

参考资料

分类:
后端
标签:
分类:
后端
标签: