JAVA 开发统一规范(规约)

客官°小女子只卖身不卖艺 2022-11-19 04:28 212阅读 0赞

开发统一规范:

1.  类和方法需要添加注释,其他比较复杂的地方也需要添加注释
2.  单个方法的总行数不超过 80 行。说明：除注释之外的方法签名、左右大括号、方法内代码、空行、回车及任何不可见字符的总行数不超过 80 行。(推荐一个显示屏的高度)
3.  重要的方法的入参和出参都需要打印日志(json格式)
4.  尽可能的使用工具类
5.  不允许任何魔法值（即未经预先定义的常量）直接出现在代码中。常用公共变量需要提取.单类中重复变量提取成类的成员变量
6.  【参考】各层命名规约：

> A) Service/DAO 层方法命名规约  
> 1）获取单个对象的方法用 get 做前缀。  
> 2）获取多个对象的方法用 list 做前缀，复数结尾，如：listObjects。  
> 3）获取统计值的方法用 count 做前缀。  
> 4）插入的方法用 save/insert 做前缀。  
> 5）删除的方法用 remove/delete 做前缀。  
> 6）修改的方法用 update 做前缀。

> B) 领域模型命名规约  
> 1）数据对象：xxxDO，xxx 即为数据表名。  
> 2）数据传输对象：xxxDTO，xxx 为业务领域相关 的名称。  
> 3）展示对象：xxxVO，xxx 一般为网页名称。 POJO 是 DO/DTO/BO/VO 的统称，禁止命名成 xxxPOJO 。

1.  POJO 类中的任何布尔类型的变量，都不要加 is 前缀，否则部分框架解析会引起序列 化错误。
2.  常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。
3.  抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾；测试类 命名以它要测试的类的名称开始，以 Test 结尾。
4.  包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用 单数形式，但是类名如果有复数含义，类名可以使用复数形式。
5.  在常量与变量的命名时，表示类型的名词放在词尾，以提升辨识度
6.  在 long 或者 Long 赋值时，数值后使用大写字母 L ，不能是小写字母 l，小写容易跟 数字混淆，造成误解。
7.  不要使用一个常量类维护所有常量，要按常量功能进行归类，分开维护。
8.  所有整型包装类对象之间值的比较，全部使用 equals 方法比较。

> 说明：对于 Integer var = ? 在-128 至 127 之间的赋值，Integer 对象是在

> IntegerCache.cache 产生， 会复用已有对象，这个区间内的 Integer  
> 值可以直接使用==进行判断，但是这个区间之外的所有数据，都 会在堆上产生，并不会复用已有对象，这是一个大坑，推荐使用 equals  
> 方法进行判断。

1.  所有的 POJO 类属性必须使用包装数据类型。
2.  RPC 方法的返回值和参数必须使用包装数据类型。
3.  所有的局部变量使用基本数据类型。
    
    > 说明：POJO 类属性没有初值是提醒使用者在需要使用时，必须自己显式地进行赋值，任何 NPE 问题，或 者入库检查，都由使用者来保证。  
    > 正例：数据库的查询结果可能是 null，因为自动拆箱，用基本数据类型接收有 NPE 风险。  
    > 反例：某业务的交易报表上显示成交总额涨跌情况，即正负 x%，x 为基本数据类型，调用的 RPC 服务，调 用不成功时，返回的是默认值，页面显示为 0%，这是不合理的，应该显示成中划线-。所以包装数据类型 的 null 值，能够表示额外的信息，如：远程调用失败，异常退出。
4.  使用索引访问用 String 的 split 方法得到的数组时，需做最后一个分隔符后有无内容 的检查，否则会有抛 IndexOutOfBoundsException 的风险。

说明： String str = “a,b,c,” ; String[] ary = str.split("," );
     // 预期大于 3，结果是 3 System.out.println(ary. length);

1.  获取当前毫秒数：System.currentTimeMillis(); 而不是 new Date().getTime()。 说明：如果想获取更加精确的纳秒级时间值，使用 System.nanoTime 的方式。在 JDK8 中，针对统计时间 等场景，推荐使用 Instant 类。
2.  ArrayList 的 subList 结果不可强转成 ArrayList ，否则会抛出 ClassCastException 异 常：java.util.RandomAccessSubList cannot be cast to java.util.ArrayList 。

> 说明：subList()返回的是 ArrayList 的内部类 SubList，并不是 ArrayList 本身，而是 ArrayList 的一个视 图，对于 SubList 的所有操作最终会反映到原列表上。

1.  使用集合转数组的方法，必须使用集合的 toArray(T\[\] array)，传入的是类型完全一 致、长度为 0 的空数组。

反例：直接使用 toArray 无参方法存在问题，此方法返回值只能是 Object[] 类，若强转其它类型数组将出现 ClassCastException 错误。
    正例：
    List list = new ArrayList<> (2);
    list.add(“guan” );
    list.add(“bao” );
    String[] array = list. toArray(new String[0]);
    说明：使用 toArray 带参方法，数组空间大小的 length ：
    1）等于 0，动态创建与 size 相同的数组，性能最好。
    2）大于 0 但小于 size，重新创建大小等于 size 的数组，增加 GC 负担。
    3）等于 size，在高并发情况下，数组创建完成之后，size 正在变大的情况下，负面影响与 2 相同。 4 ） 大于 size，空间浪费，且在 size 处插入 null 值，存在 NPE 隐患

1.  泛型通配符< ? extends T>来接收返回的数据，此写法的泛型集合不能使用 add 方法， 而< ? super T> 不能使用 get 方法，两者在接口调 用赋值的场景中容易出错。  
    说明：扩展说一下 PECS(Producer Extends Consumer Super) 原则：第一、频繁往外读取内容的，适合用 <? extends T>。第二、经常往里插入的，适合用< ? super T>
2.  不要在 foreach 循环里进行元素的 remove/add 操作。remove 元素请使用 Iterator 方式，如果并发操作，需要对 Iterator 对象加锁。

正例：
    List<String > list = new ArrayList<> ();
    list.add("1");
    list.add("2");
    Iterator<String> iterator = list.iterator();
    while (iterator.hasNext ()) { 
        String item = iterator.next();
        if (删除元素的条件) { 
            iterator.remove();
        }
    }
    反例：
    for (String item : list) { 
        if ("1".equals (item)) { 
            list.remove(item );
        }
    }

1.  集合初始化时，指定集合初始值大小。

> 说明：HashMap 使用 HashMap(int initialCapacity) 初始化，如果暂时无法确定集合大小，那么指定默 认值（16 ）即可。  
> 正例：initialCapacity = (需要存储的元素个数 / 负载 因子) + 1 。注意负载因子（即 loader factor）默认 为 0.75 ，如果暂时无法确定初始值大小，请设置为 16（即默认值）。  
> 反例： HashMap 需要放置 1024 个元素，由于没有设置容量初始大小，随着元素增加而被迫不断扩容， resize()方法总共会调用 8 次，反复重建哈希表和数据迁移。当放置的集合元素个数达千万级时会影响程序 性能。

1.  合理利用好集合的有序性(sort)和稳定性(order)，避免集合的无序性(unsort)和不稳 定性(unorder)带来的负面影响。  
    说明：有序性是指遍历的结果是按某种比较规则依次排列的。 稳定性指集合每次遍历的元素次序是一定的。 如：ArrayList 是 order/unsort；HashMap 是 unorder/unsort ；TreeSet 是 order/sort。

### 前端 ###

1.  重要的操作需要二次确认(例如: 删除)