Java后端开发常用规范

原文网址：Java后端开发常用规范_IT利刃出鞘的博客-CSDN博客

        本文介绍Java后端开发的一些规范。持续更新。

        本规范是本人总结出来的，可提高项目的可维护性、提高扩展性、提高开发速度。本文可以解决项目中效率低下、难以维护、让人心累的痛点等问题。

模块的划分

        单个项目分为xxx-api模块和xxx-core模块。比如用户项目，分为：user-api、user-core。

• xxx-api：供其他项目依赖。包括：DTO、本项目的feign定义、本项目的工具类。
• xxx-core：主体项目。包括：业务代码（Controller、Service、Entity）、配置类等等。

业务代码的结构

按每个表对应一个包，Controller、Service、Entity放到一个包里，例如：

优点

1. 模块化，业务分离清晰
2. 开发速度快（只需关注自己模块代码即可）

说明

        要用枚举来表示类型，不要用数字。比如：有三种支付方式：微信、支付宝、银联，则这样定义枚举：

package com.example.pay;
 
public enum PayType {
    ALIPAY("支付宝支付"),
    WECHAT_PAY("微信支付"),
    BANK_CARD_PAY("银行卡支付")
    ;
 
    
    private final String description;
 
    PayType(String description) {
        this.description = description;
    }
 
    public String getDescription() {
        return description;
    }
}

所有用到的地方都用枚举来表示。比如：

1. Controller：会自动将前端传过来的字符串转为枚举类（根据name()来转换）。
2. Entity：写数据：自动将枚举对象的name()值写入数据库；读数据：根据name()转为枚举

不要这样写

1：支付宝支付；2：微信支付；3：银联支付

原因：可读性极差，排查问题也麻烦。比如：前端页面上看到了2这个类型，还要看接口文档或者问后端这是什么意思，浪费时间！

优点

可读性好

说明

        使用Knife4j+Yapi。

Knife4j

        Knife4j的用法见这里。例如：

Yapi

        使用Yapi将Knife4j的接口信息导入进来：将上图中的真实IP+端口与“分组Url”拼接：真实IP+端口/v3/api-docs?group=all，然后导入到Yapi：

点击“上传”

点击“确认”

查看接口

优点

1. 减少接口文档的代码冗余
2. 可快速导入接口

说明

        将git分支分为主分支和临时分支。

• 主分支：test（测试）、pre（预发布）、prod（生产）
• 临时分支：需求点和bug修改

开发与提交流程

1. 每个修改点（需求或bug）都要从prod新拉分支
2. 合代码（合代码时都是从临时分支cherry pick到目的分支（主分支））
   1. 往test分支合代码时，需要先把自己的临时分支压缩为一个点，再cherry pick到test。
   2. 往pre分支合代码时，从临时分支cherry pick到pre分支，不要从test分支cherry pick。（因为test肯定有没测试的，不能上pre）
   3. 往prod分支合代码时，组员告诉组长自己的提交点，由组长从临时分支cherry pick到prod分支（因为pre肯定有没测试的，不能上正式）
3. 远程有更新时，要rebase（以远程为基准），不要用merge（以本地为基准）
4. 修改点上线（临时分支cherry pick到master）后，删除临时分支（防止分支过多）
5. 定期（两三周）对test进行清理，删除test并重新从prod拉分支，作为test分支。（防止test与prod差距较远，导致临时分支往test分支合代码时冲突很多）
6. 定期（两三周）对pre进行清理，删除pre并重新从prod拉分支，作为pre分支。（防止pre与prod差距较远，导致临时分支往pre分支合代码时冲突很多）

优点

        以上步骤是我之前所在某个公司的提交流程，按这个流程来做，可以做到：合代码基本不出问题、合代码速度快（一般不会超过3分钟）。

        以上步骤每一步都是有原因的：

• 从prod拉新分支：可保证新分支代码是基于生产的，可以保证新分支是纯粹的自己的修改点
• 合代码时都是从临时分支cherry pick到目的分支：可保证不会将其他人代码合到目的分支
• 使用rebase而不是merge：git提交清晰，而且这是人类的正常思维：以服务器的代码为准，而不是以自己本地的代码为准。
• 定期删除test、pre并从prod拉分支：从临时分支合到主分支时基本不会有冲突；而且可以删除test里无用的代码

感言

        一个正常的功能点，如果合代码超过10分钟，那么，项目的git管理大概率有问题。如果超过30分钟，项目的git管理问题有点儿大。如果超过一个小时，那么...

说明

        为了便于排查问题，建表时需要加一些必要的字段：创建人、更新人、创建时间、更新时间、删除标记。

SQL

ALTER TABLE `库名`.`表名` 
ADD COLUMN `create_id` bigint COMMENT '创建人ID',
ADD COLUMN `update_id` bigint COMMENT '修改人ID',
ADD COLUMN `create_time` datetime DEFAULT NULL COMMENT '创建时间',
ADD COLUMN `update_time` datetime DEFAULT NULL COMMENT '修改时间',
ADD COLUMN `delete_flag` bigint NOT NULL DEFAULT 0 COMMENT '删除标记。0：未删除；其他：已删除';

详解

• 创建时间和更新时间的字段名
  • 阿里开发手册的规范：
    • 嵩山版、华山版等：表必备三字段:id,create_time,update_time。
    • 泰山版等：表必备三字段:id,gmt_create,gmt_modified。
  • 个人认为时间相关的字段名应该有“time”才好。而且有一些Mock工具（例如：ApiFox)会根据字段名自动构造假数据，字段中带“time”工具就会自动生成很接近实际的mock数据，有利于前端自测代码。
• 更新时间不要设置为自动更新
  • 不要让更新时间自动更新，即：不要这样写：ADD COLUMN `update_time` datetime DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP COMMENT '修改时间',
  • 原因：
    • 数据库服务器很可能没有正确设置时区，如果“更新时间”字段使用了数据库服务器的时区进行了自动更新，那这个时间就是不正确的。
    • 以我工作的几家公司来看，数据库服务器的时区基本都是错误的。
  • 正确的方法是：“创建时间”和“更新时间”全部通过应用来自动生成。比如MybatisPlus的自动填充：MyBatis-Plus--扩展--使用/教程/实例_IT利刃出鞘的博客-CSDN博客_mybatis-plus-extension
• 删除标记不要使用0,1来表示，在删除时应该将id的值赋值给delete_flag
  • 如果用0,1表示，会影响唯一索引。见：MyBatis-Plus--解决逻辑删除与唯一索引的问题--方法/实例_IT利刃出鞘的博客-CSDN博客_mybatis唯一索引异常
• 数据库的时间字段对应的Java的DAO的字段类型要用LocalDateTime
  • 现在21世纪了，不要再用Date了。
  • LocalDateTime的优点：
    • 可明确知晓：这是个日期+时间的字段。（Date不能一眼看出是日期还是时间还是两者）
    • LocalDateTime的格式化等操作是线程安全的。
    • LocalDateTime的方法很丰富。

说明

        无论用的是哪种MQ（RabbitMQ、RocketMQ、Kafka），都会需要将Topic、队列等信息写入到MQ服务端（Broker）。

        写入服务端有两种方式：

1. 手动在MQ服务端的Web管理页面上添加
2. 写在代码里
   1. 这样项目在启动时，会自动往MQ服务端上注册。

要使用第2种方法（自动注册），不要使用第1种方法（手动添加）。

优点

1. 发布功能时省心
   1. 假设代码有test（测试）、pre（预发）、prod（生产）三个环境
      1. 若是自动注册的：只需将代码合到相应分支即可，项目启动时自动往MQ服务端注册
      2. 若是手动添加的：需要手动在三个环境添加信息
2. MQ服务端更改部署环境或者重装时无需手动处理
   1. 如果MQ服务端更改了，自动和手动的情况如下：
      1. 若是自动注册的：重启项目即可。
      2. 若是手动添加的：需要手动在新环境添加信息