Java编码手册之华山版小精华

怼烎@ 2022-11-14 10:17 164阅读 0赞

最近又复习了一下阿里出品的<Java开发手册–华山版>，对于开发过程中绝大多数开发者都遵循开发手册，相信开发团队的代码可维护性能够绝对性提高。为什么要整理出这篇文章呢？相信大家会有这种感觉—读书或者接触新知识时，如果没有人提出相关的知识点，大家看过之后会发现没有任何收获一样。  
开发手册我自问也看了好几遍，但是其中的部分点有时也会遗漏忘记遵循，故小编将自己容易遗漏或者开发过程中强制遵循的点列出来，同时也给新手抛砖，引玉就不敢了。。。。

1.【强制】类名使用 UpperCamelCase 风格，但以下情形例外：DO / BO / DTO / VO / AO / PO / UID 等。 正例：JavaServerlessPlatform / UserDO / XmlService / TcpUdpDeal / TaPromotion 反例：javaserverlessplatform / UserDo / XMLService / TCPUDPDeal / TAPromotion  
这一点大家要注意，之前小编认为DTO等类要需要遵循驼峰格式，结果误解混淆。

2.【强制】POJO 类中**布尔类型**变量都不要加 is 前缀，否则部分框架解析会引起序列化错误。  
说明：在本文 MySQL 规约中的建表约定第一条，表达是与否的值采用 is\_xxx 的命名方式，所以，需要在 设置从 is\_xxx 到 xxx 的映射关系。  
**反例**：定义为基本数据类型 Boolean isDeleted 的属性，它的方法也是 isDeleted()，RPC 框架在反向解 析的时候，“误以为”对应的属性名称是 deleted，导致属性获取不到，进而抛出异常。

3.【参考】枚举类名带上 Enum 后缀，枚举成员名称需要全大写，单词间用下划线隔开。  
说明：枚举其实就是特殊的类，域成员均为常量，且构造方法被默认强制是私有。  
正例：枚举名字为 ProcessStatusEnum 的成员名称：SUCCESS / UNKNOWN\_REASON。

4.【参考】各层命名规约：  
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 一般为网页名称。  
4） POJO 是 DO/DTO/BO/VO 的统称，禁止命名成 xxxPOJO。

5.【推荐】不要使用一个常量类维护所有常量，要按常量功能进行归类，分开维护。 说明：大而全的常量类，杂乱无章，使用查找功能才能定位到修改的常量，不利于理解和维护。 正例：缓存相关常量放在类 CacheConsts 下；系统配置相关常量放在类 ConfigConsts 下。

*  以上该点也需要注意，目前小编项目中就是存在相关的问题，管理起来比较麻烦，与此同时，如果自己新建常量类一定要及时与团队成员沟通，否则就会造成常量类越来越多，对于后面的成员维护造成麻烦，不知添加到那个常量类中更合适；

6.【强制】 if/for/while/switch/do 等保留字与**括号**之间都必须加空格。

7.【强制】任何二目、三目运算符的左右两边都需要加一个空格。  
说明：**运算符包括赋值运算符=、逻辑运算符&&、加减乘除符号**等。

8.【强制】注释的**双斜线与注释**内容之间**有且仅有**一个空格。  
正例： // 这是示例注释，请注意在双斜线之后有一个空格  
String param = new String();

9.【强制】在进行类型强制转换时，右括号与强制转换值之间不需要任何空格隔开。  
正例： long first = 1000000000000L; int second = (int)first + 2;

*  此处也是小编一直忽略点，不过感觉也无伤大雅，但是既然阿里大牛们整理出该条规约，必然由此的道理；

10.【推荐】不同逻辑、不同语义、不同业务的代码之间**插入一个空行**分隔开来以提升可读性。  
说明：任何情形，没有必要插入多个空行进行隔开。

11.【强制】Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用 equals。  
正例：“test”.equals(object);  
反例：object.equals(“test”); 说明：推荐使用 java.util.Objects\#equals（JDK7 引入的工具类）。

*  这点要特别注意，如果位置错误真的会抛出NPE问题，而且目前小编在code review过程中也发现同事会存在这样的问题；

12.【强制】为了防止精度损失，禁止使用构造方法 BigDecimal(double)的方式把 double 值转 化为 BigDecimal 对象。  
说明：BigDecimal(double)存在精度损失风险，在精确计算或值比较的场景中可能会导致业务逻辑异常。  
如：BigDecimal g = new BigDecimal(0.1f); 实际的存储值为：0.10000000149  
**正例**：优先推荐入参为 String 的构造方法，或使用 BigDecimal 的 valueOf 方法，此方法内部其实执行了 Double 的 toString，而 Double 的 toString 按 double 的实际能表达的精度对尾数进行了截断。

### 关于基本数据类型与包装数据类型的使用标准如下： ###

1.【强制】所有的 POJO 类属性必须使用包装数据类型。

2.【强制】RPC 方法的返回值和参数必须使用包装数据类型。

3.【强制】所有的局部变量使用基本数据类型。  
说明：POJO 类属性没有初值是提醒使用者在需要使用时，必须自己显式地进行赋值，任何 NPE 问题，或 者入库检查，都由使用者来保证。  
正例：数据库的查询结果可能是 null，因为**自动拆箱**，用基本数据类型接收有 NPE 风险。

4.【推荐】循环体内，字符串的连接方式，使用 StringBuilder 的 append 方法进行扩展。

5.【推荐】类成员与方法访问控制从严：  
1） 如果不允许外部直接通过 new 来创建对象，那么构造方法必须是 private。  
2） 工具类不允许有 public 或 default 构造方法。  
3） 类非 static 成员变量并且与子类共享，必须是 protected。  
4） 类非 static 成员变量并且仅在本类使用，必须是 private。  
5） 类 static 成员变量如果仅在本类使用，必须是 private。  
6） 若是 static 成员变量，考虑是否为 final。  
7） 类成员方法只供类内部调用，必须是 private。  
8） 类成员方法只对继承类公开，那么限制为 protected

6.【强制】关于 hashCode 和 equals 的处理，遵循如下规则：  
1） 只要覆写 equals，就必须覆写 hashCode。  
2） 因为 Set 存储的是不重复的对象，依据 hashCode 和 equals 进行判断，所以 Set 存储的对象必须覆 写这两个方法。  
3） 如果自定义对象作为 Map 的键，那么必须覆写 hashCode 和 equals。  
说明：String 已覆写 hashCode 和 equals 方法，所以我们可以愉快地使用 String 对象作为 key 来使用。

7.【强制】在使用 Collection 接口任何实现类的 addAll()方法时，都要对输入的集合参数进行 NPE 判断。  
说明：在 ArrayList\#addAll 方法的第一行代码即 Object\[\] a = c.toArray(); 其中 c 为输入集合参数，如果 为 null，则直接抛出异常。

8.【强制】不要在 foreach 循环里进行元素的 remove/add 操作。remove 元素请使用 Iterator 方式，如果并发操作，需要对 Iterator 对象加锁。

9.【强制】创建线程或线程池时请指定有意义的线程名称，方便出错时回溯。  
正例：自定义线程工厂，并且根据外部特征进行分组，比如机房信息。

10.【强制】SimpleDateFormat 是线程不安全的类，一般不要定义为 static 变量，如果定义为 static，必须加锁，或者使用 DateUtils 工具类。  
正例：注意线程安全，使用 DateUtils。亦推荐如下处理：

private static final ThreadLocal<DateFormat> df = new ThreadLocal<DateFormat>() {  
     @Override protected DateFormat initialValue() { 
      return new SimpleDateFormat("yyyy-MM-dd"); 
      }
       };

说明：如果是 JDK8 的应用，可以使用 Instant 代替 Date，LocalDateTime 代替 Calendar， DateTimeFormatter 代替 SimpleDateFormat，官方给出的解释：simple beautiful strong immutable thread-safe。

11.【强制】在使用阻塞等待获取锁的方式中，必须在 try 代码块之外，并且在加锁方法与 try 代 码块之间没有任何可能抛出异常的方法调用，避免加锁成功后，在 finally 中无法解锁。

*  说明一：如果在 lock 方法与 try 代码块之间的方法调用抛出异常，那么无法解锁，造成其它线程无法成功 获取锁。
 *  说明二：如果 lock 方法在 try 代码块之内，可能由于其它方法抛出异常，导致在 finally 代码块中， unlock 对未加锁的对象解锁，它会调用 AQS 的 tryRelease 方法（取决于具体实现类），抛出 IllegalMonitorStateException 异常。
 *  说明三：在 Lock 对象的 lock 方法实现中可能抛出 unchecked 异常，产生的后果与说明二相同。

正例： 
     Lock lock = new XxxLock(); 
     // ... lock.lock(); t
     ry {  
     doSomething(); 
     doOthers();
      } finally { 
       lock.unlock(); 
       } 
    反例：
    Lock lock = new XxxLock();
     // ... try { 
     // 如果此处抛出异常，则直接执行 finally 代码块 
     doSomething(); 
     // 无论加锁是否成功，finally 代码块都会执行 lock.lock(); doOthers(); 
     } finally { 
      lock.unlock(); 
      }

12.【强制】当 switch 括号内的变量类型为 String 并且此变量为外部参数时，必须先进行 null 判断。

13.【强制】在高并发场景中，避免使用”等于”判断作为中断或退出的条件。 说明：如果并发控制没有处理好，容易产生等值判断被“击穿”的情况，使用大于或小于的区间判断条件 来代替。 反例：判断剩余奖品数量等于 0 时，终止发放奖品，但因为并发处理错误导致奖品数量瞬间变成了负数， 这样的话，活动无法终止。

14.【强制】有 try 块放到了事务代码中，catch 异常后，如果需要回滚事务，一定要注意手动回 滚事务。

15.【强制】不要在 finally 块中使用 return。  
说明：try 块中的 return 语句执行成功后，并不马上返回，而是继续执行 finally 块中的语句，如果此处存 在 return 语句，则在此直接返回，无情丢弃掉 try 块中的返回点。

16.【推荐】防止 NPE，是程序员的基本修养，注意 NPE 产生的场景：  
1） 返回类型为基本数据类型，return 包装数据类型的对象时，自动拆箱有可能产生 NPE。  
**反例**：public int f() \{ return Integer 对象\}， 如果为 null，自动解箱抛 NPE。  
2） 数据库的查询结果可能为 null。  
3） 集合里的元素即使 isNotEmpty，取出的数据元素也可能为 null。  
4） 远程调用返回对象时，一律要求进行空指针判断，防止 NPE。  
5） 对于 Session 中获取的数据，建议进行 NPE 检查，避免空指针。  
6） 级联调用 obj.getA().getB().getC()；一连串调用，易产生 NPE。  
**正例：使用 JDK8 的 Optional 类来防止 NPE 问题。**

17.【强制】在日志输出时，字符串变量之间的拼接使用占位符的方式。  
说明：因为 String 字符串的拼接会使用 StringBuilder 的 append()方式，有一定的性能损耗。使用占位符 仅是替换动作，可以有效提升性能。  
正例：logger.debug(“Processing trade with id: \{\} and symbol: \{\}”, id, symbol);

*  此处也需要注意，之前小编项目建立之初，也是存在错误的日志打印问题。

18.【推荐】谨慎地记录日志。  
生产环境禁止输出 debug 日志；有选择地输出 info 日志；  
如果使 用 warn 来记录刚上线时的业务行为信息，一定要注意日志输出量的问题，避免把服务器磁盘 撑爆，并记得及时删除这些观察日志。  
说明：大量地输出无效日志，不利于系统性能提升，也不利于快速定位错误点。  
**记录日志时请思考：这些 日志真的有人看吗？看到这条日志你能做什么？能不能给问题排查带来好处？**

19.【强制】表达是与否概念的字段，必须使用 is\_xxx 的方式命名，数据类型是 unsigned tinyint（1 表示是，0 表示否）。  
说明：任何字段如果为非负数，必须是 unsigned。  
注意：**POJO 类中的任何布尔类型的变量，都不要加 is 前缀**，所以，需要在设置从 is\_xxx 到 Xxx 的映射关系。  
数据库表示是与否的值，使用 tinyint 类型，坚持 is\_xxx 的命名方式是为了明确其取 值含义与取值范围。  
正例：表达逻辑删除的字段名 is\_deleted，1 表示删除，0 表示未删除。

20.【强制】主键索引名为 pk\_字段名；唯一索引名为 uk\_字段名；普通索引名则为 idx\_字段名。  
说明：pk\_ 即 primary key；uk\_ 即 unique key；idx\_ 即 index 的简称。

*  这里要特别注意类，数据库的索引命名规则，特别是一些工作经验比较长的开发人员，之前可能未建立统一规约，保留类一些旧的习惯，数据库索引命名各种各样。

21.【强制】小数类型为 decimal，禁止使用 float 和 double。  
说明：在存储的时候，float 和 double 都存在精度损失的问题，很可能在比较值的时候，得到不正确的 结果。如果存储的数据范围超过 decimal 的范围，建议将数据拆成整数和小数并分开存储。

22.【推荐】防止因字段类型不同造成的隐式转换，导致索引失效。

23.【强制】不要使用 count(列名)或 count(常量)来替代 count()，count()是 SQL92 定义的 标准统计行数的语法，跟数据库无关，跟 NULL 和非 NULL 无关。  
说明：count(\*)会统计值为 NULL 的行，而 count(列名)不会统计此列为 NULL 值的行。

24.【强制】不得使用外键与级联，一切外键概念必须在应用层解决。  
说明：以学生和成绩的关系为例，学生表中的 student\_id 是主键，那么成绩表中的 student\_id 则为外 键。  
如果更新学生表中的 student\_id，同时触发成绩表中的 student\_id 更新，即为级联更新。外键与级 联更新适用于单机低并发，不适合分布式、高并发集群；级联更新是强阻塞，存在数据库更新风暴的风 险；外键影响数据库的插入速度。

25【强制】在表查询中，一律不要使用 \* 作为查询的字段列表，需要哪些字段必须明确写明。  
说明：1）增加查询分析器解析成本。  
2）增减字段容易与 resultMap 配置不一致。  
3）无用字段增加网络 消耗，尤其是 text 类型的字段。

26.【强制】不要用 resultClass 当返回参数，即使所有类属性名与数据库字段一一对应，也需要 定义；反过来，每一个表也必然有一个 POJO 类与之对应。 说明：配置映射关系，使字段与 DO 类解耦，方便维护。

27.【强制】不要写一个大而全的数据更新接口。传入为 POJO 类，不管是不是自己的目标更新 字段，都进行 update table set c1=value1,c2=value2,c3=value3; 这是不对的。执行 SQL 时，不要更新无改动的字段，一是易出错；二是效率低；三是增加 binlog 存储。

参考资料:《Java开发手册-华山版》