LegendShop代码规范

越福

2023-12-01

基本原则为面向对象设计的六大原则

1、单一职责原则
2、开闭原则
3、里氏替换原则
4、依赖倒置原则
5、接口隔离原则
6、迪米特原则

必要代码规范

1.必须严格遵守以上分层以及领域模型规范。

2.字段、方法的定义命名要遵守驼峰命名、定义清晰、可读性强。

3.每个类、方法必须加上注释。有引用意思的字段，请加上{@link} 到具体的类。

4.复杂的代码逻辑需要加上注释说明，按需考虑要添加 log.info 日志。

5.单一职责，每个dao和service只负责自己的业务。

6.日志采用lombok注解@Slf4j。

7.少写if判断，多用断言Assert和Optional类处理。

8.代码里面不要出现setxx(0),setxxx(1)这样的没有枚举表示的状态。

9.凡是update或save数据都需要返回相应的值。

命名规范

对通用名词，应用英文全称。系统内统一通用名词

例：商品：商品名为product，不管是方法还是表明还是数据库字段名，不允许简写prod，统一命名product

2、是否：当数据库需要存储是否两种条件的字段是，命名为xxxx_flag，不要命名is_xxxx，存储类型为tinyint类型，实体对象类型为Boolean

3、金额：金额数据库统一定义为decimal数据类型，不允许用double 数据类型,存储类型为decimal类型，统一二位小数，特殊要求特殊处理。

4、时间：所有的时间都使用time，创建时间和修改时间统一为：create_time和update_time 对应实体 createTime和updateTime，如果精确到日期，则用date。

5、创建人修改人：创建和修改统一用create_by，update_by ，对应实体createBy 和 updateBy

6、乐观锁：乐观锁数据库命名为：revision 对应实体 revision

7、状态：状态全部采用status命名，不能采用state命名

8、排序：所有排序的字段用sort命名

方法命名规范

通过ID查询单条数据 getById
分页查询 page
通过DTO作为筛选条件查询 queryAll
新增数据 save
修改数据 updateById
通过主键删除数据 deleteById
集合查询用query，单个对象或其他查询用get

应用分层规范

1.概述

Dev6.0版本采用前后端分离的方式，提供前端接口；前端请求后端接口，后端采用自上而下，从Controller层传递到Service层最后传递到Dao层，最后每层处理完后把结果逐级往上返回。

故此，我们需要通过制定规范，明确各层的职责规范，上层与下层之间的依赖关系、输入与输出、信息传递以及一些代码命名规范。

2.应用分层架构规范

目前Legendshop Dev6.0按照 Controller、Service、Dao 分成三层

Controller层：主要是接收Http请求，各类基本参数校验，对进行转发或重定向，响应客户端，或者对不复用的业务简单处理等（记住是不复用的业务才处理）。
Service层： 相对具体的业务逻辑服务层，具体的业务逻辑都应该在Service层处理。
DAO层：数据访问层，与底层MySQL数据库进行数据交互。

3.领域模型规范

DO（Domain Object）：领域对象，就是从现实世界中抽象出来的有形或无形的业务实体。（目前是entity,也叫Pojo）
DTO（Data Transfer Object）：数据传输对象，Service或Manager向外传输的对象。
BO (business object) 业务对象，Bo就是把业务逻辑封装为一个对象（注意是逻辑，业务逻辑），这个对象可以包括一个或多个其它的对象。
VO（View Object）：显示层对象，通常是Web向模板渲染引擎层传输的对象。
Query：数据查询对象，各层接收上层的查询请求。注意超过2个参数的查询封装，禁止使用Map类来传输。
领域模型命名规范
- DO: 数据库表名，例如ls_user表对应的领域模型，User。
- DTO：业务模型名 + DTO后缀，例如：UserDTO，xxxDTO。
- BO：业务模型名 + BO后缀，例如：UserBO，xxxBO。
- VO：页面渲染模型名 + VO后缀，例如：xxxVO、UserVO。
- Query：数据查询模型名 + Query后缀，例如：xxxQuery、UserQuery。

我们根据自身项目情况，按照自下而上进行各层的选择

Dao层
- 入参，使用DO , DTO , Query
- 出参，返回 DO ，DTO
Service层/Manager层
- 入参，使用DTO或者Query
  - 因为是前后端分离，需要加上Bean Validation @Valid 和 Swagger 注解生成swagger文档。
- 出参，使用VO , DTO
Controller层
- 入参，使用DTO或Query
  - 通常Controller入参可以直接传入到Service层做业务处理，需要加上Bean Validation @Valid 和 Swagger 注解生成swagger文档。
- 出参, 使用VO ,DTO

下层向上层返回结果规范

Dao层
- update、delete 返回int类型，小于1则等于失败。
- save 返回记录主键或DO，为null代表失败。
- 抛出DaoException代表失败，我们在Dao层不需要写代码处理，由LegendDao来负责往上抛出，Service/Manger层进行try Catch。
- 没有出现上述失败，则代表成功。
Service/Manager层
- Spring声明式事务一般应用在Service/Manager层，并且是基于异常进行事务回滚的，所以会有以下两种向上层返回结果的方式。
- 当不需要回滚事务时，封装通用的CommonResult来记录状态码、消息提示、以及对应数据。通过状态码来区分成功和各种逻辑及异常，具体请看CommonResult的定义。
- 当需要回滚事务时，封装通用的BusinessException，里面会有错误码和错误提示，然后throw抛出。
Controller层
- service层没有发生异常时，直接返回service层返回的CommonResult
- service发生异常后，在GlobalExceptionHandler全局异常处理器拦截异常并进行处理，处理的方式最终也是转换为CommonResult。

入参数据校验规范

HTTP请求参数的基本校验，比如非空校验、长度校验、手机号码格式等不需要调用RPC服务查询数据库就能完成的校验。
业务数据校验，结合业务逻辑，查询数据库才能完成的校验。比如查询店铺名是否已存在、是否超过限制创建的店铺数等。

对于第一种，指的是在Controller层完成的校验，对Controller的入参，也就是对CO、DTO进行数据校验，使用Bean Validation规范、Hibernate Validate实现，在DTO上加上相应的验证注解定义校验规则，在GlobalExceptionHandler进行统一拦截处理校验结果。

对于第二种，指的是在Service层完成的校验，对Service的入参进行校验，也就是对DTO进行校验。因为在Controller层已经做过一轮基本校验了，在service层就只做业务逻辑层面的校验，这时候通过手写代码进行校验，将校验结果写到CommonResult里面的状态码，消息提示里面即可。

4.领域模型相互转换/复制规范

上面提到了各层会有各层的领域模型，领域模型在层之间传递的时候需要一层转换，这时候可以采用Mapstruct实现。

示例：*Converter 注：只能按照上述转换关系转换，不能逆向转换。