大数据平台后端一些开发规范

Posted 2022-12-06 大数据指北

大家好，我是脚丫先生 (o^^o)

集团大数据平台之流批一体的建设之后。

一直想着能研发一套自己沉淀的小型大数据平台项目。

之后能与小伙伴们多多交流。

在研发的过程中，总结一些开发规范(参考全网)，希望可以帮助到小伙伴们。

一、编程规范

1.1 好代码的原则

参考 Kent Beck 的简单设计四原则来指导我们的如何写出优秀的代码，如何有效地判断我们的代码是优秀的。

（1）通过所有测试（Passes its tests）：强调的是外部需求，这是代码实现最重要的。

（2）尽可能消除重复 (Minimizes duplication)：代码的模块架构设计，保证代码的正交性，保证代码更容易修改。

（3）尽可能清晰表达 (Maximizes clarity)：代码的可阅读性，保证代码是容易阅读的。

（4）更少代码元素 (Has fewer elements)：保证代码是简洁的，在简洁和表达力之间，我们更看重表达力。

以上四个原则的重要程度依次降低， 这组定义被称做简单设计原则。

1.2 命名风格

（1）代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。

反例：_name / name / $name/nam{e}_{/}name$ / name

（2）代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。

（3）类名使用 UpperCamelCase 风格，但以下情形例外：DO / BO / DTO / VO / AO / PO / UID 等。

正例：JavaServerlessPlatform / UserDO / XmlService / TcpUdpDeal / TaPromotion
反例：javaserverlessplatform / UserDo / XMLService / TCPUDPDeal / TAPromotion

（4） 方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格，必须遵从驼峰形式。

正例： localValue / getHttpMessage() / inputUserId

（5）常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。

正例：MAX_STOCK_COUNT / CACHE_EXPIRED_TIME

（6）抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾；测试类命名以它要测试的类的名称开始，以 Test 结尾。

（7）包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。

正例：应用工具类包名为 com.alibaba.ai.util、类名为 MessageUtils（此规则参考 spring 的框架结构）

（8）避免在子父类的成员变量之间、或者不同代码块的局部变量之间采用完全相同的命名，使可读性降低。

反例：

public class ConfusingName  
 public int age; 
 // 非 setter/getter 的参数名称，不允许与本类成员变量同名 
 public void getData(String alibaba)  
 if(condition)  
 final int money = 531; 
 // ... 
  
 for (int i = 0; i < 10; i++)  
 // 在同一方法体中，不允许与其它代码块中的 money 命名相同 
 final int money = 615; 
 // ... 
  
  
 
class Son extends ConfusingName  
 // 不允许与父类的成员变量名称相同 
 public int age; 
 

(9) 在常量与变量的命名时，表示类型的名词放在词尾，以提升辨识度。

正例：startTime / workQueue / nameList / TERMINATED_THREAD_COUNT

反例：startedAt / QueueOfWork / listName / COUNT_TERMINATED_THREAD

(10) 接口类中的方法和属性不要加任何修饰符号（public 也不要加），保持代码的简洁性，并加上有效的 Javadoc 注释。尽量不要在接口里定义变量，如果一定要定义变量，肯定是与接口方法相关，并且是整个应用的基础常量。

正例：接口方法签名 void commit();
接口基础常量 String COMPANY = “alibaba”;

反例：接口方法定义 public abstract void f();

(11) 枚举类名带上 Enum 后缀，枚举成员名称需要全大写，单词间用下划线隔开。

正例：枚举名字为 ProcessStatusEnum 的成员名称：SUCCESS / UNKNOWN_REASON。

1.3 项目命名规范

全部采用小写方式， 以中划线分隔。

正例：mall-management-system / order-service-client / user-api

反例：mall_management-system / mallManagementSystem / orderServiceClient

1.4 方法参数规范

无论是 controller，service，manager，dao 亦或是其他的代码，每个方法最多 3 个参数，如果超出 3 个参数的话，要封装成 javabean 对象。

(1) 方便他人调用，降低出错几率。尤其是当参数是同一种类型，仅仅依靠顺序区分，稍有不慎便是灾难性后果，而且排查起来也极其恶心。

(2) 保持代码整洁、清晰度。当一个个方法里充斥着一堆堆参数的时候，再坚强的人，也会身心疲惫。

反例：

/**
* 使用证书加密数据工具方法
*
* @param param
* @param password 加密密码
* @param priCert 私钥
* @param pubCert 公钥
* @return 返回加密后的字符串
*/
public String signEnvelop(JdRequestParam param, String password, String priCert, String pubCert)

二、项目规范

2.1 1、代码目录结构

统一的目录结构是所有项目的基础。

src                               源码目录
|-- common                            各个项目的通用类库
|-- config                            项目的配置信息
|-- constant                          全局公共常量
|-- handler                           全局处理器
|-- interceptor                       全局连接器
|-- listener                          全局监听器
|-- module                            各个业务
|-- |--- employee                         员工模块
|-- |--- role                             角色模块
|-- |--- login                            登录模块
|-- third                             三方服务，比如redis, oss，微信sdk等等
|-- util                              全局工具类
|-- Application.java                  启动类

2.1.2 common 目录规范

common 目录用于存放各个项目通用的项目，但是又可以依照项目进行特定的修改。

src 源码目录
|-- common 各个项目的通用类库
|-- |--- anno          通用注解，比如权限，登录等等
|-- |--- constant      通用常量，比如 ResponseCodeConst
|-- |--- domain        全局的 javabean，比如 BaseEntity,PageParamDTO 等
|-- |--- exception     全局异常，如 BusinessException
|-- |--- json          json 类库，如 LongJsonDeserializer，LongJsonSerializer
|-- |--- swagger       swagger 文档
|-- |--- validator     适合各个项目的通用 validator，如 CheckEnum，CheckBigDecimal 等

2.1.3 config 目录规范

config 目录用于存放各个项目通用的项目，但是又可以依照项目进行特定的修改。

src                               源码目录
|-- config                            项目的所有配置信息
|-- |--- MvcConfig                    mvc的相关配置，如interceptor,filter等
|-- |--- DataSourceConfig             数据库连接池的配置
|-- |--- MybatisConfig                mybatis的配置
|-- |--- ....                         其他

2.1.4 module 目录规范

module 目录里写项目的各个业务，每个业务一个独立的顶级文件夹，在文件里进行 mvc 的相关划分。
其中，domain 包里存放 entity, dto, vo，bo 等 javabean 对象

src
|-- module                         所有业务模块
|-- |-- role                          角色模块
|-- |-- |--RoleController.java              controller
|-- |-- |--RoleConst.java                   role相关的常量
|-- |-- |--RoleService.java                 service
|-- |-- |--RoleDao.java                     dao
|-- |-- |--domain                           domain
|-- |-- |-- |-- RoleEntity.java                  表对应实体
|-- |-- |-- |-- RoleDTO.java                     dto对象
|-- |-- |-- |-- RoleVO.java                      返回对象
|-- |-- employee                      员工模块
|-- |-- login                         登录模块
|-- |-- email                         邮件模块
|-- |-- ....                          其他

2.1.5 domain 包中的 javabean 命名规范

建议对象使用 lombok 的 @Builder ，@NoArgsConstructor，同时使用这两个注解，简化对象构造方法以及set方法。

正例：

@Builder
@NoArgsConstructor
@Data
public class DemoDTO 

    private String name;
    
    private Integer age;


// 使用示例：

DemoDTO demo = DemoDTO.builder()
                .name("yeqiu")
                .age(66)
                .build();

2.1.6 数据对象；XxxxEntity，要求：

(1) 以 Entity 为结尾（阿里是为 DO 为结尾）

(2) Xxxx 与数据库表名保持一致

(3) 类中字段要与数据库字段保持一致，不能缺失或者多余

(4) 类中的每个字段添加注释，并与数据库注释保持一致不允许有组合

项目内的日期类型必须统一，建议使用 java.util.Date，java.sql.Timestamp，java.time.LocalDateTime 其中只一。

三、MVC 规范

3.1 整体分层

controller 层

service 层

impl 层

dao 层

3.2 controller 层规范

(1) 只允许在 method 上添加 RequestMapping 注解，不允许加在 class 上（为了方便的查找 url，放到 url 不能一次性查找出来）

正例：

@RestController
public class DepartmentController 

    @GetMapping("/department/list")
    public ResponseDTO<List<DepartmentVO>> listDepartment() 
        return departmentService.listDepartment();
    

反例

@RequestMapping ("/department")
public class DepartmentController 

    @GetMapping("/list")
    public ResponseDTO<List<DepartmentVO>> listDepartment() 
        return departmentService.listDepartment();
    

(2) 不推荐使用 rest 命名 url， 只能使用 get/post 方法。url 命名上规范如下：

/业务模块/子模块/动作

正例：

GET  /department/get/id      查询某个部门详细信息
POST /department/query         复杂查询
POST /department/add           添加部门
POST /department/update        更新部门
GET  /department/delete/id   删除部门

(3) 每个方法必须添加 swagger 文档注解 @ApiOperation ，并填写接口描述信息，描述最后必须加上作者信息 @author 作者 。

正例：

    @ApiOperation("更新部门信息 @author 作者")
    @PostMapping("/department/update")
    public ResponseDTO<String> updateDepartment(@Valid @RequestBody DeptUpdateDTO deptUpdateDTO) 
        return departmentService.updateDepartment(deptUpdateDTO);
    

(4) controller 负责协同和委派业务，充当路由的角色，每个方法要保持简洁：

不做任何的业务逻辑操作

不做任何的参数、业务校验，参数校验只允许使用@Valid 注解做简单的校验

不做任何的数据组合、拼装、赋值等操作

正例：

    @ApiOperation("添加部门 @author 哪吒")
    @PostMapping("/department/add")
    public ResponseDTO<String> addDepartment(@Valid @RequestBody DepartmentCreateDTO departmentCreateDTO) 
        return departmentService.addDepartment(departmentCreateDTO);
    

(5) 只能在 controller 层获取当前请求用户，并传递给 service 层。

正例

    @ApiOperation("添加员工 @author yandanyang")
    @PostMapping("/employee/add")
    public ResponseDTO<String> addEmployee(@Valid @RequestBody EmployeeAddDTO employeeAddDTO) 
        LoginTokenBO requestToken = SmartRequestTokenUtil.getRequestUser();
        return employeeService.addEmployee(employeeAddDTO, requestToken);
    

3.3 service 层规范

(1) 合理拆分 service 文件，如果业务较大，请拆分为多个 service

如订单业务,所有业务都写到 OrderService 中会导致文件过大，故需要进行拆分如下：

OrderQueryService 订单查询业务

OrderCreateService 订单新建业务

OrderDeliverService 订单发货业务

OrderValidatorService 订单验证业务

3.4 iml层规范一些开发规范

（1） 封装业务逻辑

如果你看过“屎山”你就会有深刻的感触，这特么一个方法能写几千行代码，还无任何规则可言…往往负责的人会说，这个业务太复杂，没有办法改善，实际上这都是懒的借口。不管业务再复杂，我们都能够用合理的设计、封装去提升代码可读性。下面贴两段高级开发（假装自己是高级开发）写的代码

正例 1：

@Transactional
public ChildOrder submit(Long orderId, OrderSubmitRequest.Shop shop) 
    ChildOrder childOrder = this.generateOrder(shop);
    childOrder.setOrderId(orderId);
    //订单来源 APP/微信小程序
    childOrder.setSource(userService.getOrderSource());
    // 校验优惠券
    orderAdjustmentService.validate(shop.getOrderAdjustments());
    // 订单商品
    orderProductService.add(childOrder, shop);
    // 订单附件
    orderAnnexService.add(childOrder.getId(), shop.getOrderAnnexes());
    // 处理订单地址信息
    processAddress(childOrder, shop);
    // 最后插入订单
    childOrderMapper.insert(childOrder);
    this.updateSkuInventory(shop, childOrder);
    // 发送订单创建事件
    applicationEventPublisher.publishEvent(new ChildOrderCreatedEvent(this, shop, childOrder));
    return childOrder;

正例 2：

@Transactional
public void clearBills(Long customerId) 
    // 获取清算需要的账单、deposit等信息
    ClearContext context = getClearContext(customerId);
    // 校验金额合法
    checkAmount(context);
    // 判断是否可用优惠券，返回可抵扣金额
    CouponDeductibleResponse deductibleResponse = couponDeducted(context);
    // 清算所有账单
    DepositClearResponse response = clearBills(context);
    // 更新 l_pay_deposit
    lPayDepositService.clear(context.getDeposit(), response);
    // 发送还款对账消息
    repaymentService.sendVerifyBillMessage(customerId, context.getDeposit(), EventName.DEPOSIT_SUCCEED_FLOW_REMINDER);
    // 更新账户余额
    accountService.clear(context, response);
    // 处理清算的优惠券，被用掉或者解绑
    couponService.clear(deductibleResponse);
    // 保存券抵扣记录
    clearCouponDeductService.add(context, deductibleResponse);

这段两代码里面其实业务很复杂，内部估计保守干了五万件事情，但是不同水平的人写出来就完全不同，不得不赞一下这个注释，这个业务的拆分和方法的封装。一个大业务里面有多个小业务，不同的业务调用不同的 service 方法即可，后续接手的人即使没有流程图等相关文档也能快速理解这里的业务，而很多初级开发写出来的业务方法就是上一行代码是 A 业务的，下一行代码是 B业务的，在下面一行代码又是 A 业务的，业务调用之间还嵌套这一堆单元逻辑，显得非常混乱，代码还多。

(2) 判断集合类型不为空的正确方式

很多人喜欢写这样的代码去判断集合

if (list == null || list.size() == 0) 
  return null;

当然你硬要这么写也没什么问题…但是不觉得难受么，现在框架中随便一个 jar 包都有集合工具类，比如

org.springframework.util.CollectionUtils、com.baomidou.mybatisplus.core.toolkit.CollectionUtils 。

以后请这么写

if (CollectionUtils.isEmpty(list) || CollectionUtils.isNotEmpty(list)) 
  return null;

(3) 集合类型返回值不要 return null

当你的业务方法返回值是集合类型时，请不要返回 null，正确的操作是返回一个空集合。你看 mybatis 的列表查询，如果没查询到元素返回的就是一个空集合，而不是 null。否则调用方得去做 NULL 判断，多数场景下对于对象也是如此。

(4) 映射数据库的属性尽量不要用基本类型

我们都知道 int/long 等基本数据类型作为成员变量默认值是 0。现在流行使用 mybatisplus 、mybatis 等 ORM 框架，在进行插入或者更新的时候很容易会带着默认值插入更新到数据库。我特么真想砍了之前的开发，重构的项目里面实体类里面全都是基本数据类型。

（5）封装判断条件

反例：

public void method(LoanAppEntity loanAppEntity, long operatorId) 
  if (LoanAppEntity.LoanAppStatus.OVERDUE != loanAppEntity.getStatus()
          && LoanAppEntity.LoanAppStatus.CURRENT != loanAppEntity.getStatus()
          && LoanAppEntity.LoanAppStatus.GRACE_PERIOD != loanAppEntity.getStatus()) 
    //...
    return;
  

这段代码的可读性很差，这 if 里面谁知道干啥的？我们用面向对象的思想去给 loanApp 这个对象里面封装个方法不就行了么？

public void method(LoanAppEntity loan, long operatorId) 
  if (!loan.finished()) 
    //...
    return;
  

LoanApp 这个类中封装一个方法，简单来说就是这个逻辑判断细节不该出现在业务方法中。

/**
 * 贷款单是否完成
 */
public boolean finished() 
  return LoanAppEntity.LoanAppStatus.OVERDUE != this.getStatus()
          && LoanAppEntity.LoanAppStatus.CURRENT != this.getStatus()
          && LoanAppEntity.LoanAppStatus.GRACE_PERIOD != this.getStatus();

（6） 参数传递不要使用Map、JSONObject或者实体类，使用DTO传递

使用Map或者JSONObject传递，后面维护的人员不知道传递的参数是什么，还要一一和前端核实，非常麻烦；实体类是用来封装数据的，而不是用来传递数据的，不能将它们两个混着使用，代码会很乱

（7）for里不建议写io。io包括：数据库、缓存，文件读写等

对数据库的操作是操作IO的，频繁的操作IO是非常耗性能的，因此代码当中，要杜绝编写循环操作数据库的代码，这里举个例子。

上图，改进后的代码虽然变多了一些，但是，避免了循环操作数据库，特别是当userIdList数据比较多或者数据库当中users表数据量比较大的时候，方式2的速度相比方式1肉眼可见的快。

（8） 禁止使用魔法值

反例

if (users.getType()==1)
            
 

正例： 定义一个枚举

@AllArgsConstructor
@Getter
public enum UserTypeEnum 
    ADMIN(1,"管理员"),
    TEACHER(2,"老师"),
    STUDENT(3,"学生");

    private Integer type;
    private String desc;

然后再使用

 if (users.getType()== UserTypeEnum.ADMIN.getType())
            
        

（9） 异常处理

捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之，如果不想处理它，请 将该异常抛给它的调用者。最外层的业务使用者，必须处理异常，将其转化为用户可以理解的内容。

大量try catch 对代码阅读性和性能解析都不太友好

反例：

  @GetMapping("/list")
    public Result<Map<String, Object>> getPerformanceList(AdminPerformanceSearchVO searchVO, PageVO pageVO,
                                                          HttpServletRequest request) 
        logger.info("PC端订单查询请求参数："+searchVO.toString());
        UserDO user = ShiroUtils.getUser();
        Query query = new Query(pageVO);
        Map<String, Object> params = MapperUtils.obj2Map(searchVO);
        query.putAll(params);
        try 
            formatParams(query);
         catch (DataFormatException e) 
            e.printStackTrace();
            logger.error(e.getMsg());
            return new ResultUtil<Map<String, Object>>().setErrorMsg(e.getMsg());
        
​
        Map<String, Object> map = null;
        try 
            map = adminAlyPerformanceService.getList(query, user);
         catch (BusinessException e) 
            e.printStackTrace();
            logger.error(e.getMessage());
            return new ResultUtil<Map<String, Object>>().setErrorMsg(e.getMessage());
        
        return new ResultUtil<Map<String, Object>>().setData(map);
    

正例：采用全局统一异常处理

全局统一异常
@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler 
​
    @ExceptionHandler(value = DataFormatException.class)
    public Result<?> validationExceptionHandler(DataFormatException e) 
        log.error("系统异常DataFormatException：",e);
        BindingResult bindingResult = e.getBindingResult();
        String errorMessage = bindingResult.getFieldErrors().get(0).getDefaultMessage();
        return Result.failure(errorMessage);
    
    
     @ExceptionHandler(value = BusinessException.class)
    public Result<?> validationExceptionHandler(BusinessException e) 
        log.error("系统异常BusinessException：",e);
        BindingResult bindingResult = e.getBindingResult();
        String errorMessage = bindingResult.getFieldErrors().get(0).getDefaultMessage();
        return Result.failure(errorMessage);
    

然后使用：

@GetMapping("/list")
    public Result<Map<String, Object>> getPerformanceList(AdminPerformanceSearchVO searchVO, PageVO pageVO,
                                                  HttpServletRequest request) 
        UserDO user = ShiroUtils.getUser();
        Query query = new Query(pageVO);
        Map<String, Object> params = MapperUtils.obj2Map(searchVO);
        query.putAll(params);
        formatParams(query);
        Map<String, Object> map map = adminAlyPerformanceService.getList(query, user);
        return new ResultUtil<Map<String, Object>>().setData(map);
    

3.5 dao 层规范

(1) 优先使用 mybatis-plus 框架。如果需要多个数据源操作的，可以选择使用 SmartDb 框架。

1）所有 Dao 继承自 BaseMapper

2）禁止使用 Mybatis-plus 的 Wrapper 条件构建器

3）禁止直接在 mybatis xml 中写死常量，应从 dao 中传入到 xml 中

4）建议不要使用星号 * 代替所有字段

正例：

    NoticeDao.java

    Integer noticeCount(@Param("sendStatus") Integer sendStatus);
---------------------------------------------
    NoticeMapper.xml

    <select id="noticeCount" resultType="integer">
        select
        count(1)
        from t_notice
        where
        send_status = #sendStatus
    </select>

反例：

    NoticeDao.java

    Integer noticeCount();
---------------------------------------------
    NoticeMapper.xml

    <select id="noticeCount" resultType="integer">
        select
        count(1)
        from t_notice
        where
        send_status = 0
    </select>

(2) dao层方法命名规范

获取单个对象的方法用 get 做前缀。

获取多个对象的方法用 list 做前缀。

获取统计值的方法用 count 做前缀。

插入的方法用 save/insert 做前缀。

删除的方法用 remove/delete 做前缀。

修改的方法用 update 做前缀。

建议：dao层方法命名尽量以sql语义命名，避免与业务关联。

正例：

List<PerformanceDTO> listByMonthAndItemId(@Param("month") String month, @Param("itemId") Integer itemId);

反例：

List<PerformanceDTO> getInternalData(@Param("month") String month, @Param("itemId") Integer itemId);

反例中出现的不规范操作：

get代表单个查询，批量查询的应该 list 开头。
命名与业务关联，局限了dao方法的使用场景和范围，降低了方法的复用性，造成他人困惑以及重复造轮子。

四 数据库 规范

4.1 建表规范

表必备三字段：id, create_time, update_time

id 字段 Long 类型，单表自增，自增长度为 1

create_time 字段 datetime 类型，默认值 CURRENT_TIMESTAMP

update_time 字段 datetime 类型，默认值 CURRENT_TIMESTAMP, On update CURRENT_TIMESTAMP

4.2 枚举类表字段注释需要将所有枚举含义进行注释

修改或增加字段的状态描述，必须要及时同步更新注释。
如下表的 sync_status 字段 同步状态 0 未开始 1同步中 2同步成功 3失败。

正例：

CREATE TABLE `t_change_data` (
	`id` BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
	`sync_status` TINYINT(3) UNSIGNED NOT NULL DEFAULT '0' COMMENT '同步状态 0 未开始 1同步中 2同步成功 3失败',
	`sync_time` DATETIME NULL DEFAULT NULL COMMENT '同步时间',
	`create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
	`update_time` DATETIME NULL DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP,
	PRIMARY KEY (`change_data_id`)
)

反例：

CREATE TABLE `t_change_data` (
	`id` BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
	`sync_status` TINYINT(3) UNSIGNED NOT NULL DEFAULT '0' COMMENT '同步状态 ',
	`sync_time` DATETIME NULL DEFAULT NULL COMMENT '同步时间',
	`create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
	`update_time` DATETIME NULL DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP,
	PRIMARY KEY (`change_data_id`)
)

4.3 合理结合业务给表字段添加索引和唯一索引

具体索引规范请参照《阿里巴巴 Java 开发手册》索引规约

4.4 数据库常用

（1）命名风格：小写字母，下划线命名风格

（2）数据库参数
数据库引擎：InnoDB；
字符集：utf8；
字符校对集：generic_utf8_ci

（3）数据库表
表名：前缀为项目名称首字母缩写，单词之间用下划线分割，单数形式；

必备三字段：id，create_time，update_time

id：逻辑主键

create_time：创建时间

update_time：更新时间

（4）主键

逻辑主键：无实际含义，用于唯一标识每个记录

业务主键：有实际含义

（5）属性类型

逻辑主键：bigint，无符号自增

业务主键：varchar，后端生成随机uuid

逻辑值：tinyint

日期：date

时间：timestamp（时间戳）

字符串：varchar，需要指定长度（字段长度应该统一并且适当大一点，否则未知的变化会导致前后端的频繁修改）。

好了，今天就聊到这里，祝各位终有所成，收获满满！

我是脚丫先生，我们下期见~