Java后端微服务研发规范

技术栈说明

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

项目分层说明

前后端分离

前端采用AntDesign for Vuejs Pro
微前端架构：在一个基座上承载多个SPA应用，基座上有一些基础的能力，每个应用还可以导出组件和能力。

后端微服务

interfaces：包含dto\enums\publicservice-interface。其中enums中放本模块中的所有枚举类。如果不需要向外界提供RPC服务，就没有dto和publicservice
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。
数据库命名规范

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

xxx-xx-business #业务逻辑和数据访问层
xxx-xx-interface #微服务相关
xxx-xx-protal #前端相关
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等通信类异常。

参考资料

SpringBoot系列（十）优雅的处理统一异常处理与统一结果返回
SpringBoot 统一异常处理和统一数据返回
springboot 统一返回数据格式和异常处理
SpringBoot系统列 4 - 常用注解、拦截器、异常处理
Spring Validation最佳实践及其实现原理，参数校验没那么简单！
看看别人后端API接口写得，那叫一个优雅！
SpringBoot 拦截器、过滤器、监听器、定时器使用
https://juejin.cn/post/6844903911715782669
https://juejin.cn/post/6872226869605826573
什么是接口的幂等性，如何实现接口幂等性？一文搞定
https://juejin.cn/post/6937533353914531876