Java后端开发常用规范

简介

本文介绍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提交规范

说明

将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里无用的代码。